# QI Tech — Documentação completa

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

Índice:
- TAC 使用更新 (/zh-Hans/documentation/1bb151c7-735f-4449-bd9a-4780be271da8)
- SIAPE/军队带找零转贷 (/zh-Hans/documentation/6fabde14-8ce4-42ac-9f93-28246356e45d)
- 两步式开户 (/zh-Hans/documentation/account_request)
- 延期修改手册 (/zh-Hans/documentation/aditamento/manual_aditamento)
- 安排票据（Boleto）付款 (/zh-Hans/documentation/agendamentos/agendamento_boleto)
- 安排 PIX 转账 (/zh-Hans/documentation/agendamentos/agendamento_pix)
- 执行转账 (/zh-Hans/documentation/agendamentos/agendamento_ted)
- 取消预约 (/zh-Hans/documentation/agendamentos/cancelar_agendamento)
- 查询已预约交易 (/zh-Hans/documentation/agendamentos/consulta_agendamentos)
- arranjos_e_adquirentes (/zh-Hans/documentation/arranjos_e_adquirentes/)
- 创建再协商 (/zh-Hans/documentation/arranjos_e_adquirentes/consulta_de_agenda)
- trava_de_domicilio_bancario (/zh-Hans/documentation/arranjos_e_adquirentes/trava_de_domicilio_bancario)
- emissao_de_divida (/zh-Hans/documentation/auxilio_brasil/emissao_de_divida)
- webhook_auxilio_brasil (/zh-Hans/documentation/auxilio_brasil/webhook_auxilio_brasil)
- 确认开立个人账户 (/zh-Hans/documentation/baas/account/2fa_v2/abrir_conta_pf)
- 开立企业账户 (/zh-Hans/documentation/baas/account/2fa_v2/abrir_conta_pj)
- 确认开立个人账户 (/zh-Hans/documentation/baas/account/abrir_conta_pf)
- 确认开立企业账户 (/zh-Hans/documentation/baas/account/abrir_conta_pj)
- 申请账户预留 (/zh-Hans/documentation/baas/account/account_draft_checking)
- 申请账户预留 (/zh-Hans/documentation/baas/account/d4bf7f96-69b0-424b-a9d6-0a1bc79629cd)
- 简介 (/zh-Hans/documentation/baas/account/introducao)
- 申请开立个人账户 (/zh-Hans/documentation/baas/account/reservar_conta_pf)
- 企业账户开立 (/zh-Hans/documentation/baas/account/reservar_conta_pj)
- 账户开立 Webhooks (/zh-Hans/documentation/baas/account/webhooks)
- Catálogo de Erros - Banking-as-a-Service (/zh-Hans/documentation/baas/catalogo_de_erros_baas)
- Cancelar agendamento em lote de pagamento (/zh-Hans/documentation/baas/cobranca/2fa_v2/agendamento/cancelar_agendamento_em_lote_de_pagamento)
- 确认银行票据预约 (/zh-Hans/documentation/baas/cobranca/2fa_v2/agendamento/confirmar_agendamento_de_boleto_bancario)
- 确认征税发票支付预约 (/zh-Hans/documentation/baas/cobranca/2fa_v2/agendamento/confirmar_agendamento_de_fatura_de_recolhimento)
- Confirmar agendamento em lote de boleto bancário (/zh-Hans/documentation/baas/cobranca/2fa_v2/agendamento/confirmar_agendamento_em_lote_de_boleto_bancario)
- Confirmar agendamento em lote de fatura de recolhimento (/zh-Hans/documentation/baas/cobranca/2fa_v2/agendamento/confirmar_agendamento_em_lote_de_fatura_de_recolhimento)
- Consultar lote de agendamento de pagamento (/zh-Hans/documentation/baas/cobranca/2fa_v2/agendamento/consultar_lote_de_agendamento_de_pagamento)
- Listar lotes de agendamento de pagamento (/zh-Hans/documentation/baas/cobranca/2fa_v2/agendamento/listar_lotes_de_agendamento_de_pagamento)
- 重新发送银行票据预约双因素身份验证令牌 (/zh-Hans/documentation/baas/cobranca/2fa_v2/agendamento/reenviar_token_de_agendamento_boleto_bancario)
- 重新发送征税发票预约双因素身份验证令牌 (/zh-Hans/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 (/zh-Hans/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 (/zh-Hans/documentation/baas/cobranca/2fa_v2/agendamento/reenviar_token_de_agendamento_em_lote_de_fatura_de_recolhimento)
- 申请银行票据支付预约（双因素身份验证） (/zh-Hans/documentation/baas/cobranca/2fa_v2/agendamento/solicitar_agendamento_de_boleto_bancario)
- 申请征税发票支付预约（双因素身份验证） (/zh-Hans/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) (/zh-Hans/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) (/zh-Hans/documentation/baas/cobranca/2fa_v2/agendamento/solicitar_agendamento_em_lote_de_fatura_de_recolhimento)
- 银行票据批量支付确认 (/zh-Hans/documentation/baas/cobranca/2fa_v2/confirmacao_de_lote_de_boleto_bancario)
- 代收账单（公用事业/税费）批量支付确认 (/zh-Hans/documentation/baas/cobranca/2fa_v2/confirmacao_de_lote_de_fatura_de_recolhimento)
- 银行票据支付确认 (/zh-Hans/documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_boleto_bancario)
- 确认收款单付款 (/zh-Hans/documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_fatura_de_recolhimento)
- 双因素身份验证简介 (/zh-Hans/documentation/baas/cobranca/2fa_v2/introducao_ao_pagamento_2fa)
- 双因素身份验证银行票据支付请求 (/zh-Hans/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_boleto_bancario)
- 请求双因素认证收款单付款 (/zh-Hans/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_fatura_de_recolhimento)
- 重新发送银行票据支付双因素身份验证令牌 (/zh-Hans/documentation/baas/cobranca/2fa_v2/solicitacao_de_reenvio_de_token_de_boleto_bancario)
- 重新发送征税发票支付双因素身份验证令牌 (/zh-Hans/documentation/baas/cobranca/2fa_v2/solicitacao_de_reenvio_de_token_de_fatura_de_recolhimento)
- 重新发送银行票据批量支付确认令牌 (/zh-Hans/documentation/baas/cobranca/2fa_v2/solicitacao_de_reenvio_de_token_de_lote_de_boleto_bancario)
- 重新发送代收账单批量支付确认令牌（公用事业/税费） (/zh-Hans/documentation/baas/cobranca/2fa_v2/solicitacao_de_reenvio_de_token_de_lote_de_fatura_de_recolhimento)
- 发起银行票据批量支付（双重验证） (/zh-Hans/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 (/zh-Hans/documentation/baas/cobranca/2fa_v2/solicitar_pagamento_lote_de_boleto_bancario_sem_confirmacao_de_lote)
- 发起代收账单（公用事业/税费）批量支付（双重验证） (/zh-Hans/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 (/zh-Hans/documentation/baas/cobranca/2fa_v2/solicitar_pagamento_lote_de_fatura_de_recolhimento_sem_confirmacao_de_lote)
- 银行票据批量支付令牌校验 (/zh-Hans/documentation/baas/cobranca/2fa_v2/validacao_de_token_de_lote_de_boleto_bancario)
- 代收账单批量支付令牌校验（公用事业/税费） (/zh-Hans/documentation/baas/cobranca/2fa_v2/validacao_de_token_de_lote_de_fatura_de_recolhimento)
- 预约银行票据支付 (/zh-Hans/documentation/baas/cobranca/agendamento/agendar_pagamento_de_boleto_bancario)
- 预约征税发票支付（协议/税务） (/zh-Hans/documentation/baas/cobranca/agendamento/agendar_pagamento_de_fatura_de_recolhimento)
- 取消预约 (/zh-Hans/documentation/baas/cobranca/agendamento/cancelar_agendamento)
- 查询预约 (/zh-Hans/documentation/baas/cobranca/agendamento/consultar_agendamento)
- 列出预约 (/zh-Hans/documentation/baas/cobranca/agendamento/listar_agendamentos)
- Solicitar agendamento em lote de boleto bancário (/zh-Hans/documentation/baas/cobranca/agendamento/solicitar_agendamento_em_lote_de_boleto_bancario)
- Solicitar agendamento em lote de fatura de recolhimento (/zh-Hans/documentation/baas/cobranca/agendamento/solicitar_agendamento_em_lote_de_fatura_de_recolhimento)
- Confirmação de lote de pagamento de boleto bancário (/zh-Hans/documentation/baas/cobranca/confirmacao_de_lote_de_boleto_bancario)
- Confirmação de lote de pagamento de fatura de recolhimento (convênio/tributo) (/zh-Hans/documentation/baas/cobranca/confirmacao_de_lote_de_fatura_de_recolhimento)
- 银行票据查询 (/zh-Hans/documentation/baas/cobranca/consultar_boleto_bancario)
- 征税发票查询 (/zh-Hans/documentation/baas/cobranca/consultar_fatura_de_recolhimento)
- Consultar lote de pagamento (/zh-Hans/documentation/baas/cobranca/consultar_lote_de_pagamento)
- Listar lotes de pagamento (/zh-Hans/documentation/baas/cobranca/listar_lotes_de_pagamento)
- 列出支付 (/zh-Hans/documentation/baas/cobranca/listar_pagamentos)
- 支付银行票据 (/zh-Hans/documentation/baas/cobranca/pagar_boleto_bancario)
- 支付征税发票（协议/税务） (/zh-Hans/documentation/baas/cobranca/pagar_fatura_de_recolhimento)
- 场景模拟 (/zh-Hans/documentation/baas/cobranca/simulacao_de_cenarios)
- Solicitar Pagamento em Lote de Boleto Bancário (/zh-Hans/documentation/baas/cobranca/solicitar_pagamento_lote_de_boleto_bancario_com_confirmacao_de_lote)
- Solicitar Pagamento em Lote de Boleto Bancário (/zh-Hans/documentation/baas/cobranca/solicitar_pagamento_lote_de_boleto_bancario_sem_confirmacao_de_lote)
- Solicitar Pagamento em Lote de Fatura de Recolhimento (convênio/tributo) (/zh-Hans/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) (/zh-Hans/documentation/baas/cobranca/solicitar_pagamento_lote_de_fatura_de_recolhimento_sem_confirmacao_de_lote)
- Webhooks (/zh-Hans/documentation/baas/cobranca/webhooks)
- 查询设备 (/zh-Hans/documentation/baas/dispositivo/consultar_dispositivo)
- 批准设备创建 (/zh-Hans/documentation/baas/dispositivo/create/aprovar_cadastro_dispositivo)
- 申请创建设备 (/zh-Hans/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo)
- 申请重发令牌 (/zh-Hans/documentation/baas/dispositivo/create/solicitacao_reenvio_token)
- 停用设备 (/zh-Hans/documentation/baas/dispositivo/delete/desativar_dispositivo)
- 简介 (/zh-Hans/documentation/baas/dispositivo/introducao)
- 确认开设个人账户 (/zh-Hans/documentation/baas/escrow/abrir_conta_pf)
- 确认开设企业账户 (/zh-Hans/documentation/baas/escrow/abrir_conta_pj)
- 开设个人账户 (/zh-Hans/documentation/baas/escrow/reservar_conta_pf)
- 开设企业账户 (/zh-Hans/documentation/baas/escrow/reservar_conta_pj)
- 开户 Webhooks (/zh-Hans/documentation/baas/escrow/webhooks)
- baas_consulta_de_instituicoes_financeiras (/zh-Hans/documentation/baas/lista_de_instituicoes_financeiras/baas_consulta_de_instituicoes_financeiras)
- baas_configuracao_de_notificacao (/zh-Hans/documentation/baas/notificacoes/baas_configuracao_de_notificacao)
- baas_configuracao_template (/zh-Hans/documentation/baas/notificacoes/baas_configuracao_template)
- baas_introducao (/zh-Hans/documentation/baas/notificacoes/baas_introducao)
- baas_reenvio_de_notificacoes (/zh-Hans/documentation/baas/notificacoes/baas_reenvio_de_notificacoes)
- baas_template (/zh-Hans/documentation/baas/notificacoes/baas_template)
- baas_tipos_de_evento (/zh-Hans/documentation/baas/notificacoes/baas_tipos_de_evento)
- 上传汇款文件（CNAB） (/zh-Hans/documentation/baas/pagamento_em_lote/envio_de_remessa)
- CNAB240 批量交易简介 (/zh-Hans/documentation/baas/pagamento_em_lote/introducao)
- 按账户查询付款批次数据 (/zh-Hans/documentation/baas/pix_automatico/conciliacao/consultar_lote_por_conta)
- 按 Requester 查询付款批次 (/zh-Hans/documentation/baas/pix_automatico/conciliacao/consultar_lote_requester)
- 列出账户的付款订单 (/zh-Hans/documentation/baas/pix_automatico/conciliacao/listar_payment_orders)
- 付款订单对账批次创建 Webhook (/zh-Hans/documentation/baas/pix_automatico/conciliacao/webhooks)
- FAQ - Pix 自动支付 (/zh-Hans/documentation/baas/pix_automatico/faq)
- Pix 自动扣款简介 (/zh-Hans/documentation/baas/pix_automatico/introducao)
- 接受定期付款 (/zh-Hans/documentation/baas/pix_automatico/movimentacoes/aceitar_recorrencia)
- 取消定期付款 (/zh-Hans/documentation/baas/pix_automatico/movimentacoes/cancelar_recorrencia)
- 查询定期付款 (/zh-Hans/documentation/baas/pix_automatico/movimentacoes/consultar_recorrencia)
- 创建定期付款 (/zh-Hans/documentation/baas/pix_automatico/movimentacoes/criar_recorrencia)
- 定期付款列表 (/zh-Hans/documentation/baas/pix_automatico/movimentacoes/listar_recorrencias)
- 场景模拟 (/zh-Hans/documentation/baas/pix_automatico/movimentacoes/simulacao)
- Webhooks (/zh-Hans/documentation/baas/pix_automatico/movimentacoes/webhooks)
- 更新付款订单金额 (/zh-Hans/documentation/baas/pix_automatico/pagamentos/atualizar_payment_order)
- 取消付款订单 (/zh-Hans/documentation/baas/pix_automatico/pagamentos/cancelar_payment_order)
- 查询 Payment Order (/zh-Hans/documentation/baas/pix_automatico/pagamentos/consultar_payment_order)
- 按账户列出 Payment Orders (/zh-Hans/documentation/baas/pix_automatico/pagamentos/listar_account_payment_orders)
- 解码 Pix 自动支付 QR 码 (/zh-Hans/documentation/baas/pix_automatico/qr_code/decodificar_qr_code)
- 取消定期付款 (/zh-Hans/documentation/baas/pix_automatico/recebedor/cancelar_recorrencia)
- 通过 outgoing_recurrence_key 查询定期付款数据 (/zh-Hans/documentation/baas/pix_automatico/recebedor/consultar_recorrencia)
- 通过 QR 码查询 Pix 自动定期付款数据 (/zh-Hans/documentation/baas/pix_automatico/recebedor/consultar_recorrencia_receiver)
- 付款对账与结算 (/zh-Hans/documentation/baas/pix_automatico/recebedor/introducao)
- 创建定期付款（旅程 4） (/zh-Hans/documentation/baas/pix_automatico/recebedor/journey_four)
- 创建定期付款（旅程 1） (/zh-Hans/documentation/baas/pix_automatico/recebedor/journey_one)
- 创建定期付款（旅程 3） (/zh-Hans/documentation/baas/pix_automatico/recebedor/journey_three)
- 创建定期付款（旅程 2） (/zh-Hans/documentation/baas/pix_automatico/recebedor/journey_two)
- 列出请求方的定期付款 (/zh-Hans/documentation/baas/pix_automatico/recebedor/listar_recorrencias_de_um_requester)
- 列出账户的定期付款 (/zh-Hans/documentation/baas/pix_automatico/recebedor/listar_recorrencias_de_uma_conta)
- 场景模拟 (/zh-Hans/documentation/baas/pix_automatico/recebedor/simulacao)
- Pix 自动支付 Webhooks (/zh-Hans/documentation/baas/pix_automatico/recebedor/webhooks)
- 批准双因素身份验证交易 (/zh-Hans/documentation/baas/pix/2fa_v2/aprovar_transacao_pix_2fa)
- 双因素认证简介 (/zh-Hans/documentation/baas/pix/2fa_v2/introducao_a_transacao_pix_2fa)
- 申请退还已收到的 Pix (/zh-Hans/documentation/baas/pix/2fa_v2/solicitacao_de_devolucao_pix)
- 申请为交易重新发送令牌 (/zh-Hans/documentation/baas/pix/2fa_v2/solicitacao_de_reenvio_de_token)
- 请求双因素认证交易 (/zh-Hans/documentation/baas/pix/2fa_v2/solicitacao_de_transacao_pix_2fa)
- 批准带双因素身份验证的 Pix 交易预约 (/zh-Hans/documentation/baas/pix/agendamento/aprovacao_de_agendamento_2fa)
- 批准带双因素身份验证的批量 Pix 交易预约 (/zh-Hans/documentation/baas/pix/agendamento/batch/aprovacao_de_agendamento_em_lote_2fa)
- 取消批量 Pix 交易预约 (/zh-Hans/documentation/baas/pix/agendamento/batch/cancelamento_de_agendamento_em_lote)
- 查询预约批次中的预约列表 (/zh-Hans/documentation/baas/pix/agendamento/batch/consulta_de_agendamentos_de_um_lote)
- 查询账户的预约批次列表 (/zh-Hans/documentation/baas/pix/agendamento/batch/consulta_de_agendamentos_em_lote_de_uma_conta)
- 申请批量 Pix 交易预约 (/zh-Hans/documentation/baas/pix/agendamento/batch/solicitacao_de_agendamento_em_lote)
- 申请批量 Pix 交易预约（双因素认证） (/zh-Hans/documentation/baas/pix/agendamento/batch/solicitacao_de_agendamento_em_lote_2fa)
- 申请重发批量预约令牌 (/zh-Hans/documentation/baas/pix/agendamento/batch/solicitacao_de_reenvio_de_token_para_agendamento_em_lote_2fa)
- 取消 Pix 交易预约 (/zh-Hans/documentation/baas/pix/agendamento/cancelamento_de_agendamento)
- 查询 Pix 交易预约 (/zh-Hans/documentation/baas/pix/agendamento/consulta_de_agendamento)
- 查询账户的 Pix 交易预约列表 (/zh-Hans/documentation/baas/pix/agendamento/consulta_de_agendamentos_de_uma_conta)
- Tabela de Erros para Pix Schedule (/zh-Hans/documentation/baas/pix/agendamento/erros_de_agendamento)
- 简介 (/zh-Hans/documentation/baas/pix/agendamento/introducao)
- 双因素身份验证简介 (/zh-Hans/documentation/baas/pix/agendamento/introducao_a_agendamento_2fa)
- 申请 Pix 交易预约 (/zh-Hans/documentation/baas/pix/agendamento/solicitacao_de_agendamento)
- 申请双因素认证的 Pix 交易预约 (/zh-Hans/documentation/baas/pix/agendamento/solicitacao_de_agendamento_2fa)
- 申请为预约重新发送令牌 (/zh-Hans/documentation/baas/pix/agendamento/solicitacao_de_reenvio_de_token_para_agendamento_2fa)
- Pix 预约完成 Webhook (/zh-Hans/documentation/baas/pix/agendamento/webhook_de_conclusao_de_agendamento)
- 批准带双因素身份验证的批量交易 (/zh-Hans/documentation/baas/pix/batch/aprovar_transacao_em_lote_pix_2fa)
- Pix 批量交易简介 (/zh-Hans/documentation/baas/pix/batch/introducao_a_transacao_em_lote_pix)
- 查询账户批次中的交易列表 (/zh-Hans/documentation/baas/pix/batch/listar_transacoes_de_um_lote_de_transacoes_pix)
- 列出账户的批量 Pix 交易 (/zh-Hans/documentation/baas/pix/batch/listar_transacoes_em_lote_pix_de_uma_conta)
- 申请为批量 Pix 交易重新发送令牌 (/zh-Hans/documentation/baas/pix/batch/solicitacao_de_reenvio_de_token_para_lote)
- 执行批量 Pix 交易 (/zh-Hans/documentation/baas/pix/batch/solicitacao_de_transacao_em_lote_pix)
- 执行双因素认证批量 Pix 交易 (/zh-Hans/documentation/baas/pix/batch/solicitacao_de_transacao_em_lote_pix_2fa)
- 在巴西中央银行查询 Pix 键数据 (/zh-Hans/documentation/baas/pix/consultar_chave_pix)
- 查询转账 (/zh-Hans/documentation/baas/pix/consultar_transferencias)
- Pix Transfer 错误表 (/zh-Hans/documentation/baas/pix/erros_de_pix)
- 列出账户的转账记录 (/zh-Hans/documentation/baas/pix/listar_transferencias)
- 执行 Pix 交易 (/zh-Hans/documentation/baas/pix/realizar_transferencia)
- 申请已收 Pix 的退款 (/zh-Hans/documentation/baas/pix/solicitar_devolucao)
- Webhooks (/zh-Hans/documentation/baas/pix/webhooks)
- baas_configurando_webhooks (/zh-Hans/documentation/baas/primeiros_passos/baas_configurando_webhooks)
- Configurar IP de Integração (/zh-Hans/documentation/baas/primeiros_passos/baas_configurar_ip_de_integracao)
- baas_inicio (/zh-Hans/documentation/baas/primeiros_passos/baas_inicio)
- baas_troca_de_chaves (/zh-Hans/documentation/baas/primeiros_passos/baas_troca_de_chaves)
- baas_endpoints_de_teste (/zh-Hans/documentation/baas/primeiros_passos/teste_de_autenticacao/baas_endpoints_de_teste)
- baas_possiveis_erros (/zh-Hans/documentation/baas/primeiros_passos/teste_de_autenticacao/baas_possiveis_erros)
- baas_teste_de_autenticacao_completo (/zh-Hans/documentation/baas/primeiros_passos/teste_de_autenticacao/baas_teste_de_autenticacao_completo)
- baas_teste_de_autenticacao_v2 (/zh-Hans/documentation/baas/primeiros_passos/teste_de_autenticacao/baas_teste_de_autenticacao_v2)
- baas_webhook_v2 (/zh-Hans/documentation/baas/primeiros_passos/teste_de_autenticacao/baas_webhook_v2)
- 批准双因素身份验证 TED 交易 (/zh-Hans/documentation/baas/ted/2fa/aprovar_transacao_ted_2fa)
- 使用双因素身份验证执行 TED 转账 (/zh-Hans/documentation/baas/ted/2fa/realizar_transferencia_2fa)
- 请求重新发送 TED 交易令牌 (/zh-Hans/documentation/baas/ted/2fa/solicitacao_de_reenvio_de_token)
- 批准双因素身份验证批量交易 (/zh-Hans/documentation/baas/ted/batch_2fa/aprovar_transacao_em_lote_ted_2fa)
- 请求重新发送 TED 批量交易令牌 (/zh-Hans/documentation/baas/ted/batch_2fa/solicitacao_de_reenvio_de_token_para_lote_ted)
- 使用双因素身份验证执行 TED 批量交易 (/zh-Hans/documentation/baas/ted/batch_2fa/solicitacao_de_transacao_em_lote_ted_2fa)
- TED 批量交易简介 (/zh-Hans/documentation/baas/ted/batch/introducao_a_transacao_em_lote_ted)
- 列出账户批次中的 TED 交易 (/zh-Hans/documentation/baas/ted/batch/listar_transacoes_de_um_lote_de_transacoes_ted)
- 列出账户的 TED 批量交易 (/zh-Hans/documentation/baas/ted/batch/listar_transacoes_em_lote_ted_de_uma_conta)
- 执行 TED 批量交易 (/zh-Hans/documentation/baas/ted/batch/solicitacao_de_transacao_em_lote_ted)
- 查询 TED (/zh-Hans/documentation/baas/ted/consultar_ted)
- Tabela de Erros para Ted (/zh-Hans/documentation/baas/ted/erros_ted)
- 列出 TED (/zh-Hans/documentation/baas/ted/listar_teds)
- 执行 TED 转账 (/zh-Hans/documentation/baas/ted/realizar_transferencia)
- 批准双因素身份验证 TED 调度 (/zh-Hans/documentation/baas/ted/schedule_2fa/aprovacao_de_agendamento_2fa)
- 双因素身份验证简介 (/zh-Hans/documentation/baas/ted/schedule_2fa/introducao_a_agendamento_2fa)
- 请求双因素身份验证 TED 调度 (/zh-Hans/documentation/baas/ted/schedule_2fa/solicitacao_de_agendamento_2fa)
- 请求重新发送调度令牌 (/zh-Hans/documentation/baas/ted/schedule_2fa/solicitacao_de_reenvio_de_token_para_agendamento_2fa)
- 批准双因素身份验证 TED 批量调度 (/zh-Hans/documentation/baas/ted/schedule_batch_2fa/aprovacao_de_agendamento_em_lote_2fa)
- 请求 TED 批量调度（双因素身份验证） (/zh-Hans/documentation/baas/ted/schedule_batch_2fa/solicitacao_de_agendamento_em_lote_2fa)
- 请求重新发送 TED 批量调度令牌 (/zh-Hans/documentation/baas/ted/schedule_batch_2fa/solicitacao_de_reenvio_de_token_para_agendamento_em_lote_2fa)
- 取消 TED 批量调度 (/zh-Hans/documentation/baas/ted/schedule_batch/cancelamento_de_agendamento_em_lote)
- 列出批量调度中的调度列表 (/zh-Hans/documentation/baas/ted/schedule_batch/listar_agendamentos_de_um_lote)
- 列出账户的批量调度列表 (/zh-Hans/documentation/baas/ted/schedule_batch/listar_agendamentos_em_lote_de_uma_conta)
- 请求 TED 批量调度 (/zh-Hans/documentation/baas/ted/schedule_batch/solicitacao_de_agendamento_em_lote)
- 取消 TED 交易调度 (/zh-Hans/documentation/baas/ted/schedule/cancelamento_de_agendamento)
- 查询 TED 交易调度 (/zh-Hans/documentation/baas/ted/schedule/consulta_de_agendamento)
- 简介 (/zh-Hans/documentation/baas/ted/schedule/introducao)
- 列出账户的 TED 交易调度 (/zh-Hans/documentation/baas/ted/schedule/listar_agendamentos_de_uma_conta)
- 请求调度 TED 交易 (/zh-Hans/documentation/baas/ted/schedule/solicitacao_de_agendamento)
- TED 调度完成 Webhook (/zh-Hans/documentation/baas/ted/schedule/webhook_de_conclusao_de_agendamento)
- TED 发送完成后的 Webhook (/zh-Hans/documentation/baas/ted/webhooks)
- baas_consulta_documents (/zh-Hans/documentation/baas/upload_de_documentos/baas_consulta_documents)
- baas_upload_de_documentos (/zh-Hans/documentation/baas/upload_de_documentos/)
- 批准票据支付 (/zh-Hans/documentation/boletos/2fa/realizar_pagamento_de_um_boleto)
- 请求票据支付 token (/zh-Hans/documentation/boletos/2fa/solicitar_token_para_pagamento)
- 创建钱包 (/zh-Hans/documentation/boletos/carteira/criar_carteira)
- 编辑钱包 (/zh-Hans/documentation/boletos/carteira/editar_carteira)
- 列出账户钱包 (/zh-Hans/documentation/boletos/carteira/listar_carteiras)
- 查询临时文件 (/zh-Hans/documentation/boletos/cnab/consulta_por_chave)
- 汇款文件（CNAB）- 简介 (/zh-Hans/documentation/boletos/cnab/introducao)
- 列出临时汇款文件 (/zh-Hans/documentation/boletos/cnab/listar_arquivos_temporarios)
- 列出临时记录 (/zh-Hans/documentation/boletos/cnab/listar_ocorrencias_temporarias)
- 上传汇款文件（CNAB） (/zh-Hans/documentation/boletos/cnab/upload_de_arquivo_remessa)
- 通过密钥查询 Boleto (/zh-Hans/documentation/boletos/consulta/consulta_por_chave)
- Boleto 列表查询 (/zh-Hans/documentation/boletos/consulta/listar_boletos)
- 查询催收钱包 (/zh-Hans/documentation/boletos/consultar_v1/consulta_de_carteira)
- 查询回执文件 (/zh-Hans/documentation/boletos/consultar_v1/consultar_arquivo_retorno)
- Consultar boleto (/zh-Hans/documentation/boletos/consultar_v1/consultar_boleto)
- 生成 PDF (/zh-Hans/documentation/boletos/consultar_v1/emitir_pdf)
- Francesinha (/zh-Hans/documentation/boletos/consultar_v1/francesinha)
- 列出票据 (/zh-Hans/documentation/boletos/consultar_v1/listar_boletos)
- Excel 格式日常仓位报告 (/zh-Hans/documentation/boletos/consultar_v1/posicao_diaria_excel)
- JSON 格式日常仓位报告 (/zh-Hans/documentation/boletos/consultar_v1/posicao_diaria_json)
- 回执文件对账例程 (/zh-Hans/documentation/boletos/consultar_v1/rotina_de_conciliacao_de_arquivo_retorno)
- 申请票据补发 (/zh-Hans/documentation/boletos/consultar_v1/segunda_via_de_boleto)
- 单张 Boleto 发行（即时） (/zh-Hans/documentation/boletos/emissao/emissao_boleto_unico_instantanea)
- 单张 Boleto 发行（标准） (/zh-Hans/documentation/boletos/emissao/emissao_boleto_unico_padrao)
- 批量 Boleto 发行 (/zh-Hans/documentation/boletos/emissao/emissao_em_lote)
- 取消折让 (/zh-Hans/documentation/boletos/instrucoes/abatimento/cancelar_abatimento)
- 创建折让 (/zh-Hans/documentation/boletos/instrucoes/abatimento/criar_abatimento)
- 注销 (/zh-Hans/documentation/boletos/instrucoes/baixa)
- 折扣 (/zh-Hans/documentation/boletos/instrucoes/desconto)
- 编辑 (/zh-Hans/documentation/boletos/instrucoes/edicao)
- 延期 (/zh-Hans/documentation/boletos/instrucoes/extensao)
- 利息 (/zh-Hans/documentation/boletos/instrucoes/juros)
- 查询指令批次 (/zh-Hans/documentation/boletos/instrucoes/lote/consultar_lote_de_instrucoes)
- 创建指令批次 (/zh-Hans/documentation/boletos/instrucoes/lote/criar_lote_de_instrucoes)
- 列出指令批次 (/zh-Hans/documentation/boletos/instrucoes/lote/listar_lotes_de_instrucoes)
- 罚款 (/zh-Hans/documentation/boletos/instrucoes/multa)
- 部分付款 (/zh-Hans/documentation/boletos/instrucoes/pagamento_parcial)
- 查询抗议工具文件 (/zh-Hans/documentation/boletos/instrucoes/protesto/consulta_instrumento_de_protesto)
- 通过键查询抗议 (/zh-Hans/documentation/boletos/instrucoes/protesto/consulta_por_chave)
- 撤回（中止）抗议 (/zh-Hans/documentation/boletos/instrucoes/protesto/desistencia_de_protesto)
- 撤回（中止）抗议并核销票据 (/zh-Hans/documentation/boletos/instrucoes/protesto/desistencia_de_protesto_e_baixa_do_boleto)
- 简介 (/zh-Hans/documentation/boletos/instrucoes/protesto/introducao)
- 列出抗议 (/zh-Hans/documentation/boletos/instrucoes/protesto/listar_protestos)
- 抗议申请 (/zh-Hans/documentation/boletos/instrucoes/protesto/pedido_de_protesto)
- 撤销抗议 (/zh-Hans/documentation/boletos/instrucoes/protesto/sustacao_de_protesto)
- 信用分账更新 (/zh-Hans/documentation/boletos/instrucoes/rateio_de_credito)
- 金额 (/zh-Hans/documentation/boletos/instrucoes/valor)
- 简介 (/zh-Hans/documentation/boletos/introducao)
- 列出清算组 (/zh-Hans/documentation/boletos/liquidacao/listar_grupos_de_liquidacao)
- 列出清算记录 (/zh-Hans/documentation/boletos/liquidacao/listar_liquidacoes)
- 清算场景模拟 (/zh-Hans/documentation/boletos/liquidacao/simulacao_de_cenarios_de_liquidacao)
- 批准票据付款 (/zh-Hans/documentation/boletos/pagamento/aprovar_pagamento)
- 查询票据可输入行 (/zh-Hans/documentation/boletos/pagamento/consulta_linha_digitavel)
- 执行票据付款 (/zh-Hans/documentation/boletos/pagamento/realizar_pagamento)
- 票据清算账户重定向 (/zh-Hans/documentation/boletos/redirecionamento_de_conta_de_liquidacao)
- 列出返回文件 (/zh-Hans/documentation/boletos/retorno/listar_arquivos_retorno)
- 发行 bolePix (/zh-Hans/documentation/boletos/v1/emissao/emissao_de_um_bolepix)
- 通过 CNAB 发行票据 (/zh-Hans/documentation/boletos/v1/emissao/emissao_via_cnab)
- 通过 JSON 发行票据 (/zh-Hans/documentation/boletos/v1/emissao/emissao_via_json)
- 发送票据指令 (/zh-Hans/documentation/boletos/v1/enviar_instrucao_de_boleto)
- 简介 (/zh-Hans/documentation/boletos/v1/introducao)
- Boleto Webhooks (/zh-Hans/documentation/boletos/webhooks/boleto)
- 票据钱包 Webhooks (/zh-Hans/documentation/boletos/webhooks/carteira)
- 清算 Webhooks (/zh-Hans/documentation/boletos/webhooks/liquidacao)
- 返回文件 Webhooks (/zh-Hans/documentation/boletos/webhooks/retorno)
- 认证 (/zh-Hans/documentation/caas/account_event/authentication)
- Device Validation 对象 (/zh-Hans/documentation/caas/account_event/device_validation)
- HTTP 状态码 (/zh-Hans/documentation/caas/account_event/http_status)
- 简介 (/zh-Hans/documentation/caas/account_event/introduction)
- Pre PIX Transaction (/zh-Hans/documentation/caas/account_event/pre_pix_transaction)
- 查询账户事件 (/zh-Hans/documentation/caas/account_event/query_registration)
- 标准 (/zh-Hans/documentation/caas/account_event/standards)
- 状态动态 (/zh-Hans/documentation/caas/account_event/status_dynamics)
- 账户创建 (/zh-Hans/documentation/caas/account_monitoring/account_registration)
- authentication (/zh-Hans/documentation/caas/account_monitoring/authentication)
- HTTP 状态码 (/zh-Hans/documentation/caas/account_monitoring/http_status)
- 简介 (/zh-Hans/documentation/caas/account_monitoring/introduction)
- 人员创建 (/zh-Hans/documentation/caas/account_monitoring/person_registration)
- 标准 (/zh-Hans/documentation/caas/account_monitoring/standards)
- Webhook (/zh-Hans/documentation/caas/account_monitoring/webhook)
- 创建会话 (/zh-Hans/documentation/caas/auth_session_manager/auth_session)
- 认证 (/zh-Hans/documentation/caas/auth_session_manager/authentication)
- HTTP 状态码 (/zh-Hans/documentation/caas/auth_session_manager/http_status)
- 简介 (/zh-Hans/documentation/caas/auth_session_manager/introduction)
- 会话管理 (/zh-Hans/documentation/caas/auth_session_manager/retrieve_session)
- authentication (/zh-Hans/documentation/caas/banking/authentication)
- Boleto (/zh-Hans/documentation/caas/banking/bankslips)
- 账单支付 (/zh-Hans/documentation/caas/banking/bill_payments)
- 存款 (/zh-Hans/documentation/caas/banking/deposits/introduction)
- HTTP 状态码 (/zh-Hans/documentation/caas/banking/http_status)
- 简介 (/zh-Hans/documentation/caas/banking/introduction)
- 共享对象 (/zh-Hans/documentation/caas/banking/objects)
- PIX Dict Operation (/zh-Hans/documentation/caas/banking/pix_dict_operations)
- PIX Infraction Report (/zh-Hans/documentation/caas/banking/pix_infraction_reports)
- PIX Transaction (/zh-Hans/documentation/caas/banking/pix_transactions)
- 标准 (/zh-Hans/documentation/caas/banking/standards)
- Webhook (/zh-Hans/documentation/caas/banking/webhook)
- 转账 (/zh-Hans/documentation/caas/banking/wire_transfers)
- 取款 (/zh-Hans/documentation/caas/banking/withdrawals)
- Status HTTP (/zh-Hans/documentation/caas/car_rental/http_status)
- Imagens (/zh-Hans/documentation/caas/car_rental/image)
- Introdução (/zh-Hans/documentation/caas/car_rental/introduction)
- Troca de Mensagens (/zh-Hans/documentation/caas/car_rental/messages)
- Objetos Compartilhados (/zh-Hans/documentation/caas/car_rental/objects)
- Envio de Resultado Quiz (/zh-Hans/documentation/caas/car_rental/quiz)
- RentalAgreement-v1 (/zh-Hans/documentation/caas/car_rental/rental_agreement)
- RentalAgreement-v2 (/zh-Hans/documentation/caas/car_rental/rental_agreement_v2)
- Reservation-v1 (/zh-Hans/documentation/caas/car_rental/reservation)
- Reservation-v2 (/zh-Hans/documentation/caas/car_rental/reservation_v2)
- Padrões (/zh-Hans/documentation/caas/car_rental/standards)
- Webhook (/zh-Hans/documentation/caas/car_rental/webhook)
- 持卡人警报 (/zh-Hans/documentation/caas/card_issuance/alerts)
- authentication (/zh-Hans/documentation/caas/card_issuance/authentication)
- HTTP 状态码 (/zh-Hans/documentation/caas/card_issuance/http_status)
- 简介 (/zh-Hans/documentation/caas/card_issuance/introduction)
- 标准 (/zh-Hans/documentation/caas/card_issuance/standards)
- Transaction (/zh-Hans/documentation/caas/card_issuance/transaction)
- authentication (/zh-Hans/documentation/caas/card_order/authentication)
- HTTP 状态码 (/zh-Hans/documentation/caas/card_order/http_status)
- 简介 (/zh-Hans/documentation/caas/card_order/introduction)
- 对象 (/zh-Hans/documentation/caas/card_order/objects)
- 订单 (/zh-Hans/documentation/caas/card_order/order)
- 标准 (/zh-Hans/documentation/caas/card_order/standards)
- Webhook (/zh-Hans/documentation/caas/card_order/webhook)
- authentication (/zh-Hans/documentation/caas/credit_analysis/authentication)
- 挑战流程 (/zh-Hans/documentation/caas/credit_analysis/challenge_flow)
- 检索信用分析 (/zh-Hans/documentation/caas/credit_analysis/get_credit_analysis)
- HTTP 状态码 (/zh-Hans/documentation/caas/credit_analysis/http_status)
- 图像 (/zh-Hans/documentation/caas/credit_analysis/image)
- 简介 (/zh-Hans/documentation/caas/credit_analysis/introduction)
- 信用分析 - 法人 (/zh-Hans/documentation/caas/credit_analysis/legal_person)
- 信用分析 - 自然人 (/zh-Hans/documentation/caas/credit_analysis/natural_person)
- 共享对象 (/zh-Hans/documentation/caas/credit_analysis/objects)
- 信贷信息系统数据（SCR - BACEN） (/zh-Hans/documentation/caas/credit_analysis/scr)
- 标准 (/zh-Hans/documentation/caas/credit_analysis/standards)
- 状态动态 (/zh-Hans/documentation/caas/credit_analysis/status_dynamics)
- 更新信用分析状态 (/zh-Hans/documentation/caas/credit_analysis/update_credit_analysis)
- Webhook (/zh-Hans/documentation/caas/credit_analysis/webhook)
- Account 对象 (/zh-Hans/documentation/caas/device_manager/account)
- 认证 (/zh-Hans/documentation/caas/device_manager/authentication)
- Device 对象 (/zh-Hans/documentation/caas/device_manager/device_registration)
- HTTP 状态码 (/zh-Hans/documentation/caas/device_manager/http_status)
- 简介 (/zh-Hans/documentation/caas/device_manager/introduction)
- Person 对象 (/zh-Hans/documentation/caas/device_manager/person)
- 检索或停用 Account、Person 或 Device (/zh-Hans/documentation/caas/device_manager/query_registration)
- 标准规范 (/zh-Hans/documentation/caas/device_manager/standards)
- 状态动态 (/zh-Hans/documentation/caas/device_manager/status_dynamics)
- 库兼容性 (/zh-Hans/documentation/caas/device_scan/android/compatibility)
- DeviceScan 对象 (/zh-Hans/documentation/caas/device_scan/android/device_scan_object)
- 实现 (/zh-Hans/documentation/caas/device_scan/android/example)
- 混合解决方案 (/zh-Hans/documentation/caas/device_scan/android/hybrid_solutions)
- 信息收集 (/zh-Hans/documentation/caas/device_scan/android/information_gathering)
- 简介 (/zh-Hans/documentation/caas/device_scan/android/introduction)
- 原生集成 (/zh-Hans/documentation/caas/device_scan/android/native_java)
- 权限 (/zh-Hans/documentation/caas/device_scan/android/permissions)
- 认证 (/zh-Hans/documentation/caas/device_scan/api/authentication)
- 库兼容性 (/zh-Hans/documentation/caas/device_scan/flutter/compatibility)
- QitechDeviceScan 对象 (/zh-Hans/documentation/caas/device_scan/flutter/device_scan_object)
- 实现 (/zh-Hans/documentation/caas/device_scan/flutter/example)
- 简介 (/zh-Hans/documentation/caas/device_scan/flutter/introduction)
- 权限 (/zh-Hans/documentation/caas/device_scan/flutter/permissions)
- QITechIosDeviceScan 对象 (/zh-Hans/documentation/caas/device_scan/ios/device_scan_object)
- 实现 (/zh-Hans/documentation/caas/device_scan/ios/example)
- 混合解决方案 (/zh-Hans/documentation/caas/device_scan/ios/hybrid_solutions)
- 信息收集 (/zh-Hans/documentation/caas/device_scan/ios/information_gathering)
- 简介 (/zh-Hans/documentation/caas/device_scan/ios/introduction)
- 原生集成 (/zh-Hans/documentation/caas/device_scan/ios/native_swift)
- 权限 (/zh-Hans/documentation/caas/device_scan/ios/permissions)
- Desktop Device Scan (/zh-Hans/documentation/caas/device_scan/web/desktop)
- DeviceScan 对象 (/zh-Hans/documentation/caas/device_scan/web/device_scan_object)
- 实现 (/zh-Hans/documentation/caas/device_scan/web/example)
- 导入库 (/zh-Hans/documentation/caas/device_scan/web/import)
- 收集返回值 (/zh-Hans/documentation/caas/device_scan/web/information_gathering)
- 简介 (/zh-Hans/documentation/caas/device_scan/web/introduction)
- 发送文件 (/zh-Hans/documentation/caas/document_analysis/document_submission)
- HTTP 状态码 (/zh-Hans/documentation/caas/document_analysis/http_status)
- 简介 (/zh-Hans/documentation/caas/document_analysis/introduction)
- Webhook (/zh-Hans/documentation/caas/document_analysis/webhook)
- builder (/zh-Hans/documentation/caas/face_recognition/android/builder)
- 收集结果 (/zh-Hans/documentation/caas/face_recognition/android/collecting_response)
- 1:1 验证 - Face Match (/zh-Hans/documentation/caas/face_recognition/android/face_match)
- 混合解决方案 (/zh-Hans/documentation/caas/face_recognition/android/hybrid_solutions)
- 简介 (/zh-Hans/documentation/caas/face_recognition/android/introduction)
- 原生集成 (/zh-Hans/documentation/caas/face_recognition/android/native_java)
- using_sdk (/zh-Hans/documentation/caas/face_recognition/android/using_sdk)
- 身份验证 (/zh-Hans/documentation/caas/face_recognition/api/authentication)
- Registro de rosto (1:1) (/zh-Hans/documentation/caas/face_recognition/api/face_registration)
- HTTP 状态码 (/zh-Hans/documentation/caas/face_recognition/api/http_status)
- 图片 (/zh-Hans/documentation/caas/face_recognition/api/image)
- 简介 (/zh-Hans/documentation/caas/face_recognition/api/introduction)
- Registration (/zh-Hans/documentation/caas/face_recognition/api/registration)
- 标准 (/zh-Hans/documentation/caas/face_recognition/api/standards)
- Validation (/zh-Hans/documentation/caas/face_recognition/api/validation)
- 收集 SDK 返回值 (/zh-Hans/documentation/caas/face_recognition/ios/collecting_response)
- QITechIosFaceRecognitionConfiguration (/zh-Hans/documentation/caas/face_recognition/ios/configuration)
- 混合解决方案 (/zh-Hans/documentation/caas/face_recognition/ios/hybrid_solutions)
- 简介 (/zh-Hans/documentation/caas/face_recognition/ios/introduction)
- 导入 SDK (/zh-Hans/documentation/caas/face_recognition/ios/native_swift)
- necessary_permissions (/zh-Hans/documentation/caas/face_recognition/ios/necessary_permissions)
- using_sdk (/zh-Hans/documentation/caas/face_recognition/ios/using_sdk)
- 收集 SDK 返回值 (/zh-Hans/documentation/caas/face_recognition/web/collecting_response)
- 实现 (/zh-Hans/documentation/caas/face_recognition/web/example)
- QITechWebFaceRecon.WebFaceRecon() 构造函数 (/zh-Hans/documentation/caas/face_recognition/web/example_zaigwebfacerecon)
- 导入库 (/zh-Hans/documentation/caas/face_recognition/web/import)
- 简介 (/zh-Hans/documentation/caas/face_recognition/web/introduction)
- 面部注册和 1:1 验证 (/zh-Hans/documentation/caas/face_recognition/web/registration_and_validation)
- authentication (/zh-Hans/documentation/caas/limits/authentication)
- HTTP 状态码 (/zh-Hans/documentation/caas/limits/http_status)
- 简介 (/zh-Hans/documentation/caas/limits/introduction)
- 注册新限额 (/zh-Hans/documentation/caas/limits/limit_registration)
- 创建受益人列表 (/zh-Hans/documentation/caas/limits/recipient_list)
- 标准 (/zh-Hans/documentation/caas/limits/standards)
- 状态动态 (/zh-Hans/documentation/caas/limits/status_dynamics)
- Webhook (/zh-Hans/documentation/caas/limits/webhook)
- builder (/zh-Hans/documentation/caas/ocr/android/builder)
- 收集返回值 (/zh-Hans/documentation/caas/ocr/android/collecting_response)
- DocumentDetectorStep (/zh-Hans/documentation/caas/ocr/android/document_step)
- 混合解决方案 (/zh-Hans/documentation/caas/ocr/android/hybrid_solutions)
- DocumentDetectorStep (/zh-Hans/documentation/caas/ocr/android/implementation_demo)
- 简介 (/zh-Hans/documentation/caas/ocr/android/introduction)
- 原生集成 (/zh-Hans/documentation/caas/ocr/android/native_java)
- using_sdk (/zh-Hans/documentation/caas/ocr/android/using_sdk)
- authentication (/zh-Hans/documentation/caas/ocr/api/authentication)
- HTTP 状态码 (/zh-Hans/documentation/caas/ocr/api/http_status)
- 简介 (/zh-Hans/documentation/caas/ocr/api/introduction)
- quality (/zh-Hans/documentation/caas/ocr/api/quality)
- 发送文档 (/zh-Hans/documentation/caas/ocr/api/send_image)
- 收集返回值 (/zh-Hans/documentation/caas/ocr/ios/collecting_response)
- QITechIosOcrConfiguration (/zh-Hans/documentation/caas/ocr/ios/configuration)
- 混合解决方案 (/zh-Hans/documentation/caas/ocr/ios/hybrid_solutions)
- 简介 (/zh-Hans/documentation/caas/ocr/ios/introduction)
- 导入 SDK (/zh-Hans/documentation/caas/ocr/ios/native_swift)
- necessary_permissions (/zh-Hans/documentation/caas/ocr/ios/necessary_permissions)
- 导入 SDK (/zh-Hans/documentation/caas/ocr/ios/using_sdk)
- 收集返回值 (/zh-Hans/documentation/caas/ocr/web/collecting_results)
- QiTechWebOCR.WebOCR() 构造函数 (/zh-Hans/documentation/caas/ocr/web/constructor_info)
- 实现 (/zh-Hans/documentation/caas/ocr/web/example)
- 导入库 (/zh-Hans/documentation/caas/ocr/web/import)
- initialize() 函数 (/zh-Hans/documentation/caas/ocr/web/initialize_info)
- 简介 (/zh-Hans/documentation/caas/ocr/web/introduction)
- 认证 (/zh-Hans/documentation/caas/onboarding/authentication)
- HTTP 状态码 (/zh-Hans/documentation/caas/onboarding/http_status)
- 集成 (/zh-Hans/documentation/caas/onboarding/integrations)
- 简介 (/zh-Hans/documentation/caas/onboarding/introduction)
- Legal Person 对象 (/zh-Hans/documentation/caas/onboarding/legal_person)
- Natural Person 对象 (/zh-Hans/documentation/caas/onboarding/natural_person)
- 共享对象 (/zh-Hans/documentation/caas/onboarding/objects)
- 查询注册信息 (/zh-Hans/documentation/caas/onboarding/query_registration)
- 标准规范 (/zh-Hans/documentation/caas/onboarding/standards)
- 状态动态 (/zh-Hans/documentation/caas/onboarding/status_dynamics)
- 更新注册信息 (/zh-Hans/documentation/caas/onboarding/update_registration)
- Webhook (/zh-Hans/documentation/caas/onboarding/webhook)
- 授权请求（可选） (/zh-Hans/documentation/cards/autorizacao/)
- QI Conta 交易 (/zh-Hans/documentation/cards/autorizacao/balance_transaction)
- 模拟授权 (/zh-Hans/documentation/cards/autorizacao/simular_autorizacao)
- 创建实体卡 (/zh-Hans/documentation/cards/create/gerar_cartao_fisico)
- 创建虚拟卡 (/zh-Hans/documentation/cards/create/gerar_cartao_virtual)
- 简介 (/zh-Hans/documentation/cards/introducao)
- 通过授权密钥查询授权 (/zh-Hans/documentation/cards/search/buscar_autorizacao)
- 查询授权列表 (/zh-Hans/documentation/cards/search/buscar_autorizacoes)
- 通过密钥查询卡片 (/zh-Hans/documentation/cards/search/buscar_cartao_by_key)
- 查询 PCI 数据 (/zh-Hans/documentation/cards/search/buscar_dados_pci)
- 通过卡片密钥查询配送信息 (/zh-Hans/documentation/cards/search/buscar_entrega_by_key)
- 查询 PCI 密码 (/zh-Hans/documentation/cards/search/buscar_senha)
- 列出卡片 (/zh-Hans/documentation/cards/search/listar_cartoes)
- 激活实体卡 (/zh-Hans/documentation/cards/status/ativar_cartao)
- 更新状态 (/zh-Hans/documentation/cards/status/update_status_cartao)
- 非接触式（Contactless）配置 (/zh-Hans/documentation/cards/update/contactless_cartao)
- 修改实体卡密码 (/zh-Hans/documentation/cards/update/password_cartao)
- 更新配送地址 (/zh-Hans/documentation/cards/update/update_delivery_address)
- 非接触式（Contactless）配置 (/zh-Hans/documentation/cartao_pos_pago/cartao/atualizar/atualizar_contactless)
- 更新配送地址 (/zh-Hans/documentation/cartao_pos_pago/cartao/atualizar/atualizar_endereco_entrega)
- 修改实体卡密码 (/zh-Hans/documentation/cartao_pos_pago/cartao/atualizar/atualizar_senha)
- 场景模拟 (/zh-Hans/documentation/cartao_pos_pago/cartao/atualizar/simulacao_de_cenarios)
- 通过密钥查询卡片 (/zh-Hans/documentation/cartao_pos_pago/cartao/busca/buscar_cartao_por_chave)
- 通过卡片密钥查询配送信息 (/zh-Hans/documentation/cartao_pos_pago/cartao/busca/buscar_dados_entrega_por_chave)
- 查询 PCI 数据 (/zh-Hans/documentation/cartao_pos_pago/cartao/busca/buscar_dados_pci)
- 查询 PCI 密码 (/zh-Hans/documentation/cartao_pos_pago/cartao/busca/buscar_senha)
- 激活实体卡 (/zh-Hans/documentation/cartao_pos_pago/cartao/status/ativar_cartao)
- 更新状态 (/zh-Hans/documentation/cartao_pos_pago/cartao/status/atualizar_status_cartao)
- 修改钱包额度 (/zh-Hans/documentation/cartao_pos_pago/faturas/carteira/alteracao_de_limite)
- 通过密钥查询钱包条目 (/zh-Hans/documentation/cartao_pos_pago/faturas/carteira/consulta_entrada_por_chave)
- 通过密钥查询钱包 (/zh-Hans/documentation/cartao_pos_pago/faturas/carteira/consulta_por_chave)
- 创建钱包（Wallet） (/zh-Hans/documentation/cartao_pos_pago/faturas/carteira/criacao_de_carteira)
- 列出钱包（Wallets） (/zh-Hans/documentation/cartao_pos_pago/faturas/carteira/listar_carteiras)
- 列出钱包条目 (/zh-Hans/documentation/cartao_pos_pago/faturas/carteira/listar_entradas_da_carteira)
- 查询钱包票据（Boleto） (/zh-Hans/documentation/cartao_pos_pago/faturas/fatura/boleto_de_pagamento_da_fatura)
- 通过密钥查询账单 (/zh-Hans/documentation/cartao_pos_pago/faturas/fatura/consulta_por_chave)
- 列出账单 (/zh-Hans/documentation/cartao_pos_pago/faturas/fatura/listar_faturas)
- 场景模拟 - 账单结账与到期 (/zh-Hans/documentation/cartao_pos_pago/faturas/fatura/simulacao_de_cenarios)
- 修改支付工具额度 (/zh-Hans/documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/alteracao_de_limite)
- 取消支付工具 (/zh-Hans/documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/cancelamento_de_instrumento_de_pagamento)
- 按密钥查询支付工具条目 (/zh-Hans/documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/consulta_entrada_por_chave)
- 创建支付工具 (/zh-Hans/documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/criacao_de_instrumento_de_pagamento)
- 列出支付工具条目 (/zh-Hans/documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/listar_entradas_do_instrumento_de_pagamento)
- 列出支付工具 (/zh-Hans/documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/listar_instrumentos_de_pagamento)
- 场景模拟 (/zh-Hans/documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/simulacao_de_cenarios)
- 钱包 Webhooks (/zh-Hans/documentation/cartao_pos_pago/faturas/webhooks/carteira)
- 钱包条目 Webhooks (/zh-Hans/documentation/cartao_pos_pago/faturas/webhooks/entrada_da_carteira)
- 支付工具条目 Webhooks (/zh-Hans/documentation/cartao_pos_pago/faturas/webhooks/entrada_do_instrumento_de_pagamento)
- 发票 Webhooks (/zh-Hans/documentation/cartao_pos_pago/faturas/webhooks/fatura)
- 发票付款 Webhooks (/zh-Hans/documentation/cartao_pos_pago/faturas/webhooks/pagamento_da_fatura)
- 简介 (/zh-Hans/documentation/cartao_pos_pago/introducao)
- Manual BaaS - 数字账户 (/zh-Hans/documentation/casos_de_uso/manual_baas)
- Manual BaaS - 服务 (/zh-Hans/documentation/casos_de_uso/manual_baas_servico)
- 环境 (/zh-Hans/documentation/certifiqi/ambientes)
- ZIP 文件 (/zh-Hans/documentation/certifiqi/arquivo_zip)
- 自动签名 (/zh-Hans/documentation/certifiqi/assinatura_automatica)
- 创建访问权限 (/zh-Hans/documentation/certifiqi/cadastro)
- 取消签名事件 (/zh-Hans/documentation/certifiqi/cancelar_batch_group_de_assinatura)
- 查询签名事件 (/zh-Hans/documentation/certifiqi/consultar_evento)
- 查询文件 URL (/zh-Hans/documentation/certifiqi/consultar_url)
- 创建签名事件 (/zh-Hans/documentation/certifiqi/criar_batch_group)
- 创建签名事件以通知 Fromtis (/zh-Hans/documentation/certifiqi/criar_batch_group_fromtis)
- 发送签名 (/zh-Hans/documentation/certifiqi/enviar_para_assinatura)
- 结构 (/zh-Hans/documentation/certifiqi/estrutura)
- 认证方式 (/zh-Hans/documentation/certifiqi/forma_de_autenticacao)
- 开始 (/zh-Hans/documentation/certifiqi/inicio)
- 用户权限 (/zh-Hans/documentation/certifiqi/permissoes)
- CNAB 文件上传 (/zh-Hans/documentation/certifiqi/upload_documentos_cnab_assincrono)
- PDF 文件上传 (/zh-Hans/documentation/certifiqi/upload_documentos_pdf)
- Webhook (/zh-Hans/documentation/certifiqi/webhook)
- 创建债权转让 (/zh-Hans/documentation/cessoes/criacao_de_cessao_0eaeffec-ee95-4cb1-a266-bcb52f23237d)
- 托管账户开户（个人） (/zh-Hans/documentation/contas/abertura_de_conta_escrow/abertura_de_conta_escrow_pf)
- 托管账户开户（法人） (/zh-Hans/documentation/contas/abertura_de_conta_escrow/abertura_de_conta_escrow_pj)
- 简介 (/zh-Hans/documentation/contas/abertura_de_conta_escrow/introducao)
- 个人账户开户 (/zh-Hans/documentation/contas/abertura_de_conta/abertura_de_conta_pf)
- 法人账户开户 (/zh-Hans/documentation/contas/abertura_de_conta/abertura_de_conta_pj)
- 自由活动账户草稿 - 法人 (/zh-Hans/documentation/contas/abertura_de_conta/draft_checking_legal_person)
- fluxo_de_abertura_de_conta (/zh-Hans/documentation/contas/abertura_de_conta/fluxo_de_abertura_de_conta)
- 简介 (/zh-Hans/documentation/contas/abertura_de_conta/introducao)
- 开户 Webhooks (/zh-Hans/documentation/contas/abertura_de_conta/webhooks_contas)
- 开具银行关系证明函 (/zh-Hans/documentation/contas/carta_bancaria)
- 开具审计询证函 (/zh-Hans/documentation/contas/carta_circularizacao)
- 查询费率 (/zh-Hans/documentation/contas/consulta_de_tarifas)
- 查询账户 (/zh-Hans/documentation/contas/consultar_conta)
- 列出账户 (/zh-Hans/documentation/contas/consultar_contas)
- 查询开户请求详情 (/zh-Hans/documentation/contas/consultar_detalhes_pedido_conta)
- 账户注销 (/zh-Hans/documentation/contas/encerramento_de_conta)
- 费率对账单 (/zh-Hans/documentation/contas/extrato_de_tarifas)
- 费率管理 (/zh-Hans/documentation/contas/gestao_de_tarifas)
- 收益报告 (/zh-Hans/documentation/contas/informe_rendimentos)
- 查询账户冻结记录 (/zh-Hans/documentation/contas/ordens_de_bloqueio)
- 场景模拟 (/zh-Hans/documentation/contas/simulacao)
- 为 Escrow 账户创建目标账户 (/zh-Hans/documentation/d88ff174-100d-4b55-80b7-86e11f508400)
- 在 DDA 中注册账户 (/zh-Hans/documentation/dda/cadastro_dda)
- 从 DDA 中移除账户 (/zh-Hans/documentation/dda/cancelamento_dda)
- 查询 DDA 中注册的账户 (/zh-Hans/documentation/dda/consultar_dados_conta)
- Erros retornados na api (/zh-Hans/documentation/dda/erros)
- 介绍 (/zh-Hans/documentation/dda/introducao)
- 列出 DDA 中注册的账户 (/zh-Hans/documentation/dda/lista_contas_cadastradas)
- 带过滤条件的 DDA 银行票据通知列表 (/zh-Hans/documentation/dda/lista_notificacoes_de_boletos)
- 获取 DDA 注册的接受和取消条款 (/zh-Hans/documentation/dda/recuperacao_termo)
- 模拟银行票据注册和修改场景 (/zh-Hans/documentation/dda/simulacoes)
- Webhook 格式 (/zh-Hans/documentation/dda/webhooks)
- acg1 (/zh-Hans/documentation/documentacoes ocultas/agc1/acg1)
- introducao (/zh-Hans/documentation/documentacoes ocultas/agc1/introducao)
- 权限（通用）： (/zh-Hans/documentation/documentacoes ocultas/perfis_de_acesso)
- cancelamento_de_solicitacao.md (/zh-Hans/documentation/documentacoes ocultas/scr/cancelamento_de_solicitacao.md)
- consultar_solicitacao (/zh-Hans/documentation/documentacoes ocultas/scr/consultar_solicitacao)
- consultar_solicitacoes (/zh-Hans/documentation/documentacoes ocultas/scr/consultar_solicitacoes)
- introducao (/zh-Hans/documentation/documentacoes ocultas/scr/introducao)
- refazer_consulta (/zh-Hans/documentation/documentacoes ocultas/scr/refazer_consulta)
- solicitacao_de_consulta (/zh-Hans/documentation/documentacoes ocultas/scr/solicitacao_de_consulta)
- webhook (/zh-Hans/documentation/documentacoes ocultas/scr/webhook)
- 更新信贷合同受让方 (/zh-Hans/documentation/emissao_de_divida/atualizar_cessionario_047911bb-d3fb-48fe-88fd-aebdeb7e11ad)
- 更新信贷合同关联方信息 (/zh-Hans/documentation/emissao_de_divida/atualizar_dados_da_parte_relacionada)
- 授权放款 (/zh-Hans/documentation/emissao_de_divida/autorizar_desembolso)
- 放款前取消债务 (/zh-Hans/documentation/emissao_de_divida/cancelamento/cancelar_divida_antes_de_desembolsar)
- 永久取消 (/zh-Hans/documentation/emissao_de_divida/cancelamento/cancelar_permanentemente)
- 放款后七天内取消债务 (/zh-Hans/documentation/emissao_de_divida/cancelamento/desistencia/cancelamento_de_divida_em_ate_sete_dias_apos_o_desembolso)
- 查询退款 pix qr code (/zh-Hans/documentation/emissao_de_divida/cancelamento/desistencia/consulta_de_pix_qr_code_de_devolucao)
- 简介 (/zh-Hans/documentation/emissao_de_divida/cancelamento/desistencia/introducao)
- 简介 (/zh-Hans/documentation/emissao_de_divida/cancelamento/introducao)
- Catálogo de Erros - Lending-as-a-Service (/zh-Hans/documentation/emissao_de_divida/catalogo_de_erros_laas)
- 配置放款日期 (/zh-Hans/documentation/emissao_de_divida/configurar_data_de_desembolso)
- 债务查询 (/zh-Hans/documentation/emissao_de_divida/consulta_de_divida)
- 按合同编号查询债务 (/zh-Hans/documentation/emissao_de_divida/consulta_por_contract_number)
- 按信贷操作密钥查询债务 (/zh-Hans/documentation/emissao_de_divida/consulta_por_credit_operation_key)
- 按请求标识符密钥查询债务 (/zh-Hans/documentation/emissao_de_divida/consulta_por_requester_identifier_key)
- 操作放款 (/zh-Hans/documentation/emissao_de_divida/desembolso_da_operacao)
- 个人债务发行 (/zh-Hans/documentation/emissao_de_divida/emissao/emissao_de_divida_pf)
- 企业债务发行 (/zh-Hans/documentation/emissao_de_divida/emissao/emissao_de_divida_pj)
- 放款 Payload 示例 (/zh-Hans/documentation/emissao_de_divida/emissao/exemplo_payloads_desembolso)
- 替代签署方式 (/zh-Hans/documentation/emissao_de_divida/formalizacao/assinatura_de_contrato)
- 通过 OPT-IN 签署合同 (/zh-Hans/documentation/emissao_de_divida/formalizacao/assinatura_opt_in)
- 发送已签署 PDF (/zh-Hans/documentation/emissao_de_divida/formalizacao/assinatura_pdf)
- 通过自拍签署合同 (/zh-Hans/documentation/emissao_de_divida/formalizacao/assinatura_selfie)
- 合同签署 (/zh-Hans/documentation/emissao_de_divida/formalizacao/introducao_formalizacao)
- 为分期付款生成 Boleto 或 PIX (/zh-Hans/documentation/emissao_de_divida/gerar_boleto_ou_pix_para_uma_parcela)
- 简介 (/zh-Hans/documentation/emissao_de_divida/introducao)
- 银行代理人监控 (/zh-Hans/documentation/emissao_de_divida/mcb)
- Metadata (/zh-Hans/documentation/emissao_de_divida/metadata)
- 请勿打扰 (/zh-Hans/documentation/emissao_de_divida/nao_me_perturbe)
- 简介 (/zh-Hans/documentation/emissao_de_divida/reapresentacao_de_conta_bancaria)
- 重新发送信贷合同关联方文件 (/zh-Hans/documentation/emissao_de_divida/reenviar_documentos_das_partes_relacionadas)
- 放款后操作 (/zh-Hans/documentation/emissao_de_divida/reprocessar_acao_pos_desembolso)
- 重新计算信贷合同 (/zh-Hans/documentation/emissao_de_divida/reprocessar_contrato)
- 更改放款数据 (/zh-Hans/documentation/emissao_de_divida/reprocessar_multiplas_datas/trocar_conta)
- 更改放款日期 (/zh-Hans/documentation/emissao_de_divida/reprocessar_multiplas_datas/trocar_data)
- 保险 (/zh-Hans/documentation/emissao_de_divida/seguro)
- 债务模拟（旧版） (/zh-Hans/documentation/emissao_de_divida/simulacao_de_divida_antigo)
- 债务模拟（新版） (/zh-Hans/documentation/emissao_de_divida/simulacao_de_divida_novo)
- 在沙盒中模拟错误 (/zh-Hans/documentation/emissao_de_divida/simulando_erros)
- 债务的可能状态 (/zh-Hans/documentation/emissao_de_divida/status_de_uma_divida)
- 错误目录 (/zh-Hans/documentation/erros/catalogo_de_erros)
- Amortização Extraordinária (/zh-Hans/documentation/escrituracao/amortizacao-extraordinaria/conceito)
- Consultar Amortização Extraordinária (/zh-Hans/documentation/escrituracao/amortizacao-extraordinaria/endpoints/consultar-amortizacao)
- Criar Amortização Extraordinária (/zh-Hans/documentation/escrituracao/amortizacao-extraordinaria/endpoints/criar-amortizacao)
- 模拟特别摊销现值 (/zh-Hans/documentation/escrituracao/amortizacao-extraordinaria/endpoints/simular-valor-presente)
- Exemplos — Amortização Extraordinária (/zh-Hans/documentation/escrituracao/amortizacao-extraordinaria/exemplos)
- Amortização com Recompra (/zh-Hans/documentation/escrituracao/amortizacao-extraordinaria/recompra-de-operacao)
- Regras de Negócio — Amortização Extraordinária (/zh-Hans/documentation/escrituracao/amortizacao-extraordinaria/regras-de-negocio)
- 错误目录 (/zh-Hans/documentation/escrituracao/catalogo-erros/catalogo-erros)
- Webhook 配置 (/zh-Hans/documentation/escrituracao/configuracao-webhooks)
- 登记基础资产（Lastro） (/zh-Hans/documentation/escrituracao/emissao-cr/cadastro-lastro)
- 登记CR操作 (/zh-Hans/documentation/escrituracao/emissao-cr/cadastro-operacao)
- 提交文件 (/zh-Hans/documentation/escrituracao/emissao-cr/envio-documento)
- 提交操作的外部文件 (/zh-Hans/documentation/escrituracao/emissao-cr/envio-documento-externo)
- 登记基础资产（Lastro） (/zh-Hans/documentation/escrituracao/emissao-cra/cadastro-lastro)
- 登记CRA操作 (/zh-Hans/documentation/escrituracao/emissao-cra/cadastro-operacao)
- 提交文件 (/zh-Hans/documentation/escrituracao/emissao-cra/envio-documento)
- 提交操作的外部文件 (/zh-Hans/documentation/escrituracao/emissao-cra/envio-documento-externo)
- 登记基础资产（Lastro） (/zh-Hans/documentation/escrituracao/emissao-cri/cadastro-lastro)
- 登记CRI操作 (/zh-Hans/documentation/escrituracao/emissao-cri/cadastro-operacao)
- 提交文件 (/zh-Hans/documentation/escrituracao/emissao-cri/envio-documento)
- 提交操作的外部文件 (/zh-Hans/documentation/escrituracao/emissao-cri/envio-documento-externo)
- 更新操作的拨付账户 (/zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-conta-desembolso)
- 更新操作的财务数据 (/zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-dados-financeiros)
- 更新操作中的投资人数据 (/zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-investidores)
- 更新操作的签名方式 (/zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-metodo-assinatura)
- 在操作中添加担保品 (/zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/cadastro-garantia)
- 从操作中移除担保品 (/zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/remover-garantia)
- 文件上传 (/zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/upload-documento)
- 在操作中登记和删除元数据 (/zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-metadata-identificacao)
- 发送和删除关联方代表的文件 (/zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-documento)
- 发送和删除关联方代表的签名人组 (/zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-grupo-assinantes)
- 在特定文件中登记和删除关联方 (/zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-parte-relacionada-em-documento)
- 登记和删除关联方 (/zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/cadastrar-parte-relacionada)
- 登记商业票据操作 (/zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/criar-operacao)
- Campos Extras (Extra Fields) (/zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/extra-fields)
- 取消操作 (/zh-Hans/documentation/escrituracao/emissao-de-notas/cancelar-operacao)
- 查询通过 QI SIGN 签署的操作合同链接 (/zh-Hans/documentation/escrituracao/emissao-de-notas/consulta-link-assinado-qisign)
- 查询通过 QI SIGN 签署操作的链接 (/zh-Hans/documentation/escrituracao/emissao-de-notas/consulta-link-assinatura-qisign)
- 通过键查询操作 (/zh-Hans/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-chave)
- 通过筛选条件查询操作 (/zh-Hans/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-filtros)
- Consulta do Próximo Número de Emissão por Emissor (/zh-Hans/documentation/escrituracao/emissao-de-notas/consulta/consulta-proximo-numero-emissao)
- 提交已签署的批准会议纪要 (/zh-Hans/documentation/escrituracao/emissao-de-notas/envio-ata-aprovacao)
- 提交操作的已签署合同 (/zh-Hans/documentation/escrituracao/emissao-de-notas/envio-contratos-assinados)
- 将操作提交分析 (/zh-Hans/documentation/escrituracao/emissao-de-notas/envio-para-analise)
- 将操作提交签名 (/zh-Hans/documentation/escrituracao/emissao-de-notas/envio-para-assinatura)
- 更改加入条款模板 (/zh-Hans/documentation/escrituracao/emissao-de-notas/geracao-minutas/alterar-template-ta)
- 更改组成性条款模板 (/zh-Hans/documentation/escrituracao/emissao-de-notas/geracao-minutas/alterar-template-tc)
- 查询可用模板 (/zh-Hans/documentation/escrituracao/emissao-de-notas/geracao-minutas/consulta-minutas-disponiveis)
- 预览加入条款 (/zh-Hans/documentation/escrituracao/emissao-de-notas/geracao-minutas/gerar-minuta-adesao)
- 预览组成性条款 (/zh-Hans/documentation/escrituracao/emissao-de-notas/geracao-minutas/gerar-minuta-contrato)
- 商业票据发行介绍 (/zh-Hans/documentation/escrituracao/emissao-de-notas/inicio)
- 财务条件模拟 (/zh-Hans/documentation/escrituracao/emissao-de-notas/simulacao)
- 登记债券操作 (/zh-Hans/documentation/escrituracao/emissao-debentures/cadastro-operacao)
- 提交文件 (/zh-Hans/documentation/escrituracao/emissao-debentures/envio-documento)
- 提交操作的外部文件 (/zh-Hans/documentation/escrituracao/emissao-debentures/envio-documento-externo)
- 提交操作担保 (/zh-Hans/documentation/escrituracao/emissao-debentures/envio-garantia)
- 更新发行人登记 (/zh-Hans/documentation/escrituracao/homologacao-emissor/alteracao-cadastro/)
- 登记发行人签名人组 (/zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor)
- 删除发行人签名人组 (/zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor-remocao)
- 发行人基本登记 (/zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/cadastro-basico)
- 登记发行人银行账户 (/zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor)
- Definição de Conta Bancária Principal do Emissor (/zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor-principal)
- 删除发行人银行账户 (/zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor-remocao)
- 提交发行人文件 (/zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor)
- 删除发行人文件 (/zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor-remocao)
- 提交发行人代表文件 (/zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor)
- 删除发行人代表文件 (/zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor-remocao)
- 登记发行人联系信息 (/zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor)
- Definição de Contato Principal do Emissor (/zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor-principal)
- 删除发行人联系信息 (/zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor-remocao)
- 登记发行人代表 (/zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor)
- 删除发行人代表 (/zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor-remocao)
- 查询发行人 (/zh-Hans/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-chave)
- 按过滤条件查询发行人 (/zh-Hans/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-filtro)
- 提交发行人分析 (/zh-Hans/documentation/escrituracao/homologacao-emissor/envio-analise/)
- 介绍 (/zh-Hans/documentation/escrituracao/homologacao-emissor/inicio)
- 申请访问发行人数据 (/zh-Hans/documentation/escrituracao/homologacao-emissor/solicitacao-acesso)
- 更新投资人登记 (/zh-Hans/documentation/escrituracao/homologacao-investidor/alteracao-cadastro/)
- 登记投资人签名人组 (/zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/assinantes-investidor)
- 删除投资人签名人组 (/zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/assinantes-investidor-remocao)
- 投资人基本登记 (/zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/cadastro-basico)
- 登记投资人银行账户 (/zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/conta-bancaria-investidor)
- 删除投资人银行账户 (/zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/conta-bancaria-investidor-remocao)
- 提交投资人文件 (/zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/documentos-investidor)
- 删除投资人文件 (/zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/documentos-investidor-remocao)
- 上传投资者代表文件 (/zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/documentos-representantes-investidor)
- 删除投资者代表文件 (/zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/documentos-representantes-investidor-remocao)
- 注册投资者联系信息 (/zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/informacao-contato-investidor)
- 删除投资者联系信息 (/zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/informacao-contato-investidor-remocao)
- 登记投资人代表 (/zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/representantes-investidor)
- 删除投资人代表 (/zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/representantes-investidor-remocao)
- 查询投资人 (/zh-Hans/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-chave)
- 按过滤条件查询投资人 (/zh-Hans/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-filtro)
- 提交投资人分析 (/zh-Hans/documentation/escrituracao/homologacao-investidor/envio-analise/)
- 介绍 (/zh-Hans/documentation/escrituracao/homologacao-investidor/inicio)
- **申请访问投资人数据** (/zh-Hans/documentation/escrituracao/homologacao-investidor/solicitacao-acesso)
- 查询交易凭证 (/zh-Hans/documentation/escrituracao/integralizacao-cotas/consulta-comprovante-transacao)
- Consulta de Conta de Liquidação (/zh-Hans/documentation/escrituracao/integralizacao-cotas/consulta-conta-liquidacao)
- 按键查询认缴 (/zh-Hans/documentation/escrituracao/integralizacao-cotas/consulta-processo-integralizacao)
- 查询认缴交易列表 (/zh-Hans/documentation/escrituracao/integralizacao-cotas/consulta-transacoes-integralizacao)
- 股份认缴介绍 (/zh-Hans/documentation/escrituracao/integralizacao-cotas/inicio)
- 登记认购 (/zh-Hans/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/cadastro-subscricao)
- 取消认购 (/zh-Hans/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/cancelar-subscricao)
- 确认或拒绝认购付款 (/zh-Hans/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/confirmacao-pagamento)
- 查询认购 (/zh-Hans/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/consulta-subscricao-cotas)
- 登记认购付款 (/zh-Hans/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/registro-de-pagamento)
- 接收 Webhooks (/zh-Hans/documentation/escrituracao/introducao/autenticacao_webhooks)
- 商业票据书写 (/zh-Hans/documentation/escrituracao/introducao/)
- 测试端点 (/zh-Hans/documentation/escrituracao/introducao/teste-autenticacao/endpoints_de_teste)
- 认证测试 (/zh-Hans/documentation/escrituracao/introducao/teste-autenticacao/teste_de_autenticacao)
- 密钥交换 (/zh-Hans/documentation/escrituracao/introducao/troca_de_chaves)
- 查询资产 (/zh-Hans/documentation/escrituracao/operacoes-ativas/consulta-security)
- 查询投资人持仓 (/zh-Hans/documentation/escrituracao/operacoes-ativas/posicao-investidor)
- 商业票据书写集成路线图 (/zh-Hans/documentation/escrituracao/roteiro-integracao/roteiro-integracao-padrao)
- Roteiro de Integração de escrituração de notas comerciais (/zh-Hans/documentation/escrituracao/roteiro-integracao/roteiro-integracao-padrao-external)
- Roteiro de Integração de escrituração de notas comerciais + Boletos + Sistema de baixas (/zh-Hans/documentation/escrituracao/roteiro-integracao/roteiro-integracao-securities-baas-dtvm)
- 书写 Webhooks (/zh-Hans/documentation/escrituracao/webhooks-escrituracao)
- Aprovação de Reserva (/zh-Hans/documentation/garantia_veicular/aprovacao_reserva)
- Cancelamento (/zh-Hans/documentation/garantia_veicular/cancelamento)
- Consultas (/zh-Hans/documentation/garantia_veicular/consultas)
- Mapa de Status e Etapas (/zh-Hans/documentation/garantia_veicular/mapa_de_status)
- Simulação e Emissão (/zh-Hans/documentation/garantia_veicular/simulacao_e_emissao)
- Mocks (Sandbox) (/zh-Hans/documentation/garantia_veicular/testes_homologacao)
- Webhooks — Garantia Veicular (/zh-Hans/documentation/garantia_veicular/webhooks)
- 修改人员联系方式 (/zh-Hans/documentation/gestao_de_usuarios/alteracao_de_contato_de_pessoa)
- 修改关联联系方式 (/zh-Hans/documentation/gestao_de_usuarios/alteracao_de_contato_de_vinculo)
- 修改个人数据 (/zh-Hans/documentation/gestao_de_usuarios/alteracao_de_dados_pessoais)
- 修改地址 (/zh-Hans/documentation/gestao_de_usuarios/alteracao_de_endereco)
- 查询关联方 (/zh-Hans/documentation/gestao_de_usuarios/consulta_partes_relacionadas)
- 创建人员 (/zh-Hans/documentation/gestao_de_usuarios/criacao_de_pessoa)
- 删除关联 (/zh-Hans/documentation/gestao_de_usuarios/exclusao_de_vinculo)
- 添加关联 (/zh-Hans/documentation/gestao_de_usuarios/inclusao_de_vinculo)
- 双因素授权（TFA）简介 (/zh-Hans/documentation/gestao_de_usuarios/tfa_introducao)
- Consulta Offline de Saldo (/zh-Hans/documentation/guides/INSS/inquiries/offline-balance-request)
- INSS 工资贷款 (/zh-Hans/documentation/guides/INSS/intro)
- Mocks (Sandbox) (/zh-Hans/documentation/guides/INSS/mocks-sandbox)
- INSS 手册 - 新增信贷或再融资 (/zh-Hans/documentation/guides/INSS/new-credit-and-refinancing/end-to-end)
- 重新计算信贷操作 (/zh-Hans/documentation/guides/INSS/new-credit-and-refinancing/recalculate)
- Anuência (pending confirmation) (/zh-Hans/documentation/guides/INSS/pending_confirmation)
- Alterando o Cessionário (/zh-Hans/documentation/guides/INSS/portability+refinancing/alterando-cessionario)
- Consultas e Enumeradores (/zh-Hans/documentation/guides/INSS/portability+refinancing/consultas-e-enumeradores)
- INSS 贷款转移 + 再融资手册 (/zh-Hans/documentation/guides/INSS/portability+refinancing/end-to-end)
- Máquinas de Status (/zh-Hans/documentation/guides/INSS/portability+refinancing/maquinas-de-status)
- Recálculo e Reformalização do Refinanciamento (/zh-Hans/documentation/guides/INSS/portability+refinancing/reformalization)
- Fura-fila (priority request) (/zh-Hans/documentation/guides/INSS/reservations/priority-request)
- Fila prioritária (/zh-Hans/documentation/guides/INSS/reservations/priority-reservation)
- Assinatura em grupo (INSS) (/zh-Hans/documentation/guides/INSS/signatures/batch-group-signature)
- Assinatura em lote (INSS) (/zh-Hans/documentation/guides/INSS/signatures/batch-signature)
- 插入文档 (/zh-Hans/documentation/iaas/aditamento_recebiveis/envio_documento)
- 简介 (/zh-Hans/documentation/iaas/aditamento_recebiveis/inicio)
- 创建补充协议申请 (/zh-Hans/documentation/iaas/aditamento_recebiveis/pedido_aditamento_contrato)
- 公共债券交易单 (/zh-Hans/documentation/iaas/boletador/boletador_titulos_publicos)
- 公共债券列表 (/zh-Hans/documentation/iaas/boletador/listagem_titulos_publicos)
- 简介 (/zh-Hans/documentation/iaas/boletos/inicio)
- Instruções de Boleto (/zh-Hans/documentation/iaas/boletos/instrucoes_boleto)
- 获取 CNAB 文件 (/zh-Hans/documentation/iaas/boletos/recuperar_arquivo_retorno)
- Recuperação de Boleto e Segunda via (/zh-Hans/documentation/iaas/boletos/recuperar_boleto)
- 获取银行划账单 (/zh-Hans/documentation/iaas/boletos/recuperar_boletos)
- 获取 Boleto 档案 (/zh-Hans/documentation/iaas/boletos/recuperar_carteiras_cobranca)
- 获取 Boleto 配置 (/zh-Hans/documentation/iaas/boletos/recuperar_configuracoes_boleto)
- Webhooks (/zh-Hans/documentation/iaas/boletos/webhook)
- 投资组合 - 审批 (/zh-Hans/documentation/iaas/composicao_carteira/aprovar_carteira)
- 投资组合 - 下载 (/zh-Hans/documentation/iaas/composicao_carteira/baixar_carteira)
- 简介 (/zh-Hans/documentation/iaas/composicao_carteira/inicio)
- 投资组合 - 获取 (/zh-Hans/documentation/iaas/composicao_carteira/recuperar_carteira)
- 按基金类别查询金融申购 (/zh-Hans/documentation/iaas/cotas_de_fundo/consulta_paginada_aplicacoes_financeiras)
- 按基金类别查询赎回 (/zh-Hans/documentation/iaas/cotas_de_fundo/consulta_paginada_resgates)
- 查询发行系列 (/zh-Hans/documentation/iaas/cotas_de_fundo/consulta_paginada_series_de_emissao)
- 简介 (/zh-Hans/documentation/iaas/cotas_de_fundo/inicio)
- 创建金融申购 (/zh-Hans/documentation/iaas/cotas_de_fundo/operacao_aplicacoes_financeiras)
- 创建赎回申请 (/zh-Hans/documentation/iaas/cotas_de_fundo/operacao_resgates)
- Consulta de despesas consolidadas (/zh-Hans/documentation/iaas/despesas/despesa_consolidada/consulta_despesas)
- Atualização do Contrato (/zh-Hans/documentation/iaas/despesas/submissao_despesa/contrato/atualizacao)
- Cancelamento do Contrato (/zh-Hans/documentation/iaas/despesas/submissao_despesa/contrato/cancelamento)
- Criação do Contrato (/zh-Hans/documentation/iaas/despesas/submissao_despesa/contrato/criacao)
- Listagem de Contratos (/zh-Hans/documentation/iaas/despesas/submissao_despesa/contrato/listagem)
- Consulta de Contrato (/zh-Hans/documentation/iaas/despesas/submissao_despesa/contrato/recuperacao)
- Submissão do Contrato (/zh-Hans/documentation/iaas/despesas/submissao_despesa/contrato/submissao)
- Atualização da Despesa (/zh-Hans/documentation/iaas/despesas/submissao_despesa/despesa/atualizacao)
- Cancelamento da Despesa (/zh-Hans/documentation/iaas/despesas/submissao_despesa/despesa/cancelamento)
- Criação da Despesa (/zh-Hans/documentation/iaas/despesas/submissao_despesa/despesa/criacao)
- Listagem de Despesas (/zh-Hans/documentation/iaas/despesas/submissao_despesa/despesa/listagem)
- Consulta de Despesa (/zh-Hans/documentation/iaas/despesas/submissao_despesa/despesa/recuperacao)
- Submissão da Despesa (/zh-Hans/documentation/iaas/despesas/submissao_despesa/despesa/submissao)
- Listagem de Documentos (/zh-Hans/documentation/iaas/despesas/submissao_despesa/documentos/listagem)
- Upload de Documentos (/zh-Hans/documentation/iaas/despesas/submissao_despesa/documentos/upload)
- Fluxo de submissão de despesas (/zh-Hans/documentation/iaas/despesas/submissao_despesa/fluxo_despesas)
- Anotações da Análise (/zh-Hans/documentation/iaas/despesas/submissao_despesa/fornecedor/anotacoes)
- Atualização de Dados da Análise (/zh-Hans/documentation/iaas/despesas/submissao_despesa/fornecedor/atualizacao)
- Cancelamento da Análise (/zh-Hans/documentation/iaas/despesas/submissao_despesa/fornecedor/cancelamento)
- Cadastro de Fornecedor (/zh-Hans/documentation/iaas/despesas/submissao_despesa/fornecedor/criacao)
- Documentos da Análise (/zh-Hans/documentation/iaas/despesas/submissao_despesa/fornecedor/documentos)
- Consulta de Fornecedores e Análises (/zh-Hans/documentation/iaas/despesas/submissao_despesa/fornecedor/listagem)
- Submissão para Análise (/zh-Hans/documentation/iaas/despesas/submissao_despesa/fornecedor/submissao)
- Submissão de Despesas (/zh-Hans/documentation/iaas/despesas/submissao_despesa/inicio)
- 发行 - 整合认购 (/zh-Hans/documentation/iaas/emissoes/cadastrar_boleta)
- 资产注册 - 发行 (/zh-Hans/documentation/iaas/emissoes/cadastro_ativo)
- 发行确认 (/zh-Hans/documentation/iaas/emissoes/confirmacao_emissao)
- 简介 (/zh-Hans/documentation/iaas/emissoes/inicio)
- Apontamentos de Compliance (/zh-Hans/documentation/iaas/homologacao_cedente/cadastro/apontamentos)
- 注册更新 (/zh-Hans/documentation/iaas/homologacao_cedente/cadastro/atualizacao_de_cadastro)
- Definição de Assinantes (/zh-Hans/documentation/iaas/homologacao_cedente/cadastro/definicao_de_assinantes)
- 提交审查 (/zh-Hans/documentation/iaas/homologacao_cedente/cadastro/disparo_da_analise)
- 提交注册 (/zh-Hans/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro)
- 文件提交 (/zh-Hans/documentation/iaas/homologacao_cedente/cadastro/envio_de_documentos)
- 分支机构注册 (/zh-Hans/documentation/iaas/homologacao_cedente/cadastro/filiais)
- 转让方账户 (/zh-Hans/documentation/iaas/homologacao_cedente/cadastro/manutencao_de_contas)
- Webhooks (/zh-Hans/documentation/iaas/homologacao_cedente/cadastro/webhooks_analise)
- 审查查询 (/zh-Hans/documentation/iaas/homologacao_cedente/consulta/consulta_de_analise)
- 转让方查询 (/zh-Hans/documentation/iaas/homologacao_cedente/consulta/consulta_de_cedente)
- 查询文件 (/zh-Hans/documentation/iaas/homologacao_cedente/contrato_de_cessao/consulta_de_documentos)
- 合同管理 (/zh-Hans/documentation/iaas/homologacao_cedente/contrato_de_cessao/manutencao_do_contrato)
- 转让合同 (/zh-Hans/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato)
- 获取合同 (/zh-Hans/documentation/iaas/homologacao_cedente/contrato_de_cessao/recuperacao_de_contrato)
- 合同 Webhooks (/zh-Hans/documentation/iaas/homologacao_cedente/contrato_de_cessao/webhooks_contrato)
- 简介 (/zh-Hans/documentation/iaas/homologacao_cedente/inicio)
- SFTP 集成 (/zh-Hans/documentation/iaas/integracao_sftp/inicio)
- Webhook 接收 (/zh-Hans/documentation/iaas/introducao/autenticacao_webhooks)
- 简介 (/zh-Hans/documentation/iaas/introducao/inicio)
- 端点包 (/zh-Hans/documentation/iaas/introducao/pacote_endpoints)
- 测试端点 (/zh-Hans/documentation/iaas/introducao/teste_de_autenticacao/endpoints_de_teste)
- 认证测试 (/zh-Hans/documentation/iaas/introducao/teste_de_autenticacao/)
- 密钥交换 (/zh-Hans/documentation/iaas/introducao/troca_de_chaves)
- Início (/zh-Hans/documentation/iaas/investidor/cadastro_investidor/inicio)
- atualizacao_cadastral (/zh-Hans/documentation/iaas/investidor/cadastro/atualizacao_cadastral)
- atualizar_status_grupo_assinantes (/zh-Hans/documentation/iaas/investidor/cadastro/atualizar_status_grupo_assinantes)
- busca_informacoes_de_uma_analise_cadastral_do_investidor (/zh-Hans/documentation/iaas/investidor/cadastro/busca_informacoes_de_uma_analise_cadastral_do_investidor)
- busca_informacoes_do_investidor (/zh-Hans/documentation/iaas/investidor/cadastro/busca_informacoes_do_investidor)
- buscar_documentos_para_assinatura (/zh-Hans/documentation/iaas/investidor/cadastro/buscar_documentos_para_assinatura)
- 分页查询投资者数据 (/zh-Hans/documentation/iaas/investidor/cadastro/buscar_investidores_paginado)
- consultar_analise_em_andamento (/zh-Hans/documentation/iaas/investidor/cadastro/consultar_analise_em_andamento)
- atualizar_status_conta_bancaria (/zh-Hans/documentation/iaas/investidor/cadastro/contas_bancarias/atualizar_status_conta_bancaria)
- definir_conta_principal (/zh-Hans/documentation/iaas/investidor/cadastro/contas_bancarias/definir_conta_principal)
- enviar_contas_bancarias (/zh-Hans/documentation/iaas/investidor/cadastro/contas_bancarias/enviar_contas_bancarias)
- 创建投资者/投资者分析 (/zh-Hans/documentation/iaas/investidor/cadastro/criar_investidor)
- definir_grupo_assinantes_padrao (/zh-Hans/documentation/iaas/investidor/cadastro/definir_grupo_assinantes_padrao)
- enviar_cadastro_para_analise (/zh-Hans/documentation/iaas/investidor/cadastro/enviar_cadastro_para_analise)
- enviar_dados_cadastrais (/zh-Hans/documentation/iaas/investidor/cadastro/enviar_dados_cadastrais)
- enviar_endereco (/zh-Hans/documentation/iaas/investidor/cadastro/enviar_endereco)
- enviar_grupos_assinantes (/zh-Hans/documentation/iaas/investidor/cadastro/enviar_grupos_assinantes)
- enviar_investor_document (/zh-Hans/documentation/iaas/investidor/cadastro/enviar_investor_document)
- enviar_patrimonio (/zh-Hans/documentation/iaas/investidor/cadastro/enviar_patrimonio)
- consultar_feedback (/zh-Hans/documentation/iaas/investidor/cadastro/feedback/consultar_feedback)
- enviar_mensagem_feedback (/zh-Hans/documentation/iaas/investidor/cadastro/feedback/enviar_mensagem_feedback)
- listar_feedbacks (/zh-Hans/documentation/iaas/investidor/cadastro/feedback/listar_feedbacks)
- Introdução (/zh-Hans/documentation/iaas/investidor/cadastro/introducao)
- criar_parte_relacionada (/zh-Hans/documentation/iaas/investidor/cadastro/related_party/criar_parte_relacionada)
- enviar_documento_parte_relacionada (/zh-Hans/documentation/iaas/investidor/cadastro/related_party/enviar_documento_parte_relacionada)
- consultar_formulario_suitability (/zh-Hans/documentation/iaas/investidor/cadastro/suitability/consultar_formulario_suitability)
- enviar_suitability (/zh-Hans/documentation/iaas/investidor/cadastro/suitability/enviar_suitability)
- atualizacao_cadastral (/zh-Hans/documentation/iaas/investidor/carteira_administrada/atualizacao_cadastral)
- atualizar_status_grupo_assinantes (/zh-Hans/documentation/iaas/investidor/carteira_administrada/atualizar_status_grupo_assinantes)
- busca_informacoes_de_uma_analise_cadastral_do_investidor (/zh-Hans/documentation/iaas/investidor/carteira_administrada/busca_informacoes_de_uma_analise_cadastral_do_investidor)
- busca_informacoes_do_investidor (/zh-Hans/documentation/iaas/investidor/carteira_administrada/busca_informacoes_do_investidor)
- buscar_documentos_para_assinatura (/zh-Hans/documentation/iaas/investidor/carteira_administrada/buscar_documentos_para_assinatura)
- consultar_analise_em_andamento (/zh-Hans/documentation/iaas/investidor/carteira_administrada/consultar_analise_em_andamento)
- atualizar_status_conta_bancaria (/zh-Hans/documentation/iaas/investidor/carteira_administrada/contas_bancarias/atualizar_status_conta_bancaria)
- definir_conta_principal (/zh-Hans/documentation/iaas/investidor/carteira_administrada/contas_bancarias/definir_conta_principal)
- enviar_contas_bancarias (/zh-Hans/documentation/iaas/investidor/carteira_administrada/contas_bancarias/enviar_contas_bancarias)
- 创建投资者/投资者分析 (/zh-Hans/documentation/iaas/investidor/carteira_administrada/criar_investidor)
- definir_grupo_assinantes_padrao (/zh-Hans/documentation/iaas/investidor/carteira_administrada/definir_grupo_assinantes_padrao)
- enviar_cadastro_para_analise (/zh-Hans/documentation/iaas/investidor/carteira_administrada/enviar_cadastro_para_analise)
- enviar_dados_cadastrais (/zh-Hans/documentation/iaas/investidor/carteira_administrada/enviar_dados_cadastrais)
- enviar_endereco (/zh-Hans/documentation/iaas/investidor/carteira_administrada/enviar_endereco)
- enviar_grupos_assinantes (/zh-Hans/documentation/iaas/investidor/carteira_administrada/enviar_grupos_assinantes)
- enviar_investor_document (/zh-Hans/documentation/iaas/investidor/carteira_administrada/enviar_investor_document)
- enviar_patrimonio (/zh-Hans/documentation/iaas/investidor/carteira_administrada/enviar_patrimonio)
- consultar_feedback (/zh-Hans/documentation/iaas/investidor/carteira_administrada/feedback/consultar_feedback)
- enviar_mensagem_feedback (/zh-Hans/documentation/iaas/investidor/carteira_administrada/feedback/enviar_mensagem_feedback)
- listar_feedbacks (/zh-Hans/documentation/iaas/investidor/carteira_administrada/feedback/listar_feedbacks)
- Introdução (/zh-Hans/documentation/iaas/investidor/carteira_administrada/introducao)
- enviar_documento_investor_owner (/zh-Hans/documentation/iaas/investidor/carteira_administrada/investor_owner/enviar_documento_investor_owner)
- criar_parte_relacionada (/zh-Hans/documentation/iaas/investidor/carteira_administrada/related_party/criar_parte_relacionada)
- enviar_documento_parte_relacionada (/zh-Hans/documentation/iaas/investidor/carteira_administrada/related_party/enviar_documento_parte_relacionada)
- consultar_formulario_suitability (/zh-Hans/documentation/iaas/investidor/carteira_administrada/suitability/consultar_formulario_suitability)
- enviar_suitability (/zh-Hans/documentation/iaas/investidor/carteira_administrada/suitability/enviar_suitability)
- Assinar Documento (/zh-Hans/documentation/iaas/investidor/compartilhado/assinar_documento)
- Atualização Cadastral (/zh-Hans/documentation/iaas/investidor/compartilhado/atualizacao_cadastral)
- Atualizar Status do Grupo de Assinantes (/zh-Hans/documentation/iaas/investidor/compartilhado/atualizar_status_grupo_assinantes)
- 查询投资者信息 (/zh-Hans/documentation/iaas/investidor/compartilhado/busca_informacoes_de_uma_analise_cadastral_do_investidor)
- 查询投资者信息 (/zh-Hans/documentation/iaas/investidor/compartilhado/busca_informacoes_do_investidor)
- 发送已签署文件 (/zh-Hans/documentation/iaas/investidor/compartilhado/buscar_documentos_para_assinatura)
- Consultar Análise em Andamento (/zh-Hans/documentation/iaas/investidor/compartilhado/consultar_analise_em_andamento)
- 添加银行账户 (/zh-Hans/documentation/iaas/investidor/compartilhado/contas_bancarias/adicionar_contas_bancarias)
- 更新银行账户 (/zh-Hans/documentation/iaas/investidor/compartilhado/contas_bancarias/atualizar_conta_bancaria)
- Atualizar Status da Conta Bancária (/zh-Hans/documentation/iaas/investidor/compartilhado/contas_bancarias/atualizar_status_conta_bancaria)
- 查询银行账户 (/zh-Hans/documentation/iaas/investidor/compartilhado/contas_bancarias/buscar_contas_bancarias)
- Definir Conta Bancária Principal (/zh-Hans/documentation/iaas/investidor/compartilhado/contas_bancarias/definir_conta_principal)
- Enviar Conta Bancária do Investidor (/zh-Hans/documentation/iaas/investidor/compartilhado/contas_bancarias/enviar_contas_bancarias)
- Criar investidor (/zh-Hans/documentation/iaas/investidor/compartilhado/criar_investidor)
- Definir Grupo de Assinantes Padrão (/zh-Hans/documentation/iaas/investidor/compartilhado/definir_grupo_assinantes_padrao)
- 发送投资者注册进行分析 (/zh-Hans/documentation/iaas/investidor/compartilhado/enviar_cadastro_para_analise)
- 发送投资者注册数据 (/zh-Hans/documentation/iaas/investidor/compartilhado/enviar_dados_cadastrais)
- Enviar Documento Assinado (/zh-Hans/documentation/iaas/investidor/compartilhado/enviar_documento_assinado)
- 发送投资者注册数据 (/zh-Hans/documentation/iaas/investidor/compartilhado/enviar_endereco)
- Enviar Grupo de Assinantes (/zh-Hans/documentation/iaas/investidor/compartilhado/enviar_grupos_assinantes)
- Enviar Documento do Investidor (/zh-Hans/documentation/iaas/investidor/compartilhado/enviar_investor_document)
- Enviar Patrimônio do Investidor (/zh-Hans/documentation/iaas/investidor/compartilhado/enviar_patrimonio)
- Consultar Feedback (/zh-Hans/documentation/iaas/investidor/compartilhado/feedback/consultar_feedback)
- Enviar Mensagem em Feedback (/zh-Hans/documentation/iaas/investidor/compartilhado/feedback/enviar_mensagem_feedback)
- Listar Feedbacks (/zh-Hans/documentation/iaas/investidor/compartilhado/feedback/listar_feedbacks)
- Criar Investor Owner (/zh-Hans/documentation/iaas/investidor/compartilhado/investor_owner/criar_investor_owner)
- Enviar Documento de Investor Owner (/zh-Hans/documentation/iaas/investidor/compartilhado/investor_owner/enviar_documento_investor_owner)
- 创建关联方 (/zh-Hans/documentation/iaas/investidor/compartilhado/related_party/criar_parte_relacionada)
- 发送关联方文件 (/zh-Hans/documentation/iaas/investidor/compartilhado/related_party/enviar_documento_parte_relacionada)
- Consultar Formulário Suitability (/zh-Hans/documentation/iaas/investidor/compartilhado/suitability/consultar_formulario_suitability)
- Enviar Resposta Suitability (/zh-Hans/documentation/iaas/investidor/compartilhado/suitability/enviar_suitability)
- assinar_documento (/zh-Hans/documentation/iaas/investidor/distribuicao_externa/assinar_documento)
- atualizacao_cadastral (/zh-Hans/documentation/iaas/investidor/distribuicao_externa/atualizacao_cadastral)
- atualizar_status_grupo_assinantes (/zh-Hans/documentation/iaas/investidor/distribuicao_externa/atualizar_status_grupo_assinantes)
- busca_informacoes_de_uma_analise_cadastral_do_investidor (/zh-Hans/documentation/iaas/investidor/distribuicao_externa/busca_informacoes_de_uma_analise_cadastral_do_investidor)
- busca_informacoes_do_investidor (/zh-Hans/documentation/iaas/investidor/distribuicao_externa/busca_informacoes_do_investidor)
- buscar_documentos_para_assinatura (/zh-Hans/documentation/iaas/investidor/distribuicao_externa/buscar_documentos_para_assinatura)
- consultar_analise_em_andamento (/zh-Hans/documentation/iaas/investidor/distribuicao_externa/consultar_analise_em_andamento)
- atualizar_status_conta_bancaria (/zh-Hans/documentation/iaas/investidor/distribuicao_externa/contas_bancarias/atualizar_status_conta_bancaria)
- definir_conta_principal (/zh-Hans/documentation/iaas/investidor/distribuicao_externa/contas_bancarias/definir_conta_principal)
- enviar_contas_bancarias (/zh-Hans/documentation/iaas/investidor/distribuicao_externa/contas_bancarias/enviar_contas_bancarias)
- 创建投资者/投资者分析 (/zh-Hans/documentation/iaas/investidor/distribuicao_externa/criar_investidor)
- definir_grupo_assinantes_padrao (/zh-Hans/documentation/iaas/investidor/distribuicao_externa/definir_grupo_assinantes_padrao)
- enviar_cadastro_para_analise (/zh-Hans/documentation/iaas/investidor/distribuicao_externa/enviar_cadastro_para_analise)
- 发送投资者注册数据 (/zh-Hans/documentation/iaas/investidor/distribuicao_externa/enviar_dados_cadastrais)
- enviar_documento_assinado (/zh-Hans/documentation/iaas/investidor/distribuicao_externa/enviar_documento_assinado)
- enviar_endereco (/zh-Hans/documentation/iaas/investidor/distribuicao_externa/enviar_endereco)
- enviar_grupos_assinantes (/zh-Hans/documentation/iaas/investidor/distribuicao_externa/enviar_grupos_assinantes)
- 发送投资者文件 (/zh-Hans/documentation/iaas/investidor/distribuicao_externa/enviar_investor_document)
- enviar_patrimonio (/zh-Hans/documentation/iaas/investidor/distribuicao_externa/enviar_patrimonio)
- Enviar Resposta Suitability (/zh-Hans/documentation/iaas/investidor/distribuicao_externa/enviar_suitability)
- consultar_feedback (/zh-Hans/documentation/iaas/investidor/distribuicao_externa/feedback/consultar_feedback)
- enviar_mensagem_feedback (/zh-Hans/documentation/iaas/investidor/distribuicao_externa/feedback/enviar_mensagem_feedback)
- listar_feedbacks (/zh-Hans/documentation/iaas/investidor/distribuicao_externa/feedback/listar_feedbacks)
- Introdução (/zh-Hans/documentation/iaas/investidor/distribuicao_externa/introducao)
- criar_investor_owner (/zh-Hans/documentation/iaas/investidor/distribuicao_externa/investor_owner/criar_investor_owner)
- enviar_documento_investor_owner (/zh-Hans/documentation/iaas/investidor/distribuicao_externa/investor_owner/enviar_documento_investor_owner)
- criar_parte_relacionada (/zh-Hans/documentation/iaas/investidor/distribuicao_externa/related_party/criar_parte_relacionada)
- enviar_documento_parte_relacionada (/zh-Hans/documentation/iaas/investidor/distribuicao_externa/related_party/enviar_documento_parte_relacionada)
- atualizacao_cadastral (/zh-Hans/documentation/iaas/investidor/fundo_de_investimento/atualizacao_cadastral)
- busca_informacoes_de_uma_analise_cadastral_do_investidor (/zh-Hans/documentation/iaas/investidor/fundo_de_investimento/busca_informacoes_de_uma_analise_cadastral_do_investidor)
- busca_informacoes_do_investidor (/zh-Hans/documentation/iaas/investidor/fundo_de_investimento/busca_informacoes_do_investidor)
- buscar_documentos_para_assinatura (/zh-Hans/documentation/iaas/investidor/fundo_de_investimento/buscar_documentos_para_assinatura)
- atualizar_status_conta_bancaria (/zh-Hans/documentation/iaas/investidor/fundo_de_investimento/contas_bancarias/atualizar_status_conta_bancaria)
- definir_conta_principal (/zh-Hans/documentation/iaas/investidor/fundo_de_investimento/contas_bancarias/definir_conta_principal)
- enviar_contas_bancarias (/zh-Hans/documentation/iaas/investidor/fundo_de_investimento/contas_bancarias/enviar_contas_bancarias)
- 创建投资者/投资者分析 (/zh-Hans/documentation/iaas/investidor/fundo_de_investimento/criar_investidor)
- enviar_cadastro_para_analise (/zh-Hans/documentation/iaas/investidor/fundo_de_investimento/enviar_cadastro_para_analise)
- 发送投资者注册数据 (/zh-Hans/documentation/iaas/investidor/fundo_de_investimento/enviar_dados_cadastrais)
- consultar_feedback (/zh-Hans/documentation/iaas/investidor/fundo_de_investimento/feedback/consultar_feedback)
- enviar_mensagem_feedback (/zh-Hans/documentation/iaas/investidor/fundo_de_investimento/feedback/enviar_mensagem_feedback)
- listar_feedbacks (/zh-Hans/documentation/iaas/investidor/fundo_de_investimento/feedback/listar_feedbacks)
- Introdução (/zh-Hans/documentation/iaas/investidor/fundo_de_investimento/introducao)
- criar_parte_relacionada (/zh-Hans/documentation/iaas/investidor/fundo_de_investimento/related_party/criar_parte_relacionada)
- enviar_documento_parte_relacionada (/zh-Hans/documentation/iaas/investidor/fundo_de_investimento/related_party/enviar_documento_parte_relacionada)
- 获取投资者持仓信息 (/zh-Hans/documentation/iaas/investidor/informacoes_posicao_investidor)
- 简介 (/zh-Hans/documentation/iaas/investidor/inicio)
- 插入清算记录 (/zh-Hans/documentation/iaas/liquidacao_ativos/ativos/)
- 删除清算记录 (/zh-Hans/documentation/iaas/liquidacao_ativos/ativos/remocao_liquidacoes)
- Webhooks (/zh-Hans/documentation/iaas/liquidacao_ativos/ativos/webhook)
- Fluxo de liquidação de ativos (/zh-Hans/documentation/iaas/liquidacao_ativos/fluxo_liquidacao)
- 简介 (/zh-Hans/documentation/iaas/liquidacao_ativos/inicio)
- 创建付款批次 (/zh-Hans/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao)
- 关闭付款批次的插入 (/zh-Hans/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento)
- 清算批次列表 (/zh-Hans/documentation/iaas/liquidacao_ativos/lote_pagamento/listagem)
- 产品 Webhooks (/zh-Hans/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook)
- 资产 - 信贷业务 (/zh-Hans/documentation/iaas/negociacao_recebiveis/asset/criacao_co)
- Criação de Ativo — CTE (/zh-Hans/documentation/iaas/negociacao_recebiveis/asset/criacao_cte)
- 资产 - 信贷业务 (/zh-Hans/documentation/iaas/negociacao_recebiveis/asset/criacao_discounted_contract)
- 资产 - 信贷业务 (/zh-Hans/documentation/iaas/negociacao_recebiveis/asset/criacao_duplicata)
- 插入待回购资产 (/zh-Hans/documentation/iaas/negociacao_recebiveis/asset/criacao_repurchased_asset)
- 插入文件 (/zh-Hans/documentation/iaas/negociacao_recebiveis/asset/documents)
- 查询批次中的资产 (/zh-Hans/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos)
- 从批次中移除资产 (/zh-Hans/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos)
- Webhooks (/zh-Hans/documentation/iaas/negociacao_recebiveis/asset/webhooks)
- 管理员审批 (/zh-Hans/documentation/iaas/negociacao_recebiveis/assignment/aprovacao)
- 创建转让/替代批次 (/zh-Hans/documentation/iaas/negociacao_recebiveis/assignment/criacao)
- 转让文件 (/zh-Hans/documentation/iaas/negociacao_recebiveis/assignment/documento_da_cessao)
- 结束资产插入 (/zh-Hans/documentation/iaas/negociacao_recebiveis/assignment/fechamento)
- 转让批次列表 (/zh-Hans/documentation/iaas/negociacao_recebiveis/assignment/listagem)
- 获取转让批次 (/zh-Hans/documentation/iaas/negociacao_recebiveis/assignment/recuperacao)
- 如何创建转让？ (/zh-Hans/documentation/iaas/negociacao_recebiveis/assignment/video_cessao)
- Webhooks (/zh-Hans/documentation/iaas/negociacao_recebiveis/assignment/webhooks)
- Fluxo de Cessão (/zh-Hans/documentation/iaas/negociacao_recebiveis/fluxo_cessao)
- 简介 (/zh-Hans/documentation/iaas/negociacao_recebiveis/inicio)
- 转让配置列表 (/zh-Hans/documentation/iaas/negociacao_recebiveis/listagem)
- 信用权利转让手册 (/zh-Hans/documentation/iaas/negociacao_recebiveis/manual_api)
- Listagem de Solicitações de Amortização (/zh-Hans/documentation/iaas/passivo/amortizacao/listagem)
- 分页查询金融申请 (/zh-Hans/documentation/iaas/passivo/aplicacao_financeira/busca_paginada_aplicacoes_financeiras)
- 金融申请结算分页查询 (/zh-Hans/documentation/iaas/passivo/aplicacao_financeira/busca_paginada_fechamento_das_aplicacoes_financeiras)
- 通过键查询金融申请 (/zh-Hans/documentation/iaas/passivo/aplicacao_financeira/buscar_aplicacao_financeira_por_chave)
- 创建金融申请 (/zh-Hans/documentation/iaas/passivo/aplicacao_financeira/criar_aplicacao_financeira)
- 手动批准份额锁定 (/zh-Hans/documentation/iaas/passivo/bloqueio_de_cotas/aprovar_bloqueio_pendente_aprovacao)
- 查询份额锁定 (/zh-Hans/documentation/iaas/passivo/bloqueio_de_cotas/consulta_de_bloqueio_de_cotas)
- 查询投资者的份额锁定 (/zh-Hans/documentation/iaas/passivo/bloqueio_de_cotas/consulta_de_bloqueio_de_cotas_de_um_investidor)
- 发送担保文件 (/zh-Hans/documentation/iaas/passivo/bloqueio_de_cotas/enviar_documento_da_garantia)
- 发送资产文件 (/zh-Hans/documentation/iaas/passivo/bloqueio_de_cotas/enviar_documento_do_ativo)
- 减少份额锁定 (/zh-Hans/documentation/iaas/passivo/bloqueio_de_cotas/reduzir_bloqueio_de_cotas)
- 申请份额锁定 (/zh-Hans/documentation/iaas/passivo/bloqueio_de_cotas/solicitar_bloqueio_de_cotas)
- 份额锁定 Webhook (/zh-Hans/documentation/iaas/passivo/bloqueio_de_cotas/webhooks_de_bloqueio_de_cota)
- Consulta paginada de investidores por classe de fundo (/zh-Hans/documentation/iaas/passivo/consultas/consulta_investidores_classe_fundo)
- Consulta paginada de posições de cotistas por classe de fundo (/zh-Hans/documentation/iaas/passivo/consultas/consulta_posicoes_cotistas_classe_fundo)
- 份额演变图分页查询 (/zh-Hans/documentation/iaas/passivo/consultas/consultar_mapa_de_evolucao_de_cotas)
- 发行系列分页查询 (/zh-Hans/documentation/iaas/passivo/consultas/consultar_todas_series_de_emissao)
- 基金分页查询 (/zh-Hans/documentation/iaas/passivo/consultas/consultar_todos_fundos)
- 发送已签署认购公告 (/zh-Hans/documentation/iaas/passivo/controle_de_oferta/enviar_boletim_de_subscricao_assinado)
- 获取认购公告信息 (/zh-Hans/documentation/iaas/passivo/controle_de_oferta/informacoes_boletins_de_subscricao)
- 获取发行信息 (/zh-Hans/documentation/iaas/passivo/controle_de_oferta/informacoes_das_ofertas)
- 申请认购公告 (/zh-Hans/documentation/iaas/passivo/controle_de_oferta/solicitar_boletim_de_subscricao)
- 获取公开份额 (/zh-Hans/documentation/iaas/passivo/fundos/cotas_publicas)
- 简介 (/zh-Hans/documentation/iaas/passivo/inicio)
- 按键查询赎回申请 (/zh-Hans/documentation/iaas/passivo/pedido_de_resgate/buscar_pedido_de_resgate_por_chave)
- Consulta paginada de pedidos de resgate por classe de fundo (/zh-Hans/documentation/iaas/passivo/pedido_de_resgate/consulta_pedidos_resgate_classe_fundo)
- Consulta paginada de pedidos de resgate por investidor (/zh-Hans/documentation/iaas/passivo/pedido_de_resgate/consulta_pedidos_resgate_investidor)
- 创建赎回申请 (/zh-Hans/documentation/iaas/passivo/pedido_de_resgate/criar_pedido_de_resgate)
- 发送已签署入会协议 (/zh-Hans/documentation/iaas/passivo/termo_de_adesao/enviar_termo_de_adesao_assinado)
- Solicitar Termo de Adesão (/zh-Hans/documentation/iaas/passivo/termo_de_adesao/solicitar_termo_de_adesao)
- Razão Contábil (/zh-Hans/documentation/iaas/relatorios_dtvm/accounting_ledger)
- Composição de Carteira de Ativos (/zh-Hans/documentation/iaas/relatorios_dtvm/assets_wallet_composition)
- Composição de Ativos da Cessão (/zh-Hans/documentation/iaas/relatorios_dtvm/assignment_assets_wallet_composition)
- Lastros da Cessão (/zh-Hans/documentation/iaas/relatorios_dtvm/assignment_documents)
- Relatório de Balanço (/zh-Hans/documentation/iaas/relatorios_dtvm/balance_report)
- Demonstrativo de Caixa (/zh-Hans/documentation/iaas/relatorios_dtvm/cash_account_demonstrative)
- Movimentações de Caixa (/zh-Hans/documentation/iaas/relatorios_dtvm/cash_account_demonstrative_movements)
- Aquisição Consolidada de Direitos Creditórios (/zh-Hans/documentation/iaas/relatorios_dtvm/consolidated_credit_rights_acquisition_assets)
- Conciliação Consolidada de Direitos Creditórios (/zh-Hans/documentation/iaas/relatorios_dtvm/consolidated_credit_rights_conciliation_assets)
- Relatórios DTVM (/zh-Hans/documentation/iaas/relatorios_dtvm/)
- Cotas MEC (/zh-Hans/documentation/iaas/relatorios_dtvm/quota_mec)
- Composição da Carteira (/zh-Hans/documentation/iaas/relatorios_dtvm/wallet_composition)
- XML ANBIMA (tipos 5 e 401) (/zh-Hans/documentation/iaas/relatorios_dtvm/xml_anbima)
- 创建待回购/出售的资产 (/zh-Hans/documentation/iaas/venda_ativos/asset/criacao_recompra)
- 经理审批 (/zh-Hans/documentation/iaas/venda_ativos/assignment/aprovacao_recompra)
- 创建回购批次 (/zh-Hans/documentation/iaas/venda_ativos/assignment/criacao_recompra)
- 结束资产插入 (/zh-Hans/documentation/iaas/venda_ativos/assignment/fechamento_recompra)
- 资产回购与出售 (/zh-Hans/documentation/iaas/venda_ativos/inicio)
- 获取账户信息 (/zh-Hans/documentation/iaas/visibildade_de_caixa/get_accounts)
- 获取账户交易记录 (/zh-Hans/documentation/iaas/visibildade_de_caixa/get_transaction_reversals)
- 获取账户交易记录 (/zh-Hans/documentation/iaas/visibildade_de_caixa/get_transactions)
- 简介 (/zh-Hans/documentation/iaas/visibildade_de_caixa/inicio)
- 基金账户间转账 (/zh-Hans/documentation/iaas/visibildade_de_caixa/post_internal_transfer)
- 创建退款申请 (/zh-Hans/documentation/iaas/visibildade_de_caixa/post_transaction_reversal)
- Webhooks (/zh-Hans/documentation/iaas/visibildade_de_caixa/webhook_transaction_reversal)
- 文档介绍 (/zh-Hans/documentation/introducao_api_reference)
- 欢迎来到 QI Tech API 手册区 (/zh-Hans/documentation/introducao_manuais)
- 欢迎来到 QI Tech API 手册区 (/zh-Hans/documentation/introducao_operational_guides)
- 金融机构查询 (/zh-Hans/documentation/lista_de_instituicoes_financeiras/consulta_de_instituicoes_financeiras)
- 空军薪资代扣贷款手册 (/zh-Hans/documentation/manual_aeronautica/manual_consignado)
- Homologation Roadmap - BNPL (/zh-Hans/documentation/manual_bnpl_ecommerce/manual_bnpl)
- 对接路线图 - BNPL (/zh-Hans/documentation/manual_bnpl_ecommerce/)
- Consulta - Emissão BNPL (/zh-Hans/documentation/manual_bnpl_full/emissao/consulta)
- Emissão BNPL (/zh-Hans/documentation/manual_bnpl_full/emissao/)
- Simulação - Emissão BNPL (/zh-Hans/documentation/manual_bnpl_full/emissao/simulacao)
- Webhooks - Emissão BNPL (/zh-Hans/documentation/manual_bnpl_full/emissao/webhooks)
- Estorno BNPL (/zh-Hans/documentation/manual_bnpl_full/estorno/)
- Estorno via Amortização — equal_amount e full_settle (/zh-Hans/documentation/manual_bnpl_full/estorno/estorno_amortizacao)
- Webhooks - Estorno BNPL (/zh-Hans/documentation/manual_bnpl_full/estorno/webhooks)
- Consulta de Valor Presente - Refinanciamento BNPL (/zh-Hans/documentation/manual_bnpl_full/refinanciamento/consulta_valor_presente)
- Criação - Refinanciamento BNPL (/zh-Hans/documentation/manual_bnpl_full/refinanciamento/criacao)
- Introdução - Refinanciamento BNPL (/zh-Hans/documentation/manual_bnpl_full/refinanciamento/introducao)
- Simulação - Refinanciamento BNPL (/zh-Hans/documentation/manual_bnpl_full/refinanciamento/simulacao)
- Cenários - Renegociação em Lote BNPL (/zh-Hans/documentation/manual_bnpl_full/renegociacao/cenarios)
- Consulta - Renegociação em Lote BNPL (/zh-Hans/documentation/manual_bnpl_full/renegociacao/consulta)
- Renegociação com IOF Spread e Desconto Somente Juros - BNPL (/zh-Hans/documentation/manual_bnpl_full/renegociacao/iof-spread-e-desconto-juros)
- Proposta de Renegociação em Lote - BNPL (/zh-Hans/documentation/manual_bnpl_full/renegociacao/proposta)
- Simulação - Renegociação em Lote BNPL (/zh-Hans/documentation/manual_bnpl_full/renegociacao/simulacao)
- Webhooks - Renegociação em Lote BNPL (/zh-Hans/documentation/manual_bnpl_full/renegociacao/webhooks)
- Scripts de Integração - BNPL Full (/zh-Hans/documentation/manual_bnpl_full/scripts_integracao)
- 薪资卡手册 - 跟踪查询 (/zh-Hans/documentation/manual_cartao_beneficio/manual_cartao_beneficio_acompanhamento)
- 文件与签名 (/zh-Hans/documentation/manual_cartao_beneficio/manual_cartao_beneficio_documentos)
- 薪资卡手册 - 创建 (/zh-Hans/documentation/manual_cartao_beneficio/manual_cartao_beneficio_emissao)
- 地址管理 (/zh-Hans/documentation/manual_cartao_beneficio/manual_cartao_beneficio_endereco)
- 薪资卡手册 - Webhook (/zh-Hans/documentation/manual_cartao_beneficio/manual_cartao_beneficio_webhook)
- CertifiQI 手册 (/zh-Hans/documentation/manual_certifiqi/dc37cf4f-adad-45c5-9251-9c957fb9ce8e)
- Cessão (/zh-Hans/documentation/manual_cessao/)
- Conciliação (/zh-Hans/documentation/manual_conciliacao/)
- 私人薪资抵押贷款手册 - 外部签署形式 (/zh-Hans/documentation/manual_consignado_privado/manual_assinatura_externa)
- 私人薪资抵押贷款手册 - 信贷操作跟踪 (/zh-Hans/documentation/manual_consignado_privado/manual_assinatura_leilao)
- 私人薪资抵押贷款手册 - 核批与放款 (/zh-Hans/documentation/manual_consignado_privado/manual_averbacao_desembolso)
- 私人薪资抵押贷款手册 - 拍卖提案接收过滤器配置 (/zh-Hans/documentation/manual_consignado_privado/manual_configuracao_filtros)
- 私人薪资抵押贷款手册 - 账目查询 (/zh-Hans/documentation/manual_consignado_privado/manual_consultas_conciliacao)
- 私人薪资抵押贷款手册 - 工人查询 (/zh-Hans/documentation/manual_consignado_privado/manual_consultas_trabalhador)
- 私人薪资抵押贷款手册 - 遗留合同 (/zh-Hans/documentation/manual_consignado_privado/manual_contratos_legados)
- 私人薪资抵押贷款手册 - 新信贷 (/zh-Hans/documentation/manual_consignado_privado/manual_credito_novo)
- 私人薪资抵押贷款手册 - 主动发行流程 (/zh-Hans/documentation/manual_consignado_privado/manual_detalhamento_fluxo_ativo)
- 私人薪资抵押贷款手册 - 拍卖发行流程 (/zh-Hans/documentation/manual_consignado_privado/manual_detalhamento_fluxo_leilao)
- 私人薪资抵押贷款手册 - 内部拍卖 (/zh-Hans/documentation/manual_consignado_privado/manual_leilao_interno)
- 私人薪资抵押贷款手册 - 再融资 (/zh-Hans/documentation/manual_consignado_privado/manual_refinanciamento)
- 保险 (/zh-Hans/documentation/manual_consignado_privado/manual_seguro)
- 私人薪资抵押贷款手册 - 遗留合同归档 (/zh-Hans/documentation/manual_consignado_privado/manual_tombamento_legado)
- 手册 - 私人薪资抵押贷款：雇佣关系 (/zh-Hans/documentation/manual_consignado_privado/manual_vinculos_empregaticios)
- Manual Consignado Privado - Portabilidade: Consultas Prévias (/zh-Hans/documentation/manual_consignado_privado/portabilidade/consultas)
- Manual Consignado Privado - Portabilidade: Consultas e Operações Pós-Proposta (/zh-Hans/documentation/manual_consignado_privado/portabilidade/consultas_pos_proposta)
- Manual Consignado Privado - Portabilidade: Enumeradores (/zh-Hans/documentation/manual_consignado_privado/portabilidade/enumeradores)
- Manual Consignado Privado - Portabilidade: Formalização (/zh-Hans/documentation/manual_consignado_privado/portabilidade/formalizacao)
- Manual Consignado Privado - Portabilidade: Acompanhamento da Operação (/zh-Hans/documentation/manual_consignado_privado/portabilidade/maquina_de_status)
- Manual Consignado Privado - Portabilidade: Mocks e Sandbox (/zh-Hans/documentation/manual_consignado_privado/portabilidade/mocks_sandbox)
- Manual Consignado Privado - Portabilidade: Digitação da Proposta (/zh-Hans/documentation/manual_consignado_privado/portabilidade/proposta)
- Manual Consignado Privado - Portabilidade: Simulação (/zh-Hans/documentation/manual_consignado_privado/portabilidade/simulacao)
- Manual Consignado Privado - Portabilidade + Refinanciamento (/zh-Hans/documentation/manual_consignado_privado/portabilidade/visao_geral)
- FGTS 授权查询手册 (/zh-Hans/documentation/manual_consulta_de_autorizacao_FGTS/)
- Consulta - Emissão Crédito Clean (/zh-Hans/documentation/manual_credito_clean/emissao/consulta)
- Consulta de Cessão (/zh-Hans/documentation/manual_credito_clean/emissao/consulta_cessao)
- Emissão Crédito Clean (/zh-Hans/documentation/manual_credito_clean/emissao/)
- Emissão com Assinatura Posterior (/zh-Hans/documentation/manual_credito_clean/emissao/emissao_dois_passos)
- Emissão com Assinatura Imediata (/signed_debt) (/zh-Hans/documentation/manual_credito_clean/emissao/emissao_signed_debt)
- Simulação - Emissão Crédito Clean (/zh-Hans/documentation/manual_credito_clean/emissao/simulacao)
- Webhooks - Emissão Crédito Clean (/zh-Hans/documentation/manual_credito_clean/emissao/webhooks)
- Estorno Crédito Clean (/zh-Hans/documentation/manual_credito_clean/estorno/)
- Webhooks - Estorno Crédito Clean (/zh-Hans/documentation/manual_credito_clean/estorno/webhooks)
- Notificações - Crédito Clean (/zh-Hans/documentation/manual_credito_clean/notificacoes)
- Consulta de Valor Presente - Refinanciamento Crédito Clean (/zh-Hans/documentation/manual_credito_clean/refinanciamento/consulta_valor_presente)
- Criação - Refinanciamento Crédito Clean (/zh-Hans/documentation/manual_credito_clean/refinanciamento/criacao)
- Introdução - Refinanciamento Crédito Clean (/zh-Hans/documentation/manual_credito_clean/refinanciamento/introducao)
- Simulação - Refinanciamento Crédito Clean (/zh-Hans/documentation/manual_credito_clean/refinanciamento/simulacao)
- Cenários - Renegociação em Lote Crédito Clean (/zh-Hans/documentation/manual_credito_clean/renegociacao/cenarios)
- Consulta - Renegociação em Lote Crédito Clean (/zh-Hans/documentation/manual_credito_clean/renegociacao/consulta)
- Proposta de Renegociação em Lote - Crédito Clean (/zh-Hans/documentation/manual_credito_clean/renegociacao/proposta)
- Simulação - Renegociação em Lote Crédito Clean (/zh-Hans/documentation/manual_credito_clean/renegociacao/simulacao)
- Webhooks - Renegociação em Lote Crédito Clean (/zh-Hans/documentation/manual_credito_clean/renegociacao/webhooks)
- Scripts de Integração - Crédito Clean (/zh-Hans/documentation/manual_credito_clean/scripts_integracao)
- Emissão de Dívida PJ com Assinatura Imediata (/zh-Hans/documentation/manual_emissao_pj_signed_debt/emissao_signed_debt_pj)
- Assinatura em Lote (/zh-Hans/documentation/manual_exercito/assinatura-em-lote)
- Cancelamento, Desaverbação e Reversal (/zh-Hans/documentation/manual_exercito/cancelamento)
- Consulta de Margem Consignável (/zh-Hans/documentation/manual_exercito/consulta-margem)
- Conta Interna para Desembolso (/zh-Hans/documentation/manual_exercito/conta-interna-desembolso)
- Modelos de Formalização (/zh-Hans/documentation/manual_exercito/formalizacao)
- Consignado do Exército — Introdução (/zh-Hans/documentation/manual_exercito/introducao)
- Mapa de Status (/zh-Hans/documentation/manual_exercito/mapa-de-status)
- Margem Livre (Crédito Novo) (/zh-Hans/documentation/manual_exercito/margem-livre)
- Mocks (Sandbox) (/zh-Hans/documentation/manual_exercito/mocks-sandbox)
- Portabilidade + Refinanciamento (/zh-Hans/documentation/manual_exercito/portabilidade-refin)
- Webhooks (/zh-Hans/documentation/manual_exercito/webhooks)
- FGTS 周年提款手册 (/zh-Hans/documentation/manual_FGTS/)
- Manual de Garantia Veicular (/zh-Hans/documentation/manual_garantia_veicular/)
- 我的 INSS 提案拍卖手册 (/zh-Hans/documentation/manual_leilao_meu_inss/)
- 可携性转出 - 保留证据 (/zh-Hans/documentation/manual_portabilidade/evidencias_de_retencao)
- 可携性 Out (/zh-Hans/documentation/manual_portabilidade/portabilidade_out)
- QI 卡 - 预付卡 (/zh-Hans/documentation/manual_pre_pago/casos_uso)
- 私人养老金手册 - 批注与放款 (/zh-Hans/documentation/manual_previdencia_privada/manual_previdencia_privada_averbacao_desembolso)
- 私人养老金手册 - 查询 (/zh-Hans/documentation/manual_previdencia_privada/manual_previdencia_privada_consulta)
- 私人养老金手册 - 新增信贷 (/zh-Hans/documentation/manual_previdencia_privada/manual_previdencia_privada_credito_novo)
- QI FATURA (/zh-Hans/documentation/manual_qi_fatura/pix_parcelado)
- QI Sign 手册 (/zh-Hans/documentation/manual_qi_sign/)
- 审批转账 (/zh-Hans/documentation/movimentacao_de_contas/aprovar_transferencia)
- 转账凭证 (/zh-Hans/documentation/movimentacao_de_contas/comprovante_de_transferencia)
- 交易查询 (/zh-Hans/documentation/movimentacao_de_contas/consulta_de_transacoes)
- 查询待处理交易 (/zh-Hans/documentation/movimentacao_de_contas/consulta_de_transacoes_pendentes)
- 查询已完成转账 (/zh-Hans/documentation/movimentacao_de_contas/consulta_de_transferencias_realizadas)
- 发起转账 (/zh-Hans/documentation/movimentacao_de_contas/realizar_transferencia)
- 模拟交易 (/zh-Hans/documentation/movimentacao_de_contas/transacao)
- Webhooks (/zh-Hans/documentation/movimentacao_de_contas/webhook_movimentacoes)
- 通知配置 (/zh-Hans/documentation/notificacoes/configuracao_de_notificacao)
- 模板配置 (/zh-Hans/documentation/notificacoes/configuracao_template)
- 通知简介 (/zh-Hans/documentation/notificacoes/introducao)
- 重发 Webhook (/zh-Hans/documentation/notificacoes/reenvio_de_notificacoes)
- 通知模板 (/zh-Hans/documentation/notificacoes/template)
- 事件类型 (/zh-Hans/documentation/notificacoes/tipos_de_evento)
- Address 对象 (/zh-Hans/documentation/objetos_compartilhados/address)
- Borrower 对象 (/zh-Hans/documentation/objetos_compartilhados/borrower)
- Disbursement Account 对象 (/zh-Hans/documentation/objetos_compartilhados/disbursement_account)
- Financial Institution 对象 (/zh-Hans/documentation/objetos_compartilhados/financial_institution)
- 银行单据（Boletos）运营手册 (/zh-Hans/documentation/operational_guide/boletos)
- 执行 Peer To Peer 交易 (/zh-Hans/documentation/peer_to_peer)
- 为 Alias 创建 PIX 密钥 (/zh-Hans/documentation/pix_indireto/chaves_pix/criacao_de_chaves)
- 删除 Alias 的 PIX 密钥 (/zh-Hans/documentation/pix_indireto/chaves_pix/deletar_chaves)
- 为 Alias 管理 PIX 密钥简介 (/zh-Hans/documentation/pix_indireto/chaves_pix/introducao_chaves_pix)
- 列出 Alias 的 PIX 密钥 (/zh-Hans/documentation/pix_indireto/chaves_pix/listar_chaves)
- 取消退款请求 (/zh-Hans/documentation/pix_indireto/devolucao/cancelar_devolucao)
- 查询退款请求 (/zh-Hans/documentation/pix_indireto/devolucao/consultar_devolucao)
- 创建退款请求 (/zh-Hans/documentation/pix_indireto/devolucao/criar_devolucao)
- 关闭退款请求 (/zh-Hans/documentation/pix_indireto/devolucao/fechar_devolucao)
- 列出退款请求 (/zh-Hans/documentation/pix_indireto/devolucao/listar_solicitacoes)
- 退款流程简介 (/zh-Hans/documentation/pix_indireto/devolucao/maquina_estados)
- 场景模拟 (/zh-Hans/documentation/pix_indireto/devolucao/simulacao_de_cenarios)
- 接收退款请求 (/zh-Hans/documentation/pix_indireto/devolucao/webhooks_devolucao)
- 查询 Alias 实体 (/zh-Hans/documentation/pix_indireto/gerenciamento_de_alias/consultar_alias)
- 通过 Request Control Key 查询 Alias (/zh-Hans/documentation/pix_indireto/gerenciamento_de_alias/consultar_request_control_key)
- 创建 Alias 实体 (/zh-Hans/documentation/pix_indireto/gerenciamento_de_alias/criacao_de_alias)
- 删除 Alias 实体 (/zh-Hans/documentation/pix_indireto/gerenciamento_de_alias/deletar_alias)
- Alias 实体简介 (/zh-Hans/documentation/pix_indireto/gerenciamento_de_alias/introducao_alias)
- Alias 列表 (/zh-Hans/documentation/pix_indireto/gerenciamento_de_alias/listagem_de_alias)
- 简介 (/zh-Hans/documentation/pix_indireto/introducao)
- 沙盒环境中的模拟 PIX 密钥 (/zh-Hans/documentation/pix_indireto/movimentacoes/chaves_pix_mockadas)
- 在巴西中央银行查询 PIX 密钥数据 (/zh-Hans/documentation/pix_indireto/movimentacoes/consultar_chave_pix)
- 查询 PIX 交易 (/zh-Hans/documentation/pix_indireto/movimentacoes/consultar_pix)
- 执行 PIX 退款 (/zh-Hans/documentation/pix_indireto/movimentacoes/devolucao_pix)
- PIX 范围内交易简介 (/zh-Hans/documentation/pix_indireto/movimentacoes/introducao_movimentacoes)
- 场景模拟 (/zh-Hans/documentation/pix_indireto/movimentacoes/simulacao)
- 执行手动 PIX 异步转账 (/zh-Hans/documentation/pix_indireto/movimentacoes/transacao_async/transacao_pix_manual)
- 通过 PIX 密钥执行异步转账 (/zh-Hans/documentation/pix_indireto/movimentacoes/transacao_async/transacao_pix_normal)
- 执行 PIX QR 码异步转账 (/zh-Hans/documentation/pix_indireto/movimentacoes/transacao_async/transacao_pix_qr_code)
- 通过 PIX 密钥进行 PIX 交易 (/zh-Hans/documentation/pix_indireto/movimentacoes/transacao/transacao_pix_chave_sync)
- 手动 PIX 交易 (/zh-Hans/documentation/pix_indireto/movimentacoes/transacao/transacao_pix_manual_sync)
- 通过 QR 码进行 PIX 交易 (/zh-Hans/documentation/pix_indireto/movimentacoes/transacao/transacao_pix_qr_code_sync)
- PIX 退款 Webhook (/zh-Hans/documentation/pix_indireto/movimentacoes/webhook/webhook_devolucao_outgoing_pix)
- 入站 PIX Webhook (/zh-Hans/documentation/pix_indireto/movimentacoes/webhook/webhook_incoming_pix)
- 待处理交易 Webhook (/zh-Hans/documentation/pix_indireto/movimentacoes/webhook/webhook_transacao)
- 取消可携性申请 (/zh-Hans/documentation/pix_indireto/portabilidade/cancelar_pedido_de_portabilidade)
- 完成可携性申请 (/zh-Hans/documentation/pix_indireto/portabilidade/completar_pedido_de_portabilidade)
- 确认可携性申请 (/zh-Hans/documentation/pix_indireto/portabilidade/confirmar_pedido_de_portabilidade)
- 查询可携性申请 (/zh-Hans/documentation/pix_indireto/portabilidade/consultar_pedido_de_portabilidade)
- 创建可携性申请 (/zh-Hans/documentation/pix_indireto/portabilidade/criar_pedido_de_portabilidade)
- 可携性请求简介 (/zh-Hans/documentation/pix_indireto/portabilidade/introducao_portabilidade)
- 查询某 Alias 的可携性申请列表 (/zh-Hans/documentation/pix_indireto/portabilidade/listar_pedidos_de_portabilidade_de_um_alias)
- 可携性更新 Webhook (/zh-Hans/documentation/pix_indireto/portabilidade/webhook/webhook_atualizacao_do_pedido_de_portabilidade)
- 外部可携性记录 Webhook (/zh-Hans/documentation/pix_indireto/portabilidade/webhook/webhook_receber_registro_externo_de_portabilidade)
- 查询 PIX QR 码 (/zh-Hans/documentation/pix_indireto/qr_code/consultar_qr_code)
- 创建有效期动态 PIX QR 码 (/zh-Hans/documentation/pix_indireto/qr_code/Criar QR Code/criar_qr_code_dinamico_com_vencimento)
- 创建即时支付动态 PIX QR 码 (/zh-Hans/documentation/pix_indireto/qr_code/Criar QR Code/criar_qr_code_dinamico_imediato)
- 创建静态 PIX QR 码 (/zh-Hans/documentation/pix_indireto/qr_code/Criar QR Code/criar_qr_code_estatico)
- 列出某 Alias 的 QR 码 (/zh-Hans/documentation/pix_indireto/qr_code/decodificar_qr_code)
- 修改 PIX QR 码 (/zh-Hans/documentation/pix_indireto/qr_code/desativar_qr_code)
- PIX QR 码简介 (/zh-Hans/documentation/pix_indireto/qr_code/introducao_qr_code)
- 列出某 Alias 的 QR 码 (/zh-Hans/documentation/pix_indireto/qr_code/listar_alias_qr_codes)
- QR 码支付入站 PIX Webhook (/zh-Hans/documentation/pix_indireto/qr_code/webhook_incoming_pix)
- 取消违规举报 (/zh-Hans/documentation/pix_indireto/relato_de_infracao/cancelar_relato_infracao)
- 查询违规举报 (/zh-Hans/documentation/pix_indireto/relato_de_infracao/consultar_relato_infracao)
- 发起违规举报 (/zh-Hans/documentation/pix_indireto/relato_de_infracao/criar_relato_infracao)
- 关闭违规举报 (/zh-Hans/documentation/pix_indireto/relato_de_infracao/fechar_relato_infracao)
- 列出违规举报 (/zh-Hans/documentation/pix_indireto/relato_de_infracao/listar_relatos)
- 违规举报流程简介 (/zh-Hans/documentation/pix_indireto/relato_de_infracao/maquina_estados)
- 场景模拟 (/zh-Hans/documentation/pix_indireto/relato_de_infracao/simulacao_de_cenarios)
- 接收违规举报 (/zh-Hans/documentation/pix_indireto/relato_de_infracao/webhooks_relato_infracao)
- Pix (/zh-Hans/documentation/pix_v2)
- 审批转账 (/zh-Hans/documentation/pix/2fa/aprovar_solicitacao_de_transferencia)
- 申请 Pix 退款 (/zh-Hans/documentation/pix/2fa/solicitar_chargeback_pix)
- 申请转账审批令牌 (/zh-Hans/documentation/pix/2fa/solicitar_token_de_aprovacao)
- 申请 Pix 转账 (/zh-Hans/documentation/pix/2fa/solicitar_transferencia)
- 批准转账申请 (/zh-Hans/documentation/pix/aprovar_solicitacao_de_transferencia)
- 在巴西中央银行查询 Pix 密钥数据 (/zh-Hans/documentation/pix/baas_v2/consultar_chave_pix)
- 注销动态 Pix QR Code (/zh-Hans/documentation/pix/baixar_qr_code_dinamico)
- 查询 Pix 限额申请 (/zh-Hans/documentation/pix/busca_por_solicitacao_de_limite_pix)
- 查询 Pix 限额使用情况 (/zh-Hans/documentation/pix/busca_por_uso_de_limite_pix)
- Chaves PIX mockadas em ambiente de sandbox (/zh-Hans/documentation/pix/chaves_pix_mockadas)
- 交易凭证 (/zh-Hans/documentation/pix/comprovante_de_transferencia)
- 定期转账收据 (/zh-Hans/documentation/pix/comprovante_de_transferencia_agendada)
- 查询 Pix 密钥 (/zh-Hans/documentation/pix/consultar_chave)
- 查询 Pix 密钥 (/zh-Hans/documentation/pix/consultar_chave_v2)
- 创建 Pix 密钥 (/zh-Hans/documentation/pix/criar_chave)
- 创建动态 Pix QR Code (/zh-Hans/documentation/pix/criar_qr_code_dinamico)
- 创建静态 QR Code (/zh-Hans/documentation/pix/criar_qr_code_estatico)
- 解码 Pix QR Code (/zh-Hans/documentation/pix/decodificar_qr_code)
- 删除 Pix 密钥 (/zh-Hans/documentation/pix/excluir_chave)
- 简介 (/zh-Hans/documentation/pix/introducao)
- 列出账户的 Pix 密钥 (/zh-Hans/documentation/pix/listar_chaves_pix)
- MED 2.0 — 查询资金追回 (/zh-Hans/documentation/pix/med/consultar_recuperacao_de_valores)
- PIX 特殊退款机制（MED） (/zh-Hans/documentation/pix/med/introducao)
- 接收退款申请 (/zh-Hans/documentation/pix/med/recebimento_pedidos_de_devolucao)
- MED 2.0 — 接收资金追回 (/zh-Hans/documentation/pix/med/recebimento_recuperacao_de_valores)
- 接收违规报告 (/zh-Hans/documentation/pix/med/recebimento_relatos_de_infracao)
- MED 2.0 — 回复资金追回 (/zh-Hans/documentation/pix/med/responder_recuperacao_de_valores)
- 回复违规报告 (/zh-Hans/documentation/pix/med/resposta_relatos_de_infracao)
- 查询自有动态 Pix QR Code (/zh-Hans/documentation/pix/pesquisar_por_qr_code_dinamico)
- 查询出站 Pix 转账 (/zh-Hans/documentation/pix/pesquisar_por_transferencia_pix_de_saida)
- 可携性完成 (/zh-Hans/documentation/pix/portabilidade/conclusao_de_portabilidade)
- 按账户查询可携性 (/zh-Hans/documentation/pix/portabilidade/consulta_de_portabilidade_por_conta)
- 创建可携性申请 (/zh-Hans/documentation/pix/portabilidade/criando_um_pedido_de_portabilidade)
- 删除可携性申请 (/zh-Hans/documentation/pix/portabilidade/deletando_um_pedido_de_portabilidade)
- 可携性 (/zh-Hans/documentation/pix/portabilidade/recebendo_pedido_de_portabilidade)
- 重新发送双因素验证 (/zh-Hans/documentation/pix/portabilidade/reenviando_a_2fa)
- 可携性 (/zh-Hans/documentation/pix/portabilidade/respondendo_pedido_de_portabilidade)
- 模拟可携性状态变更 (/zh-Hans/documentation/pix/portabilidade/simular_alteracao_de_status_de_portabilidade)
- 模拟可携性申请完成 Webhook (/zh-Hans/documentation/pix/portabilidade/simular_webhook_de_conclusao)
- 模拟接收可携性申请 Webhook (/zh-Hans/documentation/pix/portabilidade/simular_webhook_recebimento)
- 双因素验证 (/zh-Hans/documentation/pix/portabilidade/validacao_de_dois_fatores)
- 场景模拟 (/zh-Hans/documentation/pix/simulacao)
- 申请修改 Pix 限额 (/zh-Hans/documentation/pix/solicitar_alteracao_de_limite_pix)
- 申请 Pix 退款 (/zh-Hans/documentation/pix/solicitar_chargeback_pix)
- solicitar_transferencia (/zh-Hans/documentation/pix/solicitar_transferencia)
- 动态 Pix QR Code 过期 Webhook (/zh-Hans/documentation/pix/webhook_por_qr_code_expirado)
- 配置 Webhooks (/zh-Hans/documentation/primeiros_passos/configurando_webhooks)
- 配置集成 IP 白名单 (/zh-Hans/documentation/primeiros_passos/configurar_ip_de_integracao)
- 简介 (/zh-Hans/documentation/primeiros_passos/inicio)
- 测试端点 (/zh-Hans/documentation/primeiros_passos/teste_de_autenticacao/endpoints_de_teste)
- 常见错误 (/zh-Hans/documentation/primeiros_passos/teste_de_autenticacao/possiveis_erros)
- 完整身份验证示例 (/zh-Hans/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_completo)
- 身份验证测试 (/zh-Hans/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2)
- Webhook 验证 (/zh-Hans/documentation/primeiros_passos/teste_de_autenticacao/webhook_v2)
- 密钥交换 (/zh-Hans/documentation/primeiros_passos/troca_de_chaves)
- 查询操作的当前价值 (/zh-Hans/documentation/refinanciamento/consulta_de_valor_presente_de_uma_operacao)
- introducao (/zh-Hans/documentation/refinanciamento/introducao)
- 模拟再融资 (/zh-Hans/documentation/refinanciamento/simulando_refinanciamento)
- 创建再融资 (/zh-Hans/documentation/refinanciamento/solicitando_refinanciamento)
- 更新自动划转规则 (/zh-Hans/documentation/regras_de_movimentacao/atualizar_regra_movimentacao)
- 创建自动划转规则 (/zh-Hans/documentation/regras_de_movimentacao/criar_regra_de_movimentacao)
- 资金划转规则 (/zh-Hans/documentation/regras_de_movimentacao/)
- 取消重组方案 (/zh-Hans/documentation/renegociacao/cancelar_uma_renegociacao)
- 查询重组方案 (/zh-Hans/documentation/renegociacao/consultar_uma_renegociacao)
- 创建重组方案 (/zh-Hans/documentation/renegociacao/criacao_de_uma_renegociacao)
- Renegociação internal e external (/zh-Hans/documentation/renegociacao/criacao_renegociacao_internal)
- 查询重组方案列表 (/zh-Hans/documentation/renegociacao/listar_renegociacoes)
- 重组方案支付 (/zh-Hans/documentation/renegociacao/pagamento_renegociacao)
- 批量重组 (/zh-Hans/documentation/renegociacao/renegociacao_em_lote)
- 按分期金额模拟 (/zh-Hans/documentation/renegociacao/simulacao_com_valor_por_parcela)
- 模拟重组方案 (/zh-Hans/documentation/renegociacao/simulacao_de_uma_renegociacao)
- 更新手动支付记录 (/zh-Hans/documentation/renegociacao/update_de_um_pagamento_manual)
- 测试指南 - 购物回路 (/zh-Hans/documentation/roteiros_de_homologacao/circuito_dd46f8d3-f078-41ba-a311-55be848f1c69)
- 测试指南 - BaaS 数字账户 (/zh-Hans/documentation/roteiros_de_homologacao/conta_digital)
- 测试指南 - BaaS 数字账户（双重认证） (/zh-Hans/documentation/roteiros_de_homologacao/conta_digital_2fa)
- 测试指南 - BaaS 数字账户（双重认证） (/zh-Hans/documentation/roteiros_de_homologacao/conta_digital_2fa_baas)
- 测试指南 - BaaS 数字账户 (/zh-Hans/documentation/roteiros_de_homologacao/conta_digital_baas)
- 测试指南 - BaaS 数字账户 Escrow (/zh-Hans/documentation/roteiros_de_homologacao/conta_digital_escrow)
- 测试指南 - BaaS 数字账户 Escrow (/zh-Hans/documentation/roteiros_de_homologacao/conta_digital_escrow_caas)
- 测试指南 - BaaS 收款 (/zh-Hans/documentation/roteiros_de_homologacao/roteiro_cobranca)
- 测试指南 - BaaS 数字账户（双重认证） (/zh-Hans/documentation/roteiros_de_homologacao/roteiro_conta_digital)
- 测试指南 - BaaS 数字账户 (/zh-Hans/documentation/roteiros_de_homologacao/roteiro_conta_digital_d795dc71-05b2-4476-bfbc-07ef247abd90)
- 同质化测试路线图 - 集成账户 (/zh-Hans/documentation/roteiros_de_homologacao/roteiro_conta_integrada)
- 后台构建指南 (/zh-Hans/documentation/roteiros_de_homologacao/roteiro_criacao_backoffice_cliente)
- 测试指南 - BaaS Conta Payments (/zh-Hans/documentation/roteiros_de_homologacao/roteiro_payments)
- 测试指南 - Pix 综合账户 (/zh-Hans/documentation/roteiros_de_homologacao/roteiro_pix_conta_integrada)
- 测试指南 - 间接 Pix (/zh-Hans/documentation/roteiros_de_homologacao/roteiro_pix_indireto)
- Roteiro de Homologação - Emissão de dívida PF com desembolso pagando QR Code (/zh-Hans/documentation/roteiros_laas/roteiro_00f2a5d3-39c2-4f3d-9234-7d1525daaaf2)
- 同质化路线 - 个人债务发行 - 预付法院判决款（Precatório） (/zh-Hans/documentation/roteiros_laas/roteiro_5d068423-6094-49e4-b15b-7740038295a8)
- Homologation Roadmap - Credit Pay (/zh-Hans/documentation/roteiros_laas/roteiro_cecdd0e2-081a-4590-b571-188c376a7c64)
- APP Integration (/zh-Hans/documentation/roteiros_laas/roteiro_e7030e18-a9c7-452b-8236-1cf8edfb4de9)
- INSS Webhooks (/zh-Hans/documentation/roteiros_laas/webhooks_inss)
- 查询可用余额 (/zh-Hans/documentation/saque_aniversario_fgts/consultar_saldo_disponivel)
- 创建信贷操作 (/zh-Hans/documentation/saque_aniversario_fgts/criacao_da_operacao)
- FGTS 生日提款简介 (/zh-Hans/documentation/saque_aniversario_fgts/introducao)
- roteiro_de_homologacao (/zh-Hans/documentation/saque_aniversario_fgts/roteiro_de_homologacao)
- 按期望金额模拟 (/zh-Hans/documentation/saque_aniversario_fgts/simulacao_do_valor_desejado)
- 最高金额模拟 (/zh-Hans/documentation/saque_aniversario_fgts/simulacao_do_valor_maximo)
- 余额查询 Webhook (/zh-Hans/documentation/saque_aniversario_fgts/webhooks_de_consulta_de_saldo)
- Assinatura em Lote (/zh-Hans/documentation/siape/assinatura-em-lote)
- Cancelamento, Desaverbação e Reversal (SIAPE) (/zh-Hans/documentation/siape/cancelamento)
- Consulta de Margem Consignável (SIAPE) (/zh-Hans/documentation/siape/consulta-margem)
- Conta Interna para Desembolso (/zh-Hans/documentation/siape/conta-interna-desembolso)
- Modelos de Formalização (SIAPE) (/zh-Hans/documentation/siape/formalizacao)
- SIAPE-SIGEPE — Introdução (/zh-Hans/documentation/siape/introducao)
- Mapa de Status (/zh-Hans/documentation/siape/mapa-de-status)
- Margem Livre (Crédito Novo) (/zh-Hans/documentation/siape/margem-livre)
- Mocks (Sandbox) (/zh-Hans/documentation/siape/mocks-sandbox)
- Portabilidade + Refinanciamento (/zh-Hans/documentation/siape/portabilidade-refin)
- Webhooks (/zh-Hans/documentation/siape/webhooks)
- 审批转账 (/zh-Hans/documentation/ted/2fa/aprovar_transferencia)
- 申请转账 (/zh-Hans/documentation/ted/2fa/solicitar_transferencia)
- TED (/zh-Hans/documentation/ted/ted_v2)
- consulta_de_agenda_com_opt_in (/zh-Hans/documentation/trava_de_domicilio_bancario/consulta_de_agenda_com_opt_in)
- consulta_de_agenda_sem_opt_in (/zh-Hans/documentation/trava_de_domicilio_bancario/consulta_de_agenda_sem_opt_in)
- emissao_de_divida_com_trava_de_agenda (/zh-Hans/documentation/trava_de_domicilio_bancario/emissao_de_divida_com_trava_de_agenda)
- introducao (/zh-Hans/documentation/trava_de_domicilio_bancario/introducao)
- 开启票据 tombamento 批次 (/zh-Hans/documentation/troca_de_titularidade/abrir_lote)
- 批准票据 tombamento 批次 (/zh-Hans/documentation/troca_de_titularidade/aprovar_lote)
- 取消票据 tombamento 批次 (/zh-Hans/documentation/troca_de_titularidade/cancelar_lote)
- 创建票据 tombamento 批次 (/zh-Hans/documentation/troca_de_titularidade/criar_lote_batch)
- 将票据加入 tombamento 批次 (/zh-Hans/documentation/troca_de_titularidade/incluir_boletos)
- 简介 (/zh-Hans/documentation/troca_de_titularidade/introducao)
- 列出 tombamento 批次中的票据 (/zh-Hans/documentation/troca_de_titularidade/listar_boletos_lote)
- 列出票据 tombamento 批次 - 目标方 (/zh-Hans/documentation/troca_de_titularidade/listar_lotes_destino)
- 列出票据 tombamento 批次 - 来源方 (/zh-Hans/documentation/troca_de_titularidade/listar_lotes_origem)
- 票据 Tombamento Webhook (/zh-Hans/documentation/troca_de_titularidade/notificacoes_webhooks)
- 从 tombamento 批次中移除票据 (/zh-Hans/documentation/troca_de_titularidade/remover_boletos)
- 发送票据 tombamento 批次 (/zh-Hans/documentation/troca_de_titularidade/validar_lote_e_enviar)
- 文档查询 (/zh-Hans/documentation/upload_de_documentos/consulta_documents)
- 文档上传 (/zh-Hans/documentation/upload_de_documentos/)
- acg1 (/zh-Hans/documentation/webhooks/acg1)
- agenda_de_recebiveis (/zh-Hans/documentation/webhooks/agenda_de_recebiveis)
- 银行划款 Webhook (/zh-Hans/documentation/webhooks/boletos)
- 债务 Webhook (/zh-Hans/documentation/webhooks/dividas)
- Webhooks de gestão de risco (/zh-Hans/documentation/webhooks/gestao_de_risco)
- 不当款项 Webhook (/zh-Hans/documentation/webhooks/indevidos)
- notificacoes_baas_e_laas (/zh-Hans/documentation/webhooks/notificacoes_baas_e_laas)
- 分期支付 Webhook (/zh-Hans/documentation/webhooks/pagamento_de_parcela)
- 分期 Webhook (/zh-Hans/documentation/webhooks/parcelas)

---

# TAC 使用更新

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

## CPF 资格查询

持有 **CPF** 数据后，可查询该 CPF 的资格状态。

### Request

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

### Path Params

| 字段               | 描述                     | 字符数 |
|-------------------|--------------------------|--------|
| `document_number` | 债务人 CPF 号码          | 11     |

### Response

STATUS 200

Response Body

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

### 字段说明
| 字段        | 类型    | 
|-------------|---------|
| `elegible`  | boolean | 

:::caution 注意
对于返回 **"eligible": false** 的 CPF，在 **rebates** 列表中包含 TAC 时，模拟和债务发行均将无法进行。
:::

 

## 模拟和发行债务时的资格错误
当对不符合 TAC 收费条件的 CPF 在模拟或操作发行时发送 TAC 值，将返回同步错误。

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"
}
```

## 取消不符合资格的操作

若同时向同一借款人发送多笔含 TAC 的操作，第一笔放款将强制取消其余操作。届时，将发送以下载荷的取消 Webhook。

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"
}

```

---

# SIAPE/军队带找零转贷

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

## 合同列表查询

:::caution 注意
此功能**仅适用于**与军队 API 的集成。
:::

持有**CPF**、**军人注册编号**和**Token**后，集成合作伙伴可通过以下端点查询可供购买的军人合同列表：

### 请求

ENDPOINT /military_payroll/portability_contracts_report
MÉTODO POST

Request Body

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

:::info
CPF 必须以文本格式提供，最多 11 个字符，不含"."和"-"，左侧以零填充。
:::

#### 请求体参数

| 字段                         | 类型   | 描述                   |
|------------------------------|--------|------------------------|
| `document_number`            | string | 军人的 CPF。           |
| `registration_code`          | string | 军人注册编号。         |
| `token`                      | string | 军人密码。             |

### 响应

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"
}
```

额度查询数据将通过 webhook 返回。

#### 响应体参数

| 字段                               | 类型   | 描述                                                                                                              |
|------------------------------------|--------|------------------------------------------------------------------------------------------------------------------------|
| `portability_contracts_report_key` | string | 合同列表查询的识别键。                                                              |
| `status`                           | enum   | [合同列表查询状态枚举值。](#enumeradores-de-status-da-consulta-da-lista-de-contratos) |

#### 合同列表查询状态枚举值

| 枚举值             | 描述                                                                    |
|--------------------|-----------------------------------------------------------------------------|
| `pending_search`   | 合同列表查询等待军队系统响应。  |
| `failed`           | 合同列表查询失败。                                       |
| `succeeded`        | 合同列表查询成功。        |  

### 查询成功

成功 webhook 将以如下形式返回：

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"			
			}
		]
		
	}
}
```

### 查询失败

失败 webhook 将以如下形式返回：

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" 
	}
}
```

每个 `enumerator` 都有更详细的描述，为便于查阅，下表列出了每种情况的对应关系。

#### failure_reason 枚举值

| 枚举值                    | 描述                                                          | Zetra 代码 |
|---------------------------|---------------------------------------------------------------|--------------|
| contracts_not_found       | 未找到与所提供数据匹配的合同                                  | 294          |
| invalid_registration_code | 提供的注册编号无效                                            | 210          |
| military_blocked          | 查询无法完成，因为该军人已被封锁                              | 352          |
| military_not_found        | 未找到与所提供数据匹配的服务器                                | 293          |

## 个人信贷业务模拟

首先需要计算清偿原信贷业务所需的个人信贷业务金额。

原债务的未偿余额应填写在 _**disbursed_amount**_ 字段中。

:::caution 注意
该业务必须以仅 1 期还款进行模拟，在 **D0** 放款，还款日期应为放款（付款）日期起的 **D+5 个工作日**。
:::

### 请求

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
	}
}
```

---

## SIAPE/军队薪资贷款业务模拟

SIAPE 薪资贷款业务的模拟，应模拟原合同的清偿以及根据可用额度和合同利率计算释放给客户的找零金额。

在此模拟中，所提供字段的值将按如下方式分配：

_**installment_face_value**_ = 可扣除额度值

_**disbursement_date**_ = 模拟时刻起 **D+5 个工作日**

_**due_balance**_ = 个人信贷业务模拟中返回的第 1 期 **total_amount**

_**original_deadline**_ = 个人信贷业务的总天数（5 天）

:::info IOF
SIAPE 薪资贷款业务的 IOF 金额，由于其再融资个人信贷业务，将仅对应释放给客户的找零金额（新资金）。
:::

### 请求

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
        }
    ]
}
```

_**data.final_disbursement_amount**_ 字段在模拟中返回的值即为支付给客户的找零金额。

---

### 查询个人信贷业务的还款期金额

#### 请求

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

:::info 信息
DEBT-KEY 是业务创建响应中返回的键（/debt 的响应）
:::

---

## 创建债务人名下账户

在录入提案之前，需要在 QI Tech 为债务人开设账户。

该账户将用于接收个人信贷业务的放款，并通过其他银行（通过 Boleto、TED 或 Pix）支付原债务的未偿余额。

### 请求

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"
	}
}
```

| 参数                                                         | 描述                               |
|--------------------------------------------------------------|------------------------------------|
| **account_owner**                                            | 债务人数据                         |
| **is_operation_account**                                     | 表示该账户为业务账户。             |

### 响应

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
/account 返回的账户数据应用作个人信贷业务的放款账户
:::

### 5xx 错误或超时

在账户成功开设之前，流程不应继续。
对于失败情况，在可能的重试开户之前，应检查账户是否确实未为客户开设。

可以通过列出特定 CPF 的已开账户来检查账户是否已为客户开设。

#### 请求

ENDPOINT /account
MÉTODO POST
PARAMETER owner_document_number, requester_key

| 参数                      | 描述                               |
|---------------------------|------------------------------------|
| **owner_document_number** | 债务人的 CPF                       |
| **requester_key**         | 集成的内部键。                     |

#### 响应
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 信息
上述响应 payload 中仅列出了相关的可读字段。
:::

---

## 业务发行

个人信贷业务和 SIAPE 薪资贷款业务的创建，**必须在同一时刻进行**，每项业务具有以下配置

- **个人信贷业务**：应在 D0 放款发行，仅有一期还款，到期日为放款日起 **D+5 个工作日**。
- **SIAPE 薪资贷款业务**：应在 **D+0** 放款发行，但放款选项可延至 **D+15 个自然日**，并按预期期数发行。

:::danger 注意
发行个人信贷业务时，"_**financial**_"对象必须与其模拟时发送的信息完全相同。

发行 SIAPE 薪资贷款业务时，"_**financial**_"对象将有以下差异：
- _**disbursement_date**_ 字段应替换为 _**disbursement_start_date**_ 和 _**disbursement_end_date**_ 字段，两者之差必须为 **15 个自然日**。
- _**refinanced_credit_operations[0].operation_key**_ 字段必须包含个人信贷业务创建返回中返回的 **DEBT-KEY**。
:::

:::info 信息
个人信贷业务只能在**工作日**放款，具体时间取决于原债务未偿余额的支付方式：
- **TED**：放款时间在 **6:30 至 17:15** 之间
- **Boleto**：放款时间在 **7:00 至 22:00** 之间
- **Pix**：任意时间（但建议在商业时间内放款，因为若操作在深夜放款，例如，Pix 的入账可能因可疑欺诈而被拒绝）
:::

### 个人信贷业务发行

发行个人信贷业务时，需要发送放款后需要支付的 Boleto/TED/Pix 信息。

:::caution 注意
合作伙伴必须生成业务的内部识别键，并在债务发行请求的"_**requester_identifier_key**_"字段中发送
:::

#### 请求示例

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"
    }
}
```
    

#### 婚姻状态枚举值
| 枚举值       | 描述          |
|--------------|---------------|
| **single**   | 单身          |
| **married**  | 已婚          |
| **widower**  | 丧偶          |
| **divorced** | 离婚          |

#### 5xx 错误或超时

如果请求返回 5xx 或超时，为了确认操作确实未在 QI 中创建，建议合作伙伴查询返回 5xx 或超时的操作。

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

如果 GET 请求返回 200，合作伙伴不应重试创建操作，而应继续操作流程。
如果返回 404 - Not Found，合作伙伴应重试创建操作。

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 信息
操作创建响应中的"key"字段是 **DEBT-KEY**，即操作在 QI 内的唯一键。
:::

#### 签名

**与 SIAPE ML 操作相同的签名流程**

#### 授权放款

操作签名后，需要授权操作进行放款。

:::danger 注意
个人信贷业务的放款授权，必须在收到 SIAPE 中提案录入确认 webhook 后发送。
:::

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

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

#### 放款

操作签名并授权放款后，将自动进入放款流水线。

放款处理完成后，合作伙伴将收到以下 webhook：

#### 放款成功

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"
}
```

#### 放款后操作

个人信贷业务放款至 QI 中创建的债务人账户后，将执行与清偿债务人原债务未偿余额相关的 boleto/TED/Pix 支付（放款后操作）

#### 成功

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"
}
```

  

#### 放款后操作错误

如果放款后操作支付发生错误，合作伙伴将通过以下 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"
}
```

#### 放款后操作的 TED 退款

如果放款后操作中执行的 TED 被目标金融机构退回，合作伙伴将通过以下 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"
}
```

#### 重试失败的放款后操作

如果放款后操作支付发生错误/退款，可通过以下端点重试 [/baas/action/**[ACTION-KEY]**](/documentation/emissao_de_divida/reprocessar_acao_pos_desembolso)

### SIAPE 薪资贷款业务发行

SIAPE 薪资贷款业务必须清偿个人信贷业务，并向客户释放找零（如有）

#### 请求

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"
        }
    ]
}
```

#### 响应

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

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"
}
```

#### 注销登记

SIAPE 薪资贷款业务创建后，QI 将启动业务的注销登记流程。

注销登记尝试流程从业务创建时开始，并将重试至业务最后一个放款选项日期。

录入完成后，QI 将通知合作伙伴注销登记的待同意情况：

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"
}
```

同意完成且额度注销登记确认后，QI 将通过以下 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"
}
```

---

### 军队薪资贷款业务发行

军队薪资贷款业务必须清偿个人信贷业务，并向客户释放找零（如有）

#### 请求

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"
        }
    ]
}
```

### collateral_data 对象字段详情
| 字段               | 描述                                                                                                                      | 值                                                    |
|--------------------|---------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------|
| reservation_type   | 预留类型                                                                                                                  | [枚举值](#reservation_type_enumerator)                |
| registration_code  | 军人注册编号                                                                                                              | 123456789                                             |
| reservation_method | 确定何时开始尝试薪资贷款的注销登记，是在信贷业务创建时还是在发行时。                                                    | [枚举值](#reservation_method_enumerator)              |
| portability_data   | 可携性数据                                                                                                                | [可携性对象](#portability_data_object)                |

### 预留类型表 {#reservation_type_enumerator}
| 枚举值       | 描述      |
|--------------|-----------|
| new_credit   | 新信贷    |
| portability  | 可携性    |
| refinancing  | 再融资    |

### 预留创建方法表 {#reservation_method_enumerator}

:::caution 注意
非常重要的字段，因为它直接决定何时向 Zetra 提交预留意向请求。
:::

| 枚举值    | 描述                                                                   |
|-----------|------------------------------------------------------------------------|
| creation  | 注销登记尝试将在信贷业务创建时开始。                                   |
| issuing   | 注销登记尝试将在信贷业务发行时开始，即正式化之后。                     |

### portability_data 对象字段详情 {#portability_data_object}
| 字段                | 描述                         | 值                               |
|---------------------|------------------------------|----------------------------------|
| token               | 军人提供的密码               | 1234abcd                         |
| origin_econsig_id   | Zetra 合同识别码             | 1234567                          |
| origin_econsig_ids  | Zetra 合同识别码列表         | [1234567, 1234568, 1234569]      |

#### 响应

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"
}
```

#### 注销登记

军队薪资贷款业务创建后，QI 将启动业务的注销登记流程。

注销登记尝试流程从业务创建时开始，并将重试至业务最后一个放款选项日期。

军队可扣除额度注销登记完成后，QI 将通过以下 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"
}
```
如果提供的 token 无效，我们将发送以下 webhook。如果提供的 token 已被使用且需要新 token，也将发送此 webhook。

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"
}
```

#### 导致自动取消的响应

根据 Zetra 的响应，操作将被自动取消。
发生此情况时，我们将以如下格式发送 webhook，取消原因在"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"

}
```
#### 枚举值表
| 枚举值                                        | 描述                    | Zetra 代码 |
|-----------------------------------------------|-------------------------|------------|
| military_payroll_military_not_found           | 未找到军人。            | 293        |
| military_payroll_portability_not_found        | 未找到原合同。          | 294        |
| military_payroll_consignable_margin_exceeded  | 可用额度已超出。        | 359        |

#### 可携性到期

10 天后，Zetra 将取消等待确认的可携性请求。

因此，要重新启动可携性流程，需要一个新的有效 token。如果存在新的有效 token，提案将返回到可携性意向步骤（预留状态：pending_reservation）。但是，如果不存在有效 token（通常是因为发送的 token 已在之前的可携性意向中使用），提案将更新为 pending_valid_token 状态，等待发送新 token。发送新的有效 token 后，提案将正常继续可携性意向和确认流程。

为通知相关情况，将发送以下 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"
}
```
## 取消
要对操作进行永久取消，包括取消可扣除额度的注销登记，应使用以下端点：

:::caution 注意
需要指出，取消注销登记流程是异步的，即信贷业务的取消**不一定**意味着取消注销登记已完成。要查询取消注销登记的状态，请参阅[获取最后一次请求的响应](#recuperar_ultima_request)"。
:::

:::caution 注意
永久取消也可能自动发生，当操作处于"canceled"状态超过 7 天时会发生这种情况。
:::
### 请求

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

### 操作取消成功：

操作取消完成后，合作伙伴将收到以下 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"
}
```

## 发送新的可携性 Token

可携性 token 是一次性使用的，因此，当之前的 token 被使用或 token 无效时，需要发送新 token。

发送方式是一个简单的调用：

### 请求

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

Request Body

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

### 成功情况
#### Response 204

Response Body

```json
    {}
```

### 错误情况
:::info
此请求中只应发送 token，否则流程将返回错误
:::
#### 响应

Response Body

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

## 更改业务的注销登记类型

专门将操作的注销登记类型从可携性更改为新信贷。
更改后，预留将自动遵循新信贷类型预留的注销登记流程和规则。
### 请求

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

Request Body

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

### 成功情况
#### Response 204

Response Body

```json
    {}
```

### 错误情况

#### 响应

Response Body

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

## 获取最后一次请求的响应 {#recuperar_ultima_request}

last response 是一种简单直接的方式，用于映射 QI 与 Zetra 之间通信的响应，可以了解该请求的发起时间及获得的返回值（通过枚举值）。

每个枚举值都有详细描述。我们可以在下面更详细地查看 last response 数据的呈现方式。

### 成功情况

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

#### 响应

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"
        }       
    }
}
```

#### 枚举值表
| 枚举值                    | 描述                             | 详情                                       | 预留状态             |
|---------------------------|----------------------------------|--------------------------------------------|----------------------|
| successfully_accepted     | Reservation request accepted     | 注销登记请求已被接受，正在等待确认         | pending_confirmation |
| successfully_reserved     | Reservation made successfully    | 预留已成功注销登记                         | reserved             |
| successfully_deleted      | Reservation successfully deleted | 预留已成功取消注销登记                     | deleted              |

### 错误情况

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

#### 响应

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"
    }
  }
```

#### 枚举值表
| 枚举值                       | 描述                                      | QI 操作 | 对应 Zetra 代码 |
|------------------------------|-------------------------------------------|---------|-----------------|
| waiting_confirmation         | Waiting Confirmation on Portability       | retry   |                 |
| communication_error          | Communication Error with Zetra            | retry   | 241             |
| consignable_margin_excceded  | Exceeded consignable margin               | retry   | 359             |

## 未偿余额通知

未偿余额通知在申请日后的第 5 个工作日发生，所有通知均通过 webhook 以以下信息发送：

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"
		}
	]
}
```

---

# 两步式开户

URL: /zh-Hans/documentation/account_request

## 申请自由活动账户预留

### Request

ENDPOINT /account_request/checking
MÉTODO POST

Request Body - 法人（PJ）账户持有人

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

Request Body - 自然人（PF）账户持有人

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

## 申请 Escrow 账户预留

ENDPOINT /account_request/escrow
MÉTODO POST

Request Body - 法人（PJ）账户持有人

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

Request Body - 自然人（PF）账户持有人

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

### 法人（PJ）账户持有人 Body Params

| 字段              | 类型       | 描述                                          | 字符数                                                                                               |
|-------------------|------------|-----------------------------------------------|------------------------------------------------------------------------------------------------------|
| **account_owner** | object     | 账户法人持有人的简化信息 | [PJ account_owner 对象](#objeto-account_owner-solicitar-reserva-pj) <br/><br/> [PF account_owner 对象](#objeto-account_owner-solicitar-reserva-pf) |

### 申请预留 PJ 的 account_owner 对象

| 字段                           | 类型   | 描述                    | 字符数 |
|--------------------------------|--------|-------------------------|--------|
| **company_document_number** *  | string | 账户持有人 CNPJ。       | 14     |
| **email** *                    | string | 公司联系邮箱。          | 200    |
| **foundation_date**            | string | 公司成立日期。          | 10     |
| **name** *                     | string | 账户持有公司注册名称。  | 50     |

### 申请预留 PF 的 account_owner 对象

| 字段                   | 类型   | 描述                    | 字符数 |
|------------------------|--------|-------------------------|--------|
| **document_number** *  | string | 账户持有人 CPF。        | 14     |
| **email** *            | string | 公司联系邮箱。          | 200    |
| **birthdate**          | string | 出生日期。              | 10     |
| **name** *             | string | 账户持有公司注册名称。  | 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"
}
```

### KYC 审批 Webhook

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"
}
```

### account_request_status 枚举值
| 枚举值                     | 描述                     |
|---------------------------|--------------------------|
| **pending_kyc_analysis**  | 待 KYC 审批              |
| **pending_additional_data**| 待补充信息               |
| **rejected**              | 开户被拒                 |

## 开立自由活动账户

### Request

ENDPOINT /account_request/ACCOUNT_REQUEST_KEY/checking
MÉTODO PATCH

Request Body - 法人（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"]
}
```

Request Body - 自然人（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"]
}
```

### Response

STATUS 201

Response Body

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

:::info ACCOUNT_KEY
`account_key` 将是账户的唯一识别密钥。所有与账户的交互都将通过它进行。
:::

## 开立 Escrow 账户

### Request

ENDPOINT /account_request/ACCOUNT_REQUEST_KEY/escrow
MÉTODO PATCH

Request Body - 法人（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"]
}
```

Request Body - 自然人（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"]
}
```

### Response

STATUS 201

Response Body

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

:::info ACCOUNT_KEY
`account_key` 将是账户的唯一识别密钥。所有与账户的交互都将通过它进行。
:::

### 开户 Body Params
| 字段                     | 类型   | 描述                                        | 字符数                                                                                                                                            |
|--------------------------|--------|---------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
| **account_owner** *      | object | 账户持有人的完整信息                         | **[PJ account_owner 对象](#objeto-account_owner-abertura-de-conta-pj)** <br/><br/> **[PF account_owner 对象](#objeto-account_owner-abertura-de-conta-pf)** |
| **signed_contract** *    | object | 包含账户合同及签署方数据的对象。             | **[signed_contract 对象](#objeto-signed_contract)**                                                                                               |
| **destinations** **      | list   | 已授权接收转账的目标账户列表。               | **[destinations 对象](#objeto-destinations)**                                                                                                     |
| **additional_documents** | list   | 额外/可选文件 ID 列表。                      | UUID 数组                                                                                                                                         |

`(**) Escrow 账户必填`

### 开户 PJ 的 account_owner 对象
| 字段                          | 类型       | 描述                                                                                                          | 字符数                                                              |
|-------------------------------|------------|---------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
| **address** *                 | object     | 账户持有人地址对象                                                                                            | **[address 对象](#objeto-address)**                                 |
| **cnae_code** *               | string     | 全国经济活动分类代码                                                                                          | 9                                                                   |
| **company_document_number** * | string     | CNPJ                                                                                                          | 14                                                                  |
| **company_statute** *         | uuidv4     | 公司章程 PDF 的 DOCUMENT_KEY（预先发送）。                                                                    | 36                                                                  |
| **company_type** *            | enumerator | 公司类型                                                                                                      | **[company_type 枚举值](#enumeradores-company_type)**               |
| **email** *                   | string     | 公司机构邮箱。                                                                                                | 200                                                                 |
| **foundation_date** *         | string     | 公司成立日期（格式"YYYY-MM-DD"）。                                                                            | 10                                                                  |
| **name** *                    | string     | 账户持有公司注册名称。                                                                                        | 50                                                                  |
| **person_type** *             | enumerator | 发送对象为法人的标识符。PJ 对象必须始终包含值"legal"。                                                        | **[person_type 枚举值](#enumeradores-person_type)**                 |
| **phone** *                   | object     | 账户持有人电话。                                                                                              | **[phone 对象](#objeto-phone)**                                     |
| **trading_name** *            | string     | 商业名称（商号）。                                                                                            | 200                                                                 |
| **company_representatives** * | list       | 公司法定代表人列表                                                                                            | **[company_representatives 对象](#objeto-company_representatives)** |

### 开户 PF 的 account_owner 对象
| 字段                              | 类型    | 描述                                                                                                          | 字符数                                                    |
|-----------------------------------|---------|---------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------| 
| **address**                       | string  | 账户持有人地址对象                                                                                            | **[address 对象](#objeto-address)**                       | 
| **birth_date** *                  | string  | 出生日期（格式"YYYY-MM-DD"）                                                                                  | -                                                         |
| **document_identification** *     | uuidv4  | 附有照片的身份证件（RG 或 CNH）PDF 的 DOCUMENT_KEY（预先发送）                                               | 36                                                        |
| **email** *                       | string  | 账户持有人邮箱。                                                                                              | 200                                                       |
| **individual_document_number** *  | string  | CPF（仅数字）。                                                                                               | 11                                                        |
| **is_pep** *                      | boolean | 声明该人是否为 PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep)。                         | -                                                         |
| **mother_name** *                 | string  | 账户持有人母亲姓名。                                                                                          | -                                                         |
| **name** *                        | string  | 账户持有人姓名。                                                                                              | -                                                         |
| **nationality** *                 | string  | 客户国籍。                                                                                                    | -                                                         |
| **person_type** *                 | string  | 发送对象为自然人的标识符。PF 对象必须始终包含值"natural"。                                                    | **[person_type 枚举值](#enumeradores-person_type)**        |
| **phone**                         | string  | 包含账户持有人电话数据的对象                                                                                  | 36                                                        |
| **proof_of_residence**            | uuidv4  | 所填地址的居住证明 PDF 的 DOCUMENT_KEY（预先发送）。                                                         |                                                           |

### address 对象
| 字段               | 描述   | 示例                                                                                    | 字符数 |
|--------------------|--------|-----------------------------------------------------------------------------------------|--------|
| **street** *       | string | 街道名称                                                                                | 500    |
| **state** *        | enum   | 州代码（两位大写字母）                                                                  | 2      |
| **city** *         | string | 城市名称                                                                                | 255    |
| **neighborhood** * | string | 街区/社区名称                                                                           | 500    |
| **number** *       | string | 门牌号                                                                                  | 10     |
| **postal_code** *  | string | 邮政编码 (http://www.buscacep.correios.com.br/sistemas/buscacep/)（仅数字）             | 8      |
| **complement**     | string | 地址补充信息（自由文本）                                                                | 500    |

### phone 对象
| 字段               | 描述   | 示例                                                  | 字符数 |
|--------------------|--------|-------------------------------------------------------|--------|
| **country_code** * | string | 国际区号 (https://ddi.guiamais.com.br/)               | 3      |
| **area_code** *    | string | 区号 (https://ddd.guiamais.com.br/)                   | 3      |
| **number** *       | string | 电话号码（仅数字）                                    | 10     |

### person_type 枚举值
| 枚举值      | 描述       |
|-------------|------------|
| **natural** | 自然人     |
| **legal**   | 法人       |

### document_identification_type 枚举值
| 枚举值  | 描述                     |
|---------|--------------------------|
| **rg**  | RG - 身份证              |
| **cnh** | CNH - 驾驶执照           |

### company_type 枚举值
| 枚举值                  | 描述                                       |
|-------------------------|--------------------------------------------|
| **ltda**                | 有限责任公司                               |
| **sa**                  | 股份公司                                   |
| **micro_enterprise**    | 微型企业                                   |
| **freelancer**          | 自由职业者                                 |
| **sa_opened**           | 开放型股份公司                             |
| **sa_closed**           | 封闭型股份公司                             |
| **se_ltda**             | 有限责任企业公司                           |
| **se_cn**               | 无限责任企业公司                           |
| **se_cs**               | 简单合伙企业公司                           |
| **se_ca**               | 按股合伙企业公司                           |
| **scp**                 | 参与账户公司                               |
| **ei**                  | 个人企业主                                 |
| **ese**                 | 外国公司在巴西的机构                       |
| **eeab**                | 阿根廷-巴西双边企业在巴西的机构            |
| **ssp**                 | 简单纯粹公司                               |
| **ss_ltda**             | 有限责任简单公司                           |
| **ss_cn**               | 无限责任简单公司                           |
| **ss_cs**               | 简单合伙简单公司                           |
| **eireli_ne**           | 个人有限责任公司（企业性质）               |
| **eireli_ns**           | 个人有限责任公司（简单性质）               |
| **eireli**              | 个人责任公司                               |
| **mei**                 | 个体微型企业主                             |
| **me**                  | 微型企业                                   |
| **cop**                 | 合作社                                     |
| **private_association** | 私人协会                                   |
| **association**         | 协会                                       |
| **others**              | 其他                                       |

### marital_status 枚举值
| 枚举值        | 描述      |
|---------------|-----------|
| **single**    | 单身      |
| **married**   | 已婚      |
| **widower**   | 丧偶      |
| **divorced**  | 离婚      |
| **separated** | 分居      |

---

# 延期修改手册

URL: /zh-Hans/documentation/aditamento/manual_aditamento

本手册描述了延期修改（Aditamento）流程的分步说明。该操作是对债务偿还期限的延后，即对分期付款到期日进行变更，同时保持合同编号不变。

在此延期修改流程中，放款 webhook 中返回的 `final_debt_key` 是该操作的新密钥，在此流程完成后，将为已修改的分期生成新的银行单据（boletos）。

延期修改仅对固定利率（pré-fixadas）操作有效。

## 1 - 创建延期修改操作

`desired_installments` 字段是一个包含 `due_date` 属性的对象列表。

`calculate_delay` 字段仅在请求的 POST 中发送时，才会在 Response Body 中返回。

此时，由于延期修改操作尚未放款，与银行单据相关的字段（如 `bank_slip_key`、`digitable_line`、`qr_code_key` 和 `qr_code_url`）将为空。

**1.1.** 模拟：

        **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.** 创建：

        **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\>"
	}
}

```

与模拟相比，创建操作的 Response Body 的区别在于包含了 `amendment_key`、`amendment_status`、`document_key` 和 `document_url`。

在创建延期修改操作时，`amendment_status` 始终返回为 "waiting_signature"。

## 2 - 查询延期修改操作
        **Request**

ENDPOINT /amendment/[AMENDMENT_KEY]
MÉTODO GET

执行 GET 请求时需要发送的 `amendment_key` 是在创建延期修改操作时返回的同名字段的值，代表该延期修改操作的唯一标识密钥。

        **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 - 取消延期修改操作
        **Request**

ENDPOINT /amendment/[AMENDMENT_KEY]
MÉTODO DELETE

执行 DELETE 时需要发送的 `amendment_key` 是在创建延期修改操作时返回的同名字段的值，代表该延期修改操作的唯一标识密钥。

执行 DELETE 后，不返回响应负载，延期修改操作的状态将更改为 "canceled"。

## 4 - Webhooks

:::danger 注意！
QI Tech 的 webhooks 不应被严格映射。
API 返回的 webhook 负载中可能会添加额外字段。
:::

:::info Webhook 重发
您可以按照文档中的详细说明查询和重发 webhooks：[重发 Webhooks](/documentation/notificacoes/reenvio_de_notificacoes)。
:::

以下描述了在延期修改操作签署、放款和取消情况下将发送的 webhooks。

**4.1.** 签署：

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.** 放款：

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.** 取消：

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\>"
		}
	}
}

```

cancel_reason 遵循以下枚举值：**[Cancel Reason 枚举](#enumerador-cancel-reason)**。

## 5 - 一般信息

`calendar_days` 或 `workdays` 字段中的"前一参考日期"是指：第一期的放款日期，以及其他期次中前一期的到期日。

installments 字段是一个填充了对象的列表。在此情况下，延期修改的每一期都应有一个包含相应信息的对象。

| 字段 | 类型 | 示例 | 备注 |
|---| ---| ---| ---|
| `additional_data` | json | { } | 非必填 |
| `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` | 枚举 | **[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 | 非必填，默认为 False |
| `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 | 这是新的 debt key  |
| `installment_number` | int | 3 | |
| `installment_key` | string | 1b65d775-b5ab-49d5-a833-46980387afb1	| |
| `interest_base` | 枚举 | **[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 | 始终为零，因为延期修改仅对固定利率操作有效 |
| `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 |  |

### _Interest Base_ 枚举
| 枚举值            | 描述                                                                 |
|-----------------------|---------------------------------------------------------------------------|
| **workdays**          | 以工作日为基础计算利息，一年按 252 个工作日计算    |
| **calendar_days**     | 以自然日为基础计算利息，一年按 360 天计算 |
| **calendar_days_365** | 以自然日为基础计算利息，一年按 365 天计算 |

### _Amendment Status_ 枚举
| 枚举值            | 描述                                                                 |
|-----------------------|---------------------------------------------------------------------------|
| **waiting_signature** | 等待签署													    |
| **signed**     		| 已签署																    |
| **disbursed** 		| 已放款															    |
| **canceled** 			| 已取消																    |
| **disbursing_error**	| 放款时发生错误											    |

:::caution 注意！
'disbursing_error' 状态代表一个中间状态，延期修改合同将被取消或放款。
:::

### _Cancel Reason_ 枚举
| 枚举值            	| 描述                                                                    |
|---------------------------|------------------------------------------------------------------------------|
| **delete_amendment** 		| 对 DELETE 端点发起请求											   |
| **non_signed_amendment**  | 延期修改操作在发送的参考日期（amendment_date）前未签署															    |
| **different_balance_due** | 创建延期修改操作与放款时的未偿余额不同															         |
| **different_installments_number** | 创建延期修改操作与放款时的未偿期数不同																	|

---

# 安排票据（Boleto）付款

URL: /zh-Hans/documentation/agendamentos/agendamento_boleto

遵循与其他流程中付款相同的原则，主要区别在于需要发送 schedule_date，届时您将收到 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

| 字段                     | 类型   | 描述                                                        | 字符数 |
|--------------------------|--------|-------------------------------------------------------------|--------|
| `digitable_line` *       | string | 票据的可输入行。                                            | -      |
| `resource_account_key` * | string | 将被使用的账户密钥。                                        | -      |
| `payment_date` *         | date   | 执行付款的日期。如果未发送，日期将为今天。                   | -      |
| `transaction_amount`     | float  | 要支付的金额。                                              | -      |

:::info 信息

要查看已接受的付款协议，[请点击此处](https://storage.googleapis.com/live-doc-api/public_samples/convenios_qi_tech.xlsx)。

:::

## Response

STATUS 200

Response Body: 通过自由账户付款

```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: 通过 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\"}"
}
```

---

# 安排 PIX 转账

URL: /zh-Hans/documentation/agendamentos/agendamento_pix

遵循与 PIX 转账相同的原则，主要区别在于需要发送 schedule_date，届时您将收到 schedule_key。

## Request

ENDPOINT /baas/pix_transfer
MÉTODO POST

**Manual**
Request Body: 手动转账

```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: 手动转账

```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: 密钥转账

```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: 密钥转账

```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

| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---| ---|
| `pix_transfer_type` * | string | PIX 有不同的发起类型，"manual" 为用户发送目标账户和来源账户字段，"key" 为用户发送收款方 PIX 密钥（目标账户）和来源账户数据。 | 10 |
| `source_account` * | Object | 来源账户。 | **[source_account 对象](#objeto-source_account)** | 
| `target_account` | Object | 目标账户 - 仅在 "manual" 类型交易中发送。 | **[target_account 对象](#objeto-target_account)** | 10 |
| `transaction_amount` * | string | 转账金额。 | 10 | 
| `schedule_date` | date | 交易预约日期（如未发送，转账将在审批时立即执行）。 | 10 |
| `receiver_conciliation_id` | string | 收款方对账标识。 | 10 |
| `is_chargeback` | string | PIX 交易退款标识（布尔值 True 或 False）。 | 10 |
| `requester_document_identification` * | string | 请求转账用户的 CPF。 | 10 |
| `pix_transfer_key` | string | PIX 交易的幂等密钥 - 仅在转账类型为 "key" 时发送。 | 10 |
| `chargeback_amount` | string | 退款金额 - 此字段仅在退款时发送，并免除 "transaction_amount" 字段的必填要求。 | 10 |
| `chargeback_other_reason` | string | 退款原因（仅在退款时发送）。 | 10 |
| `chargeback_message` | string | 用户在退款时插入消息的字段（仅在退款时发送）。 | 10 |
 
### source_account 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---| ---|
| `account_branch` * | string | 机构号。 | 0 |
| `branch_digit` |string | 机构检验位。| 0 |
| `account_digit` * | string | 账户检验位。| 0 |
| `account_number` * | string | 账户号。| 0 | 
| `owner_document_number` * | string | 账户持有人的 CPF 或 CNPJ（仅数字）。| 0 |

### target_account 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---| ---|
| `account_branch` * | string | 机构号。 | 10 |
| `account_digit` * | string | 账户检验位 | 10 |
| `account_number` * | string | 账户号。 | 10 |
| `owner_document_number` * | string | 账户持有人的 CPF 或 CNPJ（仅数字）。 | 10 |
| `owner_name` * | string | 账户持有人姓名。 | 10 |
| `account_type` * |string | 账户持有人的 CPF 或 CNPJ（仅数字）。| 10 |
| `trading_name` | string | 法人实体的商业名称。| 10 |
| `ispb` | string | 识别巴西支付系统转账准备金银行的八位代码。| 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\"}"
}

```

---

# 执行转账

URL: /zh-Hans/documentation/agendamentos/agendamento_ted

遵循与普通转账相同的原则，主要区别在于需要发送 schedule_date，届时您将收到 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

| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---| ---|
| `source_account` * | object | 来源账户。 | **[source_account 对象](#objeto-source_account)** | 
| `target_account` * | object | 目标账户。 | **[target_account 对象](#objeto-target_account)** | 
| `transaction_amount` * | double | 转账金额。 | 10 |
| `schedule_date` * | date | 交易预约日期，如未指定，转账将在发送时或审批后立即执行。 | 10 |

### source_account 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---| ---|
| `account_branch` * | string | 机构号。 | 10 |
| `account_digit` * | string | 账户检验位 | 10 |
| `account_number` * | string | 账户号。 | 10 |
| `owner_document_number` * | string | 账户持有人的 CPF 或 CNPJ（仅数字）。 | 10 |
| `target_account_type` * | string | 目标账户类型 | **[枚举值](#enumeradores-ted_account_type)** |

### target_account 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---| ---|
| `account_branch` * | string | 机构号。 | 10 |
| `account_digit` * | string | 账户检验位 | 10 |
| `account_number` * | string | 账户号。 | 10 |
| `owner_document_number` * | string | 账户持有人的 CPF 或 CNPJ（仅数字）。 | 10 |
| `owner_name` * | string | 账户持有人姓名。 | 10 |

### target_account_type 枚举值

| 枚举值 | 翻译 |
|---|---|
| checking_account | 支票账户 |
| deposit_account | 存款账户 |
| guaranteed_account | 担保账户 |
| investment_account | 投资账户 |
| payment_account | 支付账户 |
| saving_account | 储蓄账户 |

## Response
### 从自由活动账户转账

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"
}

```

### 从 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\"}"
}

```

---

# 取消预约

URL: /zh-Hans/documentation/agendamentos/cancelar_agendamento

## Request

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

Request Body

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

```

### Path Params

| 字段                          | 类型   | 描述                     |
|-------------------------------|--------|--------------------------|
| `SCHEDULED_TRANSACTION_KEY`   | string | 标识预约的密钥            |

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 一般说明：
只有在适用审批的情况下，已批准的预约才可取消！
:::

---

# 查询已预约交易

URL: /zh-Hans/documentation/agendamentos/consulta_agendamentos

## Request

ENDPOINT /account/ACCOUNT_KEY/scheduled_transactions
MÉTODO GET

### QUERY PARAMS

| 字段           | 描述                       |
|----------------|----------------------------|
| `status`       | 票据状态                   |
| `date`         | 预约日期                   |
| `page_number`  | 当前查询的页码             |
| `page_size`    | 每页结果数量               |

### Path Params

| 字段          | 描述                             |
|---------------|----------------------------------|
| `ACCOUNT_KEY` | 交易来源账户的 account_key       |

## 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 一般说明：
只有在适用审批的情况下，已批准的预约才会被列出！
:::

---

# arranjos_e_adquirentes

URL: /zh-Hans/documentation/arranjos_e_adquirentes/

## 支付安排与收单机构

### 收单机构

收单机构是指 Stone、Cielo、Rede 等公司，其职责是通过信用卡和借记卡清算金融交易。为此，它们与卡组织（品牌）和发卡银行（如 Nubank、Itaú、Santander 等）进行通信来处理交易。

收单机构列表：

| 名称 | 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|

### 支付安排

支付安排基本上是一套规则、法规和流程，用于提供金融服务，如取款、转账、信用卡和借记卡发行以及其他支付解决方案。

安排列表：

| 代码 | 描述 |
|---|---|
|ACC|Amex 信用卡|
|BCC|Banescard 信用卡|
|BCD|Banescard 借记卡|
|BVV|Banescard 借记卡|
|BVV|Ben Visa Vale|
|CAC|Cielo Amex 信用|
|CBC|Cabal 信用|
|CBD|Cabal 借记|
|CBP|Cabal 预付|
|CDC|Cielo Diners 信用卡|
|CEC|Cielo Elo 信用卡|
|CED|Cielo Elo 借记卡|
|CHC|Cielo Hipercard 信用|
|CMC|Cielo Mastercard 信用|
|CMD|Cielo Mastercard 借记|
|CZC|Credz 信用|
|DCC|Diners 信用卡|
|ECC|Elo 信用卡|
|ECD|Elo 借记卡|
|GCC|Goodcard 信用|
|GDC|Global Payments Diners 信用|
|GMC|Global Payments Mastercard 信用|
|GMD|Global Payments Mastercard 借记|
|GVC|Global Payments Visa 信用|
|GVD|Global Payments Visa 借记|
|HCC|Hipercard 信用卡|
|JCC|JCB 信用卡|
|MAC|Mais 信用卡|
|MCA|Mastercard ATM 卡|
|MCC|Mastercard 信用卡|
|MCD|Mastercard 借记卡|
|MCP|Mastercard 预付卡|
|OCD|Ourocard 借记卡|
|SCC|Sorocred 信用卡|
|SCD|Sorocred 借记卡|
|VCA|Visa ATM 卡|
|VCC|Visa 信用卡|
|VCD|Visa 借记卡|
|VCP|Visa 预付卡|
|VDC|Verdecard 信用卡|
|VIC|Visa 国际购买信用|
|VID|Visa 国际购买借记|
|HCD|Hiper 借记|
|SIC|Sicredi|
|BRS|Banrisul|
|CUP|Cup 信用|
|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|全部|

---

# 创建再协商

URL: /zh-Hans/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 注意！

再融资发行中使用的载荷与简单债务发行相同，另外需在 **"refinanced_credit_operations"** 中添加将被清偿的操作列表。
:::

### Body Params

| 字段                         | 类型   | 描述                         | 最大字符数 |
|------------------------------|--------|------------------------------|------------|
| **notification_type** *      | enum   | 通知类型                     | -          |
| **owner_person_type** *      | enum   | 账单查询对象的人员类型（自然人或法人） | -   |
| **owner_person_name** *      | string | 账单查询对象的姓名           | -          |
| **owner_document_number** *  | string | 账单查询对象的证件号码       | -          |
| **reference_code** *         | object | opt-in 的唯一标识符          | -          |
| **signature** *              | object | opt-in 信息                  | -          |
| **agenda** *                 | object | 账单查询参数                 | -          |

## 定义

### agenda 对象

| 字段               | 类型   | 描述                         | 最大字符数 |
|------------------|--------|------------------------------|------------|
| **acquirers** *  | array  | 收单机构证件号码列表         | -          |
| **card_schemes** * | array | 支付安排列表               | -          |
| **end_date** *   | string | 查询结束日期                 | -          |
| **start_date** * | string | 查询开始日期                 | -          |

# 枚举值

### Person Type 枚举值

| 枚举值      | 描述   |
|------------|--------|
| **legal**  | 法人   |
| **natural** | 自然人 |

### Account Type 枚举值

| 枚举值       | 描述   |
|------------|--------|
| **webhook** | 活期账户 |

## 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: /zh-Hans/documentation/arranjos_e_adquirentes/trava_de_domicilio_bancario

若客户希望以应收款为担保进行信贷操作，QI Tech 联合 CERC 可以通过与普通债务发行流程非常相似的方式创建该操作。

# 创建再协商

## 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
      }
    ],
    "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 注意！

再融资发行中使用的载荷与简单债务发行相同，另外需在 **"refinanced_credit_operations"** 中添加将被清偿的操作列表。
:::

### Body Params

| 字段                               | 类型             | 描述                                                                                | 最大字符数 |
|------------------------------------|------------------|-------------------------------------------------------------------------------------|------------|
| **borrower** *                     | object           | **[Borrower 对象](#objeto-borrower)** - 信贷操作的债务人。                          | -          |
| **disbursement_bank_account** *    | object           | **[Disbursement Bank Account 对象](#objeto-disbursement_bank_accounts)** - 操作拨付的银行账户数据。 | -  |
| **financial** *                    | object           | **[Financial 对象](#objeto-financial)** - 信贷操作的财务数据。                      | -          |
| **purchaser_document_number** *    | string           | 信贷操作受让人（购买方）的 CNPJ。                                                   | -          |
| **refinanced_credit_operations** * | array of objects | **[Refinanced Credit Operations 对象](#objeto-refinanced_credit_operations)** 列表，包含被再融资的操作。 | - |

## 定义

### Request Body 对象

| 字段                               | 类型   | 描述                                                                                | 最大字符数 |
|------------------------------------|--------|-------------------------------------------------------------------------------------|------------|
| **borrower** *                     | object | **[Borrower 对象](#objeto-borrower)** - 信贷操作的债务人                            | -          |
| **disbursement_bank_account** *    | object | **[Disbursement Bank Account 对象](#objeto-disbursement_bank_accounts)** - 操作拨付的银行账户数据 | -  |
| **financial** *                    | object | **[Financial 对象](#objeto-financial)** - 信贷操作的财务数据                        | -          |
| **purchaser_document_number** *    | string | 信贷操作受让人（购买方）的 CNPJ                                                     | -          |
| **contract** *                     | object | **[Contract 对象](#objeto-contract)** - 包含担保数据的合同对象                      | -          |

### Borrower 对象

| 字段                               | 类型    | 描述                                                                                        | 最大字符数 |
|------------------------------------|---------|--------------------------------------------------------------------------------------------|------------|
| **name** *                         | string  | 债务人姓名                                                                                  | 100        |
| **email**                          | string  | 债务人电子邮件                                                                              | 254        |
| **phone**                          | object  | **[Phone 对象](#objeto-phone)** - 债务人联系电话                                            | -          |
| **is_pep** *                       | boolean | PEP 指示符                                                                                  | -          |
| **address** *                      | object  | **[Address 对象](#objeto-address)** - 债务人地址                                            | -          |
| **role_type** *                    | enum    | 默认值：_issuer_                                                                            | -          |
| **birth_date** *                   | date    | 债务人出生日期（格式："YYYY-MM-DD"）                                                        | -          |
| **mother_name** *                  | string  | 债务人母亲姓名                                                                              | 100        |
| **nationality**                    | string  | 债务人国籍                                                                                  | 50         |
| **person_type** *                  | string  | 自然人指示符 - 默认值：_natural_                                                            | -          |
| **individual_document_number** *   | string  | 债务人 CPF（仅数字）                                                                        | 11         |
| **document_identification** *      | string  | 债务人带照片身份证件 PDF 的 **DOCUMENT_KEY**（RG 或 CNH）                                   | -          |
| **document_identification_back**   | string  | 身份证件背面 PDF 的 DOCUMENT_KEY（已预先提交）                                              | 11         |
| **wedding_certificate**            | string  | 结婚证书 PDF 的 DOCUMENT_KEY（已预先提交）。若 marital_status 为 "single"，值应为 NULL。    | 11         |
| **proof_of_residence** *           | string  | 所发送地址的居住证明 PDF 的 DOCUMENT_KEY（已预先提交）                                      | 11         |

### Address 对象

| 字段               | 类型   | 描述                          | 最大字符数 |
|--------------------|--------|-------------------------------|------------|
| **city** *         | string | 地址城市                      | 100        |
| **state** *        | string | 地址州（两位大写字母）        | 2          |
| **number** *       | string | 地址门牌号                    | 10         |
| **street** *       | string | 地址街道                      | 100        |
| **complement** *   | string | 地址补充信息（自由文本）      | 100        |
| **postal_code** *  | string | 邮政编码                      | 8          |
| **neighborhood** * | string | 地址社区                      | 100        |

### Phone 对象

| 字段               | 描述                    | 示例 | 最大字符数 |
|--------------------|-------------------------|------|------------|
| **number** *       | 电话号码                |      | 10         |
| **area_code** *    | 地区区号（DDD）         |      | 2          |
| **country_code** * | 国际区号（DDI）         |      | 3          |

### Disbursement Bank Account 对象

债务发行必须包含拨付的银行账户信息，默认为债务人名下的账户。

| 字段                  | 类型   | 描述                                          | 最大字符数 |
|-----------------------|--------|-----------------------------------------------|------------|
| name                  | string | 账户持有人姓名                                | 50         |
| document_number       | string | 账户持有人 CPF                                | 11         |
| bank_code *           | string | 金融机构 COMPE 代码（3 位数字）               | 3          |
| branch_number *       | string | 支行号码（不包含支行验证码）                  | 4          |
| account_number *      | string | 账户号码（不含账户验证码）                    | 10         |
| account_digit *       | string | 账户验证码（字母位置以零代替）                | 1          |
| account_type          | enum   | **[Account Type 枚举值](#enumerador-account-type)** - 账户类型 | 1 |

### Financial 对象

Financial 对象描述信贷操作的财务信息。

| 字段                       | 类型   | 描述                                                                                            | 最大字符数 |
|----------------------------|--------|-------------------------------------------------------------------------------------------------|------------|
| **amount**                 | float  | 信贷操作的发行/名义金额                                                                         | -          |
| **interest_type**          | object | **[Interest Type 枚举值](#enumerador-interest-type)** - 摊销方式和利息计算方法                  | -          |
| **credit_operation_type**  | object | **[Credit Operation Type 枚举值](#enumerador-credit-operation-type)** - 信贷合同类型             | -          |
| **annual_interest_rate**   | float  | 以年化小数表示的固定利率                                                                        | -          |
| **disbursement_date**      | date   | 操作拨付日期                                                                                    | -          |
| **interest_grace_period**  | int    | 利息宽限期（月）                                                                                | -          |
| **principal_grace_period** | int    | 本金宽限期                                                                                      | -          |
| **number_of_installments** | int    | 信贷操作的分期数                                                                                | -          |
| **fine_configuration**     | object | **[Fine Configuration 对象](#objeto-fine-configuration)** - 逾期利息和罚款配置                  | -          |

### Fine Configuration 对象

Fine Configuration 对象描述信贷操作的逾期罚款和利息值。

| 字段                   | 类型  | 描述                                                                            | 最大字符数 |
|------------------------|-------|---------------------------------------------------------------------------------|------------|
| **contract_fine_rate** | float | 逾期罚款百分比                                                                  | -          |
| **interest_base**      | enum  | **[Interest Base 枚举值](#enumerador-interest-base)** - 利息计算基准            | -          |
| **monthly_rate**       | float | 月逾期利息百分比                                                                | -          |

### Contract 对象

Contract 对象描述信贷操作的财务信息。

| 字段                       | 类型   | 描述                                                                                              | 最大字符数 |
|----------------------------|--------|---------------------------------------------------------------------------------------------------|------------|
| **payment_account**        | object | 应收款的支付账户。                                                                                | -          |
| **collaterals**            | array  | 担保品列表。                                                                                      | -          |
| **collateral_management**  | object | **[Collateral Management 对象](#objeto-collateral-management)** - 担保配置。                      | -          |

### Collateral Management 对象

Collateral Management 对象描述信贷操作的财务信息。

| 字段                          | 类型   | 描述                                                                                                              | 最大字符数 |
|-------------------------------|--------|-------------------------------------------------------------------------------------------------------------------|------------|
| **collateral_management_type** | enum  | **[Collateral Management Type 枚举值](#enumerador-collateral-management-type)** - 用于摊还债务的管理类型。        | -          |
| **amount**                    | float  | 将被使用的金额。                                                                                                  | -          |
| **maximum_value**             | float  | 用于支付操作的最大金额。                                                                                          | -          |
| **maximum_daily_value**       | float  | 每日使用的最大金额。                                                                                              | -          |
| **minimum_date**              | string | 开始使用应收款的最早日期。                                                                                        | -          |
| **contract_payment_type**     | enum   | **[Credit Operation Type 枚举值](#enumerador-credit-operation-type)** - 合同支付类型                             | -          |

# 枚举值

### Person Type 枚举值

| 枚举值      | 描述   |
|------------|--------|
| **legal**  | 法人   |
| **natural** | 自然人 |

### Account Type 枚举值

| 枚举值                  | 描述       |
|------------------------|------------|
| **checking_account**   | 活期账户   |
| **deposit_account**    | 存款账户   |
| **guaranteed_account** | 担保账户   |
| **investment_account** | 投资账户   |
| **payment_account**    | 支付账户   |
| **saving_account**     | 储蓄账户   |
| **salary_account**     | 工资账户   |

### Interest Type 枚举值

| 枚举值               | 描述                                                                                                            |
|----------------------|----------------------------------------------------------------------------------------------------------------|
| **pre_price_days**   | Price 摊销法（等额还款），按日计算固定利率                                                                      |
| **pre_price**        | Price 摊销法（等额还款），按固定期间（30 天）计算固定利率                                                       |
| **pre_sac**          | SAC 摊销法（固定摊还），按日计算固定利率                                                                        |
| **post_sac**         | SAC 摊销法（固定摊还），按日基于固定利率 + 浮动指数（cdi、ipca 或 igpm）计算利率                               |
| **post_price**       | Price 摊销法（等额还款），按固定期间（30 天）基于固定利率 + 浮动指数（cdi、ipca 或 igpm）计算利率              |
| **post_price_days**  | Price 摊销法（等额还款），按日基于固定利率 + 浮动指数（cdi、ipca 或 igpm）计算利率                             |

### Credit Operation Type 枚举值

| 枚举值     | 描述                   |
|-----------|------------------------|
| **ccb**   | 银行信贷凭证           |
| **cce**   | 出口信贷凭证           |
| **cci**   | 房地产信贷凭证         |
| **nce**   | 出口信贷票据           |

### Interest Base 枚举值

| 枚举值                 | 描述                                       |
|-----------------------|--------------------------------------------|
| **workdays**          | 以工作日为利息计算基准，一年 252 个工作日   |
| **calendar_days**     | 以自然日为利息计算基准，一年 360 天        |
| **calendar_days_365** | 以自然日为利息计算基准，一年 365 天        |

### Fee Type 枚举值

每种费用类型须由 QI Tech 预先启用和配置

| 枚举值                | 描述                                   |
|----------------------|----------------------------------------|
| **tac**              | 开户手续费                              |
| **spread**           | 信贷操作收购价值中收取的溢价            |
| **warranty_analysis** | 担保分析费用                           |
| **ted_fee**          | TED 手续费                              |
| **spread_ted_fee**   | TED 手续费中收取的溢价                  |

### Collateral Management Type 枚举值

| 枚举值         | 描述       |
|--------------|------------|
| **absolute** | 绝对值     |
| **percentage** | 百分比值  |

### Payment Type 枚举值

| 枚举值               | 描述       |
|--------------------|------------|
| **partial_payment** | 部分支付   |
| **total_payment**  | 全额支付   |
| **monthly_payment** | 月度支付   |

## 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": 33,
        "digitable_line": null,
        "due_date": "2023-04-03",
        "due_interest": null,
        "due_principal": 123456,
        "fine_amount": null,
        "has_interest": true,
        "installment_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "installment_number": 1,
        "installment_payment": [],
        "installment_status": "created",
        "installment_type": "principal",
        "original_due_principal": 123456,
        "original_pre_fixed_amount": 12345.67,
        "original_principal_amortization_amount": 61728,
        "original_total_amount": null,
        "paid_amount": 0,
        "paid_at": null,
        "payments": [],
        "post_fixed_amount": null,
        "pre_fixed_amount": 12345.67,
        "principal_amortization_amount": 61728,
        "tax_amount": 469.13,
        "total_amount": null,
        "total_paid_amount": 0,
        "workdays": 23
      }
    ],
    "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": null,
      "daily_rate": 0.0033388,
      "interest_base": "calendar_days",
      "monthly_rate": 0.10516767
    },
    "requester_identifier_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "total_iof": 942.82,
    "total_pre_fixed_amount": 12345.67
  },
  "event_datetime": "2023-03-02 23:48:16",
  "key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "waiting_signature",
  "webhook_type": "debt"
}
```

---

# emissao_de_divida

URL: /zh-Hans/documentation/auxilio_brasil/emissao_de_divida

## 债务发行

## Request

- ENDPOINT /debt
- MÉTODO POST
- BODY （签名前）：

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

| 字段                                   | 描述                                    |
|--------------------------------------|----------------------------------------|
| `borrower` *（必填）                  | 借款人数据。                            |
| `guarantors`                         | 操作的担保人（可以是自然人和/或法人的列表，非必填字段）。 |
| `collaterals` *（必填）               | 支付分期信息。                          |
| `financial` *（必填）                 | 财务对象描述发行的财务信息，包括利率、宽限期和债务金额等。 |
| `disbursement_bank_accounts`         | 用于拨付的银行账户信息列表（银行账户对象）。 |

### BORROWER 对象

| 字段                                     | 描述                                                                                  |
|----------------------------------------|--------------------------------------------------------------------------------------|
| `person_type` *（必填）                 | 标识发送的对象是自然人还是法人。                                                       |
| `name` *（必填）                        | 人员姓名，最多 100 个字符。                                                            |
| `mother_name`                          | 母亲姓名                                                                              |
| `birth_date`                           | 人员出生日期（格式："YYYY-MM-DD"）                                                    |
| `profession`                           | 人员职业                                                                              |
| `nationality`                          | 客户国籍，最多 50 个字符。                                                             |
| `marital_status`                       | 客户婚姻状况。                                                                         |
| `property_system`                      | 财产分割制度（仅在 marital_status 为 "married" 时必填）。                              |
| `wedding_certificate`                  | 结婚证书 PDF 的 DOCUMENT_KEY（已预先提交）。若 marital_status 为 "single"，该字段值应为 NULL。 |
| `spouse`                               | 配偶的自然人对象（仅在 "compulsory_separation_of_goods" 为特定值时必填）。若 marital_status 为 "single"，该字段值应为 NULL。 |
| `is_pep` *（必填）                      | 声明该人员是否为政治公开人士（布尔值）                                                 |
| `individual_document_number`           | CPF（仅数字）                                                                         |
| `document_identification` *（必填）     | 带照片身份证件 PDF 的 DOCUMENT_KEY（已预先提交）                                       |
| `document_identification_back`         | 身份证件背面 PDF 的 DOCUMENT_KEY（已预先提交）                                         |
| `document_identification_type`         | 身份证件类型，枚举值接受 "rg" 或 "cnh"                                                |
| `document_identification_number` *（必填） | document_identification 中发送的证件编号                                           |
| `email`                                | 人员电子邮件                                                                          |
| `phone`                                | 人员电话                                                                              |
| `address`                              | 人员地址                                                                              |
| `proof_of_residence` *（必填）          | 所发送地址的居住证明 PDF 的 DOCUMENT_KEY（已预先提交）                                 |

### GUARANTORS 对象

| 字段                                     | 描述                                                                                  |
|----------------------------------------|--------------------------------------------------------------------------------------|
| `person_type` *（必填）                 | 标识发送的对象是自然人还是法人。                                                       |
| `name` *（必填）                        | 人员姓名，最多 100 个字符。                                                            |
| `mother_name` *（必填）                 | 自然人情况下的母亲姓名，最多 100 个字符。                                              |
| `birth_date` *（必填）                  | 人员出生日期（格式："YYYY-MM-DD"）                                                    |
| `profession` *（必填）                  | 客户职业，最多 64 个字符。                                                             |
| `nationality` *（必填）                 | 客户国籍，最多 50 个字符。                                                             |
| `marital_status` *（必填）              | 客户婚姻状况。                                                                         |
| `property_system`                      | 财产分割制度（仅在 marital_status 为 "married" 时必填）。                              |
| `wedding_certificate` *（必填）         | 结婚证书 PDF 的 DOCUMENT_KEY（已预先提交）。若 marital_status 为 "single"，值应为 NULL。 |
| `spouse` *（必填）                      | 配偶的自然人对象（仅在特定条件下必填）。若 marital_status 为 "single"，值应为 NULL。   |
| `is_pep` *（必填）                      | 声明该人员是否为政治公开人士。                                                         |
| `individual_document_number` *（必填）  | CPF（仅数字），最多 11 个字符。                                                        |
| `document_identification` *（必填）     | 带照片身份证件 PDF 的 DOCUMENT_KEY（已预先提交）                                       |
| `document_identification_back`         | 身份证件背面 PDF 的 DOCUMENT_KEY（已预先提交）                                         |
| `document_identification_type`         | 所发送身份证件的类型。                                                                 |
| `document_identification_number` *（必填） | "document_identification" 中发送的证件编号，最多 16 个字符。                       |
| `email`                                | 人员电子邮件                                                                          |
| `phone`                                | 人员电话                                                                              |
| `proof_of_residence` *（必填）          | 所发送地址的居住证明 PDF 的 DOCUMENT_KEY（已预先提交）                                 |
| `address`                              | 人员地址                                                                              |

### SPOUSE 对象

| 字段                                     | 描述                                                                                  |
|----------------------------------------|--------------------------------------------------------------------------------------|
| `person_type` *（必填）                 | 标识发送的对象为自然人，始终为 "natural"                                               |
| `name` *（必填）                        | 人员姓名                                                                              |
| `mother_name` *（必填）                 | 母亲姓名                                                                              |
| `birth_date` *（必填）                  | 出生日期（格式："YYYY-MM-DD"）                                                        |
| `profession` *（必填）                  | 职业                                                                                  |
| `nationality` *（必填）                 | 国籍                                                                                  |
| `marital_status` *（必填）              | 婚姻状况："single"、"married"、"widower" 或 "divorced"                               |
| `property_system`                      | 财产分割制度（仅在 marital_status 为 "married" 时必填）                               |
| `wedding_certificate` *（必填）         | 结婚证书 PDF 的 DOCUMENT_KEY（已预先提交）。若 marital_status 为 "single"，值应为 null。 |
| `spouse` *（必填）                      | 配偶的自然人对象（仅在特定条件下必填）。若 marital_status 为 "single"，值应为 null。   |
| `is_pep` *（必填）                      | 声明该人员是否为政治公开人士（布尔值）                                                 |
| `individual_document_number` *（必填）  | CPF（仅数字）                                                                         |
| `document_identification` *（必填）     | 带照片身份证件 PDF 的 DOCUMENT_KEY（已预先提交）                                       |
| `document_identification_back`         | 身份证件背面 PDF 的 DOCUMENT_KEY（已预先提交）                                         |
| `document_identification_type`         | 身份证件类型，枚举值接受 "rg" 或 "cnh"                                                |
| `document_identification_number` *（必填） | document_identification 中发送的证件编号                                           |
| `email`                                | 人员电子邮件                                                                          |
| `phone`                                | 人员电话                                                                              |
| `proof_of_residence` *（必填）          | 居住证明 PDF 的 DOCUMENT_KEY（已预先提交）                                             |
| `address`                              | 人员地址                                                                              |

### PHONE 对象

| 字段                          | 描述                                    |
|-----------------------------|-----------------------------------------|
| `country_code` *（必填）     | 电话国际区号（DDI，须为 3 位数字）       |
| `area_code` *（必填）        | 电话地区区号（DDD）                      |
| `number` *（必填）           | 电话号码（仅数字）                       |
| `document_number` *（必填）  | 签署人证件号码                           |

### ADDRESS 对象

| 字段                        | 描述                               |
|---------------------------|------------------------------------|
| `street` *（必填）          | 地址街道                           |
| `state` *（必填）           | 地址州（两位大写字母）             |
| `city` *（必填）            | 地址城市                           |
| `neighborhood` *（必填）    | 地址社区                           |
| `number` *（必填）          | 街道门牌号                         |
| `postal_code` *（必填）     | 邮政编码（仅数字）                 |
| `complement` *（必填）      | 地址补充信息（自由文本）           |

### OCR 对象

| 字段  | 描述                               |
|-----|-----------------------------------|
| `ocr` | 用于提交 OCR SDK 生成密钥的对象   |

### COLLATERALS 对象

| 字段                         | 描述                                                      |
|----------------------------|----------------------------------------------------------|
| `collateral_data`          | 操作担保品列表。                                          |
| `percentage`               |                                                          |
| `collateral_type` *（必填） | 担保品类型。对于 Auxílio Brasil 须为 "social_benefit"    |

### COLLATERAL DATA 对象

| 字段                       | 描述                                         |
|--------------------------|----------------------------------------------|
| `reservation_period`     | 作为担保品冻结的福利期间                      |
| `reservation_amount`     | 作为担保品冻结的福利金额                      |
| `family_code`            | 福利家庭编码                                  |
| `state`                  | 福利家庭所在州（UF）                          |
| `financial_education_term` | 公民部要求的财务教育条款的回答             |

### FINANCIAL EDUCATION TERM 对象

| 字段        | 描述 |
|-----------|------|
| `questions` |      |

### QUESTIONS 对象

| 字段     | 描述 |
|--------|------|
| `answer` |      |

### FINANCIAL 对象

| 字段                              | 描述                                                        |
|---------------------------------|-------------------------------------------------------------|
| `desired_installments`          | 分期付款列表。                                               |
| `interest_type` *（必填）        | 操作的利息类型。                                             |
| `disbursement_start_date`       | 拨付期开始日期（格式："YYYY-MM-DD"）。                       |
| `disbursement_end_date`         | 拨付期结束日期（格式："YYYY-MM-DD"）。                       |
| `annual_interest_rate` *（必填） | 固定利息分期的百分比值（注意：1 = 100%）                    |
| `credit_operation_type` *（必填） | 信贷操作类型。                                             |
| `interest_grace_period`         | 利息宽限期（月）                                            |
| `number_of_installments`        | 分期数（月）                                                |
| `principal_grace_period`        | 本金宽限期（月）                                            |

### DESIRED INSTALLMENTS 对象

| 字段           | 描述         |
|--------------|--------------|
| `due_date`   | 分期日期。    |
| `total_amount` | 分期总金额  |

### REBATES 对象

| 字段                    | 描述                        |
|-----------------------|-----------------------------|
| `amount`              | 折扣金额。                   |
| `fee_type`            | 费用类型                     |
| `amount_type`         | 输入值的类型（绝对值或百分比）|
| `rebate_bank_account` | 折扣银行账户对象。            |

### FINE CONFIGURATION 对象

| 字段                          | 描述                                                              |
|-----------------------------|-------------------------------------------------------------------|
| `contract_fine_rate` *（必填） | 罚款固定百分比值                                                 |
| `interest_base`             | 罚款计时方式（"calendar_days" 为自然日，"workdays" 为工作日）    |
| `monthly_rate`              | 月罚款百分比值                                                    |

### DISBURSEMENT BANK ACCOUNT 对象

| 字段                       | 描述                                                                                                        |
|--------------------------|-------------------------------------------------------------------------------------------------------------|
| `name`                   | 拨付账户持有人姓名 - 仅在转账方式为 ted 或 pix 且存在多个拨付账户时必填（最多 80 个字符）。               |
| `bank_code`              | 金融机构 COMPE 代码（3 位数字）- 仅在转账方式为 ted 或 pix 且未发送 "ispb_number" 时必填。                |
| `branch_number`          | 支行号码 - 仅在转账方式为 ted 或 pix 时必填。                                                              |
| `account_number`         | 账户号码 - 仅在转账方式为 ted 或 pix 时必填。                                                              |
| `document_number`        | 拨付账户持有人的 CPF 或 CNPJ - 仅在转账方式为 ted 或 pix 且存在多个拨付账户时必填。                      |
| `percentage_receivable`  | 该账户在拨付中接收的百分比。用于多账户拨付时的金额分配。若未发送百分比，剩余部分将在无百分比设置的账户之间平均分配。若发送了所有百分比，总和不能超过 100 - 仅在转账方式为 ted 或 pix 时必填。 |
| `ispb_number`            | 巴西支付系统中机构标识符 - 仅在转账方式为 ted 或 pix 且未发送 "bank_code" 时必填。                       |
| `qr_code_key`            | 创建 PIX QR Code 时提供的密钥 - 可作为该对象的唯一参数发送，拨付将作为该 PIX QR Code 的付款进行。         |
| `digitable_line`         | Boleto 条形码的数字表示 - 可作为该对象的唯一参数发送，拨付将作为该 Boleto 的付款进行。                    |
| `transfer_method`        | 默认情况下操作通过 PIX 拨付，若需要通过 TED 拨付时可发送此字段。                                          |

---

# webhook_auxilio_brasil

URL: /zh-Hans/documentation/auxilio_brasil/webhook_auxilio_brasil

## Auxílio Brasil Webhook

**创建操作**

在我们系统中创建 Auxílio Brasil 操作时，可能出现以下状态：

- **success**：表示福利查询成功。
- **failure**：表示福利查询过程中发生错误。

**示例**

查询成功 Webhook

**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

**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"
    }
}

```

| 枚举值 | 描述 |
|---|---|
| `dataprev_error`  | Dataprev 意外错误 |
| `not_found_family_member` | 该人员没有有效授权 |
| `benefit_deleted`  | 福利已被删除 |

**取消操作**

有几种情况会导致信贷操作被取消，主要包括：

1. PIX/TED 失败或被冲销；
2. 已过放款日期；
3. 背书申请被拒绝；

我们系统中所有已取消的操作都可以通过修改放款日期的方式恢复到之前的状态。
某些情况无法恢复到初始状态，因为永远不会放款，例如第3种情况——背书申请被拒绝。

第一种情况：

**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"
}

```

reason_enumerator 可以是以下列表中的值：

| 枚举值 | 描述 |
|---|---|
| `invalid_document_number`  | 无效证件号 |
| `invalid_account` | 无效账户 |
| `unsupported_transaction`  | 不支持的交易 |
| `blocked_account`  | 账户已冻结 |
| `closed_account`  | 账户已关闭 |
| `rejected_payment`  | 支付被拒绝 |
| `amount_too_great`  | 金额过高 |
| `spi_timeout`  | 服务提供商超时 |
| `receiver_error`  | 接收方错误 |
| `incorrect_account_type`  | 账户类型不正确 |
| `duplicity_of_payment_order`  | 重复支付订单 |
| `refund_after_unexpected_value`  | 意外金额后的退款 |
| `refund_after_psp_error`  | PSP 错误后的退款 |
| `refund_after_technical_issues`  | 技术问题后的退款 |
| `refund_after_cancellation`  | 取消后的退款 |
| `refund_after_fraud`  | 欺诈后的退款 |
| `refund_after_payee_request`  | 收款方申请后的退款 |
| `refund_after_fraud_report`  | 欺诈报告后的退款 |
| `payee_not_in_allowed_list`  | 收款方不在许可列表中 |
| `payee_in_blocked_list`  | 收款方在黑名单中 |
| `unjustified_payment_order`  | 无依据支付订单 |

第二种情况，当某个内部流程触发操作取消时：

**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"
}

```

此处可能出现以下 "cancel_reason_enumerators"：

- PAB 拒绝中的取消原因枚举值：

| 枚举值 | 描述 |
|---|---|
| `social_benefit_ineligible_benefit`  | 不符合条件的福利 |
| `social_benefit_invalid_beneficiary_data` | 受益人数据无效 |
| `social_benefit_invalid_balance`  | 可用额度不足 |
| `social_benefit_contract_limit_exceeded`  | 客户不能拥有更多合同 |
| `social_benefit_installments_limit_exceeded`  | 客户在一份合同中不能有这么多分期 |
| `social_benefit_invalid_disbursement_account`  | 账户与 DataPrev 不符 |

- 日期变更取消原因枚举值

| 枚举值 | 描述 |
|---|---|
| `not_collateral_constituted_social_benefit`  | 日期已变更，操作的担保未被背书 |
| `waiting_signature` | 日期已变更，操作未被签署 |
| `not_assigned`  | 日期已变更，CCB 被配置为转让后放款，但未被转让 |
| `disburse_is_not_allowed`  | 日期已变更，CCB 被配置为"放款授权"流程，但尚未授权 |
| `manual`  | 日期已变更，操作未被放款。 |

以 "social_benefit" 开头的取消原因是永久性的，表示背书请求确实被拒绝了。但其他情况仍可恢复到初始状态，需仔细分析。

---

# 确认开立个人账户

URL: /zh-Hans/documentation/baas/account/2fa_v2/abrir_conta_pf

作为个人账户开立的第二步，[完成账户预留后](/documentation/baas/account/abrir_conta_pf)，需要提交账户持有人的完整注册信息及账户开立条款的接受证明。

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

## Path Params
| 字段         | 类型   | 描述                              | 字符数 |
|---------------|--------|----------------------------------------|------------|
| `account_request_key` | uuidv4 | 账户预留请求的唯一标识键。 | 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 参数

| 字段 | 类型 | 描述                                                                                  | 字符数 |
|---|---|--------------------------------------------------------------------------------------------|---|
| `account_owner` * | object  | 包含账户持有人信息的对象                                         | **[account_owner 对象](#objeto-account_owner)** |
| `signed_contract` * | object  | 包含持有人接受账户开立条款证明的对象。 | **[signed_contract 对象](#objeto-signed_contract)** |

### account_owner 对象

| 字段 | 类型 | 描述 | 字符数                            |
|---| ---| ---|---------------------------------------| 
| `address` * | string | 客户地址。 | **[address 对象](#objeto-address)** |  |
| `birth_date` * | string | 出生日期（格式 "YYYY-MM-DD"） |                                       |
| `document_identification` * | string | 附有照片的身份证明文件（RG 或 CNH）PDF 的 DOCUMENT_KEY（预先上传） |                                       |
| `document_identification_type` * | string | 预先上传的文件类型（RG 或 CNH） |                                       |
| `email` * | string | 客户电子邮件。 |                                       |
| `individual_document_number` | string | 个人 CPF（仅数字），最多 11 个字符。 |                                       |
| `is_pep` * | string | 声明该人是否为 PEP（http://www.portaldatransparencia.gov.br/download-de-dados/pep）。|                                       |
| `mother_name` * | string | 个人账户持有人母亲姓名。 | 100                                   |
| `name` * | string | 企业法定名称（PJ）或个人姓名（PF）。 | 100                                   |
| `nationality` * | string | 客户国籍。 | 50                                    |
| `person_type` * | string | 标识所提交对象为自然人或法人。|                                       |
| `phone` * | string | 电话数据对象 | **[phone 对象](#objeto-phone)**     |
| `proof_of_residence` | string | 所提供地址的居住证明 PDF 的 DOCUMENT_KEY（预先上传）。|                                       |

### address 对象

此对象出现在 PF 和 PJ 对象中，用于表示地址信息。

| 字段 | 描述 | 示例 |  最大字符数 | 
|---|---|---|---| 
| `street` *| string | 街道地址  | 100 |
| `state` *| string | 州（两位大写字母） | 2 |
| `city` *| string | 城市 | 100 |
| `neighborhood` *| string | 区/社区 | 100 |
| `number` *| string | 门牌号 | 10 |
| `postal_code` *| string | 邮政编码（http://www.buscacep.correios.com.br/sistemas/buscacep/）（仅数字） |  8 |
| `complement` *| string | 地址补充信息（自由文本） | 100 |

### signed_contract 对象
| 字段 | 类型   | 描述        | 字符数    |
|-------|--------|------------------|---------------|
| **document_key** * | uuidv4 | **账户开立条款**或**托管账户合同**文件的唯一标识键。（DOCUMENT_KEY 由[文件上传](./upload_de_documentos)端点的响应返回） | 36            |
| **signatures** *   | list   | 所提交文件的签名数据。列表中每个项目对应文件的一个签署人。      | [signatures 对象](#objeto-signatures) |

### signatures 对象
| 字段 | 类型       | 描述         | 字符数        |
|-------|------------|-------------------|-------------------|
| **authenticity** * | object     | 证明签署人进行电子签名的数据集合。 | [authenticity 对象](#objeto-authenticity) |
| **signer** * | object     | 包含文件某一签署人数据的对象。           | [signer 对象](#objeto-signer)|
| **authentication_type** * | enumerator | 签名类型。始终为 "**opt-in**"| "**opt-in**"                   |

### authenticity 对象
| 字段 | 类型   | 描述               | 字符数 |
|-------|--------|-------------------------|------------|
| **timestamp** *            | string | 文件签署时的日期和时间。                | 27         |
| **facial_recognition_key** | uuidv4 | 账户持有人自拍照片的唯一标识键。（DOCUMENT_KEY 由[文件上传](./upload_de_documentos)端点的响应返回） | 36         |
| **lang**                   | string | 签署时捕获的签署人地理位置经度坐标。                  | -          |
| **lat**                    | string | 签署时捕获的签署人地理位置纬度坐标。                   | -          |
| **ip_address**             | string | 签署人设备的 IP 地址。     | -          |
| **session_id**             | string | 签署时签署人的会话 ID。                | -          |

### signer 对象
| 字段                 | 类型   | 描述                                 | 字符数                        |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| **name** *            | string | 签署人姓名。                        | -                                 |
| **email** *           | string | 签署人电子邮件。                       | -                                 |
| **phone** *           | object | 签署人电话数据对象 | **[phone 对象](#objeto-phone)** |
| **document_number** * | string | 签署人 CPF。                         | 11                                |

### phone 对象

| 字段 | 描述 | 示例 |  最大字符数 | 
| --- | --- | --- | --- | 
|`country_code` *| string | 电话国际区号（https://ddi.guiamais.com.br/） | 3 | 
| `area_code` *| string | 区号（https://ddd.guiamais.com.br/） | 2 |
| `number` *| string | 电话号码（仅数字） |  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 注意
 `account_request_key` 字段需要保存，将用于确认账户开立。
:::

### Response Body 参数

| 字段 | 类型 | 描述 | 字符数|
|---|---| ---|---|
| `account_info` * | object  | 包含账户持有人信息的对象 |**[account_info 对象](#objeto-account_info)**  | - |
| `account_request_key` * | string  | 创建请求的标识键 | - | - |
| `account_request_status` * | string  | KYC 状态 | - | - |

### account_info 对象
| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---| --- |
| `account_branch` * | string  | 支行号 | 4 |
| `account_digit` * | string  | 电子邮件 | 11 |
| `account_number` * | string  | 账户持有人全名 | 50 |

STATUS 4xx

Response Body: Error

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`  | 描述（英文）<br/>`description` | 描述（葡文）<br/>`translation`|
|---| --- | --- | --- | --- | 
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema|
| 404 | QIT000404 | Not Found | Resource could not be found | Recurso não encontrado|

---

# 开立企业账户

URL: /zh-Hans/documentation/baas/account/2fa_v2/abrir_conta_pj

账户开立分两个必要步骤。首先，通过 POST 请求发送初步数据以预留账户。随后，系统触发状态为 `pending_additional_data` 的 `account_request.status_change` 类型 webhook。在第二步中，通过 PATCH 请求完成账户开立，以补充信息正式确认账户。

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

## Path Params
| 字段         | 类型   | 描述                              | 字符数 |
|---------------|--------|----------------------------------------|------------|
| `account_request_key` | uuidv4 | 账户预留请求的唯一标识键。 | 36         |

## 开立自由流动账户

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 参数

| 字段                 | 类型   | 描述                                                                    | 字符数                                            |
|-----------------------|--------|------------------------------------------------------------------------------|-------------------------------------------------------|
| **account_owner** *   | object | 账户所有者对象                                                         | **[account_owner 对象](#objeto-account_owner)**     |
| **allowed_user** *    | object | 与账户关联的用户。                                                   | **[allowed_user 对象](#objeto-allowed_user)**       |
| **account_manager**   | object | 将通过 API 操作账户的合作集成商数据。  | **[account_manager 对象](#objeto-account_manager)** |
| `signed_contract` *| object | 包含合同签署信息的对象。 | **[signed_contract 对象](#objeto-signed_contract)** |

### account_owner 对象

| 字段                         | 类型   | 描述                                                                                                                         | 字符数                                                            |
|-------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|
| **address** *                 | object | 账户持有人地址对象                                                                                               | **[address 对象](#objeto-address)**                                 |
| **cnae_code** *               | string | 国家经济活动分类代码                                                                                   | 9                                                                     |
| **company_document_number** * | string | CNPJ                                                                                                                              | 14                                                                    |
| **company_statute** *         | string | 公司章程 PDF 的 DOCUMENT_KEY（预先上传）。                                                                 | 36                                                                    |
| **company_type**              | enum   | 公司类型                                                                                                                   | **[company_type 枚举值](#enumeradores-company_type)**           |
| **company_representatives** * | list   | 公司法定代表人列表                                                                                        | **[company_representatives 对象](#objeto-company_representatives)** |
| **email** *                   | string | 公司机构电子邮件。                                                                                                                   | 254                                                                   |
| **foundation_date** *         | string | 公司成立日期（格式 "YYYY-MM-DD"）。                                                                               | 10                                                                    |
| **name** *                    | string | 公司法定名称。                                                                                                                     | 100                                                                   |
| **person_type** *             | enum   | 标识所提交对象为法人。PJ 对象始终应包含值 "legal"。                   | **[person_type 枚举值](#enumeradores-person_type)**             |
| **phone** *                   | object | 账户持有人电话。                                                                                                                     | **[phone 对象](#objeto-phone)**                                     | - |
| **trading_name** *            | string | 商业名称。                                                                                                                    | 200                                                                   |

### company_representatives 对象

| 字段                              | 类型    | 描述                                                                                              | 字符数                                                                              |
|------------------------------------|---------|--------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
| **name** *                         | string  | 公司代表姓名                                                                       | 100                                                                                     |
| **address** *                      | object  | 公司代表地址对象                                                            | **[address 对象](#objeto-address)**                                                   |
| **email** *                        | string  | 公司代表电子邮件                                                                      | 254                                                                                     |
| **birth_date** *                   | string  | 公司代表出生日期（格式 "YYYY-MM-DD"）                                     | 10                                                                                      |
| **individual_document_number** *   | string  | 公司代表 CPF（仅数字）。                                                      | 11                                                                                      |
| **document_identification**        | string  | 附有照片的身份证明文件（RG 或 CNH）PDF 的 DOCUMENT_KEY（预先上传） | 36                                                                                      |
| **document_identification_number** | string  | 附有照片的身份证明文件号码（RG 或 CNH）                                    | 16                                                                                      |
| **document_identification_type**   | enum    | 附有照片的身份证明文件类型（RG 或 CNH）                                      | [document_identification_type 枚举值](#enumeradores-document_identification_type) |
| **is_pep** *                       | boolean | 声明该人是否为 PEP（http://www.portaldatransparencia.gov.br/download-de-dados/pep）。          | -                                                                                       |
| **final_beneficiary**              | boolean | 声明该人是否为公司的最终受益人。                                                                             | -                                                                                       |
| **marital_status**                 | enum    | 公司代表婚姻状况                                                               | **[marital status 枚举值](#enumeradores-marital_status)**                         |
| **mother_name** *                  | string  | 公司代表母亲姓名                                                                | 100                                                                                     |
| **nationality**                    | string  | 公司代表国籍                                                              | 50                                                                                      |
| **person_type** *                  | enum    | 标识所提交对象为自然人                                              | **[person_type 枚举值](#enumeradores-person_type)**                               |
| **phone** * | object  | 公司代表电话数据对象  | **[phone 对象](#objeto-phone)** |

### address 对象

此对象出现在 PF 和 PJ 对象中，用于表示地址信息。

| 字段              | 描述 | 示例                                                                                   | 字符数 |
|--------------------|-----------|-------------------------------------------------------------------------------------------|------------|
| **street** *       | string    | 街道地址                                                                           | 500        |
| **state** *        | enum      | 州（两位大写字母）                                       | 2          |
| **city** *         | string    | 城市                                                                        | 255        |
| **neighborhood** * | string    | 区/社区                                                                        | 500        |
| **number** *       | string    | 门牌号                                                                             | 10         |
| **postal_code** *  | string    | 邮政编码（http://www.buscacep.correios.com.br/sistemas/buscacep/）（仅数字） | 8          |
| **complement**     | string    | 地址补充信息（自由文本）                                                                     | 500        |

### signed_contract 对象
| 字段 | 类型   | 描述        | 字符数    |
|-------|--------|------------------|---------------|
| **document_key** * | uuidv4 | **账户开立条款**或**托管账户合同**文件的唯一标识键。（DOCUMENT_KEY 由[文件上传](./upload_de_documentos)端点的响应返回） | 36            |
| **signatures** *   | list   | 所提交文件的签名数据。列表中每个项目对应文件的一个签署人。      | [signatures 对象](#objeto-signatures) |

### signatures 对象
| 字段 | 类型       | 描述         | 字符数        |
|-------|------------|-------------------|-------------------|
| **authenticity** * | object     | 证明签署人进行电子签名的数据集合。 | [authenticity 对象](#objeto-authenticity) |
| **signer** * | object     | 包含文件某一签署人数据的对象。           | [signer 对象](#objeto-signer)|
| **authentication_type** * | enumerator | 签名类型。始终为 "**opt-in**"| "**opt-in**"                   |

### authenticity 对象
| 字段 | 类型   | 描述               | 字符数 |
|-------|--------|-------------------------|------------|
| **timestamp** *            | string | 文件签署时的日期和时间。                | 27         |
| **facial_recognition_key** | uuidv4 | 账户持有人自拍照片的唯一标识键。（DOCUMENT_KEY 由[文件上传](./upload_de_documentos)端点的响应返回） | 36         |
| **lang**                   | string | 签署时捕获的签署人地理位置经度坐标。                  | -          |
| **lat**                    | string | 签署时捕获的签署人地理位置纬度坐标。                   | -          |
| **ip_address**             | string | 签署人设备的 IP 地址。     | -          |
| **session_id**             | string | 签署时签署人的会话 ID。                | -          |

### signer 对象
| 字段                 | 类型   | 描述                                 | 字符数                        |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| **name** *            | string | 签署人姓名。                        | -                                 |
| **email** *           | string | 签署人电子邮件。                       | -                                 |
| **phone** *           | object | 签署人电话数据对象 | **[phone 对象](#objeto-phone)** |
| **document_number** * | string | 签署人 CPF。                         | 11                                |

### phone 对象

| 字段 | 描述 | 示例 |  最大字符数 | 
| --- | --- | --- | --- | 
|`country_code` *| string | 电话国际区号（https://ddi.guiamais.com.br/） | 3 | 
| `area_code` *| string | 区号（https://ddd.guiamais.com.br/） | 2 |
| `number` *| string | 电话号码（仅数字） |  10 |

### person_type 枚举值
| 枚举值        | 描述       |
|-------------|-------------------|
| **natural** | 自然人     |
| **legal**   | 法人   |

### document_identification_type 枚举值
| 枚举值    | 描述                            |
|---------|----------------------------------------|
| **rg**  | RG - 身份证                    |
| **cnh** | CNH - 驾驶证 |

### company_type 枚举值
| 枚举值                       | 描述                                                             |
|----------------------------|--------------------------------------------------------------------------|
| **ltda**                   | 有限责任公司                                                                |
| **sa**	                    | 股份公司                                                        |
| **micro_enterprise**	      | 微型企业                                                            |
| **freelancer**             | 自由职业者                                                              |
| **sa_opened**              | 开放式股份公司                                     |
| **sa_closed**	             | 封闭式股份公司                                     |
| **se_ltda**                | 有限公司制企业                                           |
| **se_cn**                  | 合名公司制企业                                   |
| **se_cs**                  | 简单合资公司制企业                               |
| **se_ca**	                 | 股份合资公司制企业                              |
| **scp**                    | 参与账户公司                                      |
| **ei**	                    | 个体工商户                                                    |
| **ese**	                   | 在巴西境内的外国公司机构                     |
| **eeab**	                  | 在巴西境内的阿根廷-巴西双边公司机构   |
| **ssp**                    | 纯简单公司                                      |
| **ss_ltda**	               | 有限简单公司                                               |
| **ss_cn**                  | 合名简单公司                                      |
| **ss_cs**                  | 简单合资简单公司                                  |
| **eireli_ne**              | 商业性个人有限责任公司 |
| **eireli_ns**              | 简单性个人有限责任公司   |
| **eireli**                 | 个人责任公司                                  |
| **mei**                    | 个体微型创业者                                            |
| **me**	                    | 微型企业                                                            |
| **cop**	                   | 合作社                                                              |
| **private_association**	   | 私人协会                                                        |

### marital_status 枚举值
| 枚举值         | 描述  |
|--------------|---------------|
| **single**   | 未婚   |
| **married**  | 已婚    |
| **widower**  | 丧偶     |
| **divorced** | 离婚 |
| **separated** | 分居 |

## 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 注意
 `account_request_key` 字段需要保存，将用于确认账户开立。
:::

### Response Body 参数

| 字段 | 类型 | 描述 | 字符数|
|---|---| ---|---|
| `account_info` * | object  | 包含账户持有人信息的对象 |**[account_info 对象](#objeto-account_info)**  | - |
| `account_request_key` * | string  | 创建请求的标识键 | - | - |
| `account_request_status` * | string  | KYC 状态 | - | - |

### account_info 对象
| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---| --- |
| `account_branch` * | string  | 支行号 | 4 |
| `account_digit` * | string  | 电子邮件 | 11 |
| `account_number` * | string  | 账户持有人全名 | 50 |

STATUS 4xx

Response Body: Error

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`  | 描述（英文）<br/>`description` | 描述（葡文）<br/>`translation`|
|---| --- | --- | --- | --- | 
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema|
| 404 | QIT000404 | Not Found | Resource could not be found | Recurso não encontrado|

---

# 确认开立个人账户

URL: /zh-Hans/documentation/baas/account/abrir_conta_pf

作为个人账户开立的第二步，[完成账户预留后](/documentation/baas/account/abrir_conta_pf)，需要提交账户持有人的完整注册信息及账户开立条款的接受证明。

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

## Path Params
| 字段         | 类型   | 描述                              | 字符数 |
|---------------|--------|----------------------------------------|------------|
| `account_request_key` | uuidv4 | 账户预留请求的唯一标识键。 | 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 参数

| 字段 | 类型 | 描述                                                                                  | 字符数 |
|---|---|--------------------------------------------------------------------------------------------|---|
| `account_owner` * | object  | 包含账户持有人信息的对象                                         | **[account_owner 对象](#objeto-account_owner)** |
| `signed_contract` * | object  | 包含持有人接受账户开立条款证明的对象。 | **[signed_contract 对象](#objeto-signed_contract)** |

### account_owner 对象

| 字段 | 类型 | 描述 | 字符数                            |
|---| ---| ---|---------------------------------------| 
| `address` * | string | 客户地址。 | **[address 对象](#objeto-address)** |  |
| `birth_date` | string | 出生日期（格式 "YYYY-MM-DD"） |                                       |
| `document_identification` * | string | 附有照片的身份证明文件（RG 或 CNH）PDF 的 DOCUMENT_KEY（预先上传） |                                       |                                   |
| `email` * | string | 客户电子邮件。 |                                       |
| `individual_document_number`* | string | 个人 CPF（仅数字），最多 11 个字符。 |                                       |
| `is_pep` * | string | 声明该人是否为 PEP（http://www.portaldatransparencia.gov.br/download-de-dados/pep）。|                                       |
| `mother_name` | string | 个人账户持有人母亲姓名。 | 100                                   |
| `name` * | string | 企业法定名称（PJ）或个人姓名（PF）。 | 100                                   |
| `nationality` * | string | 客户国籍。 | 50                                    |
| `person_type` * | string | 标识所提交对象为自然人或法人。|                                       |
| `phone` * | string | 电话数据对象 | **[phone 对象](#objeto-phone)**     |
| `proof_of_residence` | string | 所提供地址的居住证明 PDF 的 DOCUMENT_KEY（预先上传）。|                                       |
|`monthly_income`* | number | 账户持有人月收入 | | 

### address 对象

此对象出现在 PF 和 PJ 对象中，用于表示地址信息。

| 字段 | 描述 | 示例 |  最大字符数 | 
|---|---|---|---| 
| `street` *| string | 街道地址  | 100 |
| `state` *| enum | 州（两位大写字母） | 2 |
| `city` *| string | 城市 | 100 |
| `neighborhood` *| string | 区/社区 | 100 |
| `number` *| string | 门牌号 | 10 |
| `postal_code` *| string | 邮政编码（http://www.buscacep.correios.com.br/sistemas/buscacep/）（仅数字） |  8 |
| `complement` *| string | 地址补充信息（自由文本） | 100 |

### signed_contract 对象
| 字段 | 类型   | 描述        | 字符数                                |
|-------|--------|------------------|-------------------------------------------|
| `document_key` * | uuidv4 | **账户开立条款**或**托管账户合同**文件的唯一标识键。（DOCUMENT_KEY 由[文件上传](./upload_de_documentos)端点的响应返回） | 36                                        |
| `signatures` *   | list   | 所提交文件的签名数据。列表中每个项目对应文件的一个签署人。      | **[signatures 对象](#objeto-signatures)** |

### signatures 对象
| 字段 | 类型       | 描述         | 字符数                                      |
|-------|------------|-------------------|-------------------------------------------------|
| `authenticity` * | object     | 证明签署人进行电子签名的数据集合。 | **[authenticity 对象](#objeto-authenticity)** |
| `signer` * | object     | 包含文件某一签署人数据的对象。           | **[signer 对象](#objeto-signer)**             |
| `authentication_type` * | enumerator | 签名类型。始终为 "**opt-in**"| "**opt-in**"                                    |

### authenticity 对象
| 字段 | 类型   | 描述               | 字符数 |
|-------|--------|-------------------------|------------|
| `timestamp` *            | string | 文件签署时的日期和时间。                | 27         |
| `facial_recognition_key`* | uuidv4 | 账户持有人自拍照片的唯一标识键。 | 36         |
| `lang`                  | string | 签署时捕获的签署人地理位置经度坐标。                  | -          |
| `lat`                    | string | 签署时捕获的签署人地理位置纬度坐标。                   | -          |
| `ip_address`             | string | 签署人设备的 IP 地址。     | -          |
| `session_id`  *           | string | 签署时签署人的会话 ID。                | -          |

### signer 对象
| 字段                 | 类型   | 描述                                 | 字符数                        |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| `name` *            | string | 签署人姓名。                        | -                                 |
| `email` *           | string | 签署人电子邮件。                       | -                                 |
| `phone` *           | object | 签署人电话数据对象 | **[phone 对象](#objeto-phone)** |
| `document_number` * | string | 签署人 CPF。                         | 11                                |

### phone 对象

| 字段 | 描述 | 示例 |  最大字符数 | 
| --- | --- | --- | --- | 
|`country_code` *| string | 电话国际区号（https://ddi.guiamais.com.br/） | 3 | 
| `area_code` *| string | 区号（https://ddd.guiamais.com.br/） | 2 |
| `number` *| string | 电话号码（仅数字） |  10 |

## Response

STATUS 201

Response Body

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

:::warning 注意
 `account_request_key` 字段需要保存，将用于确认账户开立。
:::

### Response Body 参数

| 字段 | 类型 | 描述 | 字符数                                      |
|---|---| ---|-------------------------------------------------|
| `account_key` * | string  | 账户唯一标识键| -                                               | - |

STATUS 4xx

Response Body: Error

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`  | 描述（英文）<br/>`description` | 描述（葡文）<br/>`translation`|
|---| --- | --- | --- | --- | 
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema|
| 404 | QIT000404 | Not Found | Resource could not be found | Recurso não encontrado|

---

# 确认开立企业账户

URL: /zh-Hans/documentation/baas/account/abrir_conta_pj

账户开立分两个必要步骤。首先，通过 POST 请求发送初步数据以预留账户。随后，系统触发状态为 `pending_additional_data` 的 `account_request.status_change` 类型 webhook。在第二步中，通过 PATCH 请求完成账户开立，以补充信息正式确认账户。

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

## Path Params
| 字段         | 类型   | 描述                              | 字符数 |
|---------------|--------|----------------------------------------|------------|
| `account_request_key` | uuidv4 | 账户预留请求的唯一标识键。 | 36         |

## 开立自由流动账户

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 参数

| 字段                 | 类型   | 描述                                                                            | 字符数                                            |
|-----------------------|--------|--------------------------------------------------------------------------------------|-------------------------------------------------------|
| `account_owner` *   | object | 账户持有人对象                                                              | **[account_owner 对象](#objeto-account_owner)**     |
| `signed_contract` *| object | 包含账户开立条款电子签名信息的对象。 | **[signed_contract 对象](#objeto-signed_contract)** |
| `additional_documents` *| list   | 包含账户持有人额外文件 `document_key` (uuidv4) 的列表。  | 36 |

### account_owner 对象

| 字段                         | 类型   | 描述                                                                                                                         | 字符数                                                            |
|-------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|
| `address` *                 | object | 账户持有人地址对象                                                                                               | **[address 对象](#objeto-address)**                                 |
| `cnae_code`               | string | 国家经济活动分类代码                                                                                   | 9                                                                     |
| `company_document_number` * | string | CNPJ                                                                                                                              | 14                                                                    |
| `company_statute` *         | string | 公司章程 PDF 的 DOCUMENT_KEY（预先上传）。                                                                 | 36                                                                    |
| `company_type`*              | enum   | 公司类型                                                                                                                   | **[company_type 枚举值](#enumeradores-company_type)**           |
| `company_representatives` * | list   | 公司法定代表人列表                                                                                        | **[company_representatives 对象](#objeto-company_representatives)** |
| `email` *                   | string | 公司机构电子邮件。                                                                                                                   | 254                                                                   |
| `foundation_date`         | string | 公司成立日期（格式 "YYYY-MM-DD"）。                                                                               | 10                                                                    |
| `name` *                    | string | 公司法定名称。                                                                                                                     | 100                                                                   |
| `person_type` *             | enum   | 标识所提交对象为法人。PJ 对象始终应包含值 "legal"。                   | **[person_type 枚举值](#enumeradores-person_type)**             |
| `phone` *                   | object | 账户持有人电话。                                                                                                                     | **[phone 对象](#objeto-phone)**                                     | - |
| `trading_name` *            | string | 商业名称。                                                                                                                    | 200                                                                   |
| `monthly_revenue`* | number | 公司月营业额 | |

### company_representatives 对象

| 字段                              | 类型    | 描述                                                                                              | 字符数                                                                                  |
|------------------------------------|---------|--------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
| `name` *                         | string  | 公司代表姓名                                                                       | 100                                                                                         |
| `address` *                      | object  | 公司代表地址对象                                                            | **[address 对象](#objeto-address)**                                                       |
| `email` *                        | string  | 公司代表电子邮件                                                                      | 254                                                                                         |
| `birth_date`                   | string  | 公司代表出生日期（格式 "YYYY-MM-DD"）                                     | 10                                                                                          |
| `individual_document_number` *   | string  | 公司代表 CPF（仅数字）。                                                      | 11                                                                                          |
| `document_identification`*        | string  | 附有照片的身份证明文件（RG 或 CNH）PDF 的 DOCUMENT_KEY（预先上传） | 36                                                                                          |
| `document_identification_number`* | string  | 附有照片的身份证明文件号码（RG 或 CNH）                                    | 16                                                                                          |
| `document_identification_type`   | enum    | 附有照片的身份证明文件类型（RG 或 CNH）                                      | **[document_identification_type 枚举值](#enumeradores-document_identification_type)** |
| `is_pep` *                       | boolean | 声明该人是否为 PEP（http://www.portaldatransparencia.gov.br/download-de-dados/pep）。          | -                                                                                           |
| `final_beneficiary`              | boolean | 声明该人是否为公司的最终受益人。                                                                         | -                                                                                           |
| `marital_status`                 | enum    | 公司代表婚姻状况                                                               | **[marital status 枚举值](#enumeradores-marital_status)**                             |
| `mother_name`                  | string  | 公司代表母亲姓名                                                                | 100                                                                                         |
| `nationality`                    | string  | 公司代表国籍                                                              | 50                                                                                          |
| `person_type` *                  | enum    | 标识所提交对象为自然人                                              | **[person_type 枚举值](#enumeradores-person_type)**                                   |
| `phone` * | object  | 公司代表电话数据对象  | **[phone 对象](#objeto-phone)**                                                           |
| `representative_relationship` * | enum | 标识公司与代表之间的关系 | **[representative_relationship 枚举值](#enumeradores-representative_relationship)**

### address 对象

此对象出现在 PF 和 PJ 对象中，用于表示地址信息。

| 字段              | 描述 | 示例                                                                                   | 字符数 |
|--------------------|-----------|-------------------------------------------------------------------------------------------|------------|
| `street` *       | string    | 街道地址                                                                           | 500        |
| `state` *        | enum      | 州（两位大写字母）                                       | 2          |
| `city` *         | string    | 城市                                                                        | 255        |
| `neighborhood` * | string    | 区/社区                                                                        | 500        |
| `number` *       | string    | 门牌号                                                                             | 10         |
| `postal_code` *  | string    | 邮政编码（http://www.buscacep.correios.com.br/sistemas/buscacep/）（仅数字） | 8          |
| `complement`*     | string    | 地址补充信息（自由文本）                                                                     | 500        |

### signed_contract 对象
| 字段 | 类型   | 描述        | 字符数    |
|-------|--------|------------------|---------------|
| `document_key` * | uuidv4 | **账户开立条款**或**托管账户合同**文件的唯一标识键。（DOCUMENT_KEY 由[文件上传](./upload_de_documentos)端点的响应返回） | 36            |
| `signatures` *   | list   | 所提交文件的签名数据。列表中每个项目对应文件的一个签署人。      | [signatures 对象](#objeto-signatures) |

### signatures 对象
| 字段 | 类型       | 描述         | 字符数        |
|-------|------------|-------------------|-------------------|
| `authenticity` * | object     | 证明签署人进行电子签名的数据集合。 | [authenticity 对象](#objeto-authenticity) |
| `signer` * | object     | 包含文件某一签署人数据的对象。           | [signer 对象](#objeto-signer)|
| `authentication_type` * | enumerator | 签名类型。始终为 "**opt-in**"| "**opt-in**"                   |

### authenticity 对象
| 字段 | 类型   | 描述               | 字符数 |
|-------|--------|-------------------------|------------|
| `timestamp` *            | string | 文件签署时的日期和时间。                | 27         |
| `facial_recognition_key`* | uuidv4 | 账户持有人自拍照片的唯一标识键。  | 36         |
| `lang`                   | string | 签署时捕获的签署人地理位置经度坐标。                  | -          |
| `lat`                    | string | 签署时捕获的签署人地理位置纬度坐标。                   | -          |
| `ip_address`             | string | 签署人设备的 IP 地址。     | -          |
| `session_id`*             | string | 签署时签署人的会话 ID。                | -          |

### signer 对象
| 字段                 | 类型   | 描述                                 | 字符数                        |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| `name` *            | string | 签署人姓名。                        | -                                 |
| `email` *           | string | 签署人电子邮件。                       | -                                 |
| `phone` *           | object | 签署人电话数据对象 | **[phone 对象](#objeto-phone)** |
| `document_number` * | string | 签署人 CPF。                         | 11                                |

### phone 对象

| 字段 | 描述 | 示例 |  最大字符数 | 
| --- | --- | --- | --- | 
|`country_code` *| string | 电话国际区号（https://ddi.guiamais.com.br/） | 3 | 
| `area_code` *| string | 区号（https://ddd.guiamais.com.br/） | 2 |
| `number` *| string | 电话号码（仅数字） |  10 |

### person_type 枚举值
| 枚举值        | 描述       |
|-------------|-------------------|
| `natural` | 自然人     |
| `legal`   | 法人   |

### representative_relationship 枚举值
| 枚举值        | 描述       |
|-------------|-------------------|
| `ceo` | 管理人  |
| `partner` | 合伙人/股东 |
| `attorney` | 代理人|

### document_identification_type 枚举值
| 枚举值    | 描述                            |
|---------|----------------------------------------|
| `rg`  | RG - 身份证                    |
| `cnh` | CNH - 驾驶证 |

### company_type 枚举值
| 枚举值                     | 描述                                                             |
|--------------------------|--------------------------------------------------------------------------|
| `ltda`                  | 有限责任公司                                                                |
| `sa`	                  | 股份公司                                                        |
| `micro_enterprise`	    | 微型企业                                                            |
| `freelancer`            | 自由职业者                                                              |
| `sa_opened`             | 开放式股份公司                                     |
| `sa_closed`	           | 封闭式股份公司                                     |
| `se_ltda`               | 有限公司制企业                                           |
| `se_cn`                 | 合名公司制企业                                   |
| `se_cs`                 | 简单合资公司制企业                               |
| `se_ca`	               | 股份合资公司制企业                              |
| `scp`                   | 参与账户公司                                      |
| `ei`	                   | 个体工商户                                                    |
| `ese`	                 | 在巴西境内的外国公司机构                     |
| `eeab`	                | 在巴西境内的阿根廷-巴西双边公司机构   |
| `ssp`                  | 纯简单公司                                      |
| `ss_ltda`	             | 有限简单公司                                               |
| `ss_cn`                | 合名简单公司                                      |
| `ss_cs`                | 简单合资简单公司                                  |
| `eireli_ne`            | 商业性个人有限责任公司 |
| `eireli_ns`            | 简单性个人有限责任公司   |
| `eireli`               | 个人责任公司                                  |
| `mei`                  | 个体微型创业者                                            |
| `me`	                  | 微型企业                                                            |
| `cop`	                 | 合作社                                                              |
| `private_association`	 | 私人协会                                                        |
| `others`	   | 其他  |

### marital_status 枚举值
| 枚举值         | 描述  |
|--------------|---------------|
| `single`   | 未婚   |
| `married`  | 已婚    |
| `widower`  | 丧偶     |
| `divorced` | 离婚 |
| `separated` | 分居 |

## Response

STATUS 201

Response Body

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

:::warning 注意
 `account_request_key` 字段需要保存，将用于确认账户开立。
:::

### Response Body 参数

| 字段 | 类型 | 描述 | 字符数                                      |
|---|---| ---|-------------------------------------------------|
| `account_key` * | string  | 账户唯一标识键| -                                               | - |

STATUS 4xx

Response Body: Error

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`  | 描述（英文）<br/>`description` | 描述（葡文）<br/>`translation`|
|---| --- | --- | --- | --- | 
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema|
| 404 | QIT000404 | Not Found | Resource could not be found | Recurso não encontrado|

---

# 申请账户预留

URL: /zh-Hans/documentation/baas/account/account_draft_checking

## Request
ENDPOINT /account_request/draft_checking
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":"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
   }
}
```

### 账户开立

### Request Body 参数

| 字段            | 类型   | 描述                                                                  |
|------------------|--------|----------------------------------------------------------------------------|
| `account_owner`* | object | 账户持有人详情，包括地址和个人信息。   |

### account_owner 对象

| 字段                         | 类型    | 描述                                                      |
|-------------------------------|---------|----------------------------------------------------------------|
| `address`*                    | object  | 账户持有人地址。                                  |
| `birth_date`*                 | string  | 持有人出生日期（格式 "YYYY-MM-DD"）。          |
| `email`*                      | string  | 账户持有人电子邮件。                                     |
| `individual_document_number`* | string  | 持有人 CPF（仅数字）。                               |
| `is_pep`*                     | boolean | 声明该人是否为 PEP。                                  |
| `mother_name`*                | string  | 持有人母亲姓名。                                        |
| `name`*                       | string  | 持有人全名。                                      |
| `nationality`                 | string  | 持有人国籍。                                      |
| `person_type`*                | enum    | 人员类型，个人账户始终为 "natural"。  |
| `phone`*                      | object  | 持有人电话。                                           |
| `monthly_income`              | number  | 持有人月收入。                                       |

### address 对象

| 字段           | 类型   | 描述              | 字符数 |
|-----------------|--------|------------------------|------------|
| `street`*       | string | 街道地址        | -        |
| `state`*        | enum   | 州     | 2          |
| `city`*         | string | 城市     | -        |
| `neighborhood`* | string | 区/社区     | -        |
| `number`*       | string | 门牌号          | -         |
| `postal_code`*  | string | 邮政编码        | -          |
| `complement`    | string | 地址补充信息| -        |

### phone 对象

| 字段            | 类型   | 描述                |
|------------------|--------|--------------------------|
| `country_code`*  | string | 电话国际区号   |
| `area_code`*     | string | 区号   |
| `number`*        | string | 电话号码       |

### person_type 枚举值

| 枚举值    | 描述    |
|---------|--------------|
| `natural` | 自然人 |
|`legal`| 法人 |

## 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 注意
 `account_request_key` 字段需要保存，将用于确认账户开立。
:::

### Response Body 参数

| 字段 | 类型 | 描述 | 字符数                                      |
|---|---| ---|-------------------------------------------------|
| `account_key` * | string  | 账户唯一标识键| -                                               | - |

STATUS 4xx

Response Body: Error

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`  | 描述（英文）<br/>`description` | 描述（葡文）<br/>`translation`|
|---| --- | --- | --- | --- | 
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema|
| 404 | QIT000404 | Not Found | Resource could not be found | Recurso não encontrado|

---

# 申请账户预留

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

## Request
ENDPOINT /account_request/draft_checking
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":"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
   }
}
```

### 账户开立

### Request Body 参数

| 字段            | 类型   | 描述                                                                  |
|------------------|--------|----------------------------------------------------------------------------|
| `account_owner`* | object | 账户持有人详情，包括地址和个人信息。   |

### account_owner 对象

| 字段                         | 类型    | 描述                                                      |
|-------------------------------|---------|----------------------------------------------------------------|
| `address`*                    | object  | 账户持有人地址。                                  |
| `birth_date`*                 | string  | 持有人出生日期（格式 "YYYY-MM-DD"）。          |
| `email`*                      | string  | 账户持有人电子邮件。                                     |
| `individual_document_number`* | string  | 持有人 CPF（仅数字）。                               |
| `is_pep`*                     | boolean | 声明该人是否为 PEP。                                  |
| `mother_name`*                | string  | 持有人母亲姓名。                                        |
| `name`*                       | string  | 持有人全名。                                      |
| `nationality`                 | string  | 持有人国籍。                                      |
| `person_type`*                | enum    | 人员类型，个人账户始终为 "natural"。  |
| `phone`*                      | object  | 持有人电话。                                           |
| `monthly_income`              | number  | 持有人月收入。                                       |

### address 对象

| 字段           | 类型   | 描述              | 字符数 |
|-----------------|--------|------------------------|------------|
| `street`*       | string | 街道地址        | -        |
| `state`*        | enum   | 州     | 2          |
| `city`*         | string | 城市     | -        |
| `neighborhood`* | string | 区/社区     | -        |
| `number`*       | string | 门牌号          | -         |
| `postal_code`*  | string | 邮政编码        | -          |
| `complement`    | string | 地址补充信息| -        |

### phone 对象

| 字段            | 类型   | 描述                |
|------------------|--------|--------------------------|
| `country_code`*  | string | 电话国际区号   |
| `area_code`*     | string | 区号   |
| `number`*        | string | 电话号码       |

### person_type 枚举值

| 枚举值    | 描述    |
|---------|--------------|
| `natural` | 自然人 |
|`legal`| 法人 |

## 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 注意
 `account_request_key` 字段需要保存，将用于确认账户开立。
:::

### Response Body 参数

| 字段 | 类型 | 描述 | 字符数                                      |
|---|---| ---|-------------------------------------------------|
| `account_key` * | string  | 账户唯一标识键| -                                               | - |

STATUS 4xx

Response Body: Error

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`  | 描述（英文）<br/>`description` | 描述（葡文）<br/>`translation`|
|---| --- | --- | --- | --- | 
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema|
| 404 | QIT000404 | Not Found | Resource could not be found | Recurso não encontrado|

---

# 简介

URL: /zh-Hans/documentation/baas/account/introducao

我们集成提供的功能之一是通过 API 管理账户及向 QI Tech 账户或其他金融机构账户进行转账，但不仅如此，我们还提供通过 API **开立**账户的可能性——无论是为您自己，还是为第三方。

与其他 API 一样，服务的开放需要与我们的团队协商，所有调用均需经过认证。

账户开立分两个必要步骤。在第一步中，发送一个包含初步数据的 POST 请求以预留账户。提交该请求后，系统会自动向中央银行（Bacen）查询，特别是与 BC Protege+ 项目关联的数据库。该系统允许自然人和法人自愿登记限制，指定不希望在其名下在哪些金融机构开立新账户，作为防欺诈措施。

在此流程中，预留的初始状态为 `pending_bacen_validation`。
若查询通过，则触发 `account_request.status_change` 类型的 webhook，将状态更新为 `pending_kyc_analysis`。

通过 KYC 分析后，系统发送新的 `account_request.status_change` webhook，将状态更改为 `pending_additional_data`——此阶段表示分析完成，需要提交补充信息。

在第二步中，需要发送一个 PATCH 请求，包含完成流程并正式开立账户所需的额外信息。

---

# 申请开立个人账户

URL: /zh-Hans/documentation/baas/account/reservar_conta_pf

账户开立分两个必要步骤。首先，通过 POST 请求发送初步数据以预留账户。随后，系统触发状态为 `pending_additional_data` 的 `account_request.status_change` 类型 webhook。在第二步中，通过 PATCH 请求完成账户开立，以补充信息正式确认账户。

## 申请账户预留

## 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 CPF/CNPJ 模拟
要模拟批准、拒绝和人工审核场景，可使用账户所有者 CPF/CNPJ 的第一位数字：

0 至 7 -> 人工审核

8 -> KYC 自动拒绝

9 -> 自动批准
:::

### Request Body 参数

| 字段 | 类型   | 描述                                         | 字符数                                        |
|---|--------|---------------------------------------------------|---------------------------------------------------|
| `account_owner` * | object | 包含账户持有人信息的对象 | **[account_owner 对象](#objeto-account_owner)** |
| `request_control_key` * | UUID   | 合作伙伴每次请求的唯一标识符  | 36                                                |

### account_owner 对象
| 字段 | 类型 | 描述 | 字符数 |
|--- | --- | --- | --- |
| `document_number` * | string  | 账户持有人 CPF | 11 |
| `email` * | string  | 电子邮件 | 11 |
| `birthdate` | string  | 账户持有人出生日期（格式 YYYY-MM-DD） | 10 |
| `name` * | string  | 账户持有人全名 | 50 |
| `documents`* | object  | 账户持有人文件 | **[documents 对象](#objeto-documents)** |
| `face`*      | uuidv4  | 反欺诈人脸识别密钥（`face_recognition_key`） | 36 |

### documents 对象

| 字段                          | 类型        | 描述                                                          | 字符数                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `rg`                           | object      | 持有人身份证正反面上传的 OCR 密钥 | **[rg 对象](#objeto-rg)**   |
| `cnh`                          | object      | 持有人驾驶证上传的 OCR 密钥                              | **[cnh 对象](#objeto-cnh)** |
| `cnh_digital`                     | object      | 持有人电子驾驶证上传的 OCR 密钥                       | **[cnh_digital 对象](#objeto-cnh_digital)** |
| `national_registry_of_foreigners` | object   | 持有人外国人登记证（RNE）正反面上传的 OCR 密钥| **[national_registry_of_foreigners 对象](#objeto-national_registry_of_foreigners)** |
| `national_migration_registry` | object   | 持有人移民登记证（CRNM）正反面上传的 OCR 密钥| **[national_migration_registry 对象](#objeto-national_migration_registry)** |
| `passport`                     | object      | 持有人护照上传的 OCR 密钥                       | **[passport 对象](#objeto-passport)** |
| `cin_digital`                     | object      | 持有人电子国家身份证上传的 OCR 密钥                       | **[cin_digital 对象](#objeto-cin_digital)** |

:::info 说明
文件图像上传的 OCR 密钥（`ocr_key` 或 `ocr_front_key` 和 `ocr_back_key`）作为反欺诈系统中图像上传的响应返回。`face_recognition_key` 在人脸识别响应中返回。
:::

### rg 对象

| 字段                          | 类型        | 描述                                                          | 字符数                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` *              | uuidv4      | 身份证正面图像上传的 OCR 密钥                      | 36                            |
| `ocr_back_key` *               | uuidv4      | 身份证背面图像上传的 OCR 密钥                       | 36                            |

或

| 字段                          | 类型        | 描述                                                          | 字符数                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | 身份证图像上传的 OCR 密钥                                | 36                       |

### cnh 对象

| 字段                          | 类型        | 描述                                                          | 字符数                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` *              | uuidv4      | 驾驶证正面图像上传的 OCR 密钥                     | 36                            |
| `ocr_back_key` *               | uuidv4      | 驾驶证背面图像上传的 OCR 密钥                      | 36                            |

或

| 字段                          | 类型        | 描述                                                          | 字符数                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | 驾驶证图像上传的 OCR 密钥                               | 36                            |

### cnh_digital 对象

| 字段                          | 类型        | 描述                                                          | 字符数                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | 电子驾驶证图像上传的 OCR 密钥                               | 36                            |

### national_registry_of_foreigners 对象

| 字段                          | 类型        | 描述                                                          | 字符数                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` *              | uuidv4      | 外国人登记证正面图像上传的 OCR 密钥                     | 36                            |
| `ocr_back_key` *               | uuidv4      | 外国人登记证背面图像上传的 OCR 密钥                      | 36                            |

或

| 字段                          | 类型        | 描述                                                          | 字符数                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | 外国人登记证图像上传的 OCR 密钥                               | 36                            |

### national_migration_registry 对象

| 字段                          | 类型        | 描述                                                          | 字符数                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` *              | uuidv4      | 移民登记证正面图像上传的 OCR 密钥                     | 36                            |
| `ocr_back_key` *               | uuidv4      | 移民登记证背面图像上传的 OCR 密钥                      | 36                            |

或

| 字段                          | 类型        | 描述                                                          | 字符数                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | 移民登记证图像上传的 OCR 密钥                               | 36                            |

### passport 对象

| 字段                          | 类型        | 描述                                                          | 字符数                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | 护照图像上传的 OCR 密钥                               | 36                            |

### cin_digital 对象

| 字段                          | 类型        | 描述                                                          | 字符数                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | 电子国家身份证图像上传的 OCR 密钥                               | 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 Bacen Protege+ 流程
提案初始状态为 `pending_bacen_validation`。系统在进行 KYC 分析前，先向 Bacen Protege+ 进行预验证。Bacen 批准后，状态将自动更新为 `pending_kyc_analysis`。
:::

:::warning 注意
 `account_request_key` 字段需要保存，将用于确认账户开立。
:::

### Response Body 参数

| 字段 | 类型 | 描述 | 字符数|
|---|---| ---|---|
| `account_info` * | object  | 包含账户持有人信息的对象 |**[account_info 对象](#objeto-account_info)**  | - |
| `account_request_key` * | string  | 创建请求的标识键 | - | - |
| `account_request_status` * | string  | KYC 状态 | - | - |

### account_info 对象
| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---| --- |
| `account_branch` * | string  | 支行号 | 4 |
| `account_digit` * | string  | 账户验证位 | 11 |
| `account_number` * | string  | 账户号码 | 50 |

STATUS 4xx

Response Body: Error

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`  | 描述（英文）<br/>`description` | 描述（葡文）<br/>`translation`|
|---| --- | --- | --- | --- | 
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema|
| 404 | QIT000404 | Not Found | Resource could not be found | Recurso não encontrado|

---

# 企业账户开立

URL: /zh-Hans/documentation/baas/account/reservar_conta_pj

账户开立分两个必要步骤。首先，通过 POST 请求发送初步数据以预留账户。随后，系统触发状态为 `pending_additional_data` 的 `account_request.status_change` 类型 webhook。在第二步中，通过 PATCH 请求完成账户开立，以补充信息正式确认账户。

## 申请账户预留

## 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 CPF/CNPJ 模拟
要模拟批准、拒绝和人工审核场景，可使用账户所有者 CPF/CNPJ 的第一位数字：

0 至 6 -> 人工审核

7 -> 被 Bacen Protege+ 拒绝

8 -> KYC 自动拒绝

9 -> 自动批准
:::

### Request Body 参数

| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---|---|
| `account_owner` * | object  | 包含账户持有人信息的对象 | **[account_owner 对象](#objeto-account_owner)** |
| `legal_representatives`* | object array | 账户代表列表及其数据 | **[legal_representative 对象](#objeto-legal_representative)** |

### account_owner 对象
| 字段 | 类型 | 描述 | 字符数 |
|--- | --- | --- | --- |
| `company_document_number` * | string  | 账户持有人 CNPJ | 50 |
| `email` * | string  | 电子邮件 | 11 |
| `foundation_date` | string  | 公司成立日期（格式 YYYY-MM-DD） | 10 |
| `name` * | string  | 账户持有人全名 | 50 |

### legal_representative 对象

| 字段 | 类型 | 描述 | 字符数 |
|--- | --- | --- | --- |
| `document_number` * | string  | 账户持有人 CPF | 11 |
| `birthdate` | string  | 出生日期（格式 YYYY-MM-DD） | 10 |
| `name` * | string  | 账户持有人姓名 | 50 |
| `documents` * | object  | 账户持有人文件 | **[documents 对象](#objeto-documents)** |
| `face`*      | uuidv4  | 反欺诈人脸识别密钥（`face_recognition_key`） | 36 |

### documents 对象

| 字段                          | 类型        | 描述                                                          | 字符数                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `rg`                           | object      | 持有人身份证正反面上传的 OCR 密钥 | **[rg 对象](#objeto-rg)**   |
| `cnh`                          | object      | 持有人驾驶证上传的 OCR 密钥                              | **[cnh 对象](#objeto-cnh)** |
| `cnh_digital`                     | object      | 持有人电子驾驶证上传的 OCR 密钥                       | **[cnh_digital 对象](#objeto-cnh_digital)** |
| `national_registry_of_foreigners` | object   | 持有人外国人登记证（RNE）正反面上传的 OCR 密钥| **[national_registry_of_foreigners 对象](#objeto-national_registry_of_foreigners)** |
| `national_migration_registry` | object   | 持有人移民登记证（CRNM）正反面上传的 OCR 密钥| **[national_migration_registry 对象](#objeto-national_migration_registry)** |
| `passport`                     | object      | 持有人护照上传的 OCR 密钥                       | **[passport 对象](#objeto-passport)** |
| `cin_digital`                     | object      | 持有人电子国家身份证上传的 OCR 密钥                       | **[cin_digital 对象](#objeto-cin_digital)** |

:::info 说明
文件图像上传的 OCR 密钥（`ocr_key` 或 `ocr_front_key` 和 `ocr_back_key`）作为反欺诈系统中图像上传的响应返回。`face_recognition_key` 在人脸识别响应中返回。
:::

### rg 对象

| 字段                          | 类型        | 描述                                                          | 字符数                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` *              | uuidv4      | 身份证正面图像上传的 OCR 密钥                      | 36                            |
| `ocr_back_key` *               | uuidv4      | 身份证背面图像上传的 OCR 密钥                       | 36                            |

或

| 字段                          | 类型        | 描述                                                          | 字符数                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | 身份证图像上传的 OCR 密钥                                | 36                            |

### cnh 对象

| 字段                          | 类型        | 描述                                                          | 字符数                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` *              | uuidv4      | 驾驶证正面图像上传的 OCR 密钥                     | 36                            |
| `ocr_back_key` *               | uuidv4      | 驾驶证背面图像上传的 OCR 密钥                      | 36                            |

或

| 字段                          | 类型        | 描述                                                          | 字符数                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | 驾驶证图像上传的 OCR 密钥                               | 36                            |

### cnh_digital 对象

| 字段                          | 类型        | 描述                                                          | 字符数                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | 电子驾驶证图像上传的 OCR 密钥                               | 36                            |

### national_registry_of_foreigners 对象

| 字段                          | 类型        | 描述                                                          | 字符数                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` *              | uuidv4      | 外国人登记证正面图像上传的 OCR 密钥                     | 36                            |
| `ocr_back_key` *               | uuidv4      | 外国人登记证背面图像上传的 OCR 密钥                      | 36                            |

或

| 字段                          | 类型        | 描述                                                          | 字符数                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | 外国人登记证图像上传的 OCR 密钥                               | 36                            |

### national_migration_registry 对象

| 字段                          | 类型        | 描述                                                          | 字符数                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` *              | uuidv4      | 移民登记证正面图像上传的 OCR 密钥                     | 36                            |
| `ocr_back_key` *               | uuidv4      | 移民登记证背面图像上传的 OCR 密钥                      | 36                            |

或

| 字段                          | 类型        | 描述                                                          | 字符数                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | 移民登记证图像上传的 OCR 密钥                               | 36                            |

### passport 对象

| 字段                          | 类型        | 描述                                                          | 字符数                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | 护照图像上传的 OCR 密钥                               | 36                            |

### cin_digital 对象

| 字段                          | 类型        | 描述                                                          | 字符数                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | 电子国家身份证图像上传的 OCR 密钥                               | 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 Bacen Protege+ 流程
提案初始状态为 `pending_bacen_validation`。系统在进行 KYC 分析前，先向 Bacen Protege+ 进行预验证。Bacen 批准后，状态将自动更新为 `pending_kyc_analysis`。
:::

:::warning 注意
 `account_request_key` 字段需要保存，将用于确认账户开立。
:::

### Response Body 参数

| 字段 | 类型 | 描述 | 字符数|
|---|---| ---|---|
| `account_info` * | object  | 包含账户持有人信息的对象 |**[account_info 对象](#objeto-account_info)**  | - |
| `account_request_key` * | string  | 创建请求的标识键 | - | - |
| `account_request_status` * | string  | KYC 状态 | - | - |

### account_info 对象
| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---| --- |
| `account_branch` * | string  | 支行号 | 4 |
| `account_digit` * | string  | 电子邮件 | 11 |
| `account_number` * | string  | 账户持有人全名 | 50 |

STATUS 4xx

Response Body: Error

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`  | 描述（英文）<br/>`description` | 描述（葡文）<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

URL: /zh-Hans/documentation/baas/account/webhooks

提交账户预留请求后，初始状态为 `pending_bacen_validation`。通过后，预留状态更新为 `pending_kyc_analysis`。随后，通过 KYC 后，状态变为 `pending_additional_data`。

对于 `pending_kyc_analysis`、`pending_additional_data` 和 `rejected` 状态，系统发送 `account_request.status_change` 类型的 webhook，此事件对于控制确认账户开立所需后续操作至关重要。

账户号码将在提交预留申请时预留，但此时**账户尚未开立**。只有在 QI Tech 完成 KYC 分析并经合作伙伴后续确认后，账户才算正式开立。

### account_request_status 枚举值
| 枚举值                        | 描述                         |
|-----------------------------|-------------------------------------|
| **pending_kyc_analysis**    | 待 KYC 批准           |
| **pending_additional_data** | 待补充信息  |
| **rejected**                | 开立被拒绝                  |

当状态为 `rejected` 时，webhook 在消息根部包含 `rejection_reason` 字段，说明拒绝原因。该字段的值为自由格式，直接由 KYC 分析返回，可能因识别到的原因而有所不同，可能来自 KYC 分析或 Bacen Protege+。

### KYC 分析待处理 Webhook

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

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（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（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: /zh-Hans/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: /zh-Hans/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. |

---

# 确认银行票据预约

URL: /zh-Hans/documentation/baas/cobranca/2fa_v2/agendamento/confirmar_agendamento_de_boleto_bancario

此端点用于确认银行票据支付预约。

:::info 银行票据
这是常规银行票据（数字行不以数字8开头）。在银行间支付结算所（CIP/Núclea）注册，可在巴西中央银行授权的金融和支付机构付款。
:::

## Request

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

### 请求路径参数

| 字段               | 类型    | 描述                               | 字符数 |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | 账户唯一标识键。  | 36         |
| `payment_schedule_key` * | uuid4   | 预约唯一标识键。 | 36         |

Request Body: 银行票据预约确认

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

### Body 参数

| 字段               | 类型          | 描述                         |
|---------------------|---------------|-----------------------------------|
| `token` * | string | 发送给账户转账审批人的验证码 |

## Response

### 成功响应

STATUS 200

Response Body: 预约已确认

```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 参数

| 字段               | 类型    | 描述                                           |
|---------------------|---------|-----------------------------------------------------|
| `payment_key` *               | uuid4 | 支付唯一标识键。          |
| `request_control_key` *       | uuid4 | 客户请求唯一标识键。 |
| `payer_name` *                | string | 实际付款人名称。                            |
| `payer_document_number` *     | string | 实际付款人文件号码（CPF/CNPJ）。  |
| `source_account_key` *        | uuid4 | 被扣款账户密钥。                            |
| `paid_amount` *               | number | 实际支付金额。                            |
| `payment_date` *              | string | 支付日期。                                  |
| `payment_type` *              | [enum](#enumeradores-payment_type) | 支付类型。                                  |
| `bank_slip`                   | [object](#objeto-bank_slip) | 银行票据。                                    |
| `collection_slip`             | object | 征税发票。                             |
| `payment_schedule_status` *            | [enum](#enumeradores-payment_schedule_status) | 预约状态。                              |

### payment_type 枚举值
| 枚举值    | 类型      | 描述     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | 银行票据    |
| `collection_slip` | string  | 征税发票 |

:::danger 警告
`collection_slip` 枚举值不适用于银行票据流程，同样 collection_slip 对象始终为空。
:::

### payment_schedule_status 枚举值
| 枚举值          | 描述                                                        |
|---------------------|------------------------------------------------------------------|
| `pending_2fa_approval` | 预约待双因素身份验证（2FA）       |
| `scheduled`          | 支付预约成功                                   |
| `executed`          | 预约已成功执行并生成相应支付 |
| `rejected`          | 预约被拒绝，未生成任何支付             |
| `canceled`         | 预约已取消                                            |
| `error`             | 预约执行错误                                   |

### bank_slip 对象
| 字段                             | 类型    | 描述                         |
|-----------------------------------|---------|-----------------------------------|
| `barcode` *                       | string | 条形码。 |
| `digitable_line` *                | string | 数字行。 |
| `payer_name` *                    | string | 付款人名称。|
| `payer_document_number` *         | string | 付款人文件号码（CPF/CNPJ）。 |
| `beneficiary_name` *              | string | 受益人名称。 |
| `beneficiary_trading_name`        | string | 受益人商业名称。 |
| `beneficiary_document_number` *   | string | 受益人文件号码（CPF/CNPJ）。 |
| `beneficiary_bank_ispb` *         | string | 受益人银行 ISPB 代码。 |
| `guarantor_name`                  | string | 保证人名称。 |
| `guarantor_document_number`       | string | 保证人文件号码（CPF/CNPJ）。 |
| `expiration_date` *               | string | 到期日期。 |
| `max_payment_date` * | string  | 最大支付日期。 |
| `partial_payment_indicator` *     | [enum](#enumeradores-partial_payment_indicator)   | 部分付款指示符。 |
| `registered_payment_amount`       | string | 已登记的总支付金额。 |
| `nominal_amount` *                | number | 原始金额。 |
| `total_amount` *                  | number | 总金额。 |
| `rebate_amount` *                 | number | 折扣金额。 |
| `discount_amount` *               | number | 优惠金额。 |
| `fine_amount` *                   | number | 罚款金额。 |
| `interest_amount` *               | number | 利息金额。 |

### partial_payment_indicator 枚举值
| 枚举值    | 类型      | 描述     |
|---------------|-----------|---------------|
| `allowed`     | string    | 允许     |
| `not_allowed` | string    | 不允许 |

### 错误响应

STATUS 4XX

Response Body

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

| HTTP 代码 | QI 代码 | 标题 | 描述（英文） | 描述（葡文） |
|-------------|-----------|--------|------------------|------------------|
| 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. |

---

# 确认征税发票支付预约

URL: /zh-Hans/documentation/baas/cobranca/2fa_v2/agendamento/confirmar_agendamento_de_fatura_de_recolhimento

此端点用于确认征税发票支付预约。

:::info 征税发票
此类账单由服务特许经营商（水、电、电话和燃气账单）和政府机构（税务）开具。它们未在银行间支付结算所（CIP/Núclea）登记，因此返回的信息与银行票据不同。
:::

## Request

### 请求端点

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

### 请求路径参数

| 字段               | 类型    | 描述                               | 字符数 |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | 账户唯一标识键。  | 36         |
| `payment_schedule_key` * | uuid4   | 预约唯一标识键。 | 36         |

Request Body: 确认征税发票预约

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

### Body 参数

| 字段               | 类型          | 描述                         |
|---------------------|---------------|-----------------------------------|
| `token` * | string | 发送给账户转账审批人的验证码 |

## Response

### 成功响应

STATUS 200

### 错误响应

STATUS 4XX

Response Body

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

| HTTP 代码 | QI 代码 | 标题 | 描述（英文） | 描述（葡文） |
|-------------|-----------|--------|------------------|------------------|
| 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         | 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         | 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. |

---

# Confirmar agendamento em lote de boleto bancário

URL: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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. |

---

# 重新发送银行票据预约双因素身份验证令牌

URL: /zh-Hans/documentation/baas/cobranca/2fa_v2/agendamento/reenviar_token_de_agendamento_boleto_bancario

此端点用于重新发送银行票据预约的身份验证令牌。

:::info 银行票据
这是常规银行票据（数字行不以数字8开头）。在银行间支付结算所（CIP/Núclea）注册，可在巴西中央银行授权的金融和支付机构付款。
:::

## Request

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

### 请求路径参数

| 字段               | 类型    | 描述                               | 字符数 |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | 账户唯一标识键。  | 36         |
| `payment_schedule_key` * | uuid4   | 预约唯一标识键。 | 36         |

### Body 参数

| 字段          | 类型   | 描述                                                                                 | 字符数 |
|----------------|--------|-------------------------------------------------------------------------------------------|------------|
| `contact_type` | enumerator | 身份验证令牌发送方式 | **[contact_type 枚举值](#enumerador-contact_type)** |

:::info 说明
若未发送 `contact_type`，令牌将以原始请求方式发送。
:::

| 枚举值 | 描述                                         |
|------------|---------------------------------------------------|
| **sms**    | 通过短信发送至手机 |
| **email**  | 通过电子邮件发送                      |

## Response

### 成功响应

STATUS 200

### 错误响应

STATUS 4XX

Response Body

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

| HTTP 代码 | QI 代码 | 标题 | 描述（英文） | 描述（葡文） |
|-------------|-----------|--------|------------------|------------------|
| 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         | 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. |

---

# 重新发送征税发票预约双因素身份验证令牌

URL: /zh-Hans/documentation/baas/cobranca/2fa_v2/agendamento/reenviar_token_de_agendamento_de_fatura_de_recolhimento

此端点用于重新发送征税发票预约的身份验证令牌。

:::info 征税发票
此类账单由服务特许经营商（水、电、电话和燃气账单）和政府机构（税务）开具。它们未在银行间支付结算所（CIP/Núclea）登记，因此返回的信息与银行票据不同。
:::

## Request

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

### 请求路径参数

| 字段               | 类型    | 描述                               | 字符数 |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | 账户唯一标识键。  | 36         |
| `payment_schedule_key` * | uuid4   | 预约唯一标识键。 | 36         |

### Body 参数

| 字段          | 类型   | 描述                                                                                 | 字符数 |
|----------------|--------|-------------------------------------------------------------------------------------------|------------|
| `contact_type` | enumerator | 身份验证令牌发送方式 | **[contact_type 枚举值](#enumerador-contact_type)** |

:::info 说明
若未发送 `contact_type`，令牌将以原始请求方式发送。
:::

| 枚举值 | 描述                                         |
|------------|---------------------------------------------------|
| **sms**    | 通过短信发送至手机 |
| **email**  | 通过电子邮件发送                      |

## Response

### 成功响应

STATUS 200

### 错误响应

STATUS 4XX

Response Body

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

| HTTP 代码 | QI 代码 | 标题 | 描述（英文） | 描述（葡文） |
|-------------|-----------|--------|------------------|------------------|
| 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         | 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: /zh-Hans/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: /zh-Hans/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.                                                 |

---

# 申请银行票据支付预约（双因素身份验证）

URL: /zh-Hans/documentation/baas/cobranca/2fa_v2/agendamento/solicitar_agendamento_de_boleto_bancario

此端点用于申请银行票据支付预约。请求应在查询之后进行，使用返回的信息以确保流程正确运行。

:::info 银行票据
这是常规银行票据（数字行不以数字8开头）。在银行间支付结算所（CIP/Núclea）注册，可在巴西中央银行授权的金融和支付机构付款。
:::

## Request

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

### 请求路径参数

| 字段               | 类型    | 描述                               | 字符数 |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | 账户唯一标识键。  | 36         |

Request Body: 使用数字行申请预约

```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: 使用条形码申请预约

```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 参数

| 字段               | 类型          | 描述                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | 客户请求的唯一标识键。 |    
| `barcode`               | string    | 条形码。 |
| `digitable_line`        | string    | 数字行。 |
| `payment_amount` *      | number    | 待支付金额。 |
| `payment_date` *        | string    | 预约支付日期（格式 YYYY-MM-DD）。 |
| `tfa_info` *            | [object](#objeto-tfa_info)    | 包含账户审批人文件和联系方式的对象。 | 

### tfa_info 对象
| 字段                             | 类型    | 描述                         |
|-----------------------------------|---------|-----------------------------------|
| `approver_document_number`* | string | 账户审批人的文件号码（CPF/CNPJ）。 | 
| `contact_type`*             | enumerator | 身份验证令牌验证方式 | **[contact_type 枚举值](#enumerador-contact_type)** |

| 枚举值 | 描述                                         |
|------------|---------------------------------------------------|
| **sms**    | 通过短信发送至手机 |
| **email**  | 通过电子邮件发送                      |

## Response

### 成功响应

STATUS 201

### Response Body 参数

| 字段               | 类型    | 描述                         |
|---------------------|---------|-----------------------------------|
| `payment_schedule_key` * | uuid4 | 预约唯一标识键。 |
| `request_control_key` *  | uuid4 | 客户请求唯一标识键。 |
| `payer_name` *            | string | 实际付款人名称。|
| `payment_schedule_status` * | enum | 预约状态。 |

### payment_schedule_status 枚举值
| 枚举值          | 描述                                                        |
|---------------------|------------------------------------------------------------------|
| `pending_2fa_approval` | 预约待双因素身份验证（2FA）       |
| `scheduled`          | 支付预约成功                                   |

### 错误响应

STATUS 4XX

Response Body

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

| HTTP 代码 | QI 代码 | 标题 | 描述（英文） | 描述（葡文） |
|-------------|-----------|--------|------------------|------------------|
| 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. |
| 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         | 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. |
| 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         | 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 |

---

# 申请征税发票支付预约（双因素身份验证）

URL: /zh-Hans/documentation/baas/cobranca/2fa_v2/agendamento/solicitar_agendamento_de_pagamento_de_fatura_de_recolhimento

此端点用于申请征税发票支付预约。请求应在查询之后进行，使用返回的信息以确保流程正确运行。

:::info 征税发票
此类账单由服务特许经营商（水、电、电话和燃气账单）和政府机构（税务）开具。它们未在银行间支付结算所（CIP/Núclea）登记，因此返回的信息与银行票据不同。
:::

## Request

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

### 请求路径参数

| 字段               | 类型    | 描述                               | 字符数 |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | 账户唯一标识键。  | 36         |

Request Body: 使用数字行申请征税发票预约

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "digitable_line": "836200000138892100450006762142420244046000010192",
  "payment_amount": 1389.21,
  "payment_date": "2024-04-30",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  }
}
```

### Body 参数

| 字段               | 类型          | 描述                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | 客户请求的唯一标识键。 |    
| `barcode`               | string    | 条形码。 |
| `digitable_line`        | string    | 数字行。 |
| `payment_amount` *      | number    | 待支付金额。 |
| `payment_date` *        | string    | 预约支付日期（格式 YYYY-MM-DD）。 |
| `tfa_info` *            | [object](#objeto-tfa_info)    | 包含账户审批人文件和联系方式的对象。 | 

### tfa_info 对象
| 字段                             | 类型    | 描述                         |
|-----------------------------------|---------|-----------------------------------|
| `approver_document_number`* | string | 账户审批人的文件号码（CPF/CNPJ）。 | 
| `contact_type`*             | enumerator | 身份验证令牌验证方式 |

| 枚举值 | 描述                                         |
|------------|---------------------------------------------------|
| **sms**    | 通过短信发送至手机 |
| **email**  | 通过电子邮件发送                      |

## Response

### 成功响应

STATUS 201

### 错误响应

STATUS 4XX

Response Body

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

| HTTP 代码 | QI 代码 | 标题 | 描述（英文） | 描述（葡文） |
|-------------|-----------|--------|------------------|------------------|
| 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         | 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. |
| 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         | 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 |

---

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

URL: /zh-Hans/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: /zh-Hans/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. |

---

# 银行票据批量支付确认

URL: /zh-Hans/documentation/baas/cobranca/2fa_v2/confirmacao_de_lote_de_boleto_bancario

本文描述与 [银行票据批量支付确认](../confirmacao_de_lote_de_boleto_bancario.md) 当操作在确认步骤要求 **双因素认证 (2FA)** 时：请求体必须包含 **`tfa_info`**，并与 `batch_status: approved` 或 `batch_status: rejected` 一起发送。随后，批次会处于 `pending_2fa_approval`（待批准）或 `pending_2fa_rejection`（待拒绝），直到完成 **token 校验**。

:::info 银行票据
这是传统银行票据（可输入行不以数字 8 开头）。其已在银行间清算系统（CIP/Núclea）登记，可在经央行授权的金融机构和支付机构缴付。
:::

## 请求

### 请求 Endpoint

ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/payment/batch_bank_slip/**PAYMENT_BATCH_KEY**/confirmation
方法 PATCH

### 请求 Path Params

| 字段                 | 类型  | 描述                                                                                | 字符数 |
| --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- |
| `account_key` *       | uuid4 | 账户唯一标识键。                                                   | 36         |
| `payment_batch_key` * | uuid4 | 批次唯一标识键（创建批次时返回的 `batch_payment_key`）。 | 36         |

### 请求 Body

**请求体：拒绝批次（含 `tfa_info`）**

```json
{
  "batch_status": "rejected",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  }
}
```

**请求体：批准批次（含 `tfa_info`）**

```json
{
  "batch_status": "approved",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  }
}
```

### Body 参数

| 字段            | 类型   | 描述                                                                                                                                                                                                                                                                                                                                              |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `batch_status` * | string | 批次决策。可选值：`approved`（继续处理流程）或 `rejected`（取消批次）。见 [batch_confirmation_status 枚举](#enumerador-batch_confirmation_status)。                                                                                                                                                     |
| `tfa_info`       | object | 该流程在 `batch_status: approved` 或 `batch_status: rejected` 时为必填；请在 [tfa_info 对象](#object-tfa_info) 中提供审批人及 token 发送渠道。 |

### 枚举 batch_confirmation_status

| 值      | 描述                                                     |
| ---------- | ------------------------------------------------------------- |
| `approved` | 批准批次并继续处理流程。          |
| `rejected` | 拒绝批次；银行票据将不进入异步处理。 |

### Object tfa_info

| 字段                        | 类型   | 描述                                                                                                                                          |
| ---------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `approver_document_number` * | string | 接收 token 的审批人证件号（CPF）。提供 `tfa_info` 时必填。                                                |
| `contact_type` *             | string | token 发送渠道（例如 `sms` 或 `email`），遵循业务与账户规则。提供 `tfa_info` 时必填。 |

## 响应

响应中的 HTTP 状态码和 `batch_status` 取决于提交的决策，以及该流程在本次调用后是否要求 token 校验。

### 响应：拒绝决策批次 — 等待 token 校验（2FA）

STATUS 202

当请求体中的 `batch_status` 为 `rejected` 且包含 `tfa_info` 时，API 返回 **202**。批次进入 token 校验等待状态，响应体中 `batch_status` 为 `pending_2fa_rejection`。token 校验完成后，拒绝决策生效。

**Response Body: 批次等待 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_approval",
  "payment_type": "bank_slip"
}
```

### 响应：批准决策批次 — 等待 token 校验（2FA）

STATUS 202

当请求体中的 `batch_status` 为 `approved` 且包含 `tfa_info` 时，API 返回 **202**。批次进入 token 校验等待状态，响应体中 `batch_status` 为 `pending_2fa_approval`。 后续步骤（发送验证码、校验与重发）见 [银行票据批次 token 校验](./validacao_de_token_de_lote_de_boleto_bancario.md) 以及 [重发银行票据批次 token](./solicitacao_de_reenvio_de_token_de_lote_de_boleto_bancario.md)。

**Response Body: 批次等待 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"
}
```

### 响应 Body Params

| 字段                   | 类型   | 描述                                                                                                                                                                                                                                                                     |
| ----------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `batch_payment_key` *   | uuid4  | 批量支付唯一标识键。                                                                                                                                                                                                                            |
| `request_control_key` * | uuid4  | 客户端请求唯一标识键（批次）。                                                                                                                                                                                                                 |
| `account_key` *         | uuid4  | 扣款账户键。                                                                                                                                                                                                                                                      |
| `total_amount` *        | number | 批次内所有项目金额之和。                                                                                                                                                                                                                                           |
| `batch_status` *        | string | 在该调用中，批次会保持在 `pending_2fa_approval`（待批准）或 `pending_2fa_rejection`（待拒绝），直到完成 token 校验。校验后最终状态将反映确认步骤提交的决策（`approved` 或 `rejected`）。 |
| `payment_type` *        | string | 支付类型；该流程应为 `bank_slip`。                                                                                                                                                                                                                    |

### 错误响应

STATUS 4XX

**Response Body**

```json
{
    "title": "标题",
    "description": "Description in english",
    "translation": "描述 em português",
    "code": "代码"
}
```

| HTTP 代码 | QI 代码 | 标题      | 描述 (eng)                               | 描述 (pt-br)                                     |
| ----------- | --------- | ----------- | --------------------------------------------- | ----------------------------------------------------- |
| 400         | BIP000013 | Bad Request | The source account is closed.                 | 源账户已关闭。                       |
| 400         | BIP000050 | Bad Request | Requester configuration does not exist        | 请求方配置不存在。                 |
| 400         | BIP000054 | Bad Request | TFA info required.                            | 需要 TFA 信息.                       |
| 404         | BIP000083 | Not Found   | Batch payment not found by batch payment key. | 未通过批次 key 找到批量支付。 |
| 400         | BIP000084 | Bad Request | Batch payment status is not pending.          | 批量支付状态不是待处理。     |

---

# 代收账单（公用事业/税费）批量支付确认

URL: /zh-Hans/documentation/baas/cobranca/2fa_v2/confirmacao_de_lote_de_fatura_de_recolhimento

本文描述与 [代收账单批量支付确认（公用事业/税费）](../confirmacao_de_lote_de_fatura_de_recolhimento.md) 当操作在确认步骤要求 **双因素认证 (2FA)** 时：请求体必须包含 **`tfa_info`**，并与 `batch_status: approved` 或 `batch_status: rejected` 一起发送。随后，批次会处于 `pending_2fa_approval`（待批准）或 `pending_2fa_rejection`（待拒绝），直到完成 **token 校验**。

:::info 代收账单（公用事业/税费）
该类收费由公用事业公司（水、电、电话、燃气）及政府机构（税费）开具。此类票据不在银行间清算系统（CIP/Núclea）登记，因此返回信息与银行票据不同。
:::

## 请求

### 请求 Endpoint

ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/payment/batch_collection_slip/**PAYMENT_BATCH_KEY**/confirmation
方法 PATCH

### 请求 Path Params

| 字段                 | 类型  | 描述                                                                                | 字符数 |
| --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- |
| `account_key` *       | uuid4 | 账户唯一标识键。                                                   | 36         |
| `payment_batch_key` * | uuid4 | 批次唯一标识键（创建批次时返回的 `batch_payment_key`）。 | 36         |

### 请求 Body

**请求体：拒绝批次（含 `tfa_info`）**

```json
{
  "batch_status": "rejected",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  }
}
```

**请求体：批准批次（含 `tfa_info`）**

```json
{
  "batch_status": "approved",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  }
}
```

### Body 参数

| 字段            | 类型   | 描述                                                                                                                                                                                                                                                                                                                                              |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `batch_status` * | string | 批次决策。可选值：`approved`（继续处理流程）或 `rejected`（取消批次）。见 [batch_confirmation_status 枚举](#enumerador-batch_confirmation_status)。                                                                                                                                                     |
| `tfa_info`       | object | 该流程在 `batch_status: approved` 或 `batch_status: rejected` 时为必填；请在 [tfa_info 对象](#object-tfa_info) 中提供审批人及 token 发送渠道。 |

### 枚举 batch_confirmation_status

`batch_status` 在请求体中的可选值：

| 值      | 描述                                                                     |
| ---------- | ----------------------------------------------------------------------------- |
| `approved` | 批准批次并继续处理流程。                          |
| `rejected` | 拒绝批次；代收账单将不进入异步处理。 |

### Object tfa_info

| 字段                        | 类型   | 描述                                                                                                                                          |
| ---------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `approver_document_number` * | string | 接收 token 的审批人证件号（CPF）。提供 `tfa_info` 时必填。                                                |
| `contact_type` *             | string | token 发送渠道（例如 `sms` 或 `email`），遵循业务与账户规则。提供 `tfa_info` 时必填。 |

## 响应

响应中的 HTTP 状态码和 `batch_status` 取决于提交的决策，以及该流程在本次调用后是否要求 token 校验。

### 响应：拒绝决策批次 — 等待 token 校验（2FA）

STATUS 202

当请求体中的 `batch_status` 为 `rejected` 且包含 `tfa_info` 时，API 返回 **202**。批次进入 token 校验等待状态，响应体中 `batch_status` 为 `pending_2fa_rejection`。token 校验完成后，拒绝决策生效。

**Response Body: 批次等待 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"
}
```

### 响应：批准决策批次 — 等待 token 校验（2FA）

STATUS 202

当请求体中的 `batch_status` 为 `approved` 且包含 `tfa_info` 时，API 返回 **202**。批次进入 token 校验等待状态，响应体中 `batch_status` 为 `pending_2fa_approval`。 后续步骤见 [代收账单批次 token 校验](./validacao_de_token_de_lote_de_fatura_de_recolhimento.md) 以及 [重发代收账单批次 token](./solicitacao_de_reenvio_de_token_de_lote_de_fatura_de_recolhimento.md)。

**Response Body: 批次等待 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"
}
```

### 响应 Body Params

| 字段                   | 类型   | 描述                                                                                                                                                                                                                                                                                    |
| ----------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `batch_payment_key` *   | uuid4  | 批量支付唯一标识键。                                                                                                                                                                                                                                           |
| `request_control_key` * | uuid4  | 客户端请求唯一标识键（批次）。                                                                                                                                                                                                                                |
| `account_key` *         | uuid4  | 扣款账户键。                                                                                                                                                                                                                                                                     |
| `total_amount` *        | number | 批次内所有项目金额之和。                                                                                                                                                                                                                                                          |
| `batch_status` *        | string | 在该调用中，批次会保持在 `pending_2fa_approval`（待批准）或 `pending_2fa_rejection`（待拒绝），直到完成 token 校验。校验后最终状态将反映确认步骤提交的决策（`approved` 或 `rejected`）。 |
| `payment_type` *        | string | 支付类型；该流程应为 `collection_slip`。                                                                                                                                                                                                                             |

### 错误响应

STATUS 4XX

**Response Body**

```json
{
    "title": "标题",
    "description": "Description in english",
    "translation": "描述 em português",
    "code": "代码"
}
```

| HTTP 代码 | QI 代码 | 标题      | 描述 (eng)                               | 描述 (pt-br)                                     |
| ----------- | --------- | ----------- | --------------------------------------------- | ----------------------------------------------------- |
| 400         | BIP000013 | Bad Request | The source account is closed.                 | 源账户已关闭。                       |
| 400         | BIP000050 | Bad Request | Requester configuration does not exist        | 请求方配置不存在。                 |
| 400         | BIP000054 | Bad Request | TFA info required.                            | 需要 TFA 信息.                       |
| 404         | BIP000083 | Not Found   | Batch payment not found by batch payment key. | 未通过批次 key 找到批量支付。 |
| 400         | BIP000084 | Bad Request | Batch payment status is not pending.          | 批量支付状态不是待处理。     |

---

# 银行票据支付确认

URL: /zh-Hans/documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_boleto_bancario

此端点用于确认银行票据支付。

:::info 银行票据
这是常规银行票据（数字行不以数字8开头）。在银行间支付结算所（CIP/Núclea）注册，可在巴西中央银行授权的金融和支付机构付款。
:::

## Request

### 请求端点

ENDPOINT /account/ ACCOUNT_KEY /payment/ PAYMENT_KEY /bank_slip/validate_token
MÉTODO PATCH

### 请求路径参数

| 字段               | 类型    | 描述                               | 字符数 |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | 账户唯一标识键。  | 36         |
| `payment_key` *     | uuid4   | 支付唯一标识键。  | 36     |

### 通过电子邮件和短信验证

Request Body: 银行票据支付确认

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

### 通过设备验证

要通过设备审批并完成验证，请求需发送空载荷。验证在内部完成，请求正文中无需附加信息。请注意，此端点只应在[支付请求](./solicitacao_de_pagamento_de_boleto_bancario.md)已启动后使用。

Request Body: 银行票据支付确认

```json
{

}
```

### Body 参数

| 字段     | 类型   | 描述                                                             | 字符数 |
|-----------|--------|-----------------------------------------------------------------------|------------|
| `token`   | string | 发送给账户转账审批人的验证码，**通过短信或电子邮件 TFA 时必填**| 6          |

## Response

### 成功响应

STATUS 200

Response Body: 支付已执行

```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: 支付待执行

```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 说明
若返回 **HTTP Status 202** 且 `payment_status` 字段值为 **pending_execution**，则不应重试该支付。

该支付将异步处理。需要通过支付查询来验证转账状态，或等待[webhooks 页面](/documentation/baas/cobranca/webhooks)中描述的待处理支付 webhook。
:::

### Response Body 参数

| 字段               | 类型    | 描述                         |
|---------------------|---------|-----------------------------------|
| `payment_key` *               | uuid4 | 支付唯一标识键。 |
| `request_control_key` *       | uuid4 | 客户请求唯一标识键。 |
| `payer_name` *                | string | 实际付款人名称。|
| `payer_document_number` *     | string | 实际付款人文件号码（CPF/CNPJ）。 |
| `source_account_key` *        | uuid4 | 被扣款账户密钥。 |
| `transaction_key` *           | uuid4 | 支付交易密钥。 |
| `transaction_revert_key`      | uuid4 | 支付冲销交易密钥。 |
| `paid_amount` *               | number | 实际支付金额。 |
| `payment_date` *              | string | 支付日期。 |
| `payment_type` *              | [enum](#enumeradores-payment_type) | 支付类型。 |
| `bank_slip`                   | [object](#objeto-bank_slip) | 银行票据。 |
| `collection_slip`             | object | 征税发票。 |
| `payment_status` *            | [enum](#enumeradores-payment_status) | 支付状态。 |

### payment_type 枚举值
| 枚举值    | 类型      | 描述     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | 银行票据    |
| `collection_slip` | string  | 征税发票 |

:::danger 警告
`collection_slip` 枚举值不适用于银行票据流程，同样 collection_slip 对象始终为空。
:::

### payment_status 枚举值
| 枚举值    | 描述     |
|---------------|---------------|
| `pending_execution`     | 待执行 |
| `executed`    | 已执行 |
| `reverted`    | 已冲销 |
| `rejected`    | 已拒绝 |
| `error`       | 错误      |

:::danger 警告
对于 QI 在两分钟内未收到 CIP 响应的支付，支付将以 `pending_execution` 状态返回。QI 收到 CIP 响应后，将向客户发送[webhooks 页面](/documentation/baas/cobranca/webhooks)中描述的待处理支付 webhook。
:::

### bank_slip 对象
| 字段                             | 类型    | 描述                         |
|-----------------------------------|---------|-----------------------------------|
| `barcode` *                       | string | 条形码。 |
| `digitable_line` *                | string | 数字行。 |
| `payer_name` *                    | string | 付款人名称。|
| `payer_document_number` *         | string | 付款人文件号码（CPF/CNPJ）。 |
| `beneficiary_name` *              | string | 受益人名称。 |
| `beneficiary_trading_name`        | string | 受益人商业名称。 |
| `beneficiary_document_number` *   | string | 受益人文件号码（CPF/CNPJ）。 |
| `beneficiary_bank_ispb` *         | string | 受益人银行 ISPB 代码。 |
| `guarantor_name`                  | string | 保证人名称。 |
| `guarantor_document_number`       | string | 保证人文件号码（CPF/CNPJ）。 |
| `expiration_date` *               | string | 到期日期。 |
| `max_payment_date` * | string  | 最大支付日期。 |
| `partial_payment_indicator` *     | [enum](#enumeradores-partial_payment_indicator)   | 部分付款指示符。 |
| `registered_payment_amount`       | string | 已登记的总支付金额。 |
| `nominal_amount` *                | number | 原始金额。 |
| `total_amount` *                  | number | 总金额。 |
| `rebate_amount` *                 | number | 折扣金额。 |
| `discount_amount` *               | number | 优惠金额。 |
| `fine_amount` *                   | number | 罚款金额。 |
| `interest_amount` *               | number | 利息金额。 |

### partial_payment_indicator 枚举值
| 枚举值    | 类型      | 描述     |
|---------------|-----------|---------------|
| `allowed`     | string    | 允许     |
| `not_allowed` | string    | 不允许 |

### 错误响应

STATUS 4XX

Response Body

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

| HTTP 代码 | QI 代码 | 标题 | 描述（英文） | 描述（葡文） |
|-------------|-----------|--------|------------------|------------------|
| 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.             |

---

# 确认收款单付款

URL: /zh-Hans/documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_fatura_de_recolhimento

此端点用于确认收款单的付款。

:::info 收款单
此类收费由服务特许经营商（水、电、电话和燃气账单）及政府机构（税款）发行。它们不在银行间支付清算所（CIP/Núclea）登记，因此返回的信息与银行划账单不同。
:::

## Request

### Request Endpoint

ENDPOINT /account/ ACCOUNT_KEY /payment/ PAYMENT_KEY /collection_slip/validate_token
MÉTODO PATCH

### Request Path Params

| 字段                | 类型    | 描述                                    | 字符数 |
|---------------------|---------|-----------------------------------------|--------|
| `account_key` *     | uuid4   | 账户的唯一标识键。                       | 36     |
| `payment_key` *     | uuid4   | 付款的唯一标识键。                       | 36     |

### 通过邮件和短信认证

Request Body: 确认收款单付款

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

### 通过设备认证

要通过设备认证批准并完成认证，请求必须以空负载发送。验证在内部进行，无需在请求体中提供额外信息。需要注意的是，此端点仅应在[付款请求](./solicitacao_de_pagamento_de_fatura_de_recolhimento.md)启动后使用。

Request Body: 确认收款单付款

```json
{

}
```

### Body Params

| 字段      | 类型   | 描述                                                                            | 字符数 |
|-----------|--------|---------------------------------------------------------------------------------|--------|
| `token`   | string | 发送给账户转账审批人的认证码，**通过短信或邮件进行二次验证时为必填项**           | 6      |

## Response

### Success Response

STATUS 200

Response Body: 付款已执行

```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

| 字段                          | 类型    | 描述                                   |
|-------------------------------|---------|----------------------------------------|
| `payment_key` *               | uuid4 | 付款的唯一标识键。                        |
| `request_control_key` *       | uuid4 | 客户请求的唯一标识键。                    |
| `payer_name` *                | string | 实际付款人姓名。                          |
| `payer_document_number` *     | string | 实际付款人的证件号（CPF/CNPJ）。           |
| `source_account_key` *        | uuid4 | 被扣款账户的键。                          |
| `transaction_key` *           | uuid4 | 付款交易的键。                            |
| `transaction_revert_key`      | uuid4 | 付款冲销交易的键。                        |
| `paid_amount` *               | number | 实际付款金额。                            |
| `payment_date` *              | string | 付款日期。                               |
| `payment_type` *              | [enum](#enumeradores-payment_type) | 付款类型。              |
| `bank_slip`                   | object | 银行划账单。                              |
| `collection_slip`             | [object](#objeto-collection_slip) | 收款单。               |
| `payment_status` *            | [enum](#enumeradores-payment_status) | 付款状态。           |

### Enumeradores payment_type
| 枚举值          | 类型      | 描述          |
|-----------------|-----------|---------------|
| `bank_slip`     | string    | 银行划账单     |
| `collection_slip` | string  | 收款单        |

:::danger 注意
`bank_slip` 枚举值不适用于收款单流程，bank_slip 对象始终为 null。
:::

### Enumeradores payment_status
| 枚举值      | 描述     |
|-------------|----------|
| `executed`  | 已执行   |
| `reverted`  | 已冲销   |
| `rejected`  | 已拒绝   |
| `error`     | 错误     |

### Objeto collection_slip
| 字段                             | 类型    | 描述                               |
|----------------------------------|---------|------------------------------------|
| `barcode`          | string | 条形码。                             |
| `digitable_line`   | string | 可输入行。                           |
| `collection_name` *         | string | 协议名称。                          |
| `collection_document_number`   | string | 协议文件编号（CPF/CNPJ）。          |
| `expiration_date` *  | string  | 到期日期。                          |
| `total_amount` *  | number | 总金额。                             |

### Error Response

STATUS 4XX

Response Body

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

| HTTP 代码   | QI 代码   | 标题         | 描述（英文）                                                                                                                                                                                  | 描述（葡文）                                                                                                                                                                                 |
|-------------|-----------|--------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 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         | 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. |

---

# 双因素身份验证简介

URL: /zh-Hans/documentation/baas/cobranca/2fa_v2/introducao_ao_pagamento_2fa

此类支付需要通过向付款账户中有转账审批权的人员发送令牌来确认付款。

配置了双因素身份验证的合作集成商发起支付请求的方式与[银行票据支付](/documentation/baas/cobranca/pagar_boleto_bancario)和[征税发票支付](/documentation/baas/cobranca/pagar_fatura_de_recolhimento)中描述的方式类似。
区别在于请求中添加了 `tfa_info` 对象，包含转账审批人信息及联系方式，以及请求响应中返回的状态。请求状态始终返回 **pending_2fa_approval**。

## 带授权的支付流程

成功支付将遵循以下流程：

- 发起[银行票据支付请求](/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_boleto_bancario)或[征税发票支付请求](/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_fatura_de_recolhimento)，同步接收状态为 **pending_2fa_approval** 和 `payment_key` 的响应。
- 指定的审批人将收到一个由6位数字组成的 `token`。
- 请求方使用 `payment_key` 和 `token` 进行[银行票据支付确认](/documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_boleto_bancario)或[征税发票支付确认](/documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_fatura_de_recolhimento)。
- 支付将同步完成。

## 注意事项

- 每笔支付最多可尝试验证 `token` 5次。达到此限制后，支付将自动置为拒绝（**rejected**）状态。
- 每个 `token` 最长有效期为5分钟。
- 支付的 `token` 可以续期并重新发送给账户审批人。此过程重置5分钟计时，但不重置无效尝试计数器。之前的 `token` 将失效。
- 支付一经审批，将同步完成。
- 向审批人发送 `token` 的通知事件为 **baas.token_validation.bill_payment.payment.single**。可以[自定义](/documentation/notificacoes/template)发送的消息。
- 已实现的令牌发送方式（`contact_type`）为 **sms** 和 **email**。

---

# 双因素身份验证银行票据支付请求

URL: /zh-Hans/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_boleto_bancario

此端点用于发起银行票据支付请求。请求应在查询之后进行，使用返回的信息以确保流程正确运行，避免处理过程中出现错误。

:::info 银行票据
这是常规银行票据（数字行不以数字8开头）。在银行间支付结算所（CIP/Núclea）注册，可在巴西中央银行授权的金融和支付机构付款。
:::

## Request

### 请求端点

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

### 请求路径参数

| 字段               | 类型    | 描述                               | 字符数 |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | 账户唯一标识键。  | 36         |

## 通过电子邮件和短信验证

Request Body: 使用数字行通过短信或电子邮件 TFA 发起银行票据支付

```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: 使用条形码通过短信或电子邮件 TFA 发起银行票据支付

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

## 通过设备验证

除了现有的 **sms** 和 **email** 验证方式外，还可以使用[预先注册的设备](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo)对交易进行验证。在这种情况下，`session_id` 需从**设备扫描**获取并在 `tfa_info` 中发送。

Request Body: 使用数字行通过设备 TFA 发起银行票据支付

```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: 使用条形码通过设备 TFA 发起银行票据支付

```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 参数

| 字段               | 类型          | 描述                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | 客户请求的唯一标识键。 |    
| `barcode`               | string    | 条形码。 |
| `digitable_line`        | string    | 数字行。 |
| `payment_amount` *      | number    | 待支付金额。 |
| `tfa_info` *            | [object](#objeto-tfa_info)    | 包含账户审批人文件和联系方式的对象。 | 

:::danger 警告
除非银行票据允许部分付款，否则 `payment_amount` 必须始终等于查询银行票据时返回的 `total_amount`。对于允许部分付款的票据，客户可以选择 `payment_amount`，但其与银行票据 `registered_payment_amount` 之和不得超过 `total_amount`。
:::

### tfa_info 对象
| 字段                             | 类型    | 描述                         |
|-----------------------------------|---------|-----------------------------------|
| `approver_document_number`* | string | 账户审批人的文件号码（CPF/CNPJ）。 | 
| `session_id`| string | UUID v4 格式的设备会话唯一标识键（设备 TFA 必填）。 |   36         |
| `contact_type`*             | enumerator | 身份验证令牌验证方式 | **[contact_type 枚举值](#enumerador-contact_type)** |

| 枚举值 | 描述                                         |
|------------|---------------------------------------------------|
| **sms**    | 通过短信发送至手机 |
| **email**  | 通过电子邮件发送                      |
| **device** | 通过设备令牌验证                |

## Response

### 成功响应

STATUS 201

Response Body: 支付待双因素审批

```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 参数

| 字段               | 类型    | 描述                         |
|---------------------|---------|-----------------------------------|
| `payment_key` *               | uuid4 | 支付唯一标识键。 |
| `request_control_key` *       | uuid4 | 客户请求唯一标识键。 |
| `payer_name` *                | string | 实际付款人名称。|
| `payer_document_number` *     | string | 实际付款人文件号码（CPF/CNPJ）。 |
| `source_account_key` *        | uuid4 | 被扣款账户密钥。 |
| `transaction_key` *           | uuid4 | 支付交易密钥。 |
| `transaction_revert_key`      | uuid4 | 支付冲销交易密钥。 |
| `paid_amount` *               | number | 实际支付金额。 |
| `payment_date` *              | string | 支付日期。 |
| `payment_type` *              | [enum](#enumeradores-payment_type) | 支付类型。 |
| `bank_slip`                   | [object](#objeto-bank_slip) | 银行票据。 |
| `collection_slip`             | object | 征税发票。 |
| `payment_status` *            | [enum](#enumeradores-payment_status) | 支付状态。 |

### payment_type 枚举值
| 枚举值    | 类型      | 描述     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | 银行票据    |
| `collection_slip` | string  | 征税发票 |

:::danger 警告
`collection_slip` 枚举值不适用于银行票据流程，同样 collection_slip 对象始终为空。
:::

### payment_status 枚举值
| 枚举值    | 描述     |
|---------------|---------------|
| `pending_2fa_approval`    | 待双因素审批 |

### bank_slip 对象
| 字段                             | 类型    | 描述                         |
|-----------------------------------|---------|-----------------------------------|
| `barcode` *                       | string | 条形码。 |
| `digitable_line` *                | string | 数字行。 |
| `payer_name` *                    | string | 付款人名称。|
| `payer_document_number` *         | string | 付款人文件号码（CPF/CNPJ）。 |
| `beneficiary_name` *              | string | 受益人名称。 |
| `beneficiary_trading_name`        | string | 受益人商业名称。 |
| `beneficiary_document_number` *   | string | 受益人文件号码（CPF/CNPJ）。 |
| `beneficiary_bank_ispb` *         | string | 受益人银行 ISPB 代码。 |
| `guarantor_name`                  | string | 保证人名称。 |
| `guarantor_document_number`       | string | 保证人文件号码（CPF/CNPJ）。 |
| `expiration_date` *               | string | 到期日期。 |
| `max_payment_date` * | string  | 最大支付日期。 |
| `partial_payment_indicator` *     | [enum](#enumeradores-partial_payment_indicator)   | 部分付款指示符。 |
| `registered_payment_amount`       | string | 已登记的总支付金额。 |
| `nominal_amount` *                | number | 原始金额。 |
| `total_amount` *                  | number | 总金额。 |
| `rebate_amount` *                 | number | 折扣金额。 |
| `discount_amount` *               | number | 优惠金额。 |
| `fine_amount` *                   | number | 罚款金额。 |
| `interest_amount` *               | number | 利息金额。 |

### partial_payment_indicator 枚举值
| 枚举值    | 类型      | 描述     |
|---------------|-----------|---------------|
| `allowed`     | string    | 允许     |
| `not_allowed` | string    | 不允许 |

### 错误响应

STATUS 4XX

Response Body

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

| HTTP 代码 | QI 代码 | 标题 | 描述（英文） | 描述（葡文） |
|-------------|-----------|--------|------------------|------------------|
| 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                |

## 沙盒环境

在我们的沙盒环境中，我们提供模拟的数字行用于模拟成功支付和错误场景测试。

| 数字行 |
|-----------------|
| 00190000090361557400500000024174396700000991000 |
| 00190000090282802601919212747174596760001294161 |
| 23793390014000000455277000249001596900000103995 |
| 75691434020137513680900001040013196770002417240 |
| 21390001171200000570700168167484796770000148206 |
| 34191090083273252027893634770007296690012513600 |
| 42297048060005815702500130494123896770000239491 |
| 07090010287045349010776686070590896770001160123 |
| 74891123702849020818918378871083196690000050000 |
| 23792374119000209350986000372408496610000122810 |

---

# 请求双因素认证收款单付款

URL: /zh-Hans/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_fatura_de_recolhimento

此端点用于通过双因素认证请求收款单付款。请求应在查询之后进行，使用返回的信息以确保流程正常运行，避免过程中出现失败。

:::info 收款单
此类收费由服务特许经营商（水、电、电话和燃气账单）及政府机构（税款）发行。它们不在银行间支付清算所（CIP/Núclea）登记，因此返回的信息与银行划账单不同。
:::

## Request

### Request Endpoint

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

### Request Path Params

| 字段               | 类型    | 描述                               | 字符数 |
|--------------------|---------|------------------------------------|--------|
| `account_key` *    | uuid4   | 账户的唯一标识键。                  | 36     |

## 通过邮件和短信认证

Request Body: 通过可输入行使用短信或邮件TFA请求收款单

```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: 通过条形码使用短信或邮件TFA请求收款单

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

## 通过设备认证

除了现有的**短信**和**邮件**认证方式外，还可以使用[预先注册的设备](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo)对交易进行认证。此时，`session_id` 需从 **Device Scan** 获取并在 `tfa_info` 中发送。

Request Body: 通过可输入行使用设备TFA请求收款单

```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: 通过条形码使用设备TFA请求收款单

```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

| 字段                    | 类型          | 描述                                          |
|-------------------------|---------------|-----------------------------------------------|
| `request_control_key` * | uuid4         | 客户请求的唯一标识键。                         |    
| `barcode`               | string        | 条形码。                                       |
| `digitable_line`        | string        | 可输入行。                                     |
| `payment_amount` *      | number        | 待付金额。                                     |
| `tfa_info` *            | [object](#objeto-tfa_info) | 包含账户审批人文件及联系方式的对象。 | 

:::danger 注意
`payment_amount` 必须始终等于查询银行划账单时返回的 `total_amount`。
:::

### Objeto tfa_info
| 字段                             | 类型    | 描述                                          |
|----------------------------------|---------|-----------------------------------------------|
| `approver_document_number`* | string | 账户审批人的文件编号（CPF/CNPJ）。              | 
| `session_id`| string | 设备会话的唯一标识键，UUID v4 格式（设备TFA时为必填项）。 | 36 |
| `contact_type`*             | enumerator | 认证令牌的验证方式 | **[Enumerador contact_type](#enumerador-contact_type)** |

| 枚举值     | 描述                     |
|------------|--------------------------|
| **sms**    | 发送至手机的短信          |
| **email**  | 发送至电子邮件            |
| **device** | 通过设备令牌验证          |

## Response

### Success Response

STATUS 201

Response Body: 付款待双因素批准

```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

| 字段                          | 类型    | 描述                                   |
|-------------------------------|---------|----------------------------------------|
| `payment_key` *               | uuid4 | 付款的唯一标识键。                        |
| `request_control_key` *       | uuid4 | 客户请求的唯一标识键。                    |
| `payer_name` *                | string | 实际付款人姓名。                          |
| `payer_document_number` *     | string | 实际付款人的证件（CPF/CNPJ）。            |
| `source_account_key` *        | uuid4 | 被扣款账户的键。                          |
| `transaction_key` *           | uuid4 | 付款交易的键。                            |
| `transaction_revert_key`      | uuid4 | 付款冲销交易的键。                        |
| `paid_amount` *               | number | 实际付款金额。                            |
| `payment_date` *              | string | 付款日期。                               |
| `payment_type` *              | [enum](#enumeradores-payment_type) | 付款类型。              |
| `bank_slip`                   | object | 银行划账单。                              |
| `collection_slip`             | [object](#objeto-collection_slip) | 收款单。               |
| `payment_status` *            | [enum](#enumeradores-payment_status) | 付款状态。           |

### Enumeradores payment_type
| 枚举值          | 类型      | 描述          |
|-----------------|-----------|---------------|
| `bank_slip`     | string    | 银行划账单     |
| `collection_slip` | string  | 收款单        |

:::danger 注意
`bank_slip` 枚举值不适用于收款单流程，bank_slip 对象始终为 null。
:::

### Enumeradores payment_status
| 枚举值                    | 描述                       |
|---------------------------|----------------------------|
| `pending_2fa_approval`    | 待双因素批准               |

### Objeto collection_slip
| 字段                              | 类型    | 描述                               |
|-----------------------------------|---------|------------------------------------|
| `barcode`          | string | 条形码。                             |
| `digitable_line`   | string | 可输入行。                           |
| `collection_name` *         | string | 协议名称。                          |
| `collection_document_number`   | string | 协议文件编号（CPF/CNPJ）。          |
| `expiration_date` *  | string  | 到期日期。                          |
| `total_amount` *  | number | 总金额。                             |

### Error Response

STATUS 4XX

Response Body

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

| HTTP 代码   | QI 代码   | 标题         | 描述（英文）                                                                                                                             | 描述（葡文）                                                                                                                           |
|-------------|-----------|--------------|------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------|
| 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 |

## Sandbox 环境

在我们的 sandbox 环境中，我们提供了模拟的可输入行，用于模拟成功付款和错误场景测试。

| 可输入行 |
|---|
| 828300000007411100972013905080001546763201900028 |
| 838000000009235700481007241345219112001474229880 |
| 848000000006308600802021201071261517689002201070 |
| 858200000015000000643025703477209504800448091020 |
| 858500000037350000643217212883260006147448091022 |

---

# 重新发送银行票据支付双因素身份验证令牌

URL: /zh-Hans/documentation/baas/cobranca/2fa_v2/solicitacao_de_reenvio_de_token_de_boleto_bancario

此端点用于重新发送银行票据支付的身份验证令牌。

:::info 银行票据
这是常规银行票据（数字行不以数字8开头）。在银行间支付结算所（CIP/Núclea）注册，可在巴西中央银行授权的金融和支付机构付款。
:::

## Request

### 请求端点

ENDPOINT /account/ ACCOUNT_KEY /payment/ PAYMENT_KEY /bank_slip/resend_token
MÉTODO PATCH

### 请求路径参数

| 字段           | 类型  | 描述                                  | 字符数 |
|-----------------|-------|--------------------------------------------|------------|
| `account_key` * | uuid4 | 账户唯一标识键。     | 36         |
| `payment_key` * | uuid4 | 支付唯一标识键。 | 36         |

### Body 参数

| 字段          | 类型       | 描述                               | 字符数                                              |
|----------------|------------|-----------------------------------------|---------------------------------------------------------|
| `contact_type` | enumerator | 身份验证令牌发送方式 | **[contact_type 枚举值](#enumerador-contact_type)** |

:::info 说明
若未发送 `contact_type`，令牌将以原始请求方式发送。
:::

| 枚举值 | 描述                                         |
|------------|---------------------------------------------------|
| **sms**    | 通过短信发送至手机 |
| **email**  | 通过电子邮件发送                      |

## Response

### 成功响应

STATUS 200

Response Body: 令牌已成功重发

```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 参数

| 字段                     | 类型                                 | 描述                                           |
|---------------------------|--------------------------------------|-----------------------------------------------------|
| `payment_key` *           | uuid4                                | 支付唯一标识键。          |
| `request_control_key` *   | uuid4                                | 客户请求唯一标识键。 |
| `payer_name` *            | string                               | 实际付款人名称。                            |
| `payer_document_number` * | string                               | 实际付款人文件号码（CPF/CNPJ）。     |
| `source_account_key` *    | uuid4                                | 被扣款账户密钥。                            |
| `transaction_key` *       | uuid4                                | 支付交易密钥。                    |
| `transaction_revert_key`  | uuid4                                | 支付冲销交易密钥。        |
| `paid_amount` *           | number                               | 实际支付金额。                            |
| `payment_date` *          | string                               | 支付日期。                                  |
| `payment_type` *          | [enum](#enumeradores-payment_type)   | 支付类型。                                  |
| `bank_slip`               | [object](#objeto-bank_slip)          | 银行票据。                                    |
| `collection_slip`         | object                               | 征税发票。                             |
| `payment_status` *        | [enum](#enumeradores-payment_status) | 支付状态。                                |

### payment_type 枚举值

| 枚举值        | 类型   | 描述              |
|-------------------|--------|------------------------|
| `bank_slip`       | string | 银行票据        |
| `collection_slip` | string | 征税发票 |

:::danger 警告
`collection_slip` 枚举值不适用于银行票据流程，同样 collection_slip 对象始终为空。
:::

### payment_status 枚举值

| 枚举值             | 描述                             |
|------------------------|---------------------------------------|
| `pending_2fa_approval` | 待双因素审批 |

### bank_slip 对象

| 字段                           | 类型                                            | 描述                                           |
|---------------------------------|-------------------------------------------------|-----------------------------------------------------|
| `barcode` *                     | string                                          | 条形码。                                   |
| `digitable_line` *              | string                                          | 数字行。                                    |
| `payer_name` *                  | string                                          | 付款人名称。                                    |
| `payer_document_number` *       | string                                          | 付款人文件号码（CPF/CNPJ）。          |
| `beneficiary_name` *            | string                                          | 受益人名称。                               |
| `beneficiary_trading_name`      | string                                          | 受益人商业名称。                      |
| `beneficiary_document_number` * | string                                          | 受益人文件号码（CPF/CNPJ）。     |
| `beneficiary_bank_ispb` *       | string                                          | 受益人银行 ISPB 代码。               |
| `guarantor_name`                | string                                          | 保证人名称。                           |
| `guarantor_document_number`     | string                                          | 保证人文件号码（CPF/CNPJ）。 |
| `expiration_date` *             | string                                          | 到期日期。                                 |
| `max_payment_date` *            | string                                          | 最大支付日期。                           |
| `partial_payment_indicator` *   | [enum](#enumeradores-partial_payment_indicator) | 部分付款指示符。                     |
| `registered_payment_amount`     | string                                          | 已登记的总支付金额。                |
| `nominal_amount` *              | number                                          | 原始金额。                                     |
| `total_amount` *                | number                                          | 总金额。                                        |
| `rebate_amount` *               | number                                          | 折扣金额。                                |
| `discount_amount` *             | number                                          | 优惠金额。                                  |
| `fine_amount` *                 | number                                          | 罚款金额。                                     |
| `interest_amount` *             | number                                          | 利息金额。                                     |

### partial_payment_indicator 枚举值

| 枚举值    | 类型   | 描述     |
|---------------|--------|---------------|
| `allowed`     | string | 允许     |
| `not_allowed` | string | 不允许 |

### 错误响应

STATUS 4XX

Response Body

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

| HTTP 代码 | QI 代码 | 标题      | 描述（英文）                                                                                    | 描述（葡文）                                                                                         |
|-------------|-----------|-------------|----------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------|
| 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.                                                     |

---

# 重新发送征税发票支付双因素身份验证令牌

URL: /zh-Hans/documentation/baas/cobranca/2fa_v2/solicitacao_de_reenvio_de_token_de_fatura_de_recolhimento

此端点用于重新发送征税发票支付的身份验证令牌。

:::info 征税发票
此类账单由服务特许经营商（水、电、电话和燃气账单）和政府机构（税务）开具。它们未在银行间支付结算所（CIP/Núclea）登记，因此返回的信息与银行票据不同。
:::

## Request

### 请求端点

ENDPOINT /account/ ACCOUNT_KEY /payment/ PAYMENT_KEY /collection_slip/resend_token
MÉTODO PATCH

### 请求路径参数

| 字段               | 类型    | 描述                               | 字符数 |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | 账户唯一标识键。  | 36         |
| `payment_key` *     | uuid4   | 支付唯一标识键。  | 36     |

### Body 参数

| 字段          | 类型   | 描述                                                                                 | 字符数 |
|----------------|--------|-------------------------------------------------------------------------------------------|------------|
| `contact_type` | enumerator | 身份验证令牌发送方式 | **[contact_type 枚举值](#enumerador-contact_type)** |

:::info 说明
若未发送 `contact_type`，令牌将以原始请求方式发送。
:::

| 枚举值 | 描述                                         |
|------------|---------------------------------------------------|
| **sms**    | 通过短信发送至手机 |
| **email**  | 通过电子邮件发送                      |

## Response

### 成功响应

STATUS 200

Response Body: 令牌已成功重发

```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 参数

| 字段               | 类型    | 描述                         |
|---------------------|---------|-----------------------------------|
| `payment_key` *               | uuid4 | 支付唯一标识键。 |
| `request_control_key` *       | uuid4 | 客户请求唯一标识键。 |
| `payer_name` *                | string | 实际付款人名称。|
| `payer_document_number` *     | string | 实际付款人文件号码（CPF/CNPJ）。 |
| `source_account_key` *        | uuid4 | 被扣款账户密钥。 |
| `transaction_key` *           | uuid4 | 支付交易密钥。 |
| `transaction_revert_key`      | uuid4 | 支付冲销交易密钥。 |
| `paid_amount` *               | number | 实际支付金额。 |
| `payment_date` *              | string | 支付日期。 |
| `payment_type` *              | [enum](#enumeradores-payment_type) | 支付类型。 |
| `bank_slip`                   | object | 银行票据。 |
| `collection_slip`             | [object](#objeto-collection_slip) | 征税发票。 |
| `payment_status` *            | [enum](#enumeradores-payment_status) | 支付状态。 |

### payment_type 枚举值
| 枚举值    | 类型      | 描述     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | 银行票据    |
| `collection_slip` | string  | 征税发票 |

:::danger 警告
`bank_slip` 枚举值不适用于征税发票流程，同样 bank_slip 对象始终为空。
:::

### payment_status 枚举值
| 枚举值    | 描述     |
|---------------|---------------|
| `pending_2fa_approval`    | 待双因素审批 |

### collection_slip 对象
| 字段                             | 类型    | 描述                         |
|-----------------------------------|---------|-----------------------------------|
| `barcode`          | string | 条形码。 |
| `digitable_line`   | string | 数字行。 |
| `collection_name` *         | string | 协议名称。|
| `collection_document_number`   | string | 协议文件号码（CPF/CNPJ）。|
| `expiration_date` *  | string  | 到期日期。 |
| `total_amount` *  | number | 总金额。 |

### 错误响应

STATUS 4XX

Response Body

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

| HTTP 代码 | QI 代码 | 标题 | 描述（英文） | 描述（葡文） |
|-------------|-----------|--------|------------------|------------------|
| 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. |

---

# 重新发送银行票据批量支付确认令牌

URL: /zh-Hans/documentation/baas/cobranca/2fa_v2/solicitacao_de_reenvio_de_token_de_lote_de_boleto_bancario

该端点用于**重新发送**双重验证（2FA）令牌，适用于正在等待令牌校验的银行票据批量。系统会生成并发送新的令牌给审批人。如果令牌校验尝试次数已超限，可能无法重发。

:::info 银行票据
这是传统银行票据（可输入行不以数字 8 开头）。其已在银行间清算系统（CIP/Núclea）登记，可在经央行授权的金融机构和支付机构缴付。
:::

## 请求

### 请求 Endpoint

ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/payment/batch_bank_slip/**PAYMENT_BATCH_KEY**/resend_token
方法 PATCH

### 请求 Path Params

| 字段                 | 类型  | 描述                                                                                | 字符数 |
| --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- |
| `account_key` *       | uuid4 | 账户唯一标识键。                                                   | 36         |
| `payment_batch_key` * | uuid4 | 批次唯一标识键（创建批次时返回的 `batch_payment_key`）。 | 36         |

### 请求 Body

Request Body (opcional)

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

### Body 参数

| 字段          | 类型       | 描述                               | 字符数                                              |
| -------------- | ---------- | --------------------------------------- | ------------------------------------------------------- |
| `contact_type` | enumerator | 认证 token 的发送方式 | **[contact_type 枚举](#enumerador-contact_type)** |

:::info 信息
如果未发送 `contact_type`，令牌将按最初请求的方式发送（`tfa_info.contact_type`）。
:::

### 枚举 contact_type

| Enumerador | 描述                                         |
| ---------- | ------------------------------------------------- |
| **sms**    | 通过短信发送到手机 |
| **email**  | Envio por correio eletrônico                      |

## 响应

### 成功响应

STATUS 200

响应体：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_approval",
  "payment_type": "bank_slip"
}
```

### 响应 Body Params

| 字段                   | 类型   | 描述                                                                                                                                                                                                                                                                                    |
| ----------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `batch_payment_key` *   | uuid4  | 批量支付唯一标识键。                                                                                                                                                                                                                                           |
| `request_control_key` * | uuid4  | 客户端请求唯一标识键（批次）。                                                                                                                                                                                                                                |
| `account_key` *         | uuid4  | 扣款账户键。                                                                                                                                                                                                                                                                     |
| `total_amount` *        | number | 批次内所有项目金额之和。                                                                                                                                                                                                                                                          |
| `batch_status` *        | string | 重发后，批次仍处于等待 token 校验状态。`batch_status` 生命周期遵循该业务配置的批量支付申请文档（枚举 `batch_payment_status`）。 |
| `payment_type` *        | string | 支付类型；该流程应为 `bank_slip`。                                                                                                                                                                                                                                   |

然后使用 [银行票据批次 token 校验](./validacao_de_token_de_lote_de_boleto_bancario.md) 完成 2FA。

### 错误响应

STATUS 4XX

Response Body

```json
{
  "title": "标题",
  "description": "Description in english",
  "translation": "描述 em português",
  "code": "代码"
}
```

| HTTP 代码 | QI 代码 | 标题      | 描述 (eng)                                                                                    | 描述 (pt-br)                                                                                         |
| ----------- | --------- | ----------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| 403         | BIP000010 | Forbidden   | User is not allowed to do this action                                                              | 用户无权限执行此操作                                                          |
| 404         | BIP000011 | Not Found   | The source account key was not found.                                                              | 未找到源账户 key。                                                            |
| 400         | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | 当前无法查询源账户，请稍后重试。 |
| 400         | BIP000013 | Bad Request | The source account is closed.                                                                      | 源账户已关闭。                                                                           |
| 400         | BIP000014 | Bad Request | The source account is blocked.                                                                     | 源账户已冻结。                                                                         |
| 400         | BIP000059 | Bad Request | Number of verification token validation attempts exceeded.                                         | 验证码校验尝试次数超限。                                       |
| 400         | BIP000064 | Bad Request | Error resending verification token                                                                 | 重发验证码失败                                                                     |
| 400         | BIP000065 | Bad Request | Payment verification time window exceeded.                                                         | 支付校验时间窗口已超限。                                                     |
| 404         | BIP000083 | Not Found   | Batch payment not found by batch payment key.                                                      | 未通过批次 key 找到批量支付。                                                     |
| 400         | BIP000085 | Bad Request | Batch payment status is not pending approval.                                                      | 批量支付状态不是待批准。                                                 |
| 400         | BIP000086 | Bad Request | A token is required for SMS or email validation.                    | SMS 或 Email 校验必须提供 token。             |

---

# 重新发送代收账单批量支付确认令牌（公用事业/税费）

URL: /zh-Hans/documentation/baas/cobranca/2fa_v2/solicitacao_de_reenvio_de_token_de_lote_de_fatura_de_recolhimento

该端点用于**重新发送**双重验证（2FA）令牌，适用于正在等待令牌校验的代收账单批量。系统会生成并发送新的令牌给审批人。如果令牌校验尝试次数已超限，可能无法重发。

:::info 代收账单（公用事业/税费）
该类账单由公用事业公司（水、电、电话、燃气）和公共机构（税费）开具。其不在银行间支付清算系统（CIP/Núclea）登记，因此返回信息与银行票据不同。
:::

## 请求

### 请求 Endpoint

ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/payment/batch_collection_slip/**PAYMENT_BATCH_KEY**/resend_token
方法 PATCH

### 请求 Path Params

| 字段                 | 类型  | 描述                                                                                | 字符数 |
| --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- |
| `account_key` *       | uuid4 | 账户唯一标识键。                                                   | 36         |
| `payment_batch_key` * | uuid4 | 批次唯一标识键（创建批次时返回的 `batch_payment_key`）。 | 36         |

### 请求 Body

Request Body (opcional)

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

### Body 参数

| 字段          | 类型       | 描述                               | 字符数                                              |
| -------------- | ---------- | --------------------------------------- | ------------------------------------------------------- |
| `contact_type` | enumerator | 认证 token 的发送方式 | **[contact_type 枚举](#enumerador-contact_type)** |

:::info 信息
如果未发送 `contact_type`，令牌将按最初请求的方式发送（`tfa_info.contact_type`）。
:::

### 枚举 contact_type

| Enumerador | 描述                                         |
| ---------- | ------------------------------------------------- |
| **sms**    | 通过短信发送到手机 |
| **email**  | Envio por correio eletrônico                      |

## 响应

### 成功响应

STATUS 200

响应体：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_approval",
  "payment_type": "collection_slip"
}
```

### 响应 Body Params

| 字段                   | 类型   | 描述                                                                                                                                                                                                                                                                                                      |
| ----------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `batch_payment_key` *   | uuid4  | 批量支付唯一标识键。                                                                                                                                                                                                                                                             |
| `request_control_key` * | uuid4  | 客户端请求唯一标识键（批次）。                                                                                                                                                                                                                                                  |
| `account_key` *         | uuid4  | 扣款账户键。                                                                                                                                                                                                                                                                                       |
| `total_amount` *        | number | 批次内所有项目金额之和。                                                                                                                                                                                                                                                                            |
| `batch_status` *        | string | 重发后，批次仍处于等待 token 校验状态。`batch_status` 生命周期遵循该业务配置的批量支付申请文档（枚举 `batch_payment_status`）。 |
| `payment_type` *        | string | 支付类型；该流程应为 `collection_slip`。                                                                                                                                                                                                                                               |

然后使用 [代收账单批次 token 校验](./validacao_de_token_de_lote_de_fatura_de_recolhimento.md) 完成 2FA。

### 错误响应

STATUS 4XX

Response Body

```json
{
  "title": "标题",
  "description": "Description in english",
  "translation": "描述 em português",
  "code": "代码"
}
```

| HTTP 代码 | QI 代码 | 标题      | 描述 (eng)                                                                                    | 描述 (pt-br)                                                                                         |
| ----------- | --------- | ----------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| 403         | BIP000010 | Forbidden   | User is not allowed to do this action                                                              | 用户无权限执行此操作                                                          |
| 404         | BIP000011 | Not Found   | The source account key was not found.                                                              | 未找到源账户 key。                                                            |
| 400         | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | 当前无法查询源账户，请稍后重试。 |
| 400         | BIP000013 | Bad Request | The source account is closed.                                                                      | 源账户已关闭。                                                                           |
| 400         | BIP000014 | Bad Request | The source account is blocked.                                                                     | 源账户已冻结。                                                                         |                                                |
| 400         | BIP000059 | Bad Request | Number of verification token validation attempts exceeded.                                         | 验证码校验尝试次数超限。                                       |
| 400         | BIP000064 | Bad Request | Error resending verification token                                                                 | 重发验证码失败                                                                     |
| 400         | BIP000065 | Bad Request | Payment verification time window exceeded.                                                         | 支付校验时间窗口已超限。                                                     |
| 404         | BIP000083 | Not Found   | Batch payment not found by batch payment key.                                                      | 未通过批次 key 找到批量支付。                                                     |
| 400         | BIP000085 | Bad Request | Batch payment status is not pending approval.                                                      | 批量支付状态不是待批准。
| 400         | BIP000086 | Bad Request | A token is required for SMS or email validation.                    | SMS 或 Email 校验必须提供 token。             |

---

# 发起银行票据批量支付（双重验证）

URL: /zh-Hans/documentation/baas/cobranca/2fa_v2/solicitar_pagamento_lote_de_boleto_bancario_com_confirmacao_de_lote

该端点支持在单个请求中发起多个银行票据的支付。当本次请求需要双重验证时，需提供 **`tfa_info`**。

:::info 银行票据
这是传统银行票据（可输入行不以数字 8 开头）。其已在银行间清算系统（CIP/Núclea）登记，可在经央行授权的金融机构和支付机构缴付。
:::

:::info 请求后的流程
提交后，批次可能根据业务规则进入等待 [双重验证批次确认](./confirmacao_de_lote_de_boleto_bancario.md) 状态。在该确认步骤中，请按文档中的 `tfa_info` 流程执行。
:::

## 请求

### 请求 Endpoint

ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments/batch_bank_slip
方法 POST

### 请求 Path Params

| 字段               | 类型    | 描述                               | 字符数 |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | 账户唯一标识键。  | 36         |

请求体：银行票据批量支付（此步骤无需 TFA）

```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 参数

| 字段               | 类型          | 描述                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | 客户端请求唯一标识键（批次）。 |
| `bank_slip_payments` * | array     | 银行票据支付列表。每个请求最多 **1000** 项。 |

`bank_slip_payments` 中每个元素必须包含：

| 字段               | 类型          | 描述                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | 该批次项目的客户端请求唯一标识键。 |
| `barcode`               | string    | 条形码。 |
| `digitable_line`        | string    | 可输入行。 |
| `payment_amount` *      | number    | 值 a ser pago. |

:::danger 警告
对于每个项目，提交的 `payment_amount` 必须与内部银行票据查询结果一致：若该票据不允许部分支付，金额必须等于更新后的总额；若允许部分支付，则 `payment_amount` 可按票据规则填写（包括在适用时高于票面金额），与单笔银行票据支付流程一致。
:::

### Object tfa_info

| 字段                        | 类型   | 描述                                                                                                                                          |
| ---------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `approver_document_number` * | string | 接收 token 或通过设备审批的审批人证件号（CPF/CNPJ）。提供 `tfa_info` 时必填。                |
| `session_id`                 | string | 设备会话唯一标识键（UUID v4，**设备 TFA 必填**）。                               |
| `contact_type` *             | string | token 发送或校验渠道：**[contact_type 枚举](#enumerador-contact_type)**。提供 `tfa_info` 时必填。 |

#### 枚举 contact_type

| Enumerador | 描述                                         |
|------------|---------------------------------------------------|
| **sms**    | 通过短信发送到手机 |
| **email**  | Envio por correio eletrônico                      |
| **device** | 通过设备 token 校验                |

## 响应

### 成功响应

STATUS 202

响应体：批次已接受并进入处理

```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 批次处理
响应中的 `batch_status` 表示该请求后的**即时状态**（例如待确认、待 2FA 批准或已进入处理），具体取决于所适用流程。如需执行 [批次确认](./confirmacao_de_lote_de_boleto_bancario.md)，请按该文档完成双因素认证下的批准或拒绝。`batch_status` 可选值见 [batch_payment_status](#enumeradores-batch_payment_status)。
:::

### 响应 Body Params

| 字段               | 类型    | 描述                         |
|---------------------|---------|-----------------------------------|
| `batch_payment_key` *       | uuid4 | 批量支付唯一标识键。 |
| `request_control_key` *     | uuid4 | 客户端请求唯一标识键（批次）。 |
| `account_key` *             | uuid4 | 扣款账户键。 |
| `total_amount` *            | number | 批次中所有项目 `payment_amount` 之和。 |
| `batch_status` *         | [enum](#enumeradores-batch_payment_status) | 请求后批次状态；取决于流程（确认、2FA 与即时处理）。 |
| `payment_type` *            | [enum](#enumeradores-payment_type) | 支付类型。 |

### 枚举es batch_payment_status

| Enumerador    | 描述     |
|---------------|---------------|
| `pending`     | Pendente de processamento |
| `pending_2fa_approval` | 待 2FA 批准 |
| `rejected`    | Rejeitado |
| `approved`    | Aprovado |
| `processed`   | Processado |

### 枚举es payment_type

| Enumerador    | 类型      | 描述     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | 银行票据    |
| `collection_slip` | string  | 代收账单（公用事业/税费） |

:::danger 警告
`collection_slip` 枚举不适用于本端点的银行票据批量流程；该流程中 `payment_type` 必须为 `bank_slip`。
:::

### 错误响应

STATUS 4XX

Response Body

```json
{
    "title": "标题",
    "description": "Description in english",
    "translation": "描述 em português",
    "code": "代码"
}
```

| HTTP 代码 | QI 代码 | 标题 | 描述 (eng) | 描述 (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 403         | BIP000010 | Forbidden | User is not allowed to do this action | 用户无权限执行此操作 |
| 404         | BIP000011 | Not Found | The source account key was not found. | 未找到源账户 key。 |
| 400         | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | 当前无法查询源账户，请稍后重试。 |
| 400         | BIP000024 | Bad Request | Request control key already exists. | 请求控制键已存在。 |
| 400         | BIP000050 | Bad Request | Requester configuration does not exist. | 请求方配置不存在。 |
| 400         | BIP000052 | Bad Request | Given document number does not belong to an approver for this account | 提交的证件号不属于该账户审批人 |
| 400         | BIP000053 | Bad Request | Error getting approver data | 获取审批人数据时出错 |
| 400         | BIP000054 | Bad Request | TFA info required | 需要 TFA 信息 |
| 400         | BIP000055 | Bad Request | Error sending verification token | 发送校验 token 时出错 |
| 400         | BIP000065 | Bad Request | Payment verification time window exceeded. | 支付校验时间窗口已超限。 |
| 400         | BIP000079 | Bad Request | A session_id must be provided token | 必须提供 session_id |
| 400         | BIP000080 | Bad Request | Beneficiary bank code of this bank slip is not allowed. | 该银行票据的收款行代码不被允许。 |
| 400         | BIP000081 | Bad Request | A list of bank slip payments must be provided. | 必须提供银行票据支付列表。 |

---

# Solicitar pagamento em lote de boleto bancário com autenticação de dois fatores

URL: /zh-Hans/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. |

---

# 发起代收账单（公用事业/税费）批量支付（双重验证）

URL: /zh-Hans/documentation/baas/cobranca/2fa_v2/solicitar_pagamento_lote_de_fatura_de_recolhimento_com_confirmacao_de_lote

该端点支持在单个请求中发起多个代收账单支付。当本次请求需要双重验证时，需提供 **`tfa_info`**。

:::info 代收账单（公用事业/税费）
该类收费由公用事业公司（水、电、电话、燃气）及政府机构（税费）开具。此类票据不在银行间清算系统（CIP/Núclea）登记，因此返回信息与银行票据不同。
:::

:::info 请求后的流程
请求后，批次可能根据业务规则继续等待 [带双因素认证的批次确认](./confirmacao_de_lote_de_fatura_de_recolhimento.md)。如果该申请步骤要求 2FA，请按下文和 [tfa_info 对象](#object-tfa_info) 发送 **`tfa_info`**。在该流程的批次确认步骤中，请遵循包含 `tfa_info` 的文档。
:::

## 请求

### 请求 Endpoint

ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments/batch_collection_slip
方法 POST

### 请求 Path Params

| 字段               | 类型    | 描述                               | 字符数 |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | 账户唯一标识键。  | 36         |

请求体：代收账单批量支付（此步骤无需 TFA）

```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
    }
  ]
}
```

## 通过 Email 和 SMS 认证

请求体：带可输入行的批次，TFA 通过 SMS 或 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
    }
  ]
}
```

请求体：带条形码的批次，TFA 通过 SMS 或 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
    }
  ]
}
```

## 通过设备认证

除已支持的 **sms** 与 **email** 认证方式外，也可使用 [预先注册的设备](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo) 对交易进行认证。此时需在 **Device Scan** 获取 `session_id` 并在 `tfa_info` 中发送。

请求体：带可输入行的批次，TFA 通过设备

```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
    }
  ]
}
```

请求体：带条形码的批次，TFA 通过设备

```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 参数

| 字段               | 类型          | 描述                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | 客户端请求唯一标识键（批次）。 |
| `tfa_info`       | object | 当该步骤（批次申请）要求 2FA 时，请在 [tfa_info 对象](#object-tfa_info) 中发送审批人与 token 渠道信息。若该流程在申请阶段不要求 2FA，则省略该字段。 |
| `collection_slip_payments` * | array     | 代收账单支付列表。每个请求最多 **1000** 项。 |

`collection_slip_payments` 中每个元素必须包含：

| 字段               | 类型          | 描述                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | 该批次项目的客户端请求唯一标识键。 |
| `barcode`               | string    | 条形码。 |
| `digitable_line`        | string    | 可输入行。 |
| `payment_amount` *      | number    | 值 a ser pago. |

:::danger 警告
对于每个项目，提交的 `payment_amount` 必须与内部代收账单查询结果一致（例如与 `total_amount` 及公用事业/税费规则一致），条件与单笔代收账单支付流程相同。
:::

### Object tfa_info

| 字段                        | 类型   | 描述                                                                                                                                          |
| ---------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `approver_document_number` * | string | 接收 token 或通过设备审批的审批人证件号（CPF/CNPJ）。提供 `tfa_info` 时必填。                |
| `session_id`                 | string | 设备会话唯一标识键（UUID v4，**设备 TFA 必填**）。                               |
| `contact_type` *             | string | token 发送或校验渠道：**[contact_type 枚举](#enumerador-contact_type)**。提供 `tfa_info` 时必填。 |

#### 枚举 contact_type

| Enumerador | 描述                                         |
|------------|---------------------------------------------------|
| **sms**    | 通过短信发送到手机 |
| **email**  | Envio por correio eletrônico                      |
| **device** | 通过设备 token 校验                |

## 响应

### 成功响应

STATUS 202

响应体：批次已接受并进入处理

```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 批次处理
响应中的 `batch_status` 表示该请求后的**即时状态**（例如待确认、待 2FA 批准或已进入处理），具体取决于所适用流程。如需执行 [批次确认](./confirmacao_de_lote_de_fatura_de_recolhimento.md)，请按该文档完成双因素认证下的批准或拒绝。`batch_status` 可选值见 [batch_payment_status](#enumeradores-batch_payment_status)。
:::

### 响应 Body Params

| 字段               | 类型    | 描述                         |
|---------------------|---------|-----------------------------------|
| `batch_payment_key` *       | uuid4 | 批量支付唯一标识键。 |
| `request_control_key` *     | uuid4 | 客户端请求唯一标识键（批次）。 |
| `account_key` *             | uuid4 | 扣款账户键。 |
| `total_amount` *            | number | 批次中所有项目 `payment_amount` 之和。 |
| `batch_status` *         | [enum](#enumeradores-batch_payment_status) | 请求后批次状态；取决于流程（确认、2FA 与即时处理）。 |
| `payment_type` *            | [enum](#enumeradores-payment_type) | 支付类型。 |

### 枚举es batch_payment_status

| Enumerador    | 描述     |
|---------------|---------------|
| `pending`     | Pendente de processamento |
| `pending_2fa_approval` | 待 2FA 批准 |
| `rejected`    | Rejeitado |
| `approved`    | Aprovado |
| `processed`   | Processado |

### 枚举es payment_type

| Enumerador    | 类型      | 描述     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | 银行票据    |
| `collection_slip` | string  | 代收账单（公用事业/税费） |

:::danger 警告
`bank_slip` 枚举不适用于本端点的代收账单批量流程；该流程中 `payment_type` 必须为 `collection_slip`。
:::

### 错误响应

STATUS 4XX

Response Body

```json
{
    "title": "标题",
    "description": "Description in english",
    "translation": "描述 em português",
    "code": "代码"
}
```

| HTTP 代码 | QI 代码 | 标题 | 描述 (eng) | 描述 (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400         | BIP000024 | Bad Request | Request control key already exists. | 请求控制键已存在。 |
| 400         | BIP000050 | Bad Request | Requester configuration does not exist. | 请求方配置不存在。 |
| 400         | BIP000052 | Bad Request | Given document number does not belong to an approver for this account | 提交的证件号不属于该账户审批人 |
| 400         | BIP000053 | Bad Request | Error getting approver data | 获取审批人数据时出错 |
| 400         | BIP000054 | Bad Request | TFA info required | 需要 TFA 信息 |
| 400         | BIP000055 | Bad Request | Error sending verification token | 发送校验 token 时出错 |
| 400         | BIP000065 | Bad Request | Payment verification time window exceeded. | 支付校验时间窗口已超限。 |
| 400         | BIP000079 | Bad Request | A session_id must be provided token | 必须提供 session_id |
| 400         | BIP000082 | Bad Request | A list of collection slip payments must be provided. | 必须提供代收账单支付列表。 |

---

# Solicitar pagamento em lote de fatura de recolhimento (convênio/tributo) com autenticação de dois fatores

URL: /zh-Hans/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. |

---

# 银行票据批量支付令牌校验

URL: /zh-Hans/documentation/baas/cobranca/2fa_v2/validacao_de_token_de_lote_de_boleto_bancario

该端点用于完成银行票据批量的**双重验证（2FA）**步骤。该批次在 [含 `tfa_info` 的批次确认](../confirmacao_de_lote_de_boleto_bancario_autenticacao_dois_fatores.md) 后会处于 `batch_status` **`pending_2fa_approval`**（批准）或 **`pending_2fa_rejection`**（拒绝）。令牌校验通过后，批次进入**异步处理**，最终状态反映确认阶段记录的决策（`approved` 或 `rejected`）。如需在等待状态重发令牌，请使用 [重发银行票据批量确认令牌](./solicitacao_de_reenvio_de_token_de_lote_de_boleto_bancario.md)。

:::info 银行票据
这是传统银行票据（可输入行不以数字 8 开头）。其已在银行间清算系统（CIP/Núclea）登记，可在经央行授权的金融机构和支付机构缴付。
:::

## 请求

### 请求 Endpoint

ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/payment/batch_bank_slip/**PAYMENT_BATCH_KEY**/validate_token
方法 PATCH

### 请求 Path Params

| 字段                 | 类型  | 描述                                                                                | 字符数 |
| --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- |
| `account_key` *       | uuid4 | 账户唯一标识键。                                                   | 36         |
| `payment_batch_key` * | uuid4 | 批次唯一标识键（创建批次时返回的 `batch_payment_key`）。 | 36         |

### 通过 Email 和 SMS 认证

请求体：批次 token 校验

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

### 通过设备认证

要通过设备完成认证，请发送空请求体。校验在服务端内部执行，无需额外请求体字段。仅当批次在 [含 `tfa_info` 的批次确认](../confirmacao_de_lote_de_boleto_bancario_autenticacao_dois_fatores.md) 后进入 **`pending_2fa_approval`**（批准）或 **`pending_2fa_rejection`**（拒绝）时，才应调用该端点。

请求体：批次 token 校验

```json
{

}
```

### Body 参数

| 字段   | 类型   | 描述                                                                                                        | 字符数 |
| ------- | ------ | ---------------------------------------------------------------------------------------------------------------- | ---------- |
| `token` | string | 发送给账户交易审批人的认证码，**SMS 或 Email 方式的 TFA 必填** | 6          |

## 响应

### 成功响应

校验成功后，API 返回 **202**，批次进入异步处理。最终状态遵循确认步骤记录的决策（`approved` 或 `rejected`）。

STATUS 202

响应体：token 校验后的批次（`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"
}
```

### 响应 Body Params

| 字段                   | 类型   | 描述                                                                                                                                                                                                                                                                    |
| ----------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `batch_payment_key` *   | uuid4  | 批量支付唯一标识键。                                                                                                                                                                                                                           |
| `request_control_key` * | uuid4  | 客户端请求唯一标识键（批次）。                                                                                                                                                                                                                |
| `account_key` *         | uuid4  | 扣款账户键。                                                                                                                                                                                                                                                     |
| `total_amount` *        | number | 批次内所有项目金额之和。                                                                                                                                                                                                                                          |
| `batch_status` *        | string | token 校验后，最终状态反映确认步骤记录的决策（`approved` 或 `rejected`）。`batch_status` 生命周期遵循该业务配置的批量支付申请文档（枚举 `batch_payment_status`）。 |
| `payment_type` *        | string | 支付类型；该流程应为 `bank_slip`。                                                                                                                                                                                                                     |

### 错误响应

STATUS 4XX

Response Body

```json
{
    "title": "标题",
    "description": "Description in english",
    "translation": "描述 em português",
    "code": "代码"
}
```

| HTTP 代码 | QI 代码 | 标题      | 描述 (eng)                               | 描述 (pt-br)                                                |
| ----------- | --------- | ----------- | --------------------------------------------- | ---------------------------------------------------------------- |
| 403         | BIP000010 | Forbidden   | User is not allowed to do this action         | 用户无权限执行此操作                 |
| 404         | BIP000011 | Not Found   | The source account key was not found.         | 未找到源账户 key。                   |
| 400         | BIP000013 | Bad Request | The source account is closed.                 | 源账户已关闭。                                 |
| 400         | BIP000050 | Bad Request | Requester configuration does not exist        | 请求方配置不存在。                            |
| 400         | BIP000058 | Bad Request | Error while validating verification token     | 校验 token 时出错                             |
| 400         | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | 验证码校验尝试次数超限。 |
| 400         | BIP000060 | Bad Request | Verification token expired.                   | 校验 token 已过期。                                   |
| 400         | BIP000061 | Bad Request | Verification token validation failed.       | 校验 token 验证失败。                      |
| 400         | BIP000065 | Bad Request | Payment verification time window exceeded.    | 支付校验时间窗口已超限。            |
| 404         | BIP000083 | Not Found   | Batch payment not found by batch payment key. | 未通过批次 key 找到批量支付。            |
| 400         | BIP000085 | Bad Request | Batch payment status is not pending approval. | 批量支付状态不是待批准。        |
| 400         | BIP000086 | Bad Request | A token is required for SMS or email validation.                    | SMS 或 Email 校验必须提供 token。             |

---

# 代收账单批量支付令牌校验（公用事业/税费）

URL: /zh-Hans/documentation/baas/cobranca/2fa_v2/validacao_de_token_de_lote_de_fatura_de_recolhimento

该端点用于完成代收账单批量的**双重验证（2FA）**步骤。该批次在 [含 `tfa_info` 的批次确认](../confirmacao_de_lote_de_fatura_de_recolhimento_autenticacao_dois_fatores.md) 后会处于 `batch_status` **`pending_2fa_approval`**（批准）或 **`pending_2fa_rejection`**（拒绝）。令牌校验通过后，批次进入**异步处理**，最终状态反映确认阶段记录的决策（`approved` 或 `rejected`）。如需在等待状态重发令牌，请使用 [重发代收账单批量确认令牌](./solicitacao_de_reenvio_de_token_de_lote_de_fatura_de_recolhimento.md)。

:::info 代收账单（公用事业/税费）
该类账单由公用事业公司（水、电、电话、燃气）和公共机构（税费）开具。其不在银行间支付清算系统（CIP/Núclea）登记，因此返回信息与银行票据不同。
:::

## 请求

### 请求 Endpoint

ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/payment/batch_collection_slip/**PAYMENT_BATCH_KEY**/validate_token
方法 PATCH

### 请求 Path Params

| 字段                 | 类型  | 描述                                                                                | 字符数 |
| --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- |
| `account_key` *       | uuid4 | 账户唯一标识键。                                                   | 36         |
| `payment_batch_key` * | uuid4 | 批次唯一标识键（创建批次时返回的 `batch_payment_key`）。 | 36         |

### 通过 Email 和 SMS 认证

请求体：批次 token 校验

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

### 通过设备认证

要通过设备完成认证，请发送空请求体。校验在服务端内部执行，无需额外请求体字段。仅当批次在 [含 `tfa_info` 的批次确认](../confirmacao_de_lote_de_fatura_de_recolhimento_autenticacao_dois_fatores.md) 后进入 **`pending_2fa_approval`**（批准）或 **`pending_2fa_rejection`**（拒绝）时，才应调用该端点。

请求体：批次 token 校验

```json
{

}
```

### Body 参数

| 字段   | 类型   | 描述                                                                                                        | 字符数 |
| ------- | ------ | ---------------------------------------------------------------------------------------------------------------- | ---------- |
| `token` | string | 发送给账户交易审批人的认证码，**SMS 或 Email 方式的 TFA 必填** | 6          |

## 响应

### 成功响应

校验成功后，API 返回 **202**，批次进入异步处理。最终状态遵循确认步骤记录的决策（`approved` 或 `rejected`）。

STATUS 202

响应体：token 校验后的批次（`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"
}
```

### 响应 Body Params

| 字段                   | 类型   | 描述                                                                                                                                                                                                                                                                                         |
| ----------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `batch_payment_key` *   | uuid4  | 批量支付唯一标识键。                                                                                                                                                                                                                                                |
| `request_control_key` * | uuid4  | 客户端请求唯一标识键（批次）。                                                                                                                                                                                                                                       |
| `account_key` *         | uuid4  | 扣款账户键。                                                                                                                                                                                                                                                                          |
| `total_amount` *        | number | 批次内所有项目金额之和。                                                                                                                                                                                                                                                               |
| `batch_status` *        | string | token 校验后，最终状态反映确认步骤记录的决策（`approved` 或 `rejected`）。`batch_status` 生命周期遵循该业务配置的批量支付申请文档（枚举 `batch_payment_status`）。 |
| `payment_type` *        | string | 支付类型；该流程应为 `collection_slip`。                                                                                                                                                                                                                                   |

### 错误响应

STATUS 4XX

Response Body

```json
{
    "title": "标题",
    "description": "Description in english",
    "translation": "描述 em português",
    "code": "代码"
}
```

| HTTP 代码 | QI 代码 | 标题      | 描述 (eng)                               | 描述 (pt-br)                                                |
| ----------- | --------- | ----------- | --------------------------------------------- | ---------------------------------------------------------------- |
| 403         | BIP000010 | Forbidden   | User is not allowed to do this action         | 用户无权限执行此操作                 |
| 404         | BIP000011 | Not Found   | The source account key was not found.         | 未找到源账户 key。                   |
| 400         | BIP000013 | Bad Request | The source account is closed.                 | 源账户已关闭。                                 |
| 400         | BIP000050 | Bad Request | Requester configuration does not exist        | 请求方配置不存在。                            |
| 400         | BIP000058 | Bad Request | Error while validating verification token     | 校验 token 时出错                             |
| 400         | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | 验证码校验尝试次数超限。 |
| 400         | BIP000060 | Bad Request | Verification token expired.                   | 校验 token 已过期。                                   |
| 400         | BIP000061 | Bad Request | Verification token validation failed.       | 校验 token 验证失败。                      |
| 400         | BIP000065 | Bad Request | Payment verification time window exceeded.    | 支付校验时间窗口已超限。            |
| 404         | BIP000083 | Not Found   | Batch payment not found by batch payment key. | 未通过批次 key 找到批量支付。            |
| 400         | BIP000085 | Bad Request | Batch payment status is not pending approval.         | 批量支付状态不是待批准。              |
| 400         | BIP000086 | Bad Request | A token is required for SMS or email validation.                    | SMS 或 Email 校验必须提供 token。             |

---

# 预约银行票据支付

URL: /zh-Hans/documentation/baas/cobranca/agendamento/agendar_pagamento_de_boleto_bancario

此端点用于预约银行票据支付。预约应在查询银行票据后进行，使用返回的信息以确保流程正确运行，避免支付过程中出现错误。

:::info 银行票据
这是常规银行票据（数字行不以数字8开头）。在银行间支付结算所（CIP/Núclea）注册，可在巴西中央银行授权的金融和支付机构付款。
:::

## Request

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

### 请求路径参数

| 字段               | 类型    | 描述                               | 字符数 |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | 账户唯一标识键。  | 36         |

Request Body: 使用数字行预约银行票据支付

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "digitable_line": "00190000090361557400500000024174396700000991000",
  "payment_amount": 1156.8,
  "payment_date": "2024-03-30"
}
```
Request Body: 使用条形码预约银行票据支付

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

### Body 参数

| 字段                   | 类型   | 描述                                           |
|-------------------------|--------|-----------------------------------------------------|
| `request_control_key` * | uuid4  | 客户请求唯一标识键。 |    
| `barcode`               | string | 条形码。                                   |
| `digitable_line`        | string | 数字行。                                    |
| `payment_amount` *      | number | 待支付金额。                                   |
| `payment_date` *        | string | 预约日期（格式 YYYY-MM-DD）。                                |

## Response

### 成功响应

STATUS 201

### Response Body 参数

| 字段               | 类型    | 描述                                           |
|---------------------|---------|-----------------------------------------------------|
| `payment_schedule_key` *      | uuid4 | 预约唯一标识键。          |
| `request_control_key` *       | uuid4 | 客户请求唯一标识键。 |
| `payer_name` *                | string | 付款人名称。                            |
| `payment_schedule_status` *   | enum | 预约状态。                              |

### payment_schedule_status 枚举值
| 枚举值          | 描述                                                        |
|---------------------|------------------------------------------------------------------|
| `scheduled`          | 支付预约成功                                   |
| `rejected`          | 预约被拒绝，未生成任何支付             |
| `error`             | 预约执行错误                                   |

### 错误响应

STATUS 4XX

Response Body

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

| HTTP 代码 | QI 代码 | 标题 | 描述（英文） | 描述（葡文） |
|-------------|-----------|--------|------------------|------------------|
| 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. |
| 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         | 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. |

---

# 预约征税发票支付（协议/税务）

URL: /zh-Hans/documentation/baas/cobranca/agendamento/agendar_pagamento_de_fatura_de_recolhimento

此端点用于预约征税发票支付。预约应在查询征税发票后进行，使用返回的信息以确保流程正确运行。

:::info 征税发票
此类账单由服务特许经营商（水、电、电话和燃气账单）和政府机构（税务）开具。它们未在银行间支付结算所（CIP/Núclea）登记，因此返回的信息与银行票据不同。
:::

## Request

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

### 请求路径参数

| 字段               | 类型    | 描述                               | 字符数 |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | 账户唯一标识键。  | 36         |

Request Body: 使用数字行预约征税发票支付

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "digitable_line": "00190000090361557400500000024174396700000991000",
  "payment_amount": 1156.8,
  "payment_date": "2024-03-30"
}
```
Request Body: 使用条形码预约征税发票支付

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

### Body 参数

| 字段               | 类型          | 描述                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | 客户请求唯一标识键。 |    
| `barcode`               | string    | 条形码。 |
| `digitable_line`        | string    | 数字行。 |
| `payment_amount` *      | number    | 待支付金额。 |
| `payment_date` *        | string    | 预约日期（格式 YYYY-MM-DD）。 |

## Response

### 成功响应

STATUS 201

### 错误响应

STATUS 4XX

Response Body

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

| HTTP 代码 | QI 代码 | 标题 | 描述（英文） | 描述（葡文） |
|-------------|-----------|--------|------------------|------------------|
| 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         | 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. |

---

# 取消预约

URL: /zh-Hans/documentation/baas/cobranca/agendamento/cancelar_agendamento

此端点用于取消银行票据或征税发票的支付预约。

:::info 银行票据
这是常规银行票据（数字行不以数字8开头）。在银行间支付结算所（CIP/Núclea）注册，可在巴西中央银行授权的金融和支付机构付款。
:::

:::info 征税发票
此类账单由服务特许经营商（水、电、电话和燃气账单）和政府机构（税务）开具。它们未在银行间支付结算所（CIP/Núclea）登记，因此返回的信息与银行票据不同。
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /payment_schedule/ PAYMENT_SCHEDULE_KEY /cancel
MÉTODO PATCH

### 请求路径参数

| 字段                    | 类型    | 描述                                    | 字符数 |
|--------------------------|---------|----------------------------------------------|------------|
| `account_key` *          | uuid4   | 账户唯一标识键。       | 36         |
| `payment_schedule_key` * | uuid4   | 预约唯一标识键。 | 36         |

## Response

### 成功响应

STATUS 200

Response Body: 银行票据支付预约已取消

```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: 征税发票支付预约已取消

```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 参数

| 字段               | 类型    | 描述                                           |
|---------------------|---------|-----------------------------------------------------|
| `payment_key` *               | uuid4 | 支付唯一标识键。          |
| `request_control_key` *       | uuid4 | 客户请求唯一标识键。 |
| `payer_name` *                | string | 实际付款人名称。                            |
| `payer_document_number` *     | string | 实际付款人文件号码（CPF/CNPJ）。  |
| `source_account_key` *        | uuid4 | 被扣款账户密钥。                            |
| `paid_amount` *               | number | 实际支付金额。                            |
| `payment_date` *              | string | 预约日期。                                  |
| `payment_type` *              | [enum](#enumeradores-payment_type) | 支付类型。                                  |
| `bank_slip`                   | [object](#objeto-bank_slip) | 银行票据。                                    |
| `collection_slip`             | object | 征税发票。                             |
| `payment_schedule_status` *            | [enum](#enumeradores-payment_schedule_status) | 预约状态。                              |

### payment_type 枚举值
| 枚举值    | 类型      | 描述     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | 银行票据    |
| `collection_slip` | string  | 征税发票 |

### payment_schedule_status 枚举值
| 枚举值 | 描述             |
|------------|-----------------------|
| `canceled` | 预约已取消 |

### bank_slip 对象
| 字段                             | 类型    | 描述                         |
|-----------------------------------|---------|-----------------------------------|
| `barcode` *                       | string | 条形码。 |
| `digitable_line` *                | string | 数字行。 |
| `payer_name` *                    | string | 付款人名称。|
| `payer_document_number` *         | string | 付款人文件号码（CPF/CNPJ）。 |
| `beneficiary_name` *              | string | 受益人名称。 |
| `beneficiary_trading_name`        | string | 受益人商业名称。 |
| `beneficiary_document_number` *   | string | 受益人文件号码（CPF/CNPJ）。 |
| `beneficiary_bank_ispb` *         | string | 受益人银行 ISPB 代码。 |
| `guarantor_name`                  | string | 保证人名称。 |
| `guarantor_document_number`       | string | 保证人文件号码（CPF/CNPJ）。 |
| `expiration_date` *               | string | 到期日期。 |
| `max_payment_date` * | string  | 最大支付日期。 |
| `partial_payment_indicator` *     | [enum](#enumeradores-partial_payment_indicator)   | 部分付款指示符。 |
| `registered_payment_amount`       | string | 已登记的总支付金额。 |
| `nominal_amount` *                | number | 原始金额。 |
| `total_amount` *                  | number | 总金额。 |
| `rebate_amount` *                 | number | 折扣金额。 |
| `discount_amount` *               | number | 优惠金额。 |
| `fine_amount` *                   | number | 罚款金额。 |
| `interest_amount` *               | number | 利息金额。 |

### partial_payment_indicator 枚举值
| 枚举值    | 描述     |
|---------------|---------------|
| `allowed`     | 允许     |
| `not_allowed` | 不允许 |

### collection_slip 对象
| 字段                             | 类型    | 描述                         |
|-----------------------------------|---------|-----------------------------------|
| `barcode`          | string | 条形码。 |
| `digitable_line`   | string | 数字行。 |
| `collection_name` *         | string | 协议名称。|
| `collection_document_number`   | string | 协议文件号码（CPF/CNPJ）。|
| `expiration_date` *  | string  | 到期日期。 |
| `total_amount` *  | number | 总金额。 |

### 错误响应

STATUS 4XX

Response Body

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

| HTTP 代码 | QI 代码 | 标题 | 描述（英文） | 描述（葡文） |
|-------------|-----------|--------|------------------|------------------|
| 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         | 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 |

---

# 查询预约

URL: /zh-Hans/documentation/baas/cobranca/agendamento/consultar_agendamento

此端点用于查询银行票据或征税发票支付预约的信息。

:::info 银行票据
这是常规银行票据（数字行不以数字8开头）。在银行间支付结算所（CIP/Núclea）注册，可在巴西中央银行授权的金融和支付机构付款。
:::

:::info 征税发票
此类账单由服务特许经营商（水、电、电话和燃气账单）和政府机构（税务）开具。它们未在银行间支付结算所（CIP/Núclea）登记，因此返回的信息与银行票据不同。
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /payment_schedule/ PAYMENT_SCHEDULE_KEY
MÉTODO GET

### 请求路径参数

| 字段                    | 类型    | 描述                                    | 字符数 |
|--------------------------|---------|----------------------------------------------|------------|
| `account_key` *          | uuid4   | 账户唯一标识键。       | 36         |
| `payment_schedule_key` * | uuid4   | 预约唯一标识键。 | 36         |

## Response

### 成功响应

STATUS 200

### Response Body 参数

| 字段               | 类型    | 描述                                           |
|---------------------|---------|-----------------------------------------------------|
| `payment_key` *               | uuid4 | 支付唯一标识键。          |
| `request_control_key` *       | uuid4 | 客户请求唯一标识键。 |
| `payer_name` *                | string | 实际付款人名称。                            |
| `payer_document_number` *     | string | 实际付款人文件号码（CPF/CNPJ）。  |
| `source_account_key` *        | uuid4 | 被扣款账户密钥。                            |
| `paid_amount` *               | number | 实际支付金额。                            |
| `payment_date` *              | string | 预约日期。                                  |
| `payment_type` *              | [enum](#enumeradores-payment_type) | 支付类型。                                  |
| `bank_slip`                   | object | 银行票据。                                    |
| `collection_slip`             | object | 征税发票。                             |
| `payment_schedule_status` *   | [enum](#enumeradores-payment_schedule_status) | 预约状态。                              |

### payment_type 枚举值
| 枚举值    | 类型      | 描述     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | 银行票据    |
| `collection_slip` | string  | 征税发票 |

### payment_schedule_status 枚举值
| 枚举值          | 描述                                                        |
|---------------------|------------------------------------------------------------------|
| `pending_2fa_approval` | 预约待双因素身份验证（2FA）       |
| `scheduled`          | 支付预约成功                                   |
| `executed`          | 预约已成功执行并生成相应支付 |
| `rejected`          | 预约被拒绝，未生成任何支付             |
| `canceled`         | 预约已取消                                            |
| `error`             | 预约执行错误                                   |

### 错误响应

STATUS 4XX

Response Body

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

| HTTP 代码 | QI 代码 | 标题 | 描述（英文） | 描述（葡文） |
|-------------|-----------|--------|------------------|------------------|
| 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         | BIP000056 | Not Found | Payment not found. | Pagamento não encontrado. |

---

# 列出预约

URL: /zh-Hans/documentation/baas/cobranca/agendamento/listar_agendamentos

此端点用于提供集成合作伙伴所有预约的详细信息，包括银行票据和征税发票。

:::info 银行票据
这是常规银行票据（数字行不以数字8开头）。在银行间支付结算所（CIP/Núclea）注册，可在巴西中央银行授权的金融和支付机构付款。
:::

:::info 征税发票
此类账单由服务特许经营商（水、电、电话和燃气账单）和政府机构（税务）开具。它们未在银行间支付结算所（CIP/Núclea）登记，因此返回的信息与银行票据不同。
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /payment_schedules
MÉTODO GET

### 请求路径参数

| 字段               | 类型    | 描述                               | 字符数 |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | 账户唯一标识键。  | 36         |

### 查询字符串参数

| 字段                  | 类型        | 描述                                                                |
|------------------------|-------------|--------------------------------------------------------------------------|
| `request_control_key`  | uuid4     | 客户请求唯一标识键。                      |
| `payment_schedule_key` | uuid4     | 预约唯一标识键。                             |
| `payment_key` | uuid4     | 为预约生成的支付唯一标识键。                             |
| `payment_type`         | [enum](#enumeradores-payment_type)      | 支付类型。                                                       |
| `payment_schedule_status`         | [enum](#enumeradores-payment_schedule_status)      | 预约状态。                                                       |
| `date_from`            | string    | 开始日期，格式 "YYYY-MM-DD"。                                      |
| `date_to`              | string    | 结束日期，格式 "YYYY-MM-DD"。                                        |
| `page`                 | string    | 请求的页码，默认为 1。                              |
| `page_size`            | string    | 查询中每页大小，默认最大值为 30。 |

### payment_type 枚举值
| 枚举值    | 类型      | 描述     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | 银行票据    |
| `collection_slip` | string  | 征税发票 |

### payment_schedule_status 枚举值
| 枚举值          | 描述                                                        |
|---------------------|------------------------------------------------------------------|
| `pending_2fa_approval` | 预约待双因素身份验证（2FA）       |
| `scheduled`          | 支付预约成功                                   |
| `executed`          | 预约已成功执行并生成相应支付 |
| `rejected`          | 预约被拒绝，未生成任何支付             |
| `canceled`         | 预约已取消                                            |
| `error`             | 预约执行错误

## Response

### 成功响应

STATUS 200

### 错误响应

STATUS 4XX

Response Body

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

| HTTP 代码 | QI 代码 | 标题 | 描述（英文） | 描述（葡文） |
|-------------|-----------|--------|------------------|------------------|
| 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. |

---

# Solicitar agendamento em lote de boleto bancário

URL: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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.     |

---

# 银行票据查询

URL: /zh-Hans/documentation/baas/cobranca/consultar_boleto_bancario

此端点用于查询银行票据信息。

:::info 银行票据
这是常规银行票据（数字行不以数字8开头）。在银行间支付结算所（CIP/Núclea）注册，可在巴西中央银行授权的金融和支付机构付款。
:::

## Request

### 请求端点

ENDPOINT /bill_payment/bank_slip/ DIGITABLE_LINE or BARCODE
MÉTODO GET

### 请求路径参数

| 字段               | 类型    | 描述                         | 字符数 |
|---------------------|---------|-----------------------------------|------------|
| `digitable_line`  | string  | 待查询的数字行。 | 47         |
| `barcode`         | string  | 待查询的条形码。| 44         |

### 查询字符串参数

| 字段               | 类型        | 描述                         | 字符数 |
|---------------------|-------------|-----------------------------------|------------|
| `payment_date`      | string      | 支付日期，将用于计算票据金额。 | YYYY-MM-DD |

## Response

### 成功响应

STATUS 200

Response Body: 银行票据可支付

```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 参数

| 字段               | 类型    | 描述                         |
|---------------------|---------|-----------------------------------|
| `barcode` *         | string | 条形码。 |
| `digitable_line` *  | string | 数字行。 |
| `payer_name` *         | string | 付款人名称。|
| `payer_document_number` *  | string | 付款人文件号码（CPF/CNPJ）。 |
| `beneficiary_name` *         | string | 受益人名称。 |
| `beneficiary_trading_name`  | string | 受益人商业名称。 |
| `beneficiary_document_number` *         | string | 受益人文件号码（CPF/CNPJ）。 |
| `beneficiary_bank_ispb` *         | string | 受益人银行 ISPB 代码。 |
| `guarantor_name`   | string | 保证人名称。 |
| `guarantor_document_number`        | string | 保证人文件号码（CPF/CNPJ）。 |
| `expiration_date` *  | string  | 到期日期。 |
| `max_payment_date` * | string  | 最大支付日期。 |
| `partial_payment_indicator` *  | [enum](#enumeradores-partial_payment_indicator) | 部分付款指示符 |
| `registered_payment_amount`   | string | 已登记的总支付金额。 |
| `nominal_amount` *  | number | 原始金额。 |
| `total_amount` *  | number | 总金额。 |
| `rebate_amount` *  | number | 折扣金额。 |
| `discount_amount` *  | number | 优惠金额。 |
| `fine_amount` *  | number | 罚款金额。 |
| `interest_amount` *  | number | 利息金额。 |

### partial_payment_indicator 枚举值
| 枚举值    | 类型      | 描述     |
|---------------|-----------|---------------|
| `allowed`     | string    | 允许     |
| `not_allowed` | string    | 不允许 |

### 错误响应

STATUS 4XX

Response Body

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

| HTTP 代码 | QI 代码 | 标题 | 描述（英文） | 描述（葡文） |
|-------------|-----------|--------|------------------|------------------|
| 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 |

## 沙盒环境

在我们的沙盒环境中，我们提供模拟的数字行用于模拟成功支付和错误场景测试。

### 成功场景

| 数字行 |
|---|
| 00190000090361557400500000024174396700000991000 |
| 00190000090282802601919212747174596760001294161 |
| 23793390014000000455277000249001596900000103995 |
| 75691434020137513680900001040013196770002417240 |
| 21390001171200000570700168167484796770000148206 |
| 07790001161200000039300602819070498470000182970 |
| 23792372059034189564835003432701998420000008306 |
| 03399199530490000005254172701010698420000467696 |
| 03399135012340000000830681701014198420038743888 |
| 75691324620100735471370255730478698420064900819 |
| 75691413310108906500520369970015899610000033705 |
| 13695621010000389701400000037598810770000217000 |

### 错误场景

| 数字行 | 错误代码 |
|---|---|
| 34191090083273252027893634770007296690012513600 | BIP000007 |
| 07090010287045349010776686070590896770001160123 | BIP000007 |
| 42297048060005815702500130494123896770000239491 | BIP000006 |
| 74891123702849020818918378871083196690000050000 | BIP000009 |
| 23792374119000209350986000372408496610000122810 | BIP000008 |

---

# 征税发票查询

URL: /zh-Hans/documentation/baas/cobranca/consultar_fatura_de_recolhimento

此端点用于查询征税发票信息。

:::info 征税发票
此类账单由服务特许经营商（水、电、电话和燃气账单）和政府机构（税务）开具。它们未在银行间支付结算所（CIP/Núclea）登记，因此返回的信息与银行票据不同。您可以通过此[链接](https://storage.googleapis.com/live-doc-api/public_samples/active_covenants.xlsx)查看 QI Tech 接受的协议列表及各自的支付截止时间。
:::

## Request

### 请求端点

ENDPOINT /bill_payment/collection_slip/ DIGITABLE_LINE or BARCODE
MÉTODO GET

### 请求路径参数

| 字段               | 类型    | 描述                         | 字符数 |
|---------------------|---------|-----------------------------------|------------|
| `digitable_line`  | string  | 待查询的数字行。 | 48         |
| `barcode`         | string  | 待查询的条形码。| 44         |

## Response

### 成功响应

STATUS 200

Response Body: 征税发票可支付

```json
{
  "barcode": null,
  "digitable_line": "836200000138892100450006762142420244046000010192",
  "collection_name": "CIA ULTRAGAZ SA-COD",
  "expiration_date": "2024-04-15",
  "total_amount": 1389.21
}
```

### Response Body 参数

| 字段               | 类型    | 描述                         |
|---------------------|---------|-----------------------------------|
| `barcode`          | string | 条形码。 |
| `digitable_line`   | string | 数字行。 |
| `collection_name` *         | string | 协议名称。|
| `expiration_date` *  | string  | 到期日期。 |
| `total_amount` *  | number | 总金额。 |

### 错误响应

STATUS 4XX

Response Body

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

| HTTP 代码 | QI 代码 | 标题 | 描述（英文） | 描述（葡文） |
|-------------|-----------|--------|------------------|------------------|
| 400         | BIP000033 | Bad Request | Collection slip not found. | Fatura de recolhimento não encontrada. |
| 400         | BIP000034 | Bad Request | It was not possible to consult the collection slip at this time. Please try again in a few minutes. | Não foi possível consultar a fatura neste momento. Por favor, tente novamente em alguns minutos. |
| 403         | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |

---

# Consultar lote de pagamento

URL: /zh-Hans/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: /zh-Hans/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. |

---

# 列出支付

URL: /zh-Hans/documentation/baas/cobranca/listar_pagamentos

此端点用于提供客户所有已支付账单的详细信息，包括银行票据和征税发票。

:::info 银行票据
这是常规银行票据（数字行不以数字8开头）。在银行间支付结算所（CIP/Núclea）注册，可在巴西中央银行授权的金融和支付机构付款。
:::

:::info 征税发票
此类账单由服务特许经营商（水、电、电话和燃气账单）和政府机构（税务）开具。它们未在银行间支付结算所（CIP/Núclea）登记，因此返回的信息与银行票据不同。
:::

## Request

### 请求端点

ENDPOINT /account/ ACCOUNT_KEY /payments
MÉTODO GET

### 请求路径参数

| 字段               | 类型    | 描述                               | 字符数 |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | 账户唯一标识键。  | 36         |

### 查询字符串参数

| 字段               | 类型        | 描述                         |
|---------------------|-------------|-----------------------------------|
| `request_control_key` | uuid4     | 客户请求唯一标识键。 |
| `payment_key`         | uuid4     | 支付唯一标识键。 |
| `payment_schedule_key`         | uuid4     | 支付预约唯一标识键。 |
| `payment_type`        | [enum](#enumeradores-payment_type)      | 支付类型。 |
| `payment_status`        | [enum](#enumeradores-payment_status)      | 支付状态。 |
| `date_from`           | string    | 开始日期，格式 "YYYY-MM-DD"。 |
| `date_to`             | string    | 结束日期，格式 "YYYY-MM-DD"。 |
| `page`                | string    | 请求的页码，默认为 1。 |
| `page_size`           | string    | 查询中每页大小，默认最大值为 30。 |

### payment_type 枚举值
| 枚举值    | 类型      | 描述     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | 银行票据    |
| `collection_slip` | string  | 征税发票 |

### payment_status 枚举值
| 枚举值    | 描述     |
|---------------|---------------|
| `pending_execution`     | 待执行 |
| `executed`    | 已执行 |
| `reverted`    | 已冲销 |
| `rejected`    | 已拒绝 |
| `error`       | 错误      |

## Response

### 成功响应

STATUS 200

### 错误响应

STATUS 4XX

Response Body

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

| HTTP 代码 | QI 代码 | 标题 | 描述（英文） | 描述（葡文） |
|-------------|-----------|--------|------------------|------------------|
| 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. |

---

# 支付银行票据

URL: /zh-Hans/documentation/baas/cobranca/pagar_boleto_bancario

此端点用于支付银行票据。支付必须在查询之后进行，使用查询返回的信息以确保流程正常运行，避免支付过程中出现失败。

:::info 银行票据
这是常规银行票据（数字行不以数字8开头）。在银行间支付结算所（CIP/Núclea）注册，可在巴西中央银行授权的金融和支付机构付款。
:::

## Request

### 请求端点

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

### 请求路径参数

| 字段               | 类型    | 描述                               | 字符数 |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | 账户唯一标识键。  | 36         |

Request Body: 使用数字行支付银行票据

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "digitable_line": "00190000090361557400500000024174396700000991000",
  "payment_amount": 1156.8
}
```
Request Body: 使用条形码支付银行票据

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "barcode": "00190000090361557400500000024174396700000991000",
  "payment_amount": 1156.8
}
```

### Body 参数

| 字段               | 类型          | 描述                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | 客户请求唯一标识键。 |    
| `barcode`               | string    | 条形码。 |
| `digitable_line`        | string    | 数字行。 |
| `payment_amount` *      | number    | 待支付金额。 |

:::danger 警告
若银行票据不允许部分支付，`payment_amount` 必须始终等于银行票据查询返回的 `total_amount`。对于允许部分支付的票据，客户可以任意选择 `payment_amount`，甚至可以超过票据面值（`total_amount`）。
:::

## Response

### 成功响应

STATUS 201

Response Body: 支付已执行

```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: 支付待执行

```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 信息
若返回 **HTTP Status 202** 且 `payment_status` 字段值为 **pending_execution**，则不应重新尝试支付。

该支付将异步处理。需要通过支付查询核实转账状态，或等待 [webhooks 页面](/documentation/baas/cobranca/webhooks) 中描述的待执行支付 webhook。
:::

### Response Body 参数

| 字段               | 类型    | 描述                         |
|---------------------|---------|-----------------------------------|
| `payment_key` *               | uuid4 | 支付唯一标识键。 |
| `request_control_key` *       | uuid4 | 客户请求唯一标识键。 |
| `payer_name` *                | string | 实际付款人姓名。|
| `payer_document_number` *     | string | 实际付款人文件号码（CPF/CNPJ）。 |
| `source_account_key` *        | uuid4 | 被扣款账户的键。 |
| `transaction_key` *           | uuid4 | 支付交易键。 |
| `transaction_revert_key`      | uuid4 | 支付冲销交易键。 |
| `paid_amount` *               | number | 实际支付金额。 |
| `payment_date` *              | string | 支付日期。 |
| `payment_type` *              | [enum](#enumeradores-payment_type) | 支付类型。 |
| `bank_slip`                   | [object](#objeto-bank_slip) | 银行票据。 |
| `collection_slip`             | object | 征税发票。 |
| `payment_status` *            | [enum](#enumeradores-payment_status) | 支付状态。 |

### payment_type 枚举值
| 枚举值    | 类型      | 描述     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | 银行票据    |
| `collection_slip` | string  | 征税发票 |

:::danger 警告
`collection_slip` 枚举值不适用于银行票据流程，collection_slip 对象也始终为空。
:::

### payment_status 枚举值
| 枚举值    | 描述     |
|---------------|---------------|
| `pending_execution`     | 待执行 |
| `executed`    | 已执行 |
| `reverted`    | 已冲销 |
| `rejected`    | 已拒绝 |
| `error`       | 错误      |

:::danger 警告
对于 QI 在两分钟内未收到 CIP 响应的支付，支付将以 `pending_execution` 状态返回。QI 收到 CIP 响应后，将向客户发送 [webhooks 页面](/documentation/baas/cobranca/webhooks) 中描述的待执行支付 webhook。
:::

### bank_slip 对象
| 字段                             | 类型    | 描述                         |
|-----------------------------------|---------|-----------------------------------|
| `barcode` *                       | string | 条形码。 |
| `digitable_line` *                | string | 数字行。 |
| `payer_name` *                    | string | 付款人姓名。|
| `payer_document_number` *         | string | 付款人文件号码（CPF/CNPJ）。 |
| `beneficiary_name` *              | string | 受益人姓名。 |
| `beneficiary_trading_name`        | string | 受益人商业名称。 |
| `beneficiary_document_number` *   | string | 受益人文件号码（CPF/CNPJ）。 |
| `beneficiary_bank_ispb` *         | string | 受益人银行的 ispb 代码。 |
| `guarantor_name`                  | string | 担保人姓名。 |
| `guarantor_document_number`       | string | 担保人文件号码（CPF/CNPJ）。 |
| `expiration_date` *               | string | 到期日期。 |
| `max_payment_date` * | string  | 最大支付日期。 |
| `partial_payment_indicator` *     | [enum](#enumeradores-partial_payment_indicator)   | 部分支付指示器。 |
| `registered_payment_amount`       | string | 注册的总支付金额。 |
| `nominal_amount` *                | number | 原始金额。 |
| `total_amount` *                  | number | 总金额。 |
| `rebate_amount` *                 | number | 折扣金额。 |
| `discount_amount` *               | number | 优惠金额。 |
| `fine_amount` *                   | number | 罚款金额。 |
| `interest_amount` *               | number | 利息金额。 |

### partial_payment_indicator 枚举值
| 枚举值    | 类型      | 描述     |
|---------------|-----------|---------------|
| `allowed`     | string    | 允许     |
| `not_allowed` | string    | 不允许 |

### 错误响应

STATUS 4XX

Response Body

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

| HTTP 代码 | QI 代码 | 标题 | 描述（英文） | 描述（葡文） |
|-------------|-----------|--------|------------------|------------------|
| 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. |

## Sandbox 环境

在我们的 sandbox 环境中，我们提供了模拟的数字行，用于模拟成功支付和测试错误场景。

### 成功场景

| 数字行 |
|---|
| 00190000090361557400500000024174396700000991000 |
| 00190000090282802601919212747174596760001294161 |
| 23793390014000000455277000249001596900000103995 |
| 75691434020137513680900001040013196770002417240 |
| 21390001171200000570700168167484796770000148206 |
| 07790001161200000039300602819070498470000182970 |
| 23792372059034189564835003432701998420000008306 |
| 03399199530490000005254172701010698420000467696 |
| 03399135012340000000830681701014198420038743888 |
| 75691324620100735471370255730478698420064900819 |

### `pending_execution` 场景

此场景的模拟在[模拟页面](/documentation/baas/cobranca/simulacao)中有更详细的描述。

| 数字行 |
|---|
| 75691333790100505390300569460017397220000306867 |

### 错误场景

| 数字行 | 错误代码 |
|---|---|
| 34191090083273252027893634770007296690012513600 | BIP000007 |
| 07090010287045349010776686070590896770001160123 | BIP000007 |
| 42297048060005815702500130494123896770000239491 | BIP000006 |
| 74891123702849020818918378871083196690000050000 | BIP000009 |
| 23792374119000209350986000372408496610000122810 | BIP000008 |

---

# 支付征税发票（协议/税务）

URL: /zh-Hans/documentation/baas/cobranca/pagar_fatura_de_recolhimento

此端点用于支付征税发票。支付必须在查询之后进行，使用查询返回的信息以确保流程正常运行，避免支付过程中出现失败。

:::info 征税发票
此类账单由服务特许经营商（水、电、电话和燃气账单）和政府机构（税务）开具。它们未在银行间支付结算所（CIP/Núclea）登记，因此返回的信息与银行票据不同。
:::

## Request

### 请求端点

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

### 请求路径参数

| 字段               | 类型    | 描述                               | 字符数 |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | 账户唯一标识键。  | 36         |

Request Body: 使用数字行支付征税发票

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "digitable_line": "00190000090361557400500000024174396700000991000",
  "payment_amount": 1156.8
}
```
Request Body: 使用条形码支付征税发票

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "barcode": "00190000090361557400500000024174396700000991000",
  "payment_amount": 1156.8
}
```

### Body 参数

| 字段               | 类型          | 描述                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | 客户请求唯一标识键。 |    
| `barcode`               | string    | 条形码。 |
| `digitable_line`        | string    | 数字行。 |
| `payment_amount` *      | number    | 待支付金额。 |

:::danger 警告
`payment_amount` 必须始终等于银行票据查询返回的 `total_amount`。
:::

## Response

### 成功响应

STATUS 201

Response Body: 支付已执行

```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
当支付返回状态 `202` 时，处理仍在进行中。在通过 webhook 收到最终状态更新之前，**请勿重试支付**。
:::

Response Body: 支付待处理

```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 参数

| 字段               | 类型    | 描述                         |
|---------------------|---------|-----------------------------------|
| `payment_key` *               | uuid4 | 支付唯一标识键。 |
| `request_control_key` *       | uuid4 | 客户请求唯一标识键。 |
| `payer_name` *                | string | 实际付款人姓名。|
| `payer_document_number` *     | string | 实际付款人文件号码（CPF/CNPJ）。 |
| `source_account_key` *        | uuid4 | 被扣款账户的键。 |
| `transaction_key` *           | uuid4 | 支付交易键。 |
| `transaction_revert_key`      | uuid4 | 支付冲销交易键。 |
| `paid_amount` *               | number | 实际支付金额。 |
| `payment_date` *              | string | 支付日期。 |
| `payment_type` *              | [enum](#enumeradores-payment_type) | 支付类型。 |
| `bank_slip`                   | object | 银行票据。 |
| `collection_slip`             | [object](#objeto-collection_slip) | 征税发票。 |
| `payment_status` *            | [enum](#enumeradores-payment_status) | 支付状态。 |

### payment_type 枚举值
| 枚举值    | 类型      | 描述     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | 银行票据    |
| `collection_slip` | string  | 征税发票 |

:::danger 警告
`bank_slip` 枚举值不适用于征税发票流程，bank_slip 对象也始终为空。
:::

### payment_status 枚举值
| 枚举值    | 描述     |
|---------------|---------------|
| `pending`     | 待处理    |
| `executed`    | 已执行 |
| `reverted`    | 已冲销 |
| `rejected`    | 已拒绝 |
| `error`       | 错误      |

### collection_slip 对象
| 字段                             | 类型    | 描述                         |
|-----------------------------------|---------|-----------------------------------|
| `barcode`          | string | 条形码。 |
| `digitable_line`   | string | 数字行。 |
| `collection_name` *         | string | 协议名称。|
| `collection_document_number`   | string | 协议文件号码（CPF/CNPJ）。|
| `expiration_date` *  | string  | 到期日期。 |
| `total_amount` *  | number | 总金额。 |

### 错误响应

STATUS 4XX

Response Body

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

| HTTP 代码 | QI 代码 | 标题 | 描述（英文） | 描述（葡文） |
|-------------|-----------|--------|------------------|------------------|
| 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. |

## Sandbox 环境

在我们的 sandbox 环境中，我们提供了模拟的数字行，用于模拟成功支付和测试错误场景。

### 成功场景

| 数字行 |
|---|
| 828300000007411100972013905080001546763201900028 |
| 838000000009235700481007241345219112001474229880 |
| 848000000006308600802021201071261517689002201070 |
| 858200000015000000643025703477209504800448091020 |

### 错误场景

| 数字行 | 错误代码 |
|---|---|
| 858500000037350000643217212883260006147448091022 | BIP000035 |

---

# 场景模拟

URL: /zh-Hans/documentation/baas/cobranca/simulacao_de_cenarios

## 1 - 模拟待执行状态的支付

对于 QI 在两分钟内未收到 CIP 响应的支付，支付将以 `pending_execution` 状态返回。QI 收到 CIP 响应后，将向客户发送 [webhooks 页面](/documentation/baas/cobranca/webhooks) 中描述的待执行支付 webhook。要模拟此场景，请使用数字行 `"digitable_line": "75691333790100505390300569460017397220000306867"` 进行支付。

要更新支付状态，请发送以下请求，将 `payment_status` 设置为 **approved** 以批准支付，或设置为 **rejected** 以拒绝支付。

## Request

### 请求端点

ENDPOINT /mock/account/ ACCOUNT_KEY /payment/ PAYMENT_KEY /bank_slip/confirmation
MÉTODO PATCH

### 请求路径参数

| 字段               | 类型    | 描述                               | 字符数 |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | 账户唯一标识键。  | 36         |
| `payment_key` *     | uuid4   | 支付唯一标识键。  | 36     |

Request Body: 模拟支付确认

```json
{
  "payment_status": "approved",
}
```

### Body 参数

| 字段                       | 类型   | 描述                                                             |
|-----------------------------|--------|-----------------------------------------------------------------------|
| `payment_status` *           | [enum](#enumeradores-payment_status) | 支付状态 |

### payment_status 枚举值

| 枚举值   | 描述 |
|--------------|-----------|
| `approved`    | 批准并完成支付 |
| `rejected`    | 拒绝并撤销支付 |

## Response

### 成功响应

STATUS 204

Response Body: 模拟已完成

```json
{}
```

---

# Solicitar Pagamento em Lote de Boleto Bancário

URL: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/documentation/baas/cobranca/webhooks

:::danger 注意！
QI Tech 的 webhooks 不应以严格方式进行映射。
返回的 API webhooks payload 中可能会包含额外字段。
:::

:::info Webhook 重发
您可以按照文档中的详细说明查询和重发 webhooks：[重发 Webhooks](/documentation/notificacoes/reenvio_de_notificacoes)。
:::

## 支付 Webhook

### Webhook 请求体

Request Body: 支付已执行

```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: 支付待执行

```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: 支付已拒绝

```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: 支付已冲销

```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 参数

| 字段                 | 类型   | 描述                                                 |
|-----------------------|--------|-----------------------------------------------------------|
| `webhook_type`        | string | 定义所报告事件类型的枚举值 |
| `webhook_datetime`    | string | webhook 发送的日期和时间                           |
| `request_control_key` | uuid4  | 客户请求唯一标识键。     |
| `source_account_key` *        | uuid4 | 被扣款账户的键。                            |
| `payment_key`        | uuid4  | 支付唯一标识键。 |
| `payment_schedule_key` | uuid4     | 预约唯一标识键（仅适用于由预约生成的支付）。                             |
| `barcode`            | string | 条形码。 |
| `digitable_line`     | string | 数字行。 |
| `payment_type`       | [enum](#enumeradores-payment_type) | 支付类型。 |
| `payment_status`     | [enum](#enumeradores-payment_status) | 支付状态。 |
| `error_code`       | string | 错误代码。 |
| `error_message`     | string | 错误信息。 |

### payment_type 枚举值
| 枚举值    | 类型      | 描述     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | 银行票据    |
| `collection_slip` | string  | 征税发票 |

### payment_status 枚举值
| 枚举值    | 类型      | 描述     |
|---------------|-----------|---------------|
| `executed`    | string  | 已执行 |
| `rejected`    | string  | 已拒绝 |
| `reverted`    | string  | 已冲销 |

| HTTP 代码 | QI 代码 | 标题 | 描述（英文） | 描述（葡文） |
|-------------|-----------|--------|------------------|------------------|
| 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. |

## 支付预约 Webhook

:::info 支付预约的 Webhook 流程
预约和执行支付的过程涉及使用不同的 webhooks，每个 webhook 在通知和跟踪支付状态方面都有其特定作用。

当预约在请求的日期执行时，可能进入 `executed` 状态，届时将触发状态为 `executed` 的 `payment_schedule` webhook，预约执行会创建状态为 `pending` 的 `payment` 并发送相应 webhook。或者，在账户关闭或票据金额变更等情况下，预约可能进入 `rejected` 状态，而不会创建 `payment`。在这种情况下，仅发送状态为 `rejected` 的 `payment_schedule` webhook，并附带相应错误代码。

- 最初，支付状态为 `pending`，因为支付过程正在进行中。支付完成后，将发送新的 `payment` webhook，此时状态为 `executed`。
- 如果支付无法完成（例如因账户余额不足），将发送状态为 `rejected` 的 `payment` webhook，并附带相应错误代码。
- 在账户余额不足的情况下，系统将进行最多 3 次支付尝试，每次间隔 30 分钟。在这种情况下，同一个已执行预约可能会生成多条支付记录。例如，如果仅在第三次尝试时才有足够余额，则前两次支付的 webhooks 将以 `payment` 和 `rejected` 状态触发，第三次支付的 webhooks 则以 `payment` 和 `executed` 状态触发。
:::

### Webhook 请求体

Request Body: 支付预约已执行

```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: 支付预约已拒绝

```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 参数

| 字段                 | 类型   | 描述                                                 |
|-----------------------|--------|-----------------------------------------------------------|
| `webhook_type`        | string | 定义所报告事件类型的枚举值 |
| `webhook_datetime`    | string | webhook 发送的日期和时间                           |
| `request_control_key` | uuid4  | 客户请求唯一标识键。     |
| `source_account_key` *        | uuid4 | 被扣款账户的键。                            |
| `payment_key`        | uuid4  | 支付唯一标识键。 |
| `payment_schedule_key`        | uuid4  | 支付预约唯一标识键。 |
| `barcode`            | string | 条形码。 |
| `digitable_line`     | string | 数字行。 |
| `payment_type`       | [enum](#enumeradores-payment_type) | 支付预约类型。 |
| `payment_schedule_status`     | [enum](#enumeradores-payment_schedule_status) | 支付预约状态。 |
| `error_code`       | string | 错误代码。 |
| `error_message`     | string | 错误信息。 |

### payment_type 枚举值
| 枚举值    | 类型      | 描述     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | 银行票据    |
| `collection_slip` | string  | 征税发票 |

### payment_schedule_status 枚举值
| 枚举值    | 类型      | 描述     |
|---------------|-----------|---------------|
| `executed`    | string  | 已执行 |
| `rejected`    | string  | 已拒绝 |

| HTTP 代码 | QI 代码 | 标题 | 描述（英文） | 描述（葡文） |
|-------------|-----------|--------|------------------|------------------|
| 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. |

---

# 查询设备

URL: /zh-Hans/documentation/baas/dispositivo/consultar_dispositivo

## Request

ENDPOINT /account/ ACCOUNT_KEY /device/ DEVICE_KEY
MÉTODO GET

### 路径参数

| 字段         | 类型   | 描述                              | 字符数 |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | 账户唯一标识键。 | 36         |
| `device_key` | uuidv4 | 设备唯一标识键。 | 36         |

## Response

STATUS 200

Response Body: 找到设备

```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 参数

| 字段                   | 类型   | 描述                                                                           | 字符数 |
|-------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `device_key` *          | uuidv4 | UUID v4 格式的设备唯一标识键                     | 36         |
| `session_id` *          | uuidv4 | 通过 device_scan 获取的会话标识符                                      | 36         |
| `analysis_status` *      | string | 欺诈引擎分析状态                                                | **[analysis_status 枚举值](#enumeradores-analysis_status)** |
| `status` *               | string | 设备状态                                                               | **[status 枚举值](#enumeradores-status)** |
| `device_registration_data` * | object | 设备注册数据                                            | **[device_registration_data 对象](#objeto-device_registration_data)** |
| `analysis_status_events` * | array | 分析状态变更事件历史记录                               | -          |
| `status_events` *       | array  | 设备状态变更事件历史记录                           | -          |
| `registration_date` *    | string | ISO 格式的设备注册日期（UTC - "YYYY-MM-DDTHH:MM:SSZ"）       | 20         |
| `created_at` *           | string | ISO 格式的设备创建日期（UTC - "YYYY-MM-DDTHH:MM:SSZ"）       | 20         |

### device_registration_data 对象

| 字段                   | 类型   | 描述                                                                           | 字符数 |
|-------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `device_key` *          | uuidv4 | UUID v4 格式的设备唯一标识键                     | 36         |
| `session_id` *          | uuidv4 | 通过 device_scan 获取的会话标识符                                      | 36         |
| `document_number`       | string | 用户的文件号码（CPF/CNPJ）                                          | 14         |
| `registration_date` *   | string | 带时区的 ISO 格式注册日期                                   | 25         |
| `face_recognition_key`  | uuidv4 | 人脸识别键（适用时）                                  | 36         |

### analysis_status_event 对象

| 字段                   | 类型   | 描述                                                                           | 字符数 |
|-------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `new_analisys_status` * | string | 新的分析状态                                                              | **[analysis_status 枚举值](#enumeradores-analysis_status)** |
| `reason`                | string | 状态变更原因（适用时）                                       | -          |
| `reason_description`    | string | 状态变更原因描述（适用时）                          | -          |
| `event_date` *          | string | ISO 格式的事件日期（UTC - "YYYY-MM-DDTHH:MM:SSZ"）                        | 20         |

### status_event 对象

| 字段                   | 类型   | 描述                                                                           | 字符数 |
|-------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `new_status` *          | string | 设备的新状态                                                          | **[status 枚举值](#enumeradores-status)** |
| `event_date` *          | string | ISO 格式的事件日期（UTC - "YYYY-MM-DDTHH:MM:SSZ"）                        | 20         |

### analysis_status 枚举值

| 枚举值              | 描述                               |
|-------------------------|-----------------------------------------|
| automatically_approved  | 欺诈引擎自动批准 |
| automatically_reproved | 欺诈引擎自动拒绝 |
| pending                 | 待分析                     |

### status 枚举值

| 枚举值         | 描述                               |
|--------------------|-----------------------------------------|
| registered         | 设备已注册                  |
| disabled           | 设备已停用                 |
| pending            | 设备待审批       |

STATUS 4xx

Response Body: Error

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                 | 描述（英文）<br/>`description`                                                                                       | 描述（葡文）<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.                                             |

---

# 批准设备创建

URL: /zh-Hans/documentation/baas/dispositivo/create/aprovar_cadastro_dispositivo

## Request

ENDPOINT /account/ ACCOUNT_KEY /device/ DEVICE_KEY /validate
MÉTODO PUT

### 路径参数

| 字段         | 类型   | 描述                              | 字符数 |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | 账户唯一标识键。 | 36         |
| `device_key` | uuidv4 | 设备唯一标识键。 | 36         |

Request Body

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

### Body 参数

| 字段     | 类型   | 描述                                                             | 字符数 |
|-----------|--------|-----------------------------------------------------------------------|------------|
| `token` * | string | 发送给账户交易审批人的身份验证代码 | 6          | 

## Response

STATUS 201

Response Body: 设备已创建

```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": {}
}
```

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                 | 描述（英文）<br/>`description`                                                                                       | 描述（葡文）<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                                                                |

---

# 申请创建设备

URL: /zh-Hans/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo

## Request

ENDPOINT /account/ ACCOUNT_KEY /device
MÉTODO POST

### 路径参数

| 字段         | 类型   | 描述                              | 字符数 |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | 账户唯一标识键。 | 36         |

**SMS**

Request Body: 通过 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 参数

| 字段                   | 类型       | 描述                                                                                                                                                                                                                                                 | 字符数                              |
|-------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------|
| `device_key` * | uuidv4     | UUID v4 格式的设备唯一标识键，通过 **device_scan** 获取（由集成客户端在此时创建）。                                                                                                                                                               | 36                                      | 
| `session_id` * | uuidv4     | UUID v4 格式的会话唯一标识键，通过 **device_scan** 获取（由集成客户端在此时创建）。                                                                                                                                                               | 36                                      | 
| `tfa_info`*             | Object     | 包含账户审批人文件号码及联系方式或 `image_key` 的对象。                                                                                                                                                                  | **[tfa_info 对象](#objeto-tfa_info)** |

### tfa_info 对象

| 字段                       | 类型   | 描述                                                                           | 字符数 |
|-----------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `approver_document_number`* | string | 账户审批人的文件号码。                                  | 11         | 
| `contact_type`*             | string | 指定与账户审批负责人的联系方式。可能的值为 **sms**、**email** 或 **liveness**（使用 image_key 进行身份验证时）。|            |

## Response

STATUS 202

Response Body: 交易已申请

```json
{
  "device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "device_status": "pending_2fa_approval",
  "created_at": "2024-12-22T20:30:23.459Z"
}
```

**Email**
Request Body: 通过 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 参数

| 字段                   | 类型       | 描述                                                                                         | 字符数                                          |
|-------------------------|------------|---------------------------------------------------------------------------------------------------|-----------------------------------------------------|
| `device_key` * | uuidv4     | UUID v4 格式的设备唯一标识键，通过 **device_scan** 获取（由集成客户端在此时创建）。                                                                                                                                                               | 36                                      | 
| `session_id` * | uuidv4     | UUID v4 格式的会话唯一标识键，通过 **device_scan** 获取（由集成客户端在此时创建）。                                                                                                                                                               | 36                                      | 
| `tfa_info`*             | Object     | 包含账户审批人文件号码及联系方式或 `image_key` 的对象。                                                                                                                                                                  | **[tfa_info 对象](#objeto-tfa_info)** |

### tfa_info 对象

| 字段                       | 类型   | 描述                                                                           | 字符数 |
|-----------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `approver_document_number`* | string | 账户审批人的文件号码。                                  | 11         | 
| `contact_type`*             | string | 指定与账户审批负责人的联系方式。可能的值为 **sms**、**email** 或 **liveness**（使用 image_key 进行身份验证时）。|            |

## Response

STATUS 202

Response Body: 交易已申请

```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: 通过 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 参数

| 字段                      | 类型       | 描述                                                                                                                                                                                                                                          | 字符数                                |
|----------------------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|
| `device_key` * | uuidv4     | UUID v4 格式的设备唯一标识键，通过 **device_scan** 获取（由集成客户端在此时创建）。                                                                                                                                                               | 36                                      | 
| `session_id` * | uuidv4     | UUID v4 格式的会话唯一标识键，通过 **device_scan** 获取（由集成客户端在此时创建）。                                                                                                                                                               | 36                                      | 
| `tfa_info`*             | Object     | 包含账户审批人文件号码及联系方式或 `image_key` 的对象。                                                                                                                                                                  | **[tfa_info 对象](#objeto-tfa_info)** |

### tfa_info 对象

| 字段                       | 类型   | 描述                                                                           | 字符数 |
|-----------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `approver_document_number`* | string | 账户审批人的文件号码。                                  | 11         | 
| `contact_type`*             | string | 指定与账户审批负责人的联系方式。可能的值为 **sms**、**email** 或 **liveness**（使用 image_key 进行身份验证时）。|            |
| `image_key` * | uuidv4     | UUID v4 格式的人脸识别图像唯一标识键，通过 **liveness** 过程获取。                                                                                                                                                               | 36                                      | 

## Response

STATUS 202

Response Body: 设备已创建

```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": {}
}
```

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                 | 描述（英文）<br/>`description`                                                                                       | 描述（葡文）<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                                                                                    |

---

# 申请重发令牌

URL: /zh-Hans/documentation/baas/dispositivo/create/solicitacao_reenvio_token

将生成新令牌并发送给负责创建设备的审批人（仅限通过电子邮件或 SMS 联系的情况）。若超出令牌验证尝试次数限制，则不允许重发。

## Request

ENDPOINT /account/ ACCOUNT_KEY /device/ DEVICE_KEY /resend_token
MÉTODO PATCH

### 路径参数

| 字段         | 类型   | 描述                              | 字符数 |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | 账户唯一标识键。 | 36         |
| `device_key` | uuidv4 | 设备唯一标识键。 | 36         |

### Body 参数
| 字段         | 类型   | 描述                              | 字符数 |
|---------------|--------|----------------------------------------|------------|
| `contact_type`*             | string | 指定与账户审批负责人的联系方式。可能的值为 **sms**、**email** | **[contact_type 枚举值](#enumerador-contact_type)**  |

:::info 说明
若未发送 `contact_type`，令牌将按原始申请的方式发送。
:::

| 枚举值 | 描述                                         |
|------------|---------------------------------------------------|
| **sms**    | 通过短信发送至手机 |
| **email**  | 通过电子邮件发送                      |

## Response

STATUS 202

Response Body: 重发已申请

```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": {}
}
```

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                 | 描述（英文）<br/>`description`                                                                                       | 描述（葡文）<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.                                             |

---

# 停用设备

URL: /zh-Hans/documentation/baas/dispositivo/delete/desativar_dispositivo

## Request

ENDPOINT /account/ ACCOUNT_KEY /device/ DEVICE_KEY /disable
MÉTODO DELETE

### 路径参数

| 字段         | 类型   | 描述                              | 字符数 |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | 账户唯一标识键。 | 36         |
| `device_key` | uuidv4 | 设备唯一标识键。 | 36         |

## Response

STATUS 200

Response Body: 设备已停用

```json
{
  "device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "device_status": "disabled",
  "created_at": "2024-12-22T20:30:23.459Z"
}
```

### Response Body 参数

| 字段                   | 类型   | 描述                                                                           | 字符数 |
|-------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `device_key` *          | uuidv4 | UUID v4 格式的设备唯一标识键                     | 36         |
| `device_status` *       | string | 设备状态                                                               | **[device_status 枚举值](#enumeradores-device_status)** |
| `created_at` *          | string | ISO 格式的设备创建日期（UTC - "YYYY-MM-DDTHH:MM:SSZ"）        | 20         |

### device_status 枚举值

| 枚举值         | 描述                               |
|--------------------|-----------------------------------------|
| active             | 设备处于活动状态，可用 |
| disabled           | 设备已停用                 |
| pending            | 设备待审批       |

STATUS 4xx

Response Body: Error

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                 | 描述（英文）<br/>`description`                                                                                       | 描述（葡文）<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.                                             |

---

# 简介

URL: /zh-Hans/documentation/baas/dispositivo/introducao

Onboarding API 提供设备管理功能，允许合作伙伴将特定设备注册到与账户关联的用户。通过此功能，可以加强操作安全性，确保只有授权设备才能执行交易，这些交易将通过**设备令牌**进行验证。

### 设备注册

注册用于交易验证的新设备通过分三个步骤的流程完成：

---

**I. 注册申请（POST）**  
此步骤发送包含以下内容的 `POST` 请求：  
- 通过 `device_scan` 获取的设备数据  
- 双因素认证（2FA）所需的信息

完成申请后，将生成 2FA 令牌并发送给用户（通过电子邮件或 SMS）。该令牌确保注册由有权限关联设备的实际授权人员完成。

:::info 说明
若通过人脸识别进行身份验证，则需在 2FA 字段中发送通过 [liveness](/documentation/caas/face_recognition/api/introduction) 获取的 **image_key**。
在此情况下，无需通过后续验证步骤。
:::

---

**II. 2FA 令牌验证（PUT/PATCH）**  
收到 2FA 令牌后，用户必须通过 `PUT` 请求对其进行验证。若需要重新发送代码（因丢失、未收到或过期），则使用 `PATCH` 请求来申请新令牌。  
一旦令牌验证成功，设备将被正式注册到系统中。

---

**III. 在未来交易中使用设备令牌进行身份验证**  
设备正式注册后，即可用于验证未来的交易。交易将使用设备令牌进行身份验证，使过程更加安全可靠。

---

### 查询设备

可以通过 `GET` 请求并提供 `account_key` 和 `device_key` 来查询特定设备的信息。此操作返回设备的详细信息，包括当前状态、创建日期和最后更新时间。

---

### 停用设备

必要时，可以通过 `DELETE` 请求停用设备。一旦停用，该设备将无法再用于交易验证，从而确保对操作安全性的更大控制。

---

# 确认开设个人账户

URL: /zh-Hans/documentation/baas/escrow/abrir_conta_pf

账户开设分两个必要步骤。首先，POST 请求发送初步数据以预留账户。随后，系统会触发状态为 `pending_additional_data` 的 `account_request.status_change` 类型 webhook。在第二步中，PATCH 请求完成开户，以补充信息正式确认账户。

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

## Path Params
| 字段         | 类型   | 描述                               | 字符数 |
|--------------|--------|------------------------------------|--------|
| `account_request_key` | uuidv4 | 账户预留请求的唯一标识键。 | 36     |

## 开设 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

| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---|---|
| `account_owner` * | object  | 包含账户持有人信息的对象 | **[Objeto account_owner](#objeto-account_owner)** |
| `signed_contract` * | object  | 包含账户持有人信息的对象 | **[Objeto signed_contract](#objeto-signed_contract)** |
| `destinations ` * | list  | 授权接收转账的目标账户列表。 | **[Objeto destinations](#objeto-destinations)** |
| `additional_documents`  | list  | 额外/可选文件 ID 列表。 | UUID 数组 |

### Objeto account_owner

| 字段 | 类型 | 描述 | 字符数 |
|---| ---| ---| ---| 
| `address` * | object | 账户持有人地址。 | **[Objeto adress](#objeto-address)** |  |
| `birth_date` | string | 账户持有人出生日期（格式 "AAAA-MM-DD"）。 | - |
| `document_identification` * | uuidv4 | 账户持有人带照片身份证件 PDF 的 DOCUMENT_KEY（RG 或 CNH）（事先上传） | 36 |
| `email` * | string | 账户持有人邮箱。 | 200 |
| `individual_document_number` | string | 账户持有人 CPF（仅数字），最多 11 位。 | 11 |
| `is_pep` * | string | 声明该人是否为 PEP（http://www.portaldatransparencia.gov.br/download-de-dados/pep）。| - |
| `mother_name` | string | 个人账户情况下客户的母亲姓名。 | - |
| `name` * | string | 账户持有人姓名。 | - |
| `nationality` * | string | 客户国籍。 | - |
| `person_type` * | enumerator | 标识发送的对象是自然人还是法人。| **[Enumeradores person_type](#enumeradores-person_type)**|
| `phone` * | string | 包含电话数据的对象 | **[Objeto phone](#objeto-phone)**|
| `proof_of_residence` | string | 所发送地址的居住证明 PDF 的 DOCUMENT_KEY（事先上传）。| - |
| `monthly_income`* | number | 账户持有人月收入 | | 

### Objeto address 

此对象在个人和企业对象中均存在，是一个简单的地址表示对象。

| 字段 | 类型 | 描述 | 字符数 | 
|---|---|---|---| 
| `street` *| string | 地址街道  | 500 |
| `state` *| string | 地址州（两位大写字母） | 2 |
| `city` *| string | 地址城市 | 255 |
| `neighborhood` *| string | 地址街区 | 500 |
| `number` *| string | 门牌号 | 10 |
| `postal_code` *| string | 邮政编码（http://www.buscacep.correios.com.br/sistemas/buscacep/）（仅数字） |  8 |
| `complement` *| string | 地址补充信息（自由文本） | 500 |

### Objeto destinations

| 字段 | 类型 | 描述 | 字符数 |
|---| ---| ---| ---| 
| `account_branch` * | string | 目标账户机构编号。 | 4 | 
| `account_number` * | string | 目标账户号码。 | - |
| `account_digit` * | string | 目标账户号码校验位。 | 1 |
| `document_number` * | string | 目标账户持有人 CPF/CNPJ。 | - |
| `name ` | string | 目标账户持有人姓名/公司名称。 | - |
| `ispb_number` * | string | 目标账户金融机构的 ISPB（CNPJ 基础）。| 8 |
| `financial_institution_code_number ` * | string | 目标账户金融机构代码。 | 3 |

### Objeto signed_contract 
| 字段 | 类型   | 描述        | 字符数    |
|-------|--------|------------------|---------------|
| **document_key** * | uuidv4 | **账户开设条款**或 **Escrow 账户合同**文件的唯一标识键。（DOCUMENT_KEY 在[文件上传](./upload_de_documentos)端点响应中返回） | 36            |
| **signatures** *   | list   | 发送文件的签名数据。列表中每一项对应一位文件签署人。      | [Objeto signatures](#objeto-signatures) |

### Objeto signatures
| 字段 | 类型       | 描述         | 字符数        |
|-------|------------|-------------------|-------------------|
| **authenticity** * | object     | 证明签署人完成电子签名的数据集。 | [Objeto authenticity](#objeto-authenticity) |
| **signer** * | object     | 包含文件签署人之一数据的对象。           | [Objeto signer](#objeto-signer)|
| **authentication_type** * | enumerator | 签名类型。始终为 "**opt-in**"| "**opt-in**"                   |

### Enumeradores person_type
| 枚举值 | 描述         | 
|-------|-------------------|
| **natural** * | 自然人     |
| **legal** * | 法人     |    

### Objeto authenticity
| 字段 | 类型   | 描述               | 字符数 |
|-------|--------|-------------------------|------------|
| **timestamp** *            | string | 文件签署的日期和时间。                | 27         |
| **facial_recognition_key** *| uuidv4 | 账户持有人自拍照的唯一标识键。  | 36         |
| **lang**                   | string | 签署时捕获的签署人地理位置经度坐标。                  | -          |
| **lat**                    | string | 签署时捕获的签署人地理位置纬度坐标。                   | -          |
| **ip_address**             | string | 签署人设备的 IP 地址。     | -          |
| **session_id**     *        | string | 签署时签署人的会话 ID。                | -          |

### Objeto signer
| 字段                 | 类型   | 描述                              | 字符数                        |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| **name** *            | string | 签署人姓名。                        | -                                 |
| **email** *           | string | 签署人邮箱。                       | -                                 |
| **phone** *           | object | 包含签署人电话数据的对象 | **[Objeto phone](#objeto-phone)** |
| **document_number** * | string | 签署人 CPF。                         | 11                                |

### Objeto phone 

| 字段 | 描述 | 示例 | 最大字符数 | 
| --- | --- | --- | --- | 
|`country_code` *| string | 电话 DDI 代码（https://ddi.guiamais.com.br/） | 3 | 
| `area_code` *| string | 电话 DDD 代码（https://ddd.guiamais.com.br/） | 3 |
| `number` *| string | 电话号码（仅数字） |  10 |

## Response

STATUS 201

Response Body

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

:::warning 注意
`account_key` 字段将成为账户的唯一标识键。所有与账户的交互都将通过它进行。
:::

STATUS 4xx

Response Body: Error

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`  | 描述（英文）<br/>`description` | 描述（葡文）<br/>`translation`|
|---| --- | --- | --- | --- | 
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema|
| 404 | QIT000404 | Not Found | Resource could not be found | Recurso não encontrado|

---

# 确认开设企业账户

URL: /zh-Hans/documentation/baas/escrow/abrir_conta_pj

账户开设分两个必要步骤。首先，POST 请求发送初步数据以预留账户。随后，系统会触发状态为 `pending_additional_data` 的 `account_request.status_change` 类型 webhook。在第二步中，PATCH 请求完成开户，以补充信息正式确认账户。

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

## Path Params
| 字段         | 类型   | 描述                               | 字符数 |
|--------------|--------|------------------------------------|--------|
| `account_request_key` | uuidv4 | 账户预留请求的唯一标识键。 | 36     |

## 开设 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

| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---|---|
| `account_owner` * | object  | 包含账户持有人信息的对象 | **[Objeto account_owner](#objeto-account_owner)** |
| `signed_contract` * | object  | 包含账户持有人信息的对象 | **[Objeto signed_contract](#objeto-signed_contract)** |
| `destinations ` * | list  | 授权接收转账的目标账户列表。 | **[Objeto destinations](#objeto-destinations)** |
| `additional_documents` | list | 额外/可选文件 ID 列表。 | UUID 数组 |

### Objeto account_owner

| 字段 | 类型 | 描述 | 字符数 |
|---| ---| ---| ---| 
| `address` * | object | 账户持有人地址。 | **[Objeto adress](#objeto-address)** |  |
| `cnae_code` | string | 全国经济活动分类代码 | 9 |
| `company_document_number ` * | string | CNPJ | 14 |
| `company_statute ` | uuidv4 | 企业章程 PDF 的 DOCUMENT_KEY（事先上传）。 | 36 |
| `company_type` * | enumerator | 企业类型 | **[Enumeradores company_type](#enumeradores-company_type)** |
| `email` * | string | 账户持有人邮箱。 | 200 |
| `foundation_date` | string | 企业成立日期（格式 "AAAA-MM-DD"）。 | 10 |
| `name` * | string | 账户持有人公司名称（社会名称）。 | 50 |
| `person_type` * | enumerator | 标识发送的对象是自然人还是法人。| **[Enumeradores person_type](#enumeradores-person_type)**|
| `phone` * | object | 包含电话数据的对象 | **[Objeto phone](#objeto-phone)**|
| `trading_name ` * | string | 商业名称。 | 200 |
| `company_representatives` | list | 企业法定代表人列表 | **[Objeto company_representatives](#objeto-company_representatives)** |
| `monthly_revenue`* | number | 企业月营业额 | |

### Objeto signed_contract 
| 字段 | 类型   | 描述        | 字符数    |
|-------|--------|------------------|---------------|
| ` document_key` * | uuidv4 | **账户开设条款**或 **Escrow 账户合同**文件的唯一标识键。（DOCUMENT_KEY 在[文件上传](./upload_de_documentos)端点响应中返回） | 36            |
|` signatures` *   | list   | 发送文件的签名数据。列表中每一项对应一位文件签署人。      | [Objeto signatures](#objeto-signatures) |

### Objeto destinations

| 字段 | 类型 | 描述 | 字符数 |
|---| ---| ---| ---| 
| `account_branch` * | string | 目标账户机构编号。 | 4 | 
| `account_number` * | string | 目标账户号码。 | - |
| `account_digit` * | string | 目标账户号码校验位。 | 1 |
| `document_number` * | string | 目标账户持有人 CPF/CNPJ。 | - |
| `name ` | string | 目标账户持有人姓名/公司名称。 | - |
| `ispb_number` * | string | 目标账户金融机构的 ISPB（CNPJ 基础）。| 8 |
| `financial_institution_code_number ` * | string | 目标账户金融机构代码。 | 3 |

### Objeto company_representatives

| 字段                               | 类型    | 描述                                                                                              | 字符数                                                                              |
|------------------------------------|---------|---------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------|
| **name** *                         | string  | 企业代表姓名                                                                                       | 100                                                                                 |
| **address** *                      | object  | 企业代表地址对象                                                                                   | **[Objeto address](#objeto-address)**                                               |
| **email** *                        | string  | 企业代表邮箱                                                                                       | 254                                                                                 |
| **birth_date**                   | string  | 企业代表出生日期（格式 "AAAA-MM-DD"）                                                              | 10                                                                                  |
| **individual_document_number** *   | string  | 企业代表 CPF（仅数字）。                                                                           | 11                                                                                  |
| **document_identification**        | string  | 企业代表带照片身份证件 PDF 的 DOCUMENT_KEY（RG 或 CNH）（事先上传） | 36                                                                                  |
| **document_identification_number** | string  | 企业代表带照片身份证件号码（RG 或 CNH）                                                             | 16                                                                                  |
| **document_identification_type**   | enum    | 企业代表带照片身份证件类型（RG 或 CNH）                                                             | [Enumeradores document_identification_type](#enumeradores-document_identification_type) |
| **is_pep** *                       | boolean | 声明该人是否为 PEP（http://www.portaldatransparencia.gov.br/download-de-dados/pep）。              | -                                                                                   |
| **final_beneficiary**              | boolean | 声明该人是否为公司的最终受益人。                                                                             | -                                                                                       |
| **marital_status**                 | enum    | 企业代表婚姻状况                                                                                   | **[Enumeradores marital status](#enumeradores-marital_status)**                     |
| **mother_name**                  | string  | 企业代表母亲姓名                                                                                   | 100                                                                                 |
| **nationality**                    | string  | 企业代表国籍                                                                                       | 50                                                                                  |
| **person_type** *                  | enum    | 标识发送的对象是自然人                                                                             | **[Enumeradores person_type](#enumeradores-person_type)**                           |
| **phone** * | object  | 企业代表电话数据对象  | **[Objeto phone](#objeto-phone)** |

### Objeto address

此对象在个人和企业对象中均存在，是一个简单的地址表示对象。

| 字段               | 描述 | 示例                                                                                    | 字符数 |
|--------------------|-----------|-------------------------------------------------------------------------------------------|------------|
| **street** *       | string    | 地址街道                                                                                   | 500        |
| **state** *        | enum      | 地址州（两位大写字母）                                                                     | 2          |
| **city** *         | string    | 地址城市                                                                                   | 255        |
| **neighborhood** * | string    | 地址街区                                                                                   | 500        |
| **number** *       | string    | 门牌号                                                                                     | 10         |
| **postal_code** *  | string    | 邮政编码（http://www.buscacep.correios.com.br/sistemas/buscacep/）（仅数字） | 8          |
| **complement**     | string    | 地址补充信息（自由文本）                                                                   | 500        |

### Objeto signed_contract 
| 字段 | 类型   | 描述        | 字符数    |
|-------|--------|------------------|---------------|
| **document_key** * | uuidv4 | **账户开设条款**或 **Escrow 账户合同**文件的唯一标识键。（DOCUMENT_KEY 在[文件上传](./upload_de_documentos)端点响应中返回） | 36            |
| **signatures** *   | list   | 发送文件的签名数据。列表中每一项对应一位文件签署人。      | [Objeto signatures](#objeto-signatures) |

### Objeto signatures
| 字段 | 类型       | 描述         | 字符数        |
|-------|------------|-------------------|-------------------|
| **authenticity** * | object     | 证明签署人完成电子签名的数据集。 | [Objeto authenticity](#objeto-authenticity) |
| **signer** * | object     | 包含文件签署人之一数据的对象。           | [Objeto signer](#objeto-signer)|
| **authentication_type** * | enumerator | 签名类型。始终为 "**opt-in**"| "**opt-in**"                   |

### Objeto authenticity
| 字段 | 类型   | 描述               | 字符数 |
|-------|--------|-------------------------|------------|
| **timestamp** *            | string | 文件签署的日期和时间。                | 27         |
| **facial_recognition_key** *| uuidv4 | 账户持有人自拍照的唯一标识键。| 36         |
| **lang**                   | string | 签署时捕获的签署人地理位置经度坐标。                  | -          |
| **lat**                    | string | 签署时捕获的签署人地理位置纬度坐标。                   | -          |
| **ip_address**             | string | 签署人设备的 IP 地址。     | -          |
| **session_id**  *           | string | 签署时签署人的会话 ID。                | -          |

### Objeto signer
| 字段                 | 类型   | 描述                              | 字符数                        |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| **name** *            | string | 签署人姓名。                        | -                                 |
| **email** *           | string | 签署人邮箱。                       | -                                 |
| **phone** *           | object | 包含签署人电话数据的对象 | **[Objeto phone](#objeto-phone)** |
| **document_number** * | string | 签署人 CPF。                         | 11                                |

### Objeto phone 

| 字段 | 描述 | 示例 | 最大字符数 | 
| --- | --- | --- | --- | 
|`country_code` *| string | 电话 DDI 代码（https://ddi.guiamais.com.br/） | 3 | 
| `area_code` *| string | 电话 DDD 代码（https://ddd.guiamais.com.br/） | 2 |
| `number` *| string | 电话号码（仅数字） |  10 |

### Enumeradores person_type
| 枚举值      | 描述         |
|-------------|-------------------|
| **natural** | 自然人     |
| **legal**   | 法人   |

### Enumeradores document_identification_type
| 枚举值    | 描述                               |
|-----------|----------------------------------------|
| **rg**  | RG - 注册证件                    |
| **cnh** | CNH - 全国驾驶执照 |

### Enumeradores company_type
| 枚举值                      | 描述                                                              |
|-----------------------------|--------------------------------------------------------------------------|
| **ltda**                   | 有限责任公司                                                             |
| **sa**                     | 股份公司                                                                 |
| **micro_enterprise**       | 微型企业                                                                 |
| **freelancer**             | 自由职业者                                                               |
| **sa_opened**              | 上市股份公司                                                             |
| **sa_closed**              | 非上市股份公司                                                           |
| **se_ltda**                | 有限责任商业公司                                                         |
| **se_cn**                  | 普通合伙公司                                                             |
| **se_cs**                  | 简单有限合伙公司                                                         |
| **se_ca**                  | 股份有限合伙公司                                                         |
| **scp**                    | 隐名合伙公司                                                             |
| **ei**                     | 个人企业主                                                               |
| **ese**                    | 外国公司在巴西的设立                                                     |
| **eeab**                   | 阿根廷-巴西双边公司在巴西的设立                                          |
| **ssp**                    | 简单纯粹公司                                                             |
| **ss_ltda**                | 简单有限公司                                                             |
| **ss_cn**                  | 普通合伙简单公司                                                         |
| **ss_cs**                  | 简单有限合伙公司                                                         |
| **eireli_ne**              | 企业性质个人有限责任公司                                                 |
| **eireli_ns**              | 简单性质个人有限责任公司                                                 |
| **eireli**                 | 个人有限责任公司                                                         |
| **mei**                    | 个体微型企业主                                                           |
| **me**                     | 微型企业                                                                 |
| **cop**                    | 合作社                                                                   |
| **private_association**    | 私人协会        |
| **association**            | 协会                                                         |
| **others**                 | 其他  |

### Enumeradores marital_status
| 枚举值         | 描述  |
|--------------|---------------|
| **single**   | 单身   |
| **married**  | 已婚   |
| **widower**  | 丧偶   |
| **divorced** | 离婚   |
| **separated** | 分居  |

## Response

STATUS 201

Response Body

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

:::warning 注意
`account_key` 将成为账户的唯一标识键。所有与账户的交互都将通过它进行。

STATUS 4xx

Response Body: Error

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`  | 描述（英文）<br/>`description` | 描述（葡文）<br/>`translation`|
|---| --- | --- | --- | --- | 
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema|
| 404 | QIT000404 | Not Found | Resource could not be found | Recurso não encontrado|

---

# 开设个人账户

URL: /zh-Hans/documentation/baas/escrow/reservar_conta_pf

账户开设分两个必要步骤。首先，POST 请求发送初步数据以预留账户。随后，系统会触发状态为 `pending_additional_data` 的 `account_request.status_change` 类型 webhook。在第二步中，PATCH 请求完成开户，以补充信息正式确认账户。

## 申请预留账户

## 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 CPF/CNPJ 模拟
要模拟审批、拒绝和人工审核等情况，可使用账户 owner 的 CPF/CNPJ 第一位数字：

0 至 6 -> 人工审核

7 -> 被 bacen protege+ 拒绝

8 -> KYC 自动拒绝

9 -> 自动审批
:::

### Request Body Params

| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---|---|
| `account_owner` * | object  | 包含账户持有人信息的对象 | **[Objeto account_owner](#objeto-account_owner)** |

### Objeto account_owner
| 字段 | 类型 | 描述 | 字符数 |
|--- | --- | --- | --- |
| `document_number` * | string  | 账户持有人 CPF | 11 |
| `email` * | string  | 账户持有人邮箱 | 200 |
| `birthdate` | string  | 出生日期（格式 YYYY-MM-DD） | 10 |
| `name` * | string  | 账户持有人姓名 | 50 |
| `documents` *| object  | 账户持有人证件 | **[Objeto documents](#objeto-documents)** |
| `face` *     | uuidv4  | 反欺诈人脸识别键（`face_recognition_key`） | 36 |

### Objeto documents

| 字段                          | 类型        | 描述                                                          | 字符数                        |
|-------------------------------|-------------|---------------------------------------------------------------|-------------------------------|
| `rg`                           | object      | 持有人 RG 正反面 OCR 键 | **[Objeto rg](#objeto-rg)**   |
| `cnh`                          | object      | 持有人 CNH OCR 键                              | **[Objeto cnh](#objeto-cnh)** |
| `cnh_digital`                     | object      | 持有人数字 CNH OCR 键                       | **[Objeto cnh_digital](#objeto-cnh_digital)** |
| `national_registry_of_foreigners` | object   | 持有人 RNE 正反面 OCR 键| **[Objeto national_registry_of_foreigners](#objeto-national_registry_of_foreigners)** |
| `national_migration_registry` | object   | 持有人 CRNM 正反面 OCR 键| **[Objeto national_migration_registry](#objeto-national_migration_registry)** |
| `passport`                     | object      | 持有人护照 OCR 键                       | **[Objeto passport](#objeto-passport)** |
| `cin_digital`                     | object      | 持有人数字国家身份证 OCR 键                       | **[Objeto cin_digital](#objeto-cin_digital)** |

:::info 信息
上传文档图片的 OCR 键（`ocr_key` 或 `ocr_front_key` 和 `ocr_back_key`）由反欺诈系统图片上传响应提供。`face_recognition_key` 在人脸识别响应中返回。
:::

### Objeto rg

| 字段                          | 类型        | 描述                                                          | 字符数                        |
|-------------------------------|-------------|---------------------------------------------------------------|-------------------------------|
| `ocr_front_key` *              | uuidv4      | RG 正面图片 OCR 键                      | 36                            |
| `ocr_back_key` *               | uuidv4      | RG 背面图片 OCR 键                       | 36                            |

或

| 字段                          | 类型        | 描述                                                          | 字符数                        |
|-------------------------------|-------------|---------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | RG 图片 OCR 键                                | 36                       |

### Objeto cnh

| 字段                          | 类型        | 描述                                                          | 字符数                        |
|-------------------------------|-------------|---------------------------------------------------------------|-------------------------------|
| `ocr_front_key` *              | uuidv4      | CNH 正面图片 OCR 键                     | 36                            |
| `ocr_back_key` *               | uuidv4      | CNH 背面图片 OCR 键                      | 36                            |

或

| 字段                          | 类型        | 描述                                                          | 字符数                        |
|-------------------------------|-------------|---------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | CNH 图片 OCR 键                               | 36                            |

### Objeto cnh_digital

| 字段                          | 类型        | 描述                                                          | 字符数                        |
|-------------------------------|-------------|---------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | 数字 CNH 图片 OCR 键                               | 36                            |

### Objeto national_registry_of_foreigners

| 字段                          | 类型        | 描述                                                          | 字符数                        |
|-------------------------------|-------------|---------------------------------------------------------------|-------------------------------|
| `ocr_front_key` *              | uuidv4      | RNE 正面图片 OCR 键                     | 36                            |
| `ocr_back_key` *               | uuidv4      | RNE 背面图片 OCR 键                      | 36                            |

或

| 字段                          | 类型        | 描述                                                          | 字符数                        |
|-------------------------------|-------------|---------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | RNE 图片 OCR 键                               | 36                            |

### Objeto national_migration_registry

| 字段                          | 类型        | 描述                                                          | 字符数                        |
|-------------------------------|-------------|---------------------------------------------------------------|-------------------------------|
| `ocr_front_key` *              | uuidv4      | CRNM 正面图片 OCR 键                     | 36                            |
| `ocr_back_key` *               | uuidv4      | CRNM 背面图片 OCR 键                      | 36                            |

或

| 字段                          | 类型        | 描述                                                          | 字符数                        |
|-------------------------------|-------------|---------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | CRNM 图片 OCR 键                               | 36                            |

### Objeto passport

| 字段                          | 类型        | 描述                                                          | 字符数                        |
|-------------------------------|-------------|---------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | 护照图片 OCR 键                               | 36                            |

### Objeto cin_digital

| 字段                          | 类型        | 描述                                                          | 字符数                        |
|-------------------------------|-------------|---------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | 数字国家身份证图片 OCR 键                               | 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 Bacen Protege+ 流程
提案从 `pending_bacen_validation` 状态开始。系统在继续 KYC 分析之前，先向 Bacen Protege+ 进行预验证。Bacen 批准后，状态将自动更新为 `pending_kyc_analysis`。
:::

:::warning 注意
`account_request_key` 字段需保存，将用于确认开户。
:::

### Response Body Params

| 字段 | 类型 | 描述 | 字符数|
|---|---| ---|---|
| `account_info` * | object  | 包含账户持有人信息的对象 |**[Objeto account_info](#objeto-account_info)**  | - |
| `account_request_key` * | string  | 创建请求的标识键 | - | - |
| `account_request_status` * | string  | KYC 状态 | - | - |

### Objeto account_info
| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---| --- |
| `account_branch` * | string  | 机构编号 | 4 |
| `account_digit` * | string  | 账户数字 | 11 |
| `account_number` * | string  | 账户号码 | 50 |

STATUS 4xx

Response Body: Error

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`  | 描述（英文）<br/>`description` | 描述（葡文）<br/>`translation`|
|---| --- | --- | --- | --- | 
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema|
| 404 | QIT000404 | Not Found | Resource could not be found | Recurso não encontrado|

---

# 开设企业账户

URL: /zh-Hans/documentation/baas/escrow/reservar_conta_pj

账户开设分两个必要步骤。首先，POST 请求发送初步数据以预留账户。随后，系统会触发状态为 `pending_additional_data` 的 `account_request.status_change` 类型 webhook。在第二步中，PATCH 请求完成开户，以补充信息正式确认账户。

## 申请预留账户

## 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 CPF/CNPJ 模拟
要模拟审批、拒绝和人工审核等情况，可使用账户 owner 的 CPF/CNPJ 第一位数字：

0 至 6 -> 人工审核

7 -> 被 bacen protege+ 拒绝

8 -> KYC 自动拒绝

9 -> 自动审批
:::

### Request Body Params

| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---|---|
| `account_owner` * | object  | 包含账户持有人信息的对象 | **[Objeto account_owner](#objeto-account_owner)** |
| `legal_representatives` | object array | 账户代表及其数据列表 | **[Objeto legal_representative](#objeto-legal_representative)** |

### Objeto account_owner
| 字段 | 类型 | 描述 | 字符数 |
|--- | --- | --- | --- |
| `"company_document_number"` * | string  | 账户持有人 CNPJ | 14 |
| `email` * | string  | 合同持有企业邮箱 | 200 |
| `foundation_date` | string  | 企业成立日期（格式 YYYY-MM-DD） | 10 |
| `name` * | string  | 企业名称（社会名称） | 50 |

### Objeto legal_representative

| 字段 | 类型 | 描述 | 字符数 |
|--- | --- | --- | --- |
| `document_number` * | string  | 账户持有人 CPF | 11 |
| `birthdate` | string  | 出生日期（格式 YYYY-MM-DD） | 10 |
| `name` * | string  | 账户持有人姓名 | 50 |
| `documents` * | object  | 账户持有人证件 | **[Objeto documents](#objeto-documents)** |
| `face`      | uuidv4  | 反欺诈人脸识别键（`face_recognition_key`） | 36 |

### Objeto documents

| 字段                          | 类型        | 描述                                                          | 字符数                        |
|-------------------------------|-------------|---------------------------------------------------------------|-------------------------------|
| `rg`                           | object      | 持有人 RG 正反面 OCR 键 | **[Objeto rg](#objeto-rg)**   |
| `cnh`                          | object      | 持有人 CNH OCR 键                              | **[Objeto cnh](#objeto-cnh)** |
| `cnh_digital`                     | object      | 持有人数字 CNH OCR 键                       | **[Objeto cnh_digital](#objeto-cnh_digital)** |
| `national_registry_of_foreigners` | object   | 持有人 RNE 正反面 OCR 键| **[Objeto national_registry_of_foreigners](#objeto-national_registry_of_foreigners)** |
| `national_migration_registry` | object   | 持有人 CRNM 正反面 OCR 键| **[Objeto national_migration_registry](#objeto-national_migration_registry)** |
| `passport`                     | object      | 持有人护照 OCR 键                       | **[Objeto passport](#objeto-passport)** |
| `cin_digital`                     | object      | 持有人数字国家身份证 OCR 键                       | **[Objeto cin_digital](#objeto-cin_digital)** |

:::info 信息
上传文档图片的 OCR 键（`ocr_key` 或 `ocr_front_key` 和 `ocr_back_key`）由反欺诈系统图片上传响应提供。`face_recognition_key` 在人脸识别响应中返回。
:::

### Objeto rg

| 字段                          | 类型        | 描述                                                          | 字符数                        |
|-------------------------------|-------------|---------------------------------------------------------------|-------------------------------|
| `ocr_front_key` *              | uuidv4      | RG 正面图片 OCR 键                      | 36                            |
| `ocr_back_key` *               | uuidv4      | RG 背面图片 OCR 键                       | 36                            |

或

| 字段                          | 类型        | 描述                                                          | 字符数                        |
|-------------------------------|-------------|---------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | RG 图片 OCR 键                                | 36                       |

### Objeto cnh

| 字段                          | 类型        | 描述                                                          | 字符数                        |
|-------------------------------|-------------|---------------------------------------------------------------|-------------------------------|
| `ocr_front_key` *              | uuidv4      | CNH 正面图片 OCR 键                     | 36                            |
| `ocr_back_key` *               | uuidv4      | CNH 背面图片 OCR 键                      | 36                            |

或

| 字段                          | 类型        | 描述                                                          | 字符数                        |
|-------------------------------|-------------|---------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | CNH 图片 OCR 键                               | 36                            |

### Objeto cnh_digital

| 字段                          | 类型        | 描述                                                          | 字符数                        |
|-------------------------------|-------------|---------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | 数字 CNH 图片 OCR 键                               | 36                            |

### Objeto national_registry_of_foreigners

| 字段                          | 类型        | 描述                                                          | 字符数                        |
|-------------------------------|-------------|---------------------------------------------------------------|-------------------------------|
| `ocr_front_key` *              | uuidv4      | RNE 正面图片 OCR 键                     | 36                            |
| `ocr_back_key` *               | uuidv4      | RNE 背面图片 OCR 键                      | 36                            |

或

| 字段                          | 类型        | 描述                                                          | 字符数                        |
|-------------------------------|-------------|---------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | RNE 图片 OCR 键                               | 36                            |

### Objeto national_migration_registry

| 字段                          | 类型        | 描述                                                          | 字符数                        |
|-------------------------------|-------------|---------------------------------------------------------------|-------------------------------|
| `ocr_front_key` *              | uuidv4      | CRNM 正面图片 OCR 键                     | 36                            |
| `ocr_back_key` *               | uuidv4      | CRNM 背面图片 OCR 键                      | 36                            |

或

| 字段                          | 类型        | 描述                                                          | 字符数                        |
|-------------------------------|-------------|---------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | CRNM 图片 OCR 键                               | 36                            |

### Objeto passport

| 字段                          | 类型        | 描述                                                          | 字符数                        |
|-------------------------------|-------------|---------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | 护照图片 OCR 键                               | 36                            |

### Objeto cin_digital

| 字段                          | 类型        | 描述                                                          | 字符数                        |
|-------------------------------|-------------|---------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | 数字国家身份证图片 OCR 键                               | 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 Bacen Protege+ 流程
提案从 `pending_bacen_validation` 状态开始。系统在继续 KYC 分析之前，先向 Bacen Protege+ 进行预验证。Bacen 批准后，状态将自动更新为 `pending_kyc_analysis`。
:::

:::warning 注意
`account_request_key` 字段需保存，将用于确认开户。
:::

### Response Body Params

| 字段 | 类型 | 描述 | 字符数|
|---|---| ---|---|
| `account_info` * | object  | 包含账户持有人信息的对象 |**[Objeto account_info](#objeto-account_info)**  | - |
| `account_request_key` * | string  | 创建请求的标识键 | - | - |
| `account_request_status` * | string  | KYC 状态 | - | - |

### Objeto account_info
| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---| --- |
| `account_branch` * | string  | 机构编号 | 4 |
| `account_digit` * | string  | 账户数字 | 11 |
| `account_number` * | string  | 账户号码 | 50 |

STATUS 4xx

Response Body: Error

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`  | 描述（英文）<br/>`description` | 描述（葡文）<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

URL: /zh-Hans/documentation/baas/escrow/webhooks

在发送账户预留请求后，系统会发送一个状态为 pending_additional_data 的 account_request.status_change 类型 webhook，该事件是触发发送确认开户请求的信号。

开户请求的响应可能会返回状态 "pending_kyc_analysis"，具体取决于合作方的集成配置。

在这种情况下，开户审批或拒绝的响应将通过 webhook 以异步方式返回。

账户号码将在开户申请时预留，但此时**账户尚未开立**。只有在 QI Tech 完成 KYC 分析后，账户才会正式开立。

## Webhook Pending KYC Analysis

Bacen Protege+ 批准后，开户申请状态更新为 `pending_kyc_analysis`，并发送 webhook 通知合作方。

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"
}
```

## KYC 审批 Webhook

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
| 枚举值                       | 描述                     |
|------------------------------|--------------------------|
| **pending_kyc_analysis**    | 待 KYC 审批               |
| **pending_additional_data** | 待补充额外信息             |
| **rejected**                | 开户被拒绝                |

## 企业账户

# 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"
}
```

## 个人账户

# 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: /zh-Hans/documentation/baas/lista_de_instituicoes_financeiras/baas_consulta_de_instituicoes_financeiras



---

# baas_configuracao_de_notificacao

URL: /zh-Hans/documentation/baas/notificacoes/baas_configuracao_de_notificacao



---

# baas_configuracao_template

URL: /zh-Hans/documentation/baas/notificacoes/baas_configuracao_template



---

# baas_introducao

URL: /zh-Hans/documentation/baas/notificacoes/baas_introducao



---

# baas_reenvio_de_notificacoes

URL: /zh-Hans/documentation/baas/notificacoes/baas_reenvio_de_notificacoes



---

# baas_template

URL: /zh-Hans/documentation/baas/notificacoes/baas_template



---

# baas_tipos_de_evento

URL: /zh-Hans/documentation/baas/notificacoes/baas_tipos_de_evento



---

# 上传汇款文件（CNAB）

URL: /zh-Hans/documentation/baas/pagamento_em_lote/envio_de_remessa

:::caution 注意！
调用必须按照[**文件上传**](/documentation/upload_de_documentos)部分描述的标准进行认证。
:::

## Request

ENDPOINT /payments/account/ ACCOUNT_KEY /remittance
MÉTODO POST

### Path parameters

| 字段                   | 类型   | 描述                                                    | 字符数 |
|------------------------|--------|---------------------------------------------------------|--------|
| `account_key`           | uuidv4 | 账户的唯一标识键，uuid v4 格式                           | 36     |

## Request Body Params

以下数据应以 form-data 格式在请求体中发送：

| 字段                   | 类型   | 描述                                                    | 字符数 |
|------------------------|--------|---------------------------------------------------------|--------|
| `file` *                | file   | 符合 QI Tech 规定标准的 CNAB 文件                        | -      |

## Response

STATUS 202

Response Body

```json
{
  "cnab_remittance_key": "f14e9bac-94ed-4eb1-87b4-7fd7b7a2d280",
  "cnab_remittance_status": "accepted"
}
```

### Response Body Params

| 字段                          | 类型    | 描述                                                       | 字符数                 |
|-------------------------------|---------|------------------------------------------------------------|-----------------------|
| `cnab_remittance_key` *    | uuidv4  | CNAB 文件的唯一标识键，uuid v4 格式 | 36                         |
| `cnab_remittance_status` * | string  | CNAB 文件状态 | **[Enumeradores cnab_remittance_status](#enumeradores-cnab_file_status)** |

### Enumeradores cnab_remittance_status

| 枚举值     | 描述                                                                    |
|------------|-------------------------------------------------------------------------|
| uploaded   | 上传成功，但文件尚未开始处理                                             |
| processing | 文件正在读取中                                                           |
| accepted   | 文件已读取并接受                                                         |
| rejected   | 文件已读取并拒绝（文件中所有记录均被拒绝）                               |

## Error Response

STATUS 4xx

Response Body: Error

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                 | 描述（英文）<br/>`description`                                                                                                          | 描述（葡文）<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                                                              |

---

# CNAB240 批量交易简介

URL: /zh-Hans/documentation/baas/pagamento_em_lote/introducao

QI Tech 通过 Payments API 支持使用 CNAB240 格式进行支付，支持在单次调用中处理不同类型的交易，如划账单、PIX 和 TED。该系统实现批量支付，为大量金融流程提供更高效率。

支付以异步方式处理，在提交 CNAB240 文件时进行严格验证。如果初始请求返回 HTTP 状态 4xx，则不会处理任何支付。

提交后，文件可能被接受或拒绝。如果被拒绝，API 将返回与文件格式相关的详细错误列表，允许集成方在重新提交前进行必要的修正。文件若发现任何语法错误将被拒绝。但是，文件会被完整读取，或直到发现 100 个错误为止，以便能够一次性返回所有错误，使修正更加便捷高效。

在文件读取过程中，记录会被添加到队列中，但只有在文件被接受后才会处理。也就是说，如果文件被拒绝（状态为 rejected），其所有记录也将被丢弃。另一方面，当文件被完整读取并接受（状态为 accepted）时，这些记录的处理就开始了，确保基于所提供数据的交易顺利进行。

---

# 按账户查询付款批次数据

URL: /zh-Hans/documentation/baas/pix_automatico/conciliacao/consultar_lote_por_conta

## 请求

ENDPOINT /account/ ACCOUNT_KEY /payment_order_conciliation_batch/ PAYMENT_ORDER_CONCILIATION_BATCH_KEY
方法 GET

### Path Params

| 字段                                       | 类型   | 描述                       | 字符数 |
|--------------------------------------------|--------|----------------------------|--------|
| **`ACCOUNT_KEY`** *                        | uuidv4 | 账户的唯一标识键。         | 36     |
| **`PAYMENT_ORDER_CONCILIATION_BATCH_KEY`***| uuidv4 | 批次的唯一标识键。         | 36     |

## 响应

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

| 字段                                       | 类型       | 描述                                                         | 字符数 |
|--------------------------------------------|------------|--------------------------------------------------------------|--------|
| `payment_order_conciliation_batch_status`  | enumerator | 付款订单对账批次状态。                                       | [Enumeradores payment_order_conciliation_batch_status](#enumeradores-payment_order_conciliation_batch_status) |
| `payment_order_conciliation_batch_type`    | enumerator | 付款订单对账批次类型。                                       | [Enumeradores payment_order_conciliation_batch_type](#enumeradores-payment_order_conciliation_batch_type) |
| `total_amount`                             | number     | 对账批次的总金额（巴西雷亚尔 R$）。                         | -      |
| `conciliated_amount`                       | number     | 批次中已对账的金额（巴西雷亚尔 R$）。                       | -      |
| `total_payment_orders`                     | integer    | 批次中付款订单的总数。                                       | -      |
| `conciliated_payment_orders`               | integer    | 批次中已对账的付款订单数量。                                 | -      |
| `reference_date`                           | string     | 批次参考日期（ISO 8601 格式，如 "2025-06-13"）。             | 10     |
| `created_at`                               | string     | 批次创建日期和时间（ISO 8601 格式）。                        | -      |

### Enumeradores payment_order_conciliation_batch_status

| 枚举值       | 描述             |
|--------------|------------------|
| `open`       | 对账批次已开放   |
| `closed`     | 对账批次已关闭   |
| `processing` | 对账批次处理中   |
| `completed`  | 对账批次已完成   |
| `cancelled`  | 对账批次已取消   |

### Enumeradores payment_order_conciliation_batch_type

| 枚举值            | 描述               |
|-------------------|--------------------|
| `fixed_amount`    | 固定金额对账批次   |
| `variable_amount` | 可变金额对账批次   |

STATUS 4XX

Response Error

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

| HTTP 状态码 | QI 代码<br/>`code` | 标题<br/>`title`             | 描述（英文）<br/>`description`                                             | 描述（葡文）<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.     |

---

# 按 Requester 查询付款批次

URL: /zh-Hans/documentation/baas/pix_automatico/conciliacao/consultar_lote_requester

## 请求

ENDPOINT /payment_order_conciliation_batches
方法 GET

### Query Params

| 字段                                       | 类型       | 描述                                                              | 是否必填 |
|--------------------------------------------|------------|-------------------------------------------------------------------|----------|
| `payment_order_conciliation_batch_status`  | enumerator | 按对账批次状态筛选。                                              | 否       |
| `payment_order_conciliation_batch_type`    | enumerator | 按对账批次类型筛选。                                              | 否       |
| `page`                                     | integer    | 分页页码（默认：1）。                                             | 否       |
| `page_size`                                | integer    | 分页每页大小（默认：25）。                                        | 否       |
| `from_date`                                | string     | 筛选开始日期（ISO 8601 格式，如 "2025-06-01"）。                  | 否       |
| `to_date`                                  | string     | 筛选结束日期（ISO 8601 格式，如 "2025-06-30"）。                  | 否       |

## 响应

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

| 字段                                  | 类型   | 描述                                | 字符数 |
|---------------------------------------|--------|-------------------------------------|--------|
| `payment_order_conciliation_batches`  | array  | 付款订单对账批次列表。              | [Array payment_order_conciliation_batches](#array-payment_order_conciliation_batches) |
| `pagination`                          | object | 查询分页信息。                      | [Objeto pagination](#objeto-pagination) |

### Array payment_order_conciliation_batches

| 字段                                       | 类型       | 描述                                                         | 字符数 |
|--------------------------------------------|------------|--------------------------------------------------------------|--------|
| `payment_order_conciliation_batch_key`     | uuidv4     | 对账批次的唯一标识符。                                       | 36     |
| `payment_order_conciliation_batch_status`  | enumerator | 付款订单对账批次状态。                                       | [Enumeradores payment_order_conciliation_batch_status](#enumeradores-payment_order_conciliation_batch_status) |
| `payment_order_conciliation_batch_type`    | enumerator | 付款订单对账批次类型。                                       | [Enumeradores payment_order_conciliation_batch_type](#enumeradores-payment_order_conciliation_batch_type) |
| `account_key`                              | uuidv4     | 账户的唯一标识键。                                           | 36     |
| `total_amount`                             | number     | 对账批次的总金额（巴西雷亚尔 R$）。                         | -      |
| `conciliated_amount`                       | number     | 批次中已对账的金额（巴西雷亚尔 R$）。                       | -      |
| `total_payment_orders`                     | integer    | 批次中付款订单的总数。                                       | -      |
| `conciliated_payment_orders`               | integer    | 批次中已对账的付款订单数量。                                 | -      |
| `reference_date`                           | string     | 批次参考日期（ISO 8601 格式，如 "2025-06-13"）。             | 10     |
| `created_at`                               | string     | 批次创建日期和时间（ISO 8601 格式）。                        | -      |

### Objeto pagination

| 字段              | 类型    | 描述                         | 字符数 |
|-------------------|---------|------------------------------|--------|
| `page`            | integer | 当前查询页码。               | -      |
| `page_size`       | integer | 每页大小（每页项目数量）。   | -      |
| `number_of_pages` | integer | 可用的总页数。               | -      |

### Enumeradores payment_order_conciliation_batch_status

| 枚举值       | 描述             |
|--------------|------------------|
| `open`       | 对账批次已开放   |
| `closed`     | 对账批次已关闭   |
| `processing` | 对账批次处理中   |
| `completed`  | 对账批次已完成   |
| `cancelled`  | 对账批次已取消   |

### Enumeradores payment_order_conciliation_batch_type

| 枚举值            | 描述               |
|-------------------|--------------------|
| `fixed_amount`    | 固定金额对账批次   |
| `variable_amount` | 可变金额对账批次   |

STATUS 4XX

Response Error

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

| HTTP 状态码 | QI 代码<br/>`code` | 标题<br/>`title`             | 描述（英文）<br/>`description`       | 描述（葡文）<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.          |

---

# 列出账户的付款订单

URL: /zh-Hans/documentation/baas/pix_automatico/conciliacao/listar_payment_orders

## 请求

ENDPOINT /account/ ACCOUNT_KEY /payment_order_conciliation_batch/ PAYMENT_ORDER_CONCILIATION_BATCH_KEY /payment_orders
方法 GET

### Query Params

| 字段                   | 类型       | 描述                                                             | 字符数 |
|------------------------|------------|------------------------------------------------------------------|--------|
| `payment_order_status` | enumerador | 按状态筛选付款（如 `processed`、`pending`、`failed`）。         | 30     |
| `page`                 | integer    | 要返回的页码（分页）。                                           | -      |
| `page_size`            | integer    | 每页项目数量（分页）。                                           | -      |

## 响应

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

| 字段             | 类型   | 描述                                 | 字符数 |
|------------------|--------|--------------------------------------|--------|
| `payment_orders` | array  | 付款订单对象列表。                   | [Array payment_orders](#array-payment_orders) |
| `pagination`     | object | 包含结果信息的分页对象。             | [Objeto pagination](#objeto-pagination)       |

---

### Array payment_orders

| 字段                  | 类型       | 描述                                                                    | 字符数 |
|-----------------------|------------|-------------------------------------------------------------------------|--------|
| `payment_order_key`   | uuidv4     | 付款订单的唯一标识符。                                                  | 36     |
| `payment_order_status`| string     | 付款订单状态（`processed`、`pending`、`failed` 等）。                  | 30     |
| `amount`              | number     | 付款订单金额（巴西雷亚尔 R$）。                                        | -      |
| `currency`            | string     | 支付货币。                                                              | 3      |
| `transaction_date`    | string     | 交易日期（ISO 8601 格式，如 `2023-10-05`）。                            | 10     |
| `recipient_data`      | object     | 付款接收方数据。                                                        | [Objeto recipient_data](#objeto-recipient_data) |
| `pix_key`             | string     | 接收方的 Pix 键。                                                       | 77     |
| `pix_message`         | string     | 随 Pix 交易一起发送的消息。                                             | 140    |
| `conciliation_id`     | string     | 付款对账标识符。                                                        | 36     |

---

### Objeto recipient_data

| 字段              | 类型   | 描述                       | 字符数 |
|-------------------|--------|----------------------------|--------|
| `name`            | string | 接收方姓名。               | 50     |
| `document_number` | string | 接收方的 CPF 或 CNPJ。     | 14     |
| `bank_account`    | object | 接收方银行账户数据。       | [Objeto bank_account](#objeto-bank_account) |

---

### Objeto bank_account

| 字段             | 类型   | 描述                       | 字符数 |
|------------------|--------|----------------------------|--------|
| `account_number` | string | 账户号码。                 | -      |
| `account_digit`  | string | 账户校验位。               | -      |
| `account_branch` | string | 支行。                     | -      |
| `ispb`           | string | 金融机构 ISPB。            | -      |

### Objeto pagination

| 字段              | 类型    | 描述                   | 字符数 |
|-------------------|---------|------------------------|--------|
| `page`            | integer | 返回的页码。           | -      |
| `page_size`       | integer | 每页项目数量。         | -      |
| `number_of_pages` | integer | 可用的总页数。         | -      |

### Enumeradores payment_order_status

| 枚举值                 | 描述                   |
|------------------------|------------------------|
| `pending_conciliation` | 等待对账。             |
| `pending`              | 待处理，尚未处理。     |
| `accepted`             | 已接受，等待付款。     |
| `paid`                 | 成功付款。             |
| `rejected`             | 已拒绝，不会处理。     |
| `cancelled`            | 付款前已取消。         |

STATUS 4XX

Response Error

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

| HTTP 状态码 | QI 代码<br/>`code` | 标题<br/>`title`        | 描述（英文）<br/>`description`                             | 描述（葡文）<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

URL: /zh-Hans/documentation/baas/pix_automatico/conciliacao/webhooks

通过 Webhook 发送的通知对于处理 Pix 自动付款对账事件至关重要。此 Webhook 通知付款订单对账批次的创建。

## 对账批次创建 Webhook

当新的付款订单对账批次被创建时，将发出此 Webhook。

:::danger 注意！
QI Tech 的 Webhooks 不应以限制性方式映射。
我们 API 返回的 Webhook 载荷中可能会添加额外字段。
:::

### Webhook Request Body

Request Body: 旅程 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

| 字段                  | 类型   | 描述                                                                                       | 字符数 |
|-----------------------|--------|--------------------------------------------------------------------------------------------|--------|
| `webhook_type` *      | string | Webhook 事件类型（`baas.automatic_pix.payment_order_conciliation_batch.creation`）。       | 100    |
| `webhook_datetime` *  | string | Webhook 生成的日期和时间（ISO 8601 格式）。                                                | -      |
| `data` *              | Object | 包含对账批次详情的对象。                                                                   | [Objeto data](#objeto-data) |

---

### Objeto data

| 字段                                   | 类型  | 描述                     | 字符数 |
|----------------------------------------|-------|--------------------------|--------|
| `payment_order_conciliation_batches` * | array | 已创建的对账批次列表。   | [Array payment_order_conciliation_batches](#array-payment_order_conciliation_batches) |

### Array payment_order_conciliation_batches

| 字段                                      | 类型    | 描述                                                         | 字符数 |
|-------------------------------------------|---------|--------------------------------------------------------------|--------|
| `payment_order_conciliation_batch_key`    | string  | 对账批次的唯一键。                                           | 36     |
| `payment_order_conciliation_batch_status` | string  | 对账批次状态（`open`）。                                     | -      |
| `payment_order_conciliation_batch_type`   | string  | 对账批次类型（`fixed_amount`、`variable_amount`）。          | -      |
| `account_key`                             | uuidv4  | 与批次关联的账户标识键。                                     | 36     |
| `total_amount`                            | number  | 对账批次的总金额。                                           | -      |
| `conciliated_amount`                      | number  | 批次中已对账的总金额。                                       | -      |
| `total_payment_orders`                    | number  | 批次中付款订单的总数。                                       | -      |
| `conciliated_payment_orders`              | number  | 批次中已对账的付款订单数量。                                 | -      |
| `reference_date`                          | string  | 批次参考日期（YYYY-MM-DD 格式）。                            | 10     |
| `created_at`                              | string  | 批次创建日期（ISO 8601 格式）。                              | -      |

---

# FAQ - Pix 自动支付

URL: /zh-Hans/documentation/baas/pix_automatico/faq

关于定期付款的问题
  
定期付款是否需要预先定义有效期或付款次数？
定期付款的有效期是由接收方和付款方之间关系定义的参数。授权可以 无限期 授予，也可以预先定义 收费次数 或 有效期结束日期 。

可以在周期内选择任何一天作为扣款日期吗？
可以，但需遵守调度日期与预期结算日期之间 至少 2 天的最短提前期 ，且结算日期必须 早于下个周期的开始日期 。

关于授权旅程的问题
  
带 QR 码的各旅程之间的主要区别是什么？
主要区别在于用户体验和授权定期付款的时机。 旅程 2 仅授权未来的定期付款，不立即处理付款。 旅程 3 允许在授权定期付款的同时进行首次即时付款——完成的付款激活定期付款。 旅程 4 工作方式不同：用户像普通 Pix 一样扫描 QR 码，在付款或调度后，系统会为其提供 Pix 自动支付选项。旅程 4 是唯一支持可变金额定期付款且提供更灵活用户体验的旅程。

如果通过旅程 3，结算成功但授权失败，是否需要取消付款，因为流程预期两者都成功？
由 接收方用户自行决定 。可以 退还已结算的 Pix 并启动新的旅程 3，也可以 提供另一种 Pix 自动支付授权旅程 ，专门用于为后续付款实现授权。

关于对账批次的常见问题
  
什么是对账批次？
对账批次是由系统自动创建的 付款分组 ，用于简化 Pix 自动支付付款的对账和控制。它们按 结算日期 和 定期付款类型 对付款进行组织和跟踪。

付款是如何被分组到批次中的？
付款会根据以下标准自动分组到批次中：
预期付款结算日期
定期付款类型： fixed_amount （固定金额）或 variable_amount （可变金额）
特定账户
特定请求方

批次何时创建？
当有需要为特定付款日期处理的付款订单时，批次由系统自动创建。 系统将同一天结算的订单分组到批次中 ，以便于处理、查看和对账。

批次何时关闭？
批次 始终在其参考付款日期前三天关闭 ，因为付款订单需要在该周期付款日期前最多两天发送。
系统根据付款 结算日期 减 3 天自动计算此日期，确保付款指令在巴西中央银行规定的时限内发送。

我可以查询已关闭批次的付款吗？
可以，您可以通过批次查询和特定批次付款列表端点查询已关闭批次的付款。

关于付款订单和付款尝试的问题
  
付款订单和付款尝试有什么区别？
付款订单： 是系统创建的用于在特定日期执行特定付款的指令。
付款尝试： 是该付款订单的每次单独执行，如果第一次失败，可能有多次尝试。

会进行多少次付款尝试？
系统每个付款订单最多进行 4 次付款尝试 。如果所有尝试都失败，付款订单将被标记为已拒绝。

所有尝试都失败时会发生什么？
当所有 4 次付款尝试均失败时，付款订单的状态将更改为 "rejected" （已拒绝），该周期的付款将不再进行更多尝试。

重试是如何运作的？
重试由系统根据接收方在创建定期付款时配置的重试天数自动执行。每次失败的尝试都会生成一个通知 Webhook，以便您可以跟踪该付款的状态。

关于取消的问题
  
我可以取消特定的付款订单吗？
可以，您可以通过付款订单取消端点取消特定付款订单，前提是该订单尚未结算。

取消定期付款和取消付款订单有什么区别？
取消定期付款： 取消整个定期付款及与其相关的所有未来付款订单。
取消付款订单： 仅取消该周期的特定付款订单，不影响定期付款或其他订单。

关于模拟的问题
  
模拟场景有什么用？
模拟场景用于在沙箱环境中测试 Pix 自动支付的完整流程，模拟付款服务提供商（PSP）的响应和交互。

如何正确使用模拟场景？
场景应按顺序执行以模拟完整流程：
创建定期付款
处理付款订单
更新执行日期（沙箱）
处理付款尝试
模拟入账 Pix
模拟被拒绝的尝试（如有需要）

关于 Webhook 的问题
  
Pix 自动支付会发送哪些 Webhook？
系统会为各种事件发送 Webhook，包括：
定期付款状态变更
付款订单状态变更
付款尝试状态变更
对账批次的创建和关闭

关于优势和比较的问题
  
接收方加入 Pix 自动支付相比其他现有付款方式有哪些主要优势？
Pix 自动支付为接收方用户提供了一种新的方式，利用 Pix 基础设施接收和管理周期性定期收费。主要优势包括： 扩大客户基础 、 降低运营成本 （无需与多家机构签订协议）、 多样化付款方式 （为使用卡片或银行单据的客户提供 Pix 作为替代），以及 减少逾期 和 更高效地管理 收款。

传统自动账户扣款和 Pix 自动支付之间的主要区别是什么？
专注于接收方和付款方用户体验，Pix 自动支付提供了 新的授权和定期调度管理功能 。此外， 任何 Pix 参与者都可以向客户提供该产品 ，扩大了目前无法获得仅在银行机构间有限提供的自动扣款服务的公民和企业的访问权限。

---

# Pix 自动扣款简介

URL: /zh-Hans/documentation/baas/pix_automatico/introducao

**Pix 自动扣款**是一种创新解决方案，以简化、高效且安全的方式实现循环付款自动化。它非常适合处理订阅、月费或循环账单的企业，通过消除手动交互的需求、减少逾期付款并简化财务管理，服务于企业和消费者，超越了传统支付方式。

{`
.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;
}
`}

实际如何运作？
  
适用于谁？
非常适合提供订阅、周期性服务、学费、健康计划等类似服务的企业。
    
我需要做什么？
收款方创建一个循环扣款，付款方仅需授权一次。之后，每个周期的付款将自动进行。
    
主要优势
减少延迟，无需记住付款日期，并简化双方的财务管理。

### 简单4步流程

1. 创建循环扣款
收款方定义循环扣款的特征（金额、频率、开始日期）。
    
2. 授权
付款方在银行应用中仅需授权一次，从4种可用流程中选择一种。
    
3. 调度
每个周期，收款方发送付款指令，付款方银行自动进行调度。
    
4. 结算
在计划日期，借记和贷记自动在双方账户中处理。

---

## Pix 自动扣款 API 功能

QI Tech 通过其 **API Automatic Pix**，使基于付款人对收款人的事先授权，集成自动 Pix 付款成为可能。该系统涵盖以下职责：

{`
.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;
  }
}
`}

创建与管理
以简化高效的方式，便于创建、管理和取消循环扣款。

授权编排
确保 Pix 自动扣款的循环付款获得付款人的正确授权。

调度与结算
从调度到结算，完全自动化付款周期。

日志与审计
保留所有操作的完整记录，以符合 Bacen 规定。

---

## 循环扣款类型

固定金额
固定金额循环扣款
      在固定金额模式中，付款人授权按照创建循环扣款时事先确定的固定金额进行周期性付款。
适用于： 月度订阅、学费、固定金额服务计划。

可变金额
可变金额循环扣款
      在可变金额模式中，付款人和收款人同意每次循环扣款的允许金额范围。收款人定义最低金额，付款人定义最高金额。
重要提示： 收款人必须在扣款日期前10至3天将付款订单与该期间应收取的金额进行对账。
适用于： 基于消耗的模式、可变服务账单、随时间调整的付款。

---

## 循环扣款周期

目前，可以按以下周期创建循环扣款：

可用周期
每周
每月
每季度
每半年
每年

---

## Pix 自动扣款授权流程

Pix 自动扣款支持多种授权流程，以适应不同的业务场景：

1
流程1：推送通知
      通过应用推送通知确认循环扣款，无需二维码。付款人收到通知后，直接在应用中授权。

2
流程2：二维码 - 仅循环扣款
      通过仅包含循环扣款数据的二维码进行授权。付款人扫描二维码，仅授权未来的循环扣款。

3
流程3：二维码 + 首次付款
      二维码同时允许首次即时付款和设置循环扣款。非常适合希望在同一笔交易中收取首次付款并创建循环扣款的场景。

4
流程4：完整二维码
      二维码包含即时付款/调度数据以及针对该账单的 Pix 自动扣款提议（付款或调度后）。允许在一次操作中完成付款（或调度）并提供 Pix 自动扣款。

:::info 流程文档
有关如何实现每种流程的完整详情，请参阅：
- [流程1 - 推送通知](./recebedor/journey_one.md)
- [流程2 - 二维码（仅循环扣款）](./recebedor/journey_two.md)
- [流程3 - 二维码（含首次付款）](./recebedor/journey_three.md)
- [流程4 - 二维码（含首次付款和可变金额）](./recebedor/journey_four.md)
:::

---

## 取消循环扣款

取消规则
  
取消申请
付款用户或收款方均可单方面申请取消，无需双方同意。
取消影响
授权和循环扣款同时取消，自动阻止新的付款指令。
取消流程
付款用户更新并将取消状态告知收款用户，收款用户应立即获知。
即时效果
自动取消所有关联的调度，但取消当天计划结算的除外。
收款方主动取消
收款方可自行决定或应付款方请求，通过 API 取消循环扣款。

---

## 优势与潜力

Pix 自动扣款提供多种优势，例如集中授权和付款、鼓励数字化金融，以及自动扣款解决方案的高效性，填补了传统支付方式的空白。

✓
降低延迟风险和记忆付款截止日期的需求，消除人工步骤

✓
在统一平台上集中控制授权和付款

✓
促进金融流程数字化，现代化客户关系

✓
为商家和最终客户简化操作

✓
基于 Pix 技术的自动扣款解决方案高效性

✓
填补传统支付工具的现有空白

---

## 场景模拟

在开发和测试与 Pix 自动扣款的集成过程中，在使用生产环境之前验证所有流程至关重要。**场景模拟**提供了一个完整的沙盒环境，允许测试循环扣款的整个生命周期，从创建到付款结算。

### 什么是场景模拟？

场景模拟是一个工具，允许在沙盒环境中**测试 Pix 自动扣款的完整流程**，模拟 SPI（即时支付系统）的响应，而不进行真实交易。它涵盖：

- **创建和审批循环扣款**，使用4种可用流程
- **处理付款订单**和创建对账批次
- **模拟付款尝试**，结果各异（成功或拒绝）
- **测试取消流程**和循环扣款管理

### 何时使用？

建议在以下情况下使用模拟：

- **集成验证**：测试您的应用程序是否正确集成了 API
- **开发**：免费开发和调试您的实现
- **流程测试**：验证不同场景（付款成功、拒绝、取消）
- **培训**：在投入生产前，让团队熟悉 Pix 自动扣款流程

### 如何使用？

模拟过程遵循一系列步骤，复制真实流程：

1. **创建循环扣款**，使用授权流程之一
2. **通过模拟审批循环扣款**，模拟付款人确认
3. **处理付款订单**，自动创建对账批次
4. **查询和对账**订单（可变金额必须进行）
5. **更新执行日期**，加速沙盒测试
6. **处理付款尝试**
7. **模拟结果**：入账 Pix（成功）或拒绝

:::tip 完整文档
有关如何使用场景模拟的详细分步指南，包括所有可用端点和请求示例，请参阅：

**[📋 场景模拟指南](./recebedor/simulacao.md)**
:::

### 模拟的好处

✓
在受控隔离环境中进行无成本、无风险的测试

✓
投入生产前对所有流程进行完整验证

✓
加速日期和流程，实现更快测试

✓
模拟不同场景（成功、失败、取消）

---

# 接受定期付款

URL: /zh-Hans/documentation/baas/pix_automatico/movimentacoes/aceitar_recorrencia

## 请求

ENDPOINT /account/ ACCOUNT_KEY /incoming_recurrence/ INCOMING_RECURRENCE_KEY /approve
方法 PATCH

### 请求 Path Params

| 字段                        | 类型  | 描述                         | 字符数 |
|-----------------------------|-------|------------------------------|--------|
| `account_key` *             | uuid4 | 账户的唯一标识键。           | 36     |
| `incoming_recurrence_key` * | uuid4 | 授权的唯一标识键。           | 36     |

### Request Body

Request Body: 批准固定金额定期付款

```json
{
  "incoming_recurrence_status": "active"
}
```

Request Body: 批准带最大限额的可变金额定期付款

```json
{
  "incoming_recurrence_status": "active",
  "maximum_transaction_amount": 500.00
}
```

### Body Params

| 字段                           | 类型   | 描述                                                                                              | 字符数 |
|--------------------------------|--------|---------------------------------------------------------------------------------------------------|--------|
| `incoming_recurrence_status` * | string | Pix 定期付款的状态标识符。必须为 "active" 才能激活定期付款。                                     | 20     |
| `maximum_transaction_amount`   | number | 用户每笔交易接受支付的最大金额（可选，仅适用于可变金额定期付款）。                               | 10     |

:::info 可变定期付款的最大金额
`maximum_transaction_amount` 字段是**可选的**，仅应用于**可变金额定期付款**。它允许付款方设定在授权的定期付款中每笔交易愿意支付的最大金额。
:::
## 响应

STATUS 200

Response Body: 定期付款已激活

```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"
}
```

| HTTP 状态码 | QI 代码<br/>`code` | 标题<br/>`title`                             | 描述（英文）<br/>`Description`                                        | 描述（葡文）<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                        |

---

# 取消定期付款

URL: /zh-Hans/documentation/baas/pix_automatico/movimentacoes/cancelar_recorrencia

## 请求

ENDPOINT /account/ ACCOUNT_KEY /incoming_recurrence/ INCOMING_RECURRENCE_KEY /cancel
方法 PATCH

### 请求 Path Params

| 字段                        | 类型  | 描述                         | 字符数 |
|-----------------------------|-------|------------------------------|--------|
| `account_key` *             | uuid4 | 账户的唯一标识键。           | 36     |
| `incoming_recurrence_key` * | uuid4 | 授权的唯一标识键。           | 36     |

### Request Body

Request Body: 取消定期付款

```json
{
  "incoming_recurrence_status": "cancelled",
}
```

### Body Params

| 字段                           | 类型   | 描述                              | 字符数    |
|--------------------------------|--------|-----------------------------------|-----------|
| `incoming_recurrence_status` * | string | Pix 定期付款的状态标识符。        | cancelled |
## 响应

STATUS 200

Response Body: 定期付款已取消

```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"
}
```

| HTTP 状态码 | QI 代码<br/>`code` | 标题<br/>`title`                             | 描述（英文）<br/>`Description`                                        | 描述（葡文）<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                        |

---

# 查询定期付款

URL: /zh-Hans/documentation/baas/pix_automatico/movimentacoes/consultar_recorrencia

## 通过 incoming_recurrency_key 查询 Pix 定期付款

### 请求

ENDPOINT /account/ ACCOUNT_KEY /incoming_recurrence/ INCOMING_RECURRENCE_KEY
方法 GET

### Path Params

| 字段                        | 类型  | 描述                                    | 字符数 |
|-----------------------------|-------|-----------------------------------------|--------|
| `account_key` *             | uuid4 | QI 账户的唯一标识键。                   | 36     |
| `incoming_recurrency_key` * | uuid4 | Pix 自动定期付款的唯一标识键。          | 36     |

### 响应

STATUS 200

Response Body: 查询定期付款

```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",
}

```

| 字段                           | 类型       | 描述                                                                                                                    | 最大字符数                                                                    |
|--------------------------------|------------|-------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------|
| `incoming_recurrence_key`      | uuid4      | 授权的唯一标识键。                                                                                                      | 36                                                                            |
| `incoming_recurrence_status`   | string     | 定期付款状态标识符。                                                                                                    | [Enumerador incoming_recurrence_status](#enumerador-incoming_recurrence_status)|
| `request_control_key`          | uuid4      | 客户端使用的请求唯一标识键。                                                                                            | 36                                                                            |
| `transaction_amount`           | number     | 固定金额定期付款的转账金额。                                                                                            | 10                                                                            |
| `minimum_transaction_amount`   | number     | 可变金额定期付款的最低转账金额。                                                                                        | 10                                                                            |
| `maximum_transaction_amount`   | number     | 可变金额定期付款的最高转账金额。                                                                                        | 10                                                                            |
| `periodicity`                  | enumerator | 与付款关联的周期类型。                                                                                                  | [Enumeradores periodicity](#enumeradores-periodicity)                         |
| `journey_type`                 | enumerator | 请求旅程类型。                                                                                                          | [Enumeradores journey_type](#enumeradores-journey_type)                       |
| `pix_transfer_type`            | enumerator | 要执行的 Pix 类型。                                                                                                     | [Enumeradores pix_transfer_type](#enumeradores-pix_transfer_type)             |
| `end_to_end_id`                | string     | SPI（即时支付系统）内 Pix 交易的幂等键。该键在 Pix 键查询中返回。                                                      | 32                                                                            |
| `start_date`                   | string     | 定期付款开始日期。                                                                                                      | -                                                                             |
| `end_date`                     | string     | 定期付款结束日期，对于无限期情况发送 null。                                                                             |                                                                               |
| `next_execution_date`          | string     | 定期付款下次交易的执行日期。                                                                                            | -                                                                             |
| `receiver_conciliation_id`     | string     | 接收方对账标识。                                                                                                        | 35                                                                            |
| `target_pix_key`               | string     | 交易账户的 Pix 键。                                                                                                     | 100                                                                           |
| `payer_document_number`        | string     | 交易付款人的文件编号。                                                                                                  | 14                                                                            |
| `pix_message`                  | string     | 随 Pix 转账一起发送的消息。                                                                                             | 140                                                                           |
| `created_at`                   | string     | 定期付款请求的创建时间。                                                                                                | -                                                                             |
| `updated_at`                   | string     | 定期付款请求的更新时间。                                                                                                | -                                                                             |

### Enumerador incoming_recurrence_status

| 枚举值                  | 描述                   |
|-------------------------|------------------------|
| `pending_confirmation`  | 定期付款待确认         |
| `active`                | 定期付款已激活         |
| `cancelled`             | 定期付款已取消         |
| `suspended`             | 定期付款已暂停         |
| `expired`               | 定期付款已到期         |

### Enumeradores periodicity
| 枚举值        | 描述     |
|---------------|----------|
| `weekly`      | 每周定期 |
| `monthly`     | 每月定期 |
| `quarterly`   | 每季定期 |
| `semiannual`  | 每半年定期|
| `annual`      | 每年定期 |

### Enumeradores journey_type
| 枚举值          | 描述                                           |
|-----------------|------------------------------------------------|
| `journey_one`   | 通过应用内通知申请授权                         |
| `jouney_two`    | 通过扫描 QR 码申请授权                         |
| `journey_three` | 通过扫描 QR 码进行即时 Pix 付款来授权定期付款 |
| `journey_four`  | 付款或调度 Pix 后依次申请定期付款授权          |

### Enumeradores pix_transfer_type

| 枚举值              | 描述                     |
|---------------------|--------------------------|
| `manual`            | 使用目标账户数据的 Pix   |
| `key`               | 使用 Pix 键的 Pix        |
| `static_qr_code`    | 使用静态 QR 码的 Pix     |
| `dynamic_qr_code`   | 使用动态 QR 码的 Pix     |

STATUS 4xx

Response Body: Error

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

| HTTP 状态码 | QI 代码<br/>`code` | 标题<br/>`title`                             | 描述（英文）<br/>`Description`                                        | 描述（葡文）<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                        |

---

# 创建定期付款

URL: /zh-Hans/documentation/baas/pix_automatico/movimentacoes/criar_recorrencia

## 请求

ENDPOINT /account/ ACCOUNT_KEY /incoming_recurrence
方法 POST

### 请求 Path Params

| 字段            | 类型  | 描述                 | 字符数 |
|-----------------|-------|----------------------|--------|
| `account_key` * | uuid4 | 账户的唯一标识键。   | 36     |

### Request Body

Request Body: 创建固定金额定期付款

```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: 创建可变金额定期付款

```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

| 字段                          | 类型       | 描述                                                                                                                    | 字符数 |
|-------------------------------|------------|-------------------------------------------------------------------------------------------------------------------------|--------|
| `request_control_key` *       | uuid       | 客户端使用的 uuid4 格式请求唯一标识键。                                                                                 | 36     |
| `periodicity` *               | enumerator | 与付款关联的周期类型。                                                                                                  | [Enumeradores periodicity](#enumeradores-periodicity)     |
| `journey_type` *              | enumerator | 请求旅程类型。                                                                                                          | [Enumeradores journey_type](#enumeradores-journey_type)   |
| `start_date` *                | string     | 定期付款开始日期。                                                                                                      | -      |
| `end_to_end_id` *             | string     | SPI（即时支付系统）内 Pix 交易的幂等键。该键在 Pix 键查询中返回。                                                      | 32     |
| `target_pix_key`              | string     | 接收交易的账户 Pix 键。                                                                                                 | 100    |
| `target_account`              | Object     | 目标账户 - 仅用于手动转账。                                                                                             | [Objeto target_account](#objeto-target_account) |
| `transaction_amount`          | number     | 固定金额定期付款的转账金额。                                                                                            | 10     |
| `minimum_transaction_amount`  | number     | 可变金额定期付款的最低转账金额。                                                                                        | 10     |
| `maximum_transaction_amount`  | number     | 可变金额定期付款的最高转账金额。                                                                                        | 10     |
| `end_date`                    | string     | 定期付款结束日期，对于无限期情况发送 null。                                                                             | -      |
| `pix_message`                 | string     | 随 Pix 转账一起发送的消息。                                                                                             | 140    |
| `is_retry_allowed`            | boolean    | 是否允许 Pix 交易重试。                                                                                                 | -      |

### Enumeradores periodicity
| 枚举值        | 描述     |
|---------------|----------|
| `weekly`      | 每周定期 |
| `monthly`     | 每月定期 |
| `quarterly`   | 每季定期 |
| `semiannual`  | 每半年定期|
| `annual`      | 每年定期 |

### Enumeradores journey_type
| 枚举值          | 描述                                           |
|-----------------|------------------------------------------------|
| `journey_one`   | 通过应用内通知申请授权                         |
| `journey_two`   | 通过扫描 QR 码申请授权                         |
| `journey_three` | 通过扫描 QR 码进行即时 Pix 付款来授权定期付款 |
| `journey_four`  | 付款或调度 Pix 后依次申请定期付款授权          |

### Objeto target_account

| 字段                      | 类型       | 描述                                     | 字符数                                                  |
|---------------------------|------------|------------------------------------------|---------------------------------------------------------|
| `account_branch`          | string     | 账户支行。                               | 6                                                       |
| `account_digit`           | string     | 账户校验位。                             | 1                                                       |
| `account_number`          | string     | 账户号码。                               | 20                                                      |
| `owner_document_number`   | string     | 账户持有人的 CPF 或 CNPJ（仅数字）。    | 14                                                      |
| `owner_name`              | string     | 账户持有人姓名。                         | 150                                                     |
| `account_type`            | enumerator | 账户类型。                               | [Enumerador account_type](#enumerador-account_type)     |
| `ispb`                    | string     | 基于金融机构 CNPJ 的代码（8位数字）。   | 8                                                       |

:::info
由于不同机构返回的信息不同，不同的枚举值可能表示同一种账户类型。
:::
### Enumerador account_type

| 枚举值             | 描述       |
|--------------------|------------|
| `checking_account` | 支票账户   |
| `salary_account`   | 工资账户   |
| `saving_account`   | 储蓄账户   |
| `payment_account`  | 支付账户   |

## 响应

STATUS 200

Response Body: 定期付款已创建

```json
{
  "incoming_recurrence_key": "cfa32109-a6dd-4304-94db-03a7b6d92a47",
  "incoming_recurrence_status": "pending_confirmation",
  "created_at": "2025-05-22T20:30:23.459Z",
}
```

| 字段                           | 类型    | 描述                               | 最大字符数                                                                     |
|--------------------------------|---------|------------------------------------|--------------------------------------------------------------------------------|
| `incoming_recurrence_key`      | uuid    | 授权的唯一标识键。                 | 36                                                                             |
| `incoming_recurrence_status`   | string  | 定期付款状态标识符。               | [Enumerador incoming_recurrence_status](#enumerador-incoming_recurrence_status)|
| `created_at`                   | string  | 定期付款请求的创建时间。           | -                                                                              |

### Enumerador incoming_recurrence_status

| 枚举值                   | 描述                   |
|--------------------------|------------------------|
| **pending_confirmation** | 定期付款待确认         |
| **active**               | 定期付款已激活         |
| **cancelled**            | 定期付款已取消         |
| **suspended**            | 定期付款已暂停         |
| **expired**              | 定期付款已到期         |

STATUS 4XX

Response Body

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

| HTTP 状态码 | QI 代码<br/>`code` | 标题<br/>`title`                             | 描述（英文）<br/>`Description`                                                                                   | 描述（葡文）<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                                     |

---

# 定期付款列表

URL: /zh-Hans/documentation/baas/pix_automatico/movimentacoes/listar_recorrencias

## 列出账户的 Pix 定期付款

### 请求

ENDPOINT /account/ ACCOUNT_KEY /incoming_recurrences
方法 GET

### Path Params

| 字段            | 类型  | 描述                       | 字符数 |
|-----------------|-------|----------------------------|--------|
| `account_key` * | uuid4 | QI 账户的唯一标识键。      | 36     |

### Query Params

| 字段                   | 类型   | 描述                              | 字符数                                          |
|------------------------|--------|-----------------------------------|-------------------------------------------------|
| `request_control_key`  | uuid4  | 客户端使用的请求唯一标识键。      | 36                                              |
| `status`               | string | Pix 定期付款状态标识符。          | [Enumerador status](#enumerador-status)         |
| `date_from`            | string | 列表筛选的开始日期。              | "YYYY-MM-DD" 格式                               |
| `date_to`              | string | 列表筛选的结束日期。              | "YYYY-MM-DD" 格式                               |
| `page`                 | integer| 请求的页码。                      | 默认 1                                          |
| `page_size`            | integer| 查询中请求的每页大小。            | 默认值和最大值均为 30                           |

### Enumerador status

| 枚举值                  | 描述               |
|-------------------------|--------------------|
| `pending_confirmation`  | 定期付款待确认     |
| `active`                | 定期付款已激活     |
| `cancelled`             | 定期付款已取消     |
| `suspended`             | 定期付款已暂停     |
| `expired`               | 定期付款已到期     |

### 响应

STATUS 200

Response Body: 定期付款列表

```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": {}
}
```

| HTTP 状态码 | QI 代码<br/>`code` | 标题<br/>`title`                             | 描述（英文）<br/>`Description`                                        | 描述（葡文）<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.                                         |

---

# 场景模拟

URL: /zh-Hans/documentation/baas/pix_automatico/movimentacoes/simulacao

在 PIX 自动支付框架内模拟创建定期付款和自动付款的分步说明。这些模拟包括创建定期付款和创建预定付款。

## 1 - 模拟创建定期付款

### 请求

ENDPOINT /mock/incoming_recurrence
方法 POST

Request Body: 固定金额定期付款

```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: 可变金额定期付款

```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"}
```

### Request Body 对象

| 字段                            | 类型           | 描述                                                         | 最大字符数 |
|---------------------------------|----------------|--------------------------------------------------------------|------------|
| **request_control_key***        | string         | uuid4 格式的请求唯一标识键。                                | 36         |
| **recurrence_type***            | string         | 定期付款类型（fixed_amount 或 variable_amount）。            | 20         |
| **transaction_amount**          | number, null   | 固定金额定期付款（fixed_amount）的交易金额。                | 10         |
| **minimum_transaction_amount**  | number, null   | 可变金额定期付款（variable_amount）的最低交易金额。         | 10         |
| **periodicity***                | string         | 定期付款的周期。                                             | 20         |
| **journey_type***               | string         | 授权旅程类型。                                               | 50         |
| **start_date***                 | string         | 定期付款开始日期（YYYY-MM-DD 格式）。                       | 10         |
| **end_date**                    | string, null   | 定期付款结束日期（YYYY-MM-DD 格式）。                       | 10         |
| **is_retry_allowed***           | boolean        | 是否允许交易重试。                                           | -          |
| **payer_account_information***  | object         | 付款方账户数据。                                             | -          |
| **pix_message**                 | string, null   | 与交易关联的 PIX 消息。                                     | 140        |

:::caution 注意
`transaction_amount` 或 `minimum_transaction_amount` 中至少有一个字段必须提供非空值。两个字段不能同时为空。
:::

### payer_account_information 对象

| 字段                    | 类型   | 描述                                     | 最大字符数 |
|-------------------------|--------|------------------------------------------|------------|
| **owner_name***         | string | 账户持有人姓名。                         | 150        |
| **document_number***    | string | 账户持有人的 CPF 或 CNPJ（仅数字）。    | 14         |
| **ispb***               | string | 金融机构 ISPB 代码。                     | 8          |
| **account_digit***      | string | 账户校验位。                             | 1          |
| **account_branch***     | string | 账户支行。                               | 6          |
| **account_number***     | string | 账户号码。                               | 20         |

:::info 定期付款类型
- **固定金额定期付款（fixed_amount）**：使用 `transaction_amount` 字段，不发送 `minimum_transaction_amount`。
- **可变金额定期付款（variable_amount）**：使用 `minimum_transaction_amount` 字段，不发送 `transaction_amount`。
:::

## 响应

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

| 字段                           | 类型       | 描述                                                         | 字符数 |
|--------------------------------|------------|--------------------------------------------------------------|--------|
| `incoming_recurrence_key`      | uuid       | 入账定期付款的唯一标识键。                                   | 36     |
| `incoming_recurrence_spi_id`   | string     | 入账定期付款的 SPI 标识符。                                  | 29     |
| `incoming_recurrence_status`   | enumerator | 入账定期付款的当前状态。                                     | [Enumeradores incoming_recurrence_status](#enumeradores-incoming_recurrence_status) |
| `created_at`                   | string     | 定期付款创建的日期和时间（ISO 8601 格式）。                  | -      |
| `account_key`                  | uuid       | 账户的唯一标识键。                                           | 36     |

### Enumeradores incoming_recurrence_status

| 枚举值                  | 描述               |
|-------------------------|--------------------|
| `pending_confirmation`  | 定期付款待确认     |
| `active`                | 定期付款已激活     |
| `cancelled`             | 定期付款已取消     |
| `suspended`             | 定期付款已暂停     |
| `expired`               | 定期付款已到期     |

## 2 - 模拟创建付款

### 请求

ENDPOINT /mock/incoming_recurrence/ INCOMING_RECURRENCE_SPI_ID /outgoing_payment
方法 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"
}
```

### Request Body 对象

| 字段                          | 类型   | 描述                                      | 最大字符数 |
|-------------------------------|--------|-------------------------------------------|------------|
| **transaction_amount***       | number | 交易金额。                                | 10         |
| **target_account_data**       | object | 目标账户数据。                            | -          |
| **receiver_conciliation_id*** | string | 接收方对账标识。                          | 35         |
| **outgoing_payment_spi_id***  | string | 付款 SPI 标识符。                         | 20         |
| **end_to_end_id***            | string | SPI 中 PIX 交易的幂等键。                | 32         |
| **next_execution_datetime**   | string | 下次执行的日期和时间（YYYY-MM-DD 格式）。 | 10         |

### target_account_data 对象

| 字段                        | 类型   | 描述                                     | 最大字符数 |
|-----------------------------|--------|------------------------------------------|------------|
| **owner_name***             | string | 账户持有人姓名。                         | 150        |
| **owner_document_number***  | string | 账户持有人的 CPF 或 CNPJ（仅数字）。    | 14         |
| **ispb_number***            | string | 金融机构 ISPB 代码。                     | 8          |
| **account_digit***          | string | 账户校验位。                             | 1          |
| **account_branch***         | string | 账户支行。                               | 6          |
| **account_type***           | string | 账户类型。                               | 20         |
| **account_number***         | string | 账户号码。                               | 20         |

### Enumerador account_type

| 枚举值               | 描述       |
|----------------------|------------|
| **checking_account** | 支票账户   |
| **salary_account**   | 工资账户   |
| **saving_account**   | 储蓄账户   |
| **payment_account**  | 支付账户   |

### Enumeradores periodicity

| 枚举值         | 描述       |
|----------------|------------|
| **weekly**     | 每周定期   |
| **monthly**    | 每月定期   |
| **quarterly**  | 每季定期   |
| **semiannual** | 每半年定期 |
| **annual**     | 每年定期   |

### Enumeradores journey_type

| 枚举值             | 描述                                           |
|--------------------|------------------------------------------------|
| **journey_one**    | 通过应用内通知申请授权                         |
| **journey_two**    | 通过扫描 QR 码申请授权                         |
| **journey_three**  | 通过扫描 QR 码进行即时 Pix 付款来授权定期付款 |
| **journey_four**   | 付款或调度 Pix 后依次申请定期付款授权          |

---

# Webhooks

URL: /zh-Hans/documentation/baas/pix_automatico/movimentacoes/webhooks

由于转账以异步方式进行，正确映射和处理发送的 Webhooks 至关重要。

:::danger 注意！
QI Tech 的 Webhooks 不应以限制性方式映射。
我们 API 返回的 Webhook 载荷中可能会添加额外字段。
:::

## Pix 自动定期付款创建 Webhook  

包含客户定期付款创建信息的 Webhook。

### Webhook Request Body

Request Body: 创建定期付款

```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
| 字段                           | 类型      | 描述                                                                                    | 最大字符数 |
|--------------------------------|-----------|-----------------------------------------------------------------------------------------|------------|
| `webhook_type`                 | string    | 定义报告事件类型的枚举值。                                                              | 23         |
| `webhook_datetime`             | string    | Webhook 发送日期和时间。                                                                | 20         |
| `account_key`                  | uuid4     | 账户的唯一标识键。                                                                      | 36         |
| `incoming_recurrence_key`      | uuid4     | 授权的唯一标识键。                                                                      | 36         |
| `incoming_recurrence_status`   | string    | Pix 定期付款状态标识符。                                                                | [Enumeradores incoming_recurrence_status](#enumeradores-incoming_recurrence_status) |
| `transaction_amount`           | number    | 固定金额定期付款的转账金额。                                                            | 10         |
| `minimum_transaction_amount`   | number    | 可变金额定期付款的最低转账金额。                                                        | 10         |
| `maximum_transaction_amount`   | number    | 可变金额定期付款的最高转账金额。                                                        | 10         |
| `periodicity`                  | enum      | 与付款关联的周期类型。                                                                  | [Enumeradores periodicity](#enumeradores-periodicity) |
| `journey_type`                 | enum      | 请求旅程类型。                                                                          | [Enumeradores journey_type](#enumeradores-journey_type) |
| `pix_transfer_type`            | enum      | 要执行的 Pix 类型。                                                                     | [Enumeradores pix_transfer_type](#enumeradores-pix_transfer_type) |
| `end_to_end_id`                | string    | SPI 内 Pix 交易的幂等键。                                                               | 32         |
| `start_date`                   | string    | 定期付款开始日期。                                                                      | -          |
| `end_date`                     | string    | 定期付款结束日期，对于无限期情况发送 null。                                             | -          |
| `receiver_conciliation_id`     | string    | 接收方对账标识。                                                                        | 35         |
| `target_pix_key`               | string    | 交易账户的 Pix 键。                                                                     | 100        |
| `payer_document_number`        | string    | 交易付款人的文件编号。                                                                  | 14         |
| `pix_message`                  | string    | 随 Pix 转账一起发送的消息。                                                             | 140        |
| `created_at`                   | string    | 定期付款请求的创建时间。                                                                | -          |
| `updated_at`                   | string    | 定期付款请求的更新时间。                                                                | -          |

### Enumerador incoming_recurrence_status

| 枚举值                  | 描述               |
|-------------------------|--------------------|
| `pending_confirmation`  | 定期付款待确认     |
| `active`                | 定期付款已激活     |
| `cancelled`             | 定期付款已取消     |
| `suspended`             | 定期付款已暂停     |
| `expired`               | 定期付款已到期     |

### Enumeradores periodicity
| 枚举值        | 描述     |
|---------------|----------|
| `weekly`      | 每周定期 |
| `monthly`     | 每月定期 |
| `quarterly`   | 每季定期 |
| `semiannual`  | 每半年定期|
| `annual`      | 每年定期 |

### Enumeradores journey_type
| 枚举值          | 描述                                           |
|-----------------|------------------------------------------------|
| `journey_one`   | 通过应用内通知申请授权                         |
| `journey_two`   | 通过扫描 QR 码申请授权                         |
| `journey_three` | 通过扫描 QR 码进行即时 Pix 付款来授权定期付款 |
| `journey_four`  | 付款或调度 Pix 后依次申请定期付款授权          |

### Enumeradores pix_transfer_type

| 枚举值              | 描述                     |
|---------------------|--------------------------|
| `manual`            | 使用目标账户数据的 Pix   |
| `key`               | 使用 Pix 键的 Pix        |
| `static_qr_code`    | 使用静态 QR 码的 Pix     |
| `dynamic_qr_code`   | 使用动态 QR 码的 Pix     |

[//]: # (Break here for new page -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------)

---

# 更新付款订单金额

URL: /zh-Hans/documentation/baas/pix_automatico/pagamentos/atualizar_payment_order

## 请求

ENDPOINT /account/ ACCOUNT_KEY /outgoing_recurrence/ OUTGOING_RECURRENCE_KEY /payment_order/ PAYMENT_ORDER_KEY
方法 PATCH

### Path Params

| 字段                      | 类型   | 描述                         | 字符数 |
|---------------------------|--------|------------------------------|--------|
| `ACCOUNT_KEY`             | uuidv4 | 账户的唯一标识键。           | 36     |
| `OUTGOING_RECURRENCE_KEY` | uuidv4 | 待更新的定期付款唯一键。     | 36     |
| `PAYMENT_ORDER_KEY`       | uuidv4 | 待更新的付款订单唯一键。     | 36     |

### Request Body

更新 Payment Order

```json
{
    "transaction_amount": 100
}
```

### Request Body Params

| 字段                 | 类型     | 描述                 | 字符数 |
|----------------------|----------|----------------------|--------|
| `transaction_amount` | floating | 待更新的交易金额。   | -      |

## 响应

STATUS 200

Response Body

```json
{}
```

STATUS 4XX

Response Error

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

| HTTP 状态码 | QI 代码<br/>`code` | 标题<br/>`title`        | 描述（英文）<br/>`description`                             | 描述（葡文）<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.         |

---

# 取消付款订单

URL: /zh-Hans/documentation/baas/pix_automatico/pagamentos/cancelar_payment_order

此端点允许取消与 Pix 自动定期付款关联的特定付款订单。

:::warning
只能取消状态为 pending_conciliation 或 pending 的付款订单，且必须在 reference_date 前一天的 22 时之前完成。
:::

## 请求

ENDPOINT /automatic_pix/account/ ACCOUNT_KEY /outgoing_recurrence/ OUTGOING_RECURRENCE_KEY /payment_order/ PAYMENT_ORDER_KEY /cancel
方法 PATCH

### Path Params

| 字段                      | 类型   | 描述                         | 字符数 |
|---------------------------|--------|------------------------------|--------|
| `ACCOUNT_KEY`             | uuidv4 | 账户的唯一标识键。           | 36     |
| `OUTGOING_RECURRENCE_KEY` | uuidv4 | 定期付款的唯一键。           | 36     |
| `PAYMENT_ORDER_KEY`       | uuidv4 | 待取消的付款订单唯一键。     | 36     |

### Request Body

取消 Payment Order

```json
{}
```

## 响应

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

| 字段                                    | 类型   | 描述                         | 字符数 |
|-----------------------------------------|--------|------------------------------|--------|
| `payment_order_key`                     | string | 付款订单的唯一键。           | 36     |
| `payment_order_conciliation_batch_key`  | string | 付款订单对账批次键。         | 36     |
| `payment_order_status`                  | string | 付款订单的当前状态。         | -      |

### Enumeradores payment_order_status

| 枚举值                 | 描述                   |
|------------------------|------------------------|
| `pending_conciliation` | 等待对账。             |
| `pending`              | 待处理，尚未处理。     |
| `accepted`             | 已接受，等待付款。     |
| `paid`                 | 成功付款。             |
| `rejected`             | 已拒绝，不会处理。     |
| `cancelled`            | 付款前已取消。         |

STATUS 4XX

Response Error

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

| HTTP 状态码 | QI 代码<br/>`code` | 标题<br/>`title`        | 描述（英文）<br/>`description`                             | 描述（葡文）<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.         |

---

# 查询 Payment Order

URL: /zh-Hans/documentation/baas/pix_automatico/pagamentos/consultar_payment_order

## 请求

此端点允许查询与 Pix 自动定期付款关联的特定付款订单的详细信息。

ENDPOINT /account/ ACCOUNT_KEY /outgoing_recurrence/ OUTGOING_RECURRENCE_KEY /payment_order/ PAYMENT_ORDER_KEY
方法 GET

### Path Params

| 字段                      | 类型   | 描述                         | 字符数 |
|---------------------------|--------|------------------------------|--------|
| `account_key`             | uuidv4 | 账户的唯一标识键。           | 36     |
| `outgoing_recurrence_key` | uuidv4 | 待查询的定期付款唯一键。     | 36     |
| `payment_order_key`       | uuidv4 | 待查询的付款订单唯一键。     | 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

| 字段                                    | 类型     | 描述                                 | 字符数 |
|-----------------------------------------|----------|--------------------------------------|--------|
| `outgoing_recurrence_spi_id`            | string   | 自动定期付款的 SPI ID。              | 36     |
| `payment_order_status`                  | string   | 付款订单的当前状态。                 | [Enumeradores payment_order_status](#payment_order_status) |
| `reference_date`                        | string   | 收费参考日期。                       | 10     |
| `payment_order_conciliation_batch_key`  | uuidv4   | 付款订单对账批次键。                 | 36     |
| `receiver_conciliation_id`              | uuidv4   | 接收方对账 ID。                      | 36     |
| `transaction_amount`                    | number   | 交易金额。                           | -      |
| `transaction_key`                       | uuidv4   | 交易唯一键。                         | 36     |
| `incoming_pix_transfer_key`             | uuidv4   | 收到的 Pix 转账键。                  | 36     |
| `debtor_account_data`                   | object   | 债务人账户数据。                     | [Objeto debtor_account_data](#objeto-debtor_account_data) |
| `created_at`                            | string   | 订单创建日期/时间。                  | -      |
| `paid_at`                               | string   | 付款日期/时间。                      | -      |
| `payment_order_attempts`                | array    | 订单的付款尝试记录。                 | [Array payment_order_attempts](#array-payment_order_attempts) |

### Objeto debtor_account_data

| 字段             | 类型   | 描述                 | 字符数 |
|------------------|--------|----------------------|--------|
| `account_number` | string | 账户号码。           | -      |
| `account_digit`  | string | 账户校验位。         | -      |
| `account_branch` | string | 支行。               | -      |
| `ispb`           | string | 金融机构 ISPB。      | -      |

### Array payment_order_attempts

| 字段                          | 类型     | 描述                           | 字符数 |
|-------------------------------|----------|--------------------------------|--------|
| `payment_order_attempt_key`   | string   | 付款尝试的唯一键。             | 36     |
| `end_to_end_id`               | string   | 尝试的端到端标识符。           | 36     |
| `payment_order_attempt_status`| string   | 付款尝试状态。                 | -      |
| `payment_order_attempt_error` | object   | 与付款尝试关联的错误。         | [Objeto payment_order_attempt_error](#objeto-payment_order_attempt_error) |
| `created_at`                  | string   | 尝试创建日期/时间。            | -      |

### Objeto payment_order_attempt_error

| 字段          | 类型   | 描述             | 字符数 |
|---------------|--------|------------------|--------|
| `code`        | string | 错误代码。       | -      |
| `description` | string | 错误描述。       | -      |
| `translation` | string | 描述的翻译。     | -      |

### Enumeradores payment_order_status

| 枚举值                 | 描述                   |
|------------------------|------------------------|
| `pending_conciliation` | 等待对账。             |
| `pending`              | 待处理，尚未处理。     |
| `accepted`             | 已接受，等待付款。     |
| `paid`                 | 成功付款。             |
| `rejected`             | 已拒绝，不会处理。     |
| `cancelled`            | 付款前已取消。         |

STATUS 4XX

Response Error

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

| HTTP 状态码 | QI 代码<br/>`code` | 标题<br/>`title`        | 描述（英文）<br/>`description`                             | 描述（葡文）<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.          |

---

# 按账户列出 Payment Orders

URL: /zh-Hans/documentation/baas/pix_automatico/pagamentos/listar_account_payment_orders

此端点允许列出与特定账户关联的付款订单。

ENDPOINT /account/ ACCOUNT_KEY /payment_orders
方法 GET

### Path Params

| 字段          | 类型   | 描述                     | 字符数 |
|---------------|--------|--------------------------|--------|
| `account_key` | uuidv4 | 账户的唯一标识键。       | 36     |

### Query Params

| 字段                  | 类型   | 描述                                              | 字符数 |
|-----------------------|--------|---------------------------------------------------|--------|
| `payment_order_status`| string | 按状态筛选订单（如 `paid`）。                     | -      |
| `start_date`          | string | 筛选订单的开始日期（YYYY-MM-DD 格式）。           | 10     |
| `end_date`            | string | 筛选订单的结束日期（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

| 字段                                    | 类型     | 描述                                                   | 字符数 |
|-----------------------------------------|----------|--------------------------------------------------------|--------|
| `payment_order_key`                     | uuidv4   | 付款订单的唯一键。                                     | 36     |
| `payment_order_spi_id`                  | string   | 付款订单的 SPI ID。                                    | 32     |
| `outgoing_recurrence_key`               | uuidv4   | 出账定期付款的唯一键。                                 | 36     |
| `outgoing_recurrence_spi_id`            | string   | 自动定期付款的 SPI ID。                               | 27     |
| `payment_order_conciliation_batch_key`  | uuidv4   | 付款订单对账批次键。                                   | 36     |
| `payment_order_status`                  | string   | 付款订单的当前状态。                                   | -      |
| `reference_date`                        | string   | 收费参考日期。                                         | 10     |
| `receiver_conciliation_id`              | string   | 接收方对账 ID。                                        | 32     |
| `transaction_amount`                    | number   | 交易金额（可以为 null）。                              | -      |
| `account_key`                           | uuidv4   | 账户的唯一键。                                         | 36     |
| `transaction_key`                       | uuidv4   | 交易唯一键（可以为 null）。                            | 36     |
| `incoming_pix_transfer_key`             | uuidv4   | 收到的 Pix 转账键（可以为 null）。                    | 36     |
| `debtor_account_data`                   | object   | 债务人账户数据。                                       | [Objeto debtor_account_data](#objeto-debtor_account_data) |
| `created_at`                            | string   | 订单创建日期/时间（ISO 8601 格式）。                   | -      |
| `paid_at`                               | string   | 付款日期/时间（ISO 8601 格式，可以为 null）。          | -      |
| `payment_order_attempts`                | array    | 订单的付款尝试记录。                                   | [Array payment_order_attempts](#array-payment_order_attempts) |

### Objeto debtor_account_data

| 字段             | 类型   | 描述                 | 字符数 |
|------------------|--------|----------------------|--------|
| `account_number` | string | 账户号码。           | -      |
| `account_digit`  | string | 账户校验位。         | -      |
| `account_branch` | string | 支行。               | -      |
| `ispb`           | string | 金融机构 ISPB。      | -      |

### Array payment_order_attempts

| 字段                          | 类型     | 描述                                     | 字符数 |
|-------------------------------|----------|------------------------------------------|--------|
| `payment_order_attempt_key`   | string   | 付款尝试的唯一键。                       | 36     |
| `end_to_end_id`               | string   | 尝试的端到端标识符。                     | 32     |
| `due_date`                    | string   | 尝试的到期日期（YYYY-MM-DD 格式，可为 null）。| 10 |
| `payment_order_attempt_status`| string   | 付款尝试状态。                           | -      |
| `payment_order_attempt_error` | object   | 与付款尝试关联的错误（可为 null）。      | [Objeto payment_order_attempt_error](#objeto-payment_order_attempt_error) |
| `sent_at`                     | string   | 尝试发送日期/时间（ISO 8601 格式，可为 null）。| - |
| `created_at`                  | string   | 尝试创建日期/时间（ISO 8601 格式）。     | -      |

### Objeto payment_order_attempt_error

| 字段          | 类型   | 描述             | 字符数 |
|---------------|--------|------------------|--------|
| `code`        | string | 错误代码。       | -      |
| `description` | string | 错误描述。       | -      |
| `translation` | string | 描述的翻译。     | -      |

### Enumeradores payment_order_status

| 枚举值                  | 描述                       |
|-------------------------|----------------------------|
| `pending_conciliation`  | 付款订单待对账。           |
| `pending`               | 付款订单待处理。           |
| `accepted`              | 付款订单已接受。           |
| `paid`                  | 付款订单已付款。           |
| `rejected`              | 付款订单已拒绝。           |
| `cancelled`             | 付款订单已取消。           |

STATUS 4XX

Response Error

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

| HTTP 状态码 | QI 代码<br/>`code` | 标题<br/>`title`        | 描述（英文）<br/>`description`                             | 描述（葡文）<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.          |

---

# 解码 Pix 自动支付 QR 码

URL: /zh-Hans/documentation/baas/pix_automatico/qr_code/decodificar_qr_code

## 请求

ENDPOINT /account/ ACCOUNT_KEY /qrcode/decode
方法 POST

### 请求 Path Params

| 字段            | 类型  | 描述                 | 字符数 |
|-----------------|-------|----------------------|--------|
| `account_key` * | uuid4 | 账户的唯一标识键。   | 36     |

### Request Body

Request Body: 解码 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

| 字段                 | 类型   | 描述                   | 字符数 |
|----------------------|--------|------------------------|--------|
| `qr_code_payload` *  | string | PIX 复制粘贴的 URL。   | -      |

## 响应

STATUS 200

Response Body: QR 码已解码

```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"
        }
    }
}
```

| 字段               | 类型   | 描述                                                                                  | 最大字符数 |
|--------------------|--------|---------------------------------------------------------------------------------------|------------|
| `end_to_end_id`    | string | SPI（即时支付系统）内 Pix 交易的幂等键。该键在 Pix 键查询中返回。                    | 32         |
| `qr_code_payload`  | string | PIX 复制粘贴的 URL。                                                                  | -          |
| `qr_code_key`      | uuid4  | QR 码的唯一标识键。                                                                   | 36         |
| `qr_code_data`     | Object | QR 码数据。                                                                           | [Objeto qr_code_data](#objeto-qr_code_data) |

### Objeto qr_code_data

| 字段                  | 类型   | 描述                                                                                    | 字符数 |
|-----------------------|--------|-----------------------------------------------------------------------------------------|--------|
| `incoming_recurrence` | objeto | 定期付款标识对象。                                                                      | [Objeto incoming_recurrence](#objeto-incoming_recurrence) |
| `payment_data`        | objeto | 付款信息对象，适用于 journey_types: *j3_payment_and_recurrence_qrcode*, *j4_recurrence_offer_post_payment*。 | [Objeto payment_data](#objeto-payment_data) |

### Objeto incoming_recurrence

| 字段                           | 类型       | 描述                                                                         | 字符数 |
|--------------------------------|------------|------------------------------------------------------------------------------|--------|
| `incoming_recurrence_key`      | uuid4      | 授权的唯一标识键。                                                           | 36     |
| `incoming_recurrence_status`   | string     | 定期付款状态标识符。                                                         | [Enumerador incoming_recurrence_status](#enumerador-incoming_recurrence_status) |
| `request_control_key`          | uuid4      | 客户端使用的请求唯一标识键。                                                 | 36     |
| `transaction_amount`           | number     | 固定金额定期付款的转账金额。                                                 | 10     |
| `minimum_transaction_amount`   | number     | 可变金额定期付款的最低转账金额。                                             | 10     |
| `maximum_transaction_amount`   | number     | 可变金额定期付款的最高转账金额。                                             | 10     |
| `periodicity`                  | enumerator | 与付款关联的周期类型。                                                       | [Enumeradores periodicity](#enumeradores-periodicity) |
| `journey_type`                 | enumerator | 请求旅程类型。                                                               | [Enumeradores journey_type](#enumeradores-journey_type) |
| `end_to_end_id`                | string     | SPI 内 Pix 交易的幂等键。该键在 Pix 键查询中返回。                          | 32     |
| `start_date`                   | string     | 定期付款开始日期。                                                           | -      |
| `end_date`                     | string     | 定期付款结束日期，对于无限期情况发送 null。                                  | -      |
| `next_execution_date`          | string     | 定期付款下次执行日期。                                                       | -      |
| `receiver_conciliation_id`     | string     | 接收方对账标识。                                                             | 35     |
| `target_pix_key`               | string     | 交易账户的 Pix 键。                                                          | 100    |
| `is_retry_allowed`             | boolean    | 是否允许 Pix 交易重试。                                                      | -      |
| `payer_document_number`        | string     | 交易付款人的文件编号。                                                       | 14     |
| `payer_name`                   | string     | 交易付款人姓名。                                                             | -      |
| `payer_account_key`            | string     | 交易付款人账户标识符。                                                       | -      |
| `pix_message`                  | string     | 随 Pix 转账一起发送的消息。                                                  | 140    |
| `created_at`                   | string     | 定期付款请求的创建时间。                                                     | -      |

### Objeto payment_data

| 字段                       | 类型   | 描述                                    | 字符数 |
|----------------------------|--------|-----------------------------------------|--------|
| `request_control_key`      | uuid4  | 客户端使用的请求唯一标识键。            | 36     |
| `transaction_amount`       | number | 固定金额定期付款的转账金额。            | 10     |
| `target_pix_key`           | string | 交易账户的 Pix 键。                     | 100    |
| `target_account`           | Object | 手动转账的目标账户。                    | [Objeto target_account](#objeto-target_account) |
| `receiver_conciliation_id` | string | 接收方对账标识。                        | 35     |
| `pix_message`              | string | 随 Pix 转账一起发送的消息。             | 140    |

### Objeto target_account

| 字段                      | 类型       | 描述                                     | 字符数 |
|---------------------------|------------|------------------------------------------|--------|
| `account_branch`          | string     | 账户支行。                               | 6      |
| `account_digit`           | string     | 账户校验位。                             | 1      |
| `account_number`          | string     | 账户号码。                               | 20     |
| `owner_document_number`   | string     | 账户持有人的 CPF 或 CNPJ（仅数字）。    | 14     |
| `owner_name`              | string     | 账户持有人姓名。                         | 150    |
| `account_type`            | enumerator | 账户类型。                               | [Enumerador account_type](#enumerador-account_type) |
| `ispb`                    | string     | 基于金融机构 CNPJ 的代码（8位数字）。   | 8      |

:::info
由于不同机构返回的信息不同，不同的枚举值可能表示同一种账户类型。
:::
### Enumerador account_type

| 枚举值             | 描述       |
|--------------------|------------|
| `checking_account` | 支票账户   |
| `salary_account`   | 工资账户   |
| `saving_account`   | 储蓄账户   |
| `payment_account`  | 支付账户   |

### Enumerador incoming_recurrence_status

| 枚举值                   | 描述                   |
|--------------------------|------------------------|
| **pending_confirmation** | 定期付款待确认         |
| **active**               | 定期付款已激活         |
| **cancelled**            | 定期付款已取消         |
| **suspended**            | 定期付款已暂停         |
| **expired**              | 定期付款已到期         |

### Enumeradores periodicity
| 枚举值        | 描述     |
|---------------|----------|
| `weekly`      | 每周定期 |
| `monthly`     | 每月定期 |
| `quarterly`   | 每季定期 |
| `semiannual`  | 每半年定期|
| `annual`      | 每年定期 |

### Enumeradores journey_type
| 枚举值                           | 描述                                           |
|----------------------------------|------------------------------------------------|
| `j1_in_app_only_recurrence`      | 通过应用内通知申请授权                         |
| `j2_recurrence_only_qrcode`      | 通过扫描 QR 码申请授权                         |
| `j3_payment_and_recurrence_qrcode` | 通过扫描 QR 码进行即时 Pix 付款来授权定期付款 |
| `j4_recurrence_offer_post_payment` | 付款或调度 Pix 后依次申请定期付款授权        |

### Enumeradores pix_transfer_type

| 枚举值              | 描述                     |
|---------------------|--------------------------|
| `manual`            | 使用目标账户数据的 Pix   |
| `key`               | 使用 Pix 键的 Pix        |
| `static_qr_code`    | 使用静态 QR 码的 Pix     |
| `dynamic_qr_code`   | 使用动态 QR 码的 Pix     |

STATUS 4XX

Response Body

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

| HTTP 状态码 | QI 代码<br/>`code` | 标题<br/>`title`                             | 描述（英文）<br/>`Description`                                        | 描述（葡文）<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.                                         |

---

# 取消定期付款

URL: /zh-Hans/documentation/baas/pix_automatico/recebedor/cancelar_recorrencia

## 请求

ENDPOINT /account/ ACCOUNT_KEY /outgoing_recurrence/ OUTGOING_RECURRENCE_KEY /cancel
方法 PATCH

### 请求 Path Params

| 字段                        | 类型  | 描述                         | 字符数 |
|-----------------------------|-------|------------------------------|--------|
| `account_key` *             | uuid4 | 账户的唯一标识键。           | 36     |
| `outgoing_recurrence_key` * | uuid4 | 授权的唯一标识键。           | 36     |

### Request Body

Request Body: 取消定期付款

```json
{
  "outgoing_recurrence_status": "cancelled",
}
```

### Body Params

| 字段                          | 类型   | 描述                     | 字符数    |
|-------------------------------|--------|--------------------------|-----------|
| `outgoing_recurrence_status` *| string | Pix 定期付款状态标识符。 | cancelled |
## 响应

STATUS 200

Response Body: 定期付款已取消

```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"
}
```

| HTTP 状态码 | QI 代码<br/>`code` | 标题<br/>`title`                             | 描述（英文）<br/>`Description`                                        | 描述（葡文）<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                        |

---

# 通过 outgoing_recurrence_key 查询定期付款数据

URL: /zh-Hans/documentation/baas/pix_automatico/recebedor/consultar_recorrencia

## 请求

ENDPOINT /account/ ACCOUNT_KEY /outgoing_recurrence/ OUTGOING_RECURRENCE_KEY
方法 GET

### Path Params

| 字段                        | 类型   | 描述                         | 字符数 |
|-----------------------------|--------|------------------------------|--------|
| `account_key` *             | uuidv4 | 账户的唯一标识键。           | 36     |
| `outgoing_recurrence_key` * | uuidv4 | 待查询的定期付款唯一键。     | 36     |

## 响应

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",
         "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

| 字段                           | 类型       | 描述                                                              | 字符数 |
|--------------------------------|------------|-------------------------------------------------------------------|--------|
| `request_control_key`          | uuidv4     | 请求控制的唯一键。                                                | 36     |
| `outgoing_recurrence_key`      | uuidv4     | 自动定期付款标识符。                                              | 36     |
| `outgoing_recurrence_status`   | string     | 定期付款的当前状态（`approved`、`pending`、`rejected` 等）。      | 30     |
| `periodicity`                  | enumerator | 定期付款的周期。                                                  | [Enumeradores periodicity](#enumeradores-periodicity) |
| `journey_type`                 | enumerator | 自动定期付款的旅程类型。                                          | [Enumeradores journey_type](#enumeradores-journey_type) |
| `start_date`                   | string     | 定期付款开始日期（ISO 8601 格式，如 `2025-06-10`）。             | 10     |
| `end_date`                     | string     | 定期付款结束日期（ISO 8601 格式）或 null（如为无限期）。          | 10 或 null |
| `outgoing_recurrence_data`     | object     | 汇集订阅参数和补充数据的对象。                                    | [Objeto outgoing_recurrence_data](#objeto-outgoing_recurrence_data) |
| `payment_orders`               | array      | 汇集付款订单的对象。                                              | [Objeto payment_orders](#objeto-payment_orders) |
| `outgoing_recurrence_events`   | array      | 汇集定期付款事件参数的对象。                                      | [Objeto outgoing_recurrence_events](#objeto-outgoing_recurrence_events) |

### Objeto outgoing_recurrence_data

| 字段                        | 类型       | 描述                                             | 字符数 |
|-----------------------------|------------|--------------------------------------------------|--------|
| `minimum_recurrence_amount` | number     | 可变金额定期付款中的最低预期金额。               | -      |
| `recurrence_amount`         | number     | 定期付款金额（固定金额；可变时为 null）。        | -      |
| `retry_configuration`       | object     | 未完成定期付款的重试配置。                       | [Objeto retry_configuration](#objeto-retry_configuration) |
| `debtor_data`               | object     | 债务人（订阅者）数据。                           | [Objeto debtor_data](#objeto-debtor_data) |
| `qr_code_data`              | object     | 为付款生成的 QR 码数据（如有）。                | [Objeto qr_code_data](#objeto-qr_code_data) |
| `initial_payment_data`      | object     | 初始收费数据。                                   | [Objeto initial_payment_data](#objeto-initial_payment_data) |
| `pix_message`               | string     | 随 Pix 交易一起发送的消息。                      | 140    |
| `settlement_date_type`      | enumerator | 结算日期调整类型。                               | [Enumeradores settlement_date_type](#enumeradores-settlement_date_type) |

---

### Objeto retry_configuration

| 字段            | 类型    | 描述                   | 字符数 |
|-----------------|---------|------------------------|--------|
| `retry_allowed` | boolean | 是否启用重试。         | -      |
| `retry_rule`    | object  | 重试的详细规则。       | [Objeto retry_rule](#objeto-retry_rule) |

---

### Objeto retry_rule

| 字段           | 类型   | 描述               | 字符数 |
|----------------|--------|--------------------|--------|
| `first_retry`  | object | 第 1 次重试配置。  | [Objeto retry_detail](#objeto-retry_detail) |
| `second_retry` | object | 第 2 次重试配置。  | [Objeto retry_detail](#objeto-retry_detail) |
| `third_retry`  | object | 第 3 次重试配置。  | [Objeto retry_detail](#objeto-retry_detail) |

---

### Objeto retry_detail

| 字段   | 类型   | 描述           | 字符数 |
|--------|--------|----------------|--------|
| `day`  | string | 重试日期。     | -      |
| `time` | string | 重试时间。     | -      |

---

### Objeto debtor_data

| 字段              | 类型   | 描述             | 字符数 |
|-------------------|--------|------------------|--------|
| `name`            | string | 订阅者姓名。     | 50     |
| `email`           | string | 订阅者电子邮件。 | 100    |
| `document_number` | string | CPF 或 CNPJ。   | 14     |
| `address`         | object | 订阅者地址。     | [Objeto address](#objeto-address) |
| `account_data`    | object | 银行数据。       | [Objeto account_data](#objeto-account_data) |

---

### Objeto address

| 字段          | 类型   | 描述       | 字符数 |
|---------------|--------|------------|--------|
| `city`        | string | 城市。     | -      |
| `postal_code` | string | 邮政编码。 | -      |
| `uf`          | string | 州（缩写）。| -     |
| `street`      | string | 街道。     | -      |

---

### Objeto account_data

| 字段             | 类型   | 描述                 | 字符数 |
|------------------|--------|----------------------|--------|
| `account_number` | string | 账户号码。           | -      |
| `account_digit`  | string | 账户校验位。         | -      |
| `account_branch` | string | 支行。               | -      |
| `ispb`           | string | 金融机构 ISPB。      | -      |

---

### Objeto qr_code_data

| 字段             | 类型   | 描述                  | 字符数 |
|------------------|--------|-----------------------|--------|
| `qr_code_key`    | string | 生成 QR 码的标识符。  | -      |
| `qr_code_url`    | string | QR 码查看 URL。       | -      |
| `qr_code_image`  | string | QR 码图像（Base64）。 | -      |

---

### Objeto initial_payment_data

| 字段                       | 类型     | 描述                                         | 字符数 |
|----------------------------|----------|----------------------------------------------|--------|
| `amount`                   | number   | 初始收费的主要金额（巴西雷亚尔 R$）。        | -      |
| `pix_key`                  | string   | 初始付款目标 Pix 键。                        | 77     |
| `qr_code_type`             | enum     | 初始收费的 QR 码类型。                       | [Enumeradores qr_code_type](#enumeradores-qr_code_type) |
| `additional_data`          | array    | 与收费相关的附加信息列表。                   | [Array de objects additional_data](#array-additional_data) |
| `fine_amount`              | number   | 付款逾期时的罚款金额。                       | -      |
| `interest_amount`          | number   | 付款逾期时的利息金额。                       | -      |
| `expiration_date`          | string   | 初始收费到期日期（ISO 8601 格式）。          | 10     |
| `max_payment_days`         | integer  | 到期后的最大受理天数。                       | -      |
| `rebate_amount`            | number   | 提前付款折扣金额。                           | -      |
| `discounts`                | array    | 附加折扣列表。                               | -      |
| `receiver_conciliation_id` | string   | 接收方付款对账标识符。                       | 35     |
| `transaction_data`         | object   | 与初始收费相关的交易详情。                   | [Objeto transaction_data](#objeto-transaction_data) |

---

### Array additional_data

| 字段       | 类型   | 描述                               | 字符数 |
|------------|--------|------------------------------------|--------|
| `key_name` | string | 附加信息名称（如"Juros e Multa"）。| 140    |
| `value`    | string | 附加信息的值或描述。               | 140    |

---

### Objeto transaction_data

| 字段                | 类型   | 描述                  | 字符数 |
|---------------------|--------|-----------------------|--------|
| `transaction_key`   | string | 交易唯一键。          | 36     |
| `pix_transfer_key`  | string | Pix 转账标识符。      | 36     |
| `end_to_end_id`     | string | Pix 端到端标识符。    | 32     |

---

### Objeto payment_orders

| 字段                        | 类型    | 描述                                   | 字符数 |
|-----------------------------|---------|----------------------------------------|--------|
| `payment_order_key`         | string  | 付款订单的唯一标识键。                 | 32     |
| `payment_order_status`      | string  | 付款订单状态。                         | -      |
| `reference_date`            | string  | 收费参考日期。                         | -      |
| `receiver_conciliation_id`  | uuidv4  | 接收方对账 ID。                        | 35     |
| `transaction_amount`        | number  | 交易的货币金额。                       | -      |
| `transaction_key`           | uuidv4  | 交易唯一键。                           | 36     |
| `incoming_pix_transfer_key` | uuidv4  | 收到的 Pix 转账键。                    | 36     |
| `created_at`                | string  | 订单创建日期/时间（ISO 8601 格式）。   | -      |
| `paid_at`                   | string  | 付款日期/时间（ISO 8601 格式）。       | -      |

### Objeto outgoing_recurrence_events

| 字段                              | 类型   | 描述                                   | 字符数 |
|-----------------------------------|--------|----------------------------------------|--------|
| `outgoing_recurrence_event_key`   | string | 定期付款事件的唯一标识键。             | 36     |
| `outgoing_recurrence_status`      | string | 定期付款状态。                         | -      |
| `created_at`                      | string | 订单创建日期/时间（ISO 8601 格式）。   | -      |

### Enumeradores periodicity

| 枚举值        | 描述     |
|---------------|----------|
| `weekly`      | 每周定期 |
| `monthly`     | 每月定期 |
| `quarterly`   | 每季定期 |
| `semiannual`  | 每半年定期|
| `annual`      | 每年定期 |

---

### Enumeradores journey_type

| 枚举值          | 描述                       |
|-----------------|----------------------------|
| `journey_one`   | 银行应用内直接通知         |
| `journey_two`   | 定期收费的 QR 码体验       |
| `journey_three` | 即时付款 + QR 码定期付款   |
| `journey_four`  | Pix 操作后的定期授权       |

---

### Enumeradores settlement_date_type

| 枚举值           | 描述       |
|------------------|------------|
| `workdays`       | 工作日     |
| `calendar_days`  | 日历天数   |

---

### Enumeradores qr_code_type

| 枚举值             | 描述                   |
|--------------------|------------------------|
| `dynamic_instant`  | 即时付款动态 QR 码     |
| `dynamic_term`     | 未来到期付款动态 QR 码 |

STATUS 4XX

Response Error

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

| HTTP 状态码 | QI 代码<br/>`code` | 标题<br/>`title`       | 描述（英文）<br/>`description`                             | 描述（葡文）<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.                    |

---

# 通过 QR 码查询 Pix 自动定期付款数据

URL: /zh-Hans/documentation/baas/pix_automatico/recebedor/consultar_recorrencia_receiver

## 请求

ENDPOINT /account/ ACCOUNT_KEY /outgoing_recurrence/qr_code_initial_payment/ RECEIVER_CONCILIATION_ID
方法 GET

### Path Params

| 字段                        | 类型   | 描述                                 | 字符数 |
|-----------------------------|--------|--------------------------------------|--------|
| `account_key` *             | uuidv4 | 账户的唯一标识键。                   | 36     |
| `receiver_conciliation_id` *| string | 与定期付款关联的 QR 码对账 ID。      | 32     |

## 响应

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",
      "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

| 字段                           | 类型       | 描述                                                              | 字符数 |
|--------------------------------|------------|-------------------------------------------------------------------|--------|
| `request_control_key`          | uuidv4     | 请求控制的唯一键。                                                | 36     |
| `outgoing_recurrence_key`      | uuidv4     | 自动定期付款标识符。                                              | 36     |
| `outgoing_recurrence_status`   | string     | 定期付款的当前状态（`approved`、`pending`、`rejected` 等）。      | 30     |
| `periodicity`                  | enumerator | 定期付款的周期。                                                  | [Enumeradores periodicity](#enumeradores-periodicity) |
| `journey_type`                 | enumerator | 自动定期付款的旅程类型。                                          | [Enumeradores journey_type](#enumeradores-journey_type) |
| `start_date`                   | string     | 定期付款开始日期（ISO 8601 格式，如 `2025-06-10`）。             | 10     |
| `end_date`                     | string     | 定期付款结束日期（ISO 8601 格式）或 null（如为无限期）。          | 10 或 null |
| `outgoing_recurrence_data`     | object     | 汇集订阅参数和补充数据的对象。                                    | [Objeto outgoing_recurrence_data](#objeto-outgoing_recurrence_data) |

---

### Objeto outgoing_recurrence_data

| 字段                        | 类型       | 描述                                             | 字符数 |
|-----------------------------|------------|--------------------------------------------------|--------|
| `minimum_recurrence_amount` | number     | 可变金额定期付款中的最低预期金额。               | -      |
| `recurrence_amount`         | number     | 定期付款金额（固定金额；可变时为 null）。        | -      |
| `retry_configuration`       | object     | 未完成定期付款的重试配置。                       | [Objeto retry_configuration](#objeto-retry_configuration) |
| `debtor_data`               | object     | 债务人（订阅者）数据。                           | [Objeto debtor_data](#objeto-debtor_data) |
| `qr_code_data`              | object     | 为付款生成的 QR 码数据（如有）。                | [Objeto qr_code_data](#objeto-qr_code_data) |
| `initial_payment_data`      | object     | 初始收费数据。                                   | [Objeto initial_payment_data](#objeto-initial_payment_data) |
| `pix_message`               | string     | 随 Pix 交易一起发送的消息。                      | 140    |
| `settlement_date_type`      | enumerator | 结算日期调整类型。                               | [Enumeradores settlement_date_type](#enumeradores-settlement_date_type) |

---

### Objeto retry_configuration

| 字段            | 类型    | 描述             | 字符数 |
|-----------------|---------|------------------|--------|
| `retry_allowed` | boolean | 是否启用重试。   | -      |
| `retry_rule`    | object  | 重试的详细规则。 | [Objeto retry_rule](#objeto-retry_rule) |

---

### Objeto retry_rule

| 字段           | 类型   | 描述               | 字符数 |
|----------------|--------|--------------------|--------|
| `first_retry`  | object | 第 1 次重试配置。  | [Objeto retry_detail](#objeto-retry_detail) |
| `second_retry` | object | 第 2 次重试配置。  | [Objeto retry_detail](#objeto-retry_detail) |
| `third_retry`  | object | 第 3 次重试配置。  | [Objeto retry_detail](#objeto-retry_detail) |

---

### Objeto retry_detail

| 字段   | 类型   | 描述         | 字符数 |
|--------|--------|--------------|--------|
| `day`  | string | 重试日期。   | -      |
| `time` | string | 重试时间。   | -      |

---

### Objeto debtor_data

| 字段              | 类型   | 描述             | 字符数 |
|-------------------|--------|------------------|--------|
| `name`            | string | 订阅者姓名。     | 50     |
| `email`           | string | 订阅者电子邮件。 | 100    |
| `document_number` | string | CPF 或 CNPJ。   | 14     |
| `address`         | object | 订阅者地址。     | [Objeto address](#objeto-address) |
| `account_data`    | object | 银行数据。       | [Objeto account_data](#objeto-account_data) |

---

### Objeto address

| 字段          | 类型   | 描述       | 字符数 |
|---------------|--------|------------|--------|
| `city`        | string | 城市。     | -      |
| `postal_code` | string | 邮政编码。 | -      |
| `uf`          | string | 州（缩写）。| -     |
| `street`      | string | 街道。     | -      |

---

### Objeto account_data

| 字段             | 类型   | 描述                 | 字符数 |
|------------------|--------|----------------------|--------|
| `account_number` | string | 账户号码。           | -      |
| `account_digit`  | string | 账户校验位。         | -      |
| `account_branch` | string | 支行。               | -      |
| `ispb`           | string | 金融机构 ISPB。      | -      |

---

### Objeto qr_code_data

| 字段             | 类型   | 描述                  | 字符数 |
|------------------|--------|-----------------------|--------|
| `qr_code_key`    | string | 生成 QR 码的标识符。  | -      |
| `qr_code_url`    | string | QR 码查看 URL。       | -      |
| `qr_code_image`  | string | QR 码图像（Base64）。 | -      |

---

### Objeto initial_payment_data

| 字段                       | 类型     | 描述                                         | 字符数 |
|----------------------------|----------|----------------------------------------------|--------|
| `amount`                   | number   | 初始收费的主要金额（巴西雷亚尔 R$）。        | -      |
| `pix_key`                  | string   | 初始付款目标 Pix 键。                        | 77     |
| `qr_code_type`             | enum     | 初始收费的 QR 码类型。                       | [Enumeradores qr_code_type](#enumeradores-qr_code_type) |
| `additional_data`          | array    | 与收费相关的附加信息列表。                   | [Array de objects additional_data](#array-additional_data) |
| `fine_amount`              | number   | 付款逾期时的罚款金额。                       | -      |
| `interest_amount`          | number   | 付款逾期时的利息金额。                       | -      |
| `expiration_date`          | string   | 初始收费到期日期（ISO 8601 格式）。          | 10     |
| `max_payment_days`         | integer  | 到期后的最大受理天数。                       | -      |
| `rebate_amount`            | number   | 提前付款折扣金额。                           | -      |
| `discounts`                | array    | 附加折扣列表。                               | -      |
| `receiver_conciliation_id` | string   | 接收方付款对账标识符。                       | 35     |
| `transaction_data`         | object   | 与初始收费相关的交易详情。                   | [Objeto transaction_data](#objeto-transaction_data) |

---

### Array additional_data

| 字段       | 类型   | 描述                               | 字符数 |
|------------|--------|------------------------------------|--------|
| `key_name` | string | 附加信息名称（如"Juros e Multa"）。| 140    |
| `value`    | string | 附加信息的值或描述。               | 140    |

---

### Objeto transaction_data

| 字段                | 类型   | 描述                  | 字符数 |
|---------------------|--------|-----------------------|--------|
| `transaction_key`   | string | 交易唯一键。          | 36     |
| `pix_transfer_key`  | string | Pix 转账标识符。      | 36     |
| `end_to_end_id`     | string | Pix 端到端标识符。    | 32     |

---

### Enumeradores periodicity

| 枚举值        | 描述     |
|---------------|----------|
| `weekly`      | 每周定期 |
| `monthly`     | 每月定期 |
| `quarterly`   | 每季定期 |
| `semiannual`  | 每半年定期|
| `annual`      | 每年定期 |

---

### Enumeradores journey_type

| 枚举值          | 描述                       |
|-----------------|----------------------------|
| `journey_one`   | 银行应用内直接通知         |
| `journey_two`   | 定期收费的 QR 码体验       |
| `journey_three` | 即时付款 + QR 码定期付款   |
| `journey_four`  | Pix 操作后的定期授权       |

---

### Enumeradores settlement_date_type

| 枚举值           | 描述       |
|------------------|------------|
| `workdays`       | 工作日     |
| `calendar_days`  | 日历天数   |

---

### Enumeradores qr_code_type

| 枚举值             | 描述                   |
|--------------------|------------------------|
| `dynamic_instant`  | 即时付款动态 QR 码     |
| `dynamic_term`     | 未来到期付款动态 QR 码 |

STATUS 4XX

Response Error

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

| HTTP 状态码 | QI 代码<br/>`code` | 标题<br/>`title`       | 描述（英文）<br/>`description`                             | 描述（葡文）<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.                    |

---

# 付款对账与结算

URL: /zh-Hans/documentation/baas/pix_automatico/recebedor/introducao

## 业务概述

通过 Pix 自动扣款的支付系统提供了一种高效的解决方案，用于自动化循环扣款，为付款方和收款方都提供更大便利。通过保证自动化和向相关方发送通知，最大限度地降低逾期付款风险，优化企业的现金流。

## 通过 Pix 自动扣款处理付款

在通过 Pix 自动扣款付款的预定日期，付款方银行必须在午夜至8点之间发出付款订单。确认付款后，付款用户将收到通知。如果在此步骤之前，付款方或收款方取消了扣款，则不会处理该交易。

## 可变金额循环扣款

对于可变金额的循环扣款，收款用户将定义最低金额，而付款人将确定允许的最高金额。应收取的具体金额必须由收款方在付款日期前10至2天发送。

:::warning
如果未发送，则不会进行扣款。此步骤不适用于固定金额的循环扣款。
:::

### 业务背景

可变金额的循环扣款在可收费金额可能波动的行业中特别有用，例如公用事业供应或基于使用量的订阅，允许付款灵活性。

## 付款对账批次

一组待收款的循环扣款将被称为结算组（`conciliation_batch`）。

- 对账批次在付款日期前10天创建。
- 批次在付款日期前2天关闭。
- 创建批次后，将发送包含 `conciliation_batch_key` 的 webhook。关联的循环扣款可通过特定端点获取。

### 对业务的影响

对账批次便于大规模管理应收款项，为计划的财务流量提供透明度和控制，这对任何组织的战略和财务规划都至关重要。

## 重试收款

收款用户可以在创建循环扣款时定义重试收款，并遵守以下条件：

- 重试可以在原始到期日后最多7天内进行。
- 最多可进行三次尝试，如创建时所定义。
- 金额必须与原始付款金额相同。

### 业务注意事项

重试收款是最大化应收款项的关键功能，为由于任何原因在原始日期失败的付款提供额外结算机会。这减少了因逾期付款而造成的损失，并通过提供额外灵活性改善了客户体验。

---

# 创建定期付款（旅程 4）

URL: /zh-Hans/documentation/baas/pix_automatico/recebedor/journey_four

> 旅程 4 — QR 码 + 付款或调度 + 提供 Pix 自动支付

概述
是什么 客户扫描 QR 码进行付款或调度，之后收到激活 Pix 自动支付定期付款的邀请。
适用场景 适用于账单、收据或需要提出定期授权的付款，但仅在初始付款或调度之后。
如何运作 付款人扫描 QR 码 → 付款或调度 → 完成后收到激活 Pix 自动支付的邀请（可选）。
优势 灵活性：定期付款的决定在付款/调度后做出，允许付款人自愿自发地参与。
注意事项 定期付款提议仅在付款/调度后做出——客户可以拒绝。如果该情况不适用定期付款，仅继续付款，不提供定期付款。

## 请求

ENDPOINT /account/ account_key /outgoing_recurrence/journey_four
方法 POST

### 请求 Path Params

| 字段            | 类型  | 描述                 | 字符数 |
|-----------------|-------|----------------------|--------|
| `account_key` * | uuid4 | 账户的唯一标识键。   | 36     |

### Request Body

Request Body: 创建定期付款（旅程 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",
        "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

| 字段                        | 类型       | 描述                                                             | 字符数 |
|-----------------------------|------------|------------------------------------------------------------------|--------|
| `request_control_key` *     | uuid       | uuid4 格式的请求唯一标识键。                                     | 36     |
| `periodicity` *             | enumerator | 与订阅定期付款关联的周期类型。                                   | [Enumeradores periodicity](#enumeradores-periodicity) |
| `minimum_recurrence_amount` | float      | 可变金额定期付款的最低交易金额。                                 | -      |
| `start_date` *              | string     | 定期付款开始日期（ISO 8601 格式）。                              | -      |
| `end_date`                  | string     | 定期付款结束日期；无限期情况发送 null。                          | -      |
| `pix_message` *             | string     | 随 Pix 交易一起发送的消息。                                      | 140    |
| `debtor_data` *             | Object     | 债务人（订阅者）数据。                                           | [Objeto debtor_data](#objeto-debtor_data) |
| `retry_configuration` *     | Object     | 未完成交易的重试配置。                                           | [Objeto retry_configuration](#objeto-retry_configuration) |
| `settlement_date_type` *    | enumerator | 结算日期调整类型。                                               | [Enumeradores settlement_date_type](#enumeradores-settlement_date_type) |
| `recurrence_type` *         | enumerator | 定期付款类型。                                                   | [Enumeradores recurrence_type](#enumeradores-recurrence_type) |
| `initial_payment_data` *    | Object     | 创建订阅时进行的初始收费数据。                                   | [Objeto initial_payment_data](#objeto-initial_payment_data) |

:::caution 注意
`minimum_recurrence_amount` 字段为可选字段，仅适用于可变金额定期付款。若为固定金额定期付款，应发送 `recurrence_amount` 字段及定期付款金额。`recurrence_type` 枚举值也应与定期付款类型对应。
:::

### Enumeradores periodicity

| 枚举值        | 描述     |
|---------------|----------|
| `weekly`      | 每周定期 |
| `monthly`     | 每月定期 |
| `quarterly`   | 每季定期 |
| `semiannual`  | 每半年定期|
| `annual`      | 每年定期 |

### Enumeradores settlement_date_type

| 枚举值           | 描述     |
|------------------|----------|
| `workdays`       | 工作日   |
| `calendar_days`  | 日历天数 |

### Enumeradores recurrence_type

| 枚举值            | 描述           |
|-------------------|----------------|
| `fixed_amount`    | 固定金额定期付款 |
| `variable_amount` | 可变金额定期付款 |

### Objeto debtor_data

| 字段                | 类型   | 描述                       | 字符数 |
|---------------------|--------|----------------------------|--------|
| `name` *            | string | 订阅者姓名。               | 50     |
| `email` *           | string | 订阅者电子邮件。           | 100    |
| `document_number` * | string | 订阅者 CPF 或 CNPJ。       | 14     |
| `contract_id`       | string | 订阅者合同标识符。         | 100    |
| `address` *         | Object | 订阅者地址。               | [Objeto address](#objeto-address) |

### Objeto address

| 字段           | 类型   | 描述       | 字符数 |
|----------------|--------|------------|--------|
| `street`       | string | 街道。     | -      |
| `state`        | string | 州。       | -      |
| `city`         | string | 城市。     | -      |
| `neighborhood` | string | 街区。     | -      |
| `number`       | string | 门牌号。   | -      |
| `postal_code`  | string | 邮政编码。 | -      |
| `complement`   | string | 补充信息。 | -      |

### Objeto retry_configuration

| 字段            | 类型    | 描述             | 字符数 |
|-----------------|---------|------------------|--------|
| `retry_allowed` | boolean | 是否允许重试。   | -      |
| `retry_rule`    | Object  | 重试规则。       | [Objeto retry_rule](#objeto-retry_rule) |

### Objeto retry_rule

| 字段           | 类型   | 描述               | 字符数 |
|----------------|--------|--------------------|--------|
| `first_retry`  | Object | 第 1 次重试配置。  | [Objeto retry_detail](#objeto-retry_detail) |
| `second_retry` | Object | 第 2 次重试配置。  | [Objeto retry_detail](#objeto-retry_detail) |
| `third_retry`  | Object | 第 3 次重试配置。  | [Objeto retry_detail](#objeto-retry_detail) |

### Objeto retry_detail

| 字段   | 类型   | 描述         | 字符数 |
|--------|--------|--------------|--------|
| `day`  | string | 重试日期。   | -      |

### Objeto initial_payment_data

| 字段                       | 类型       | 描述                                                        | 字符数 |
|----------------------------|------------|-------------------------------------------------------------|--------|
| `amount` *                 | number     | 初始收费的主要金额（巴西雷亚尔 R$）。                       | -      |
| `pix_key` *                | string     | 付款目标 Pix 键。                                           | 77     |
| `qr_code_type` *           | enumerator | 初始收费的 QR 码类型。                                      | [Enumeradores qr_code_type](#enumeradores-qr_code_type) |
| `additional_data` *        | array      | 与收费相关的附加信息列表。                                  | [Objetos additional_data](#obj-additional_data) |
| `fine_amount`              | number     | 付款逾期时的罚款金额。                                      | -      |
| `interest_amount`          | number     | 付款逾期时的利息金额。                                      | -      |
| `expiration_date` *        | string     | 初始收费到期日期（ISO 8601 格式）。                         | -      |
| `max_payment_days`         | integer    | 到期后可接受付款的最大天数。                                | -      |
| `rebate_amount`            | number     | 提前付款折扣金额。                                          | -      |
| `discounts`                | array      | 适用的附加折扣列表（如有）。                                | -      |
| `receiver_conciliation_id` | string     | 接收方付款对账的唯一标识符。                                | 32     |

### Enumeradores qr_code_type

| 枚举值             | 描述                               |
|--------------------|------------------------------------|
| `dynamic_instant`  | 即时付款动态 QR 码（立即到期）。   |
| `dynamic_term`     | 具有定义截止日期的动态 QR 码。     |

## 响应

STATUS 200

:::caution 注意
当付款用户收到通知时，可以选择调度 Pix 或立即付款。如果付款人立即付款，将发送包含已填写信息的 Webhook；如果是调度，相关值将为 `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": "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"
}
```

### Response Body

| 字段                   | 类型       | 描述                                       | 字符数 |
|------------------------|------------|--------------------------------------------|--------|
| `request_control_key`  | uuid       | 客户端发送的请求控制键。                   | 36     |
| `recurrence_key`       | uuid       | 订阅定期付款的唯一标识键。                 | 36     |
| `recurrence_status`    | enumerator | 定期付款的当前状态。                       | [Enumeradores recurrence_status](#enumeradores-recurrence_status) |
| `qr_code_data`         | object     | QR 码数据。                                | [Objeto qr_code_data](#objeto-qr_code_data) |
| `initial_payment_data` | object     | 初始付款信息。                             | - |
| `created_at`           | string     | 定期付款创建的日期和时间（ISO 8601 格式）。 | -      |

### Enumeradores recurrence_status

| 枚举值                  | 描述               |
|-------------------------|--------------------|
| `pending_confirmation`  | 定期付款待确认     |
| `active`                | 定期付款已激活     |
| `cancelled`             | 定期付款已取消     |
| `suspended`             | 定期付款已暂停     |
| `expired`               | 定期付款已到期     |

STATUS 4XX

Response Error

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

| HTTP 状态码 | QI 代码<br/>`code` | 标题<br/>`title`              | 描述（英文）<br/>`description`                                                | 描述（葡文）<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.              |

---

# 创建定期付款（旅程 1）

URL: /zh-Hans/documentation/baas/pix_automatico/recebedor/journey_one

> 旅程 1 — 无 QR 码（应用内通知）

概述
是什么 直接在付款人银行应用内请求授权，无需扫描 QR 码。
适用场景 主动联系（电话、聊天、面对面）或已有客户关系。
如何运作 接收方使用付款人账户数据创建定期付款 → 付款人在应用内收到通知 → 批准定期付款 → 可安排未来收费。
优势 简单直接的体验；无需展示 QR 码。

## 请求

ENDPOINT /account/ account_key /outgoing_recurrence/journey_one
方法 POST

### 请求 Path Params

| 字段            | 类型  | 描述                 | 字符数 |
|-----------------|-------|----------------------|--------|
| `account_key` * | uuid4 | 账户的唯一标识键。   | 36     |

### Request Body

Request Body: 创建定期付款（旅程 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

| 字段                        | 类型       | 描述                                                                 | 字符数 |
|-----------------------------|------------|----------------------------------------------------------------------|--------|
| `request_control_key` *     | uuid       | 客户端使用的 uuid4 格式请求唯一标识键。                              | 36     |
| `periodicity` *             | enumerator | 与订阅定期付款关联的周期类型。                                       | [Enumeradores periodicity](#enumeradores-periodicity) |
| `minimum_recurrence_amount` | number     | 可变金额定期付款的最低交易金额（以分为单位）。                       | -      |
| `start_date` *              | string     | 定期付款开始日期（ISO 8601 格式，如 "2025-07-01"）。                | -      |
| `end_date`                  | string     | 定期付款结束日期；无限期情况发送 null。                              | -      |
| `pix_message` *             | string     | 随 Pix 交易一起发送的消息。                                          | 140    |
| `debtor_data` *             | Object     | 债务人（订阅者）数据。                                               | [Objeto debtor_data](#objeto-debtor_data) |
| `retry_configuration` *     | Object     | 未完成交易的重试配置。                                               | [Objeto retry_configuration](#objeto-retry_configuration) |
| `settlement_date_type` *    | enumerator | 结算日期调整类型。                                                   | [Enumeradores settlement_date_type](#enumeradores-settlement_date_type) |
| `recurrence_type` *         | enumerator | 定期付款类型。                                                       | [Enumeradores recurrence_type](#enumeradores-recurrence_type) |

:::caution 注意
`minimum_recurrence_amount` 字段为可选字段，仅适用于可变金额定期付款。若为固定金额定期付款，应发送 `recurrence_amount` 字段及定期付款金额。`recurrence_type` 枚举值也应与定期付款类型（固定金额或可变金额）对应。
:::

### Enumeradores periodicity

| 枚举值        | 描述     |
|---------------|----------|
| `weekly`      | 每周定期 |
| `monthly`     | 每月定期 |
| `quarterly`   | 每季定期 |
| `semiannual`  | 每半年定期|
| `annual`      | 每年定期 |

### Enumeradores settlement_date_type

| 枚举值           | 描述     |
|------------------|----------|
| `workdays`       | 工作日   |
| `calendar_days`  | 日历天数 |

### Enumeradores recurrence_type

| 枚举值            | 描述           |
|-------------------|----------------|
| `fixed_amount`    | 固定金额定期付款 |
| `variable_amount` | 可变金额定期付款 |

### Objeto debtor_data

| 字段                | 类型   | 描述                       | 字符数 |
|---------------------|--------|----------------------------|--------|
| `name` *            | string | 订阅者姓名。               | 50     |
| `email` *           | string | 订阅者电子邮件。           | 100    |
| `document_number` * | string | 订阅者 CPF 或 CNPJ。       | 14     |
| `contract_id`       | string | 订阅者合同标识符。         | 100    |
| `address` *         | Object | 订阅者地址。               | [Objeto address](#objeto-address) |
| `account_data` *    | Object | 订阅者银行数据。           | [Objeto account_data](#objeto-account_data) |

### Objeto address

| 字段           | 类型   | 描述       | 字符数 |
|----------------|--------|------------|--------|
| `street`       | string | 街道。     | -      |
| `state`        | string | 州。       | -      |
| `city`         | string | 城市。     | -      |
| `neighborhood` | string | 街区。     | -      |
| `number`       | string | 门牌号。   | -      |
| `postal_code`  | string | 邮政编码。 | -      |
| `complement`   | string | 补充信息。 | -      |

### Objeto account_data

| 字段             | 类型   | 描述                     | 字符数 |
|------------------|--------|--------------------------|--------|
| `account_number` | string | 账户号码。               | -      |
| `account_digit`  | string | 账户校验位。             | -      |
| `account_branch` | string | 账户支行。               | -      |
| `ispb`           | string | 金融机构 ISPB。          | -      |

### Objeto retry_configuration

| 字段            | 类型    | 描述                   | 字符数 |
|-----------------|---------|------------------------|--------|
| `retry_allowed` | boolean | 是否允许重试。         | -      |
| `retry_rule`    | Object  | 重试规则。             | [Objeto retry_rule](#objeto-retry_rule) |

### Objeto retry_rule

| 字段           | 类型   | 描述               | 字符数 |
|----------------|--------|--------------------|--------|
| `first_retry`  | Object | 第 1 次重试配置。  | [Objeto retry_detail](#objeto-retry_detail) |
| `second_retry` | Object | 第 2 次重试配置。  | [Objeto retry_detail](#objeto-retry_detail) |
| `third_retry`  | Object | 第 3 次重试配置。  | [Objeto retry_detail](#objeto-retry_detail) |

### Objeto retry_detail

| 字段   | 类型   | 描述         | 字符数 |
|--------|--------|--------------|--------|
| `day`  | string | 重试日期。   | -      |

## 响应

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

| 字段                  | 类型       | 描述                                       | 字符数 |
|-----------------------|------------|--------------------------------------------|--------|
| `request_control_key` | uuid       | 客户端发送的请求控制键。                   | 36     |
| `recurrence_key`      | uuid       | 订阅定期付款的唯一标识键。                 | 36     |
| `recurrence_status`   | enumerator | 定期付款的当前状态。                       | [Enumeradores recurrence_status](#enumeradores-recurrence_status) |
| `created_at`          | string     | 定期付款创建的日期和时间（ISO 8601 格式）。 | -      |

### Enumeradores recurrence_status

| 枚举值                  | 描述               |
|-------------------------|--------------------|
| `pending_confirmation`  | 定期付款待确认     |
| `active`                | 定期付款已激活     |
| `cancelled`             | 定期付款已取消     |
| `suspended`             | 定期付款已暂停     |
| `expired`               | 定期付款已到期     |

STATUS 4XX

Response Error

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

| HTTP 状态码 | QI 代码<br/>`code` | 标题<br/>`title`              | 描述（英文）<br/>`description`                                                | 描述（葡文）<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.              |

---

# 创建定期付款（旅程 3）

URL: /zh-Hans/documentation/baas/pix_automatico/recebedor/journey_three

> 旅程 3 — QR 码 + 首次付款（立即激活定期付款）

概述
是什么 一个 QR 码，允许在同一流程中 立即付款 并 激活定期付款 。
适用场景 需要初始收费的情况（如加入费、注册费、首月费用）。
如何运作 付款人扫描 QR → 首次付款 → 立即授权定期付款。
优势 即时收入 + 定期付款已配置，减少摩擦和逾期。

### 旅程 3 流程

1. **扫描 QR 码** — 用户扫描为初始收费生成的动态 QR 码。
2. **立即付款** — 处理即时付款，记录初始收费。
3. **授权定期付款** — 在同一体验中，用户确认定期付款授权。
4. **定期付款已激活** — 后续周期自动化；必要时只需对账金额。

---

## 请求

ENDPOINT /account/ account_key /outgoing_recurrence/journey_three
方法 POST

### Path Params

| 字段            | 类型  | 描述                 | 字符数 |
|-----------------|-------|----------------------|--------|
| `account_key` * | uuid4 | 账户的唯一标识键。   | 36     |

### Request Body

Request Body: 创建定期付款（旅程 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",
    "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

| 字段                        | 类型       | 描述                                                             | 字符数 |
|-----------------------------|------------|------------------------------------------------------------------|--------|
| `request_control_key` *     | uuid       | uuid4 格式的请求唯一标识键。                                     | 36     |
| `periodicity` *             | enumerator | 与订阅定期付款关联的周期类型。                                   | [Enumeradores periodicity](#enumeradores-periodicity) |
| `minimum_recurrence_amount` | float      | 可变金额定期付款的最低交易金额。                                 | -      |
| `start_date` *              | string     | 定期付款开始日期（ISO 8601 格式）。                              | -      |
| `end_date`                  | string     | 定期付款结束日期；无限期情况发送 null。                          | -      |
| `pix_message` *             | string     | 随 Pix 交易一起发送的消息。                                      | 140    |
| `debtor_data` *             | Object     | 债务人（订阅者）数据。                                           | [Objeto debtor_data](#objeto-debtor_data) |
| `retry_configuration` *     | Object     | 未完成交易的重试配置。                                           | [Objeto retry_configuration](#objeto-retry_configuration) |
| `settlement_date_type` *    | enumerator | 结算日期调整类型。                                               | [Enumeradores settlement_date_type](#enumeradores-settlement_date_type) |
| `recurrence_type` *         | enumerator | 定期付款类型。                                                   | [Enumeradores recurrence_type](#enumeradores-recurrence_type) |
| `initial_payment_data` *    | Object     | 创建订阅时进行的初始收费数据。                                   | [Objeto initial_payment_data](#objeto-initial_payment_data) |

:::caution 注意
对于可变金额定期付款，请提供 `minimum_recurrence_amount`。对于固定金额，请发送 `recurrence_amount` 并相应调整 `recurrence_type` 枚举值。
:::

#### Enumeradores periodicity

| 枚举值        | 描述     |
|---------------|----------|
| `weekly`      | 每周定期 |
| `monthly`     | 每月定期 |
| `quarterly`   | 每季定期 |
| `semiannual`  | 每半年定期|
| `annual`      | 每年定期 |

#### Enumeradores settlement_date_type

| 枚举值           | 描述     |
|------------------|----------|
| `workdays`       | 工作日   |
| `calendar_days`  | 日历天数 |

#### Enumeradores recurrence_type

| 枚举值            | 描述           |
|-------------------|----------------|
| `fixed_amount`    | 固定金额定期付款 |
| `variable_amount` | 可变金额定期付款 |

#### Objeto debtor_data

| 字段                | 类型   | 描述                       | 字符数 |
|---------------------|--------|----------------------------|--------|
| `name` *            | string | 订阅者姓名。               | 50     |
| `email` *           | string | 订阅者电子邮件。           | 100    |
| `document_number` * | string | 订阅者 CPF 或 CNPJ。       | 14     |
| `contract_id`       | string | 合同标识符。               | 100    |
| `address` *         | Object | 订阅者地址。               | [Objeto address](#objeto-address) |

#### Objeto address

| 字段           | 类型   | 描述       |
|----------------|--------|------------|
| `street`       | string | 街道。     |
| `state`        | string | 州。       |
| `city`         | string | 城市。     |
| `neighborhood` | string | 街区。     |
| `number`       | string | 门牌号。   |
| `postal_code`  | string | 邮政编码。 |
| `complement`   | string | 补充信息。 |

#### Objeto retry_configuration

| 字段            | 类型    | 描述             |
|-----------------|---------|------------------|
| `retry_allowed` | boolean | 是否允许重试。   |
| `retry_rule`    | Object  | 重试规则。       |

#### Objeto retry_rule

| 字段           | 类型   | 描述               |
|----------------|--------|--------------------|
| `first_retry`  | Object | 第 1 次重试配置。  |
| `second_retry` | Object | 第 2 次重试配置。  |
| `third_retry`  | Object | 第 3 次重试配置。  |

#### Objeto retry_detail

| 字段   | 类型   | 描述         |
|--------|--------|--------------|
| `day`  | string | 重试日期。   |

### Objeto initial_payment_data

| 字段                       | 类型       | 描述                                                        | 字符数 |
|----------------------------|------------|-------------------------------------------------------------|--------|
| `amount` *                 | number     | 初始收费的主要金额（巴西雷亚尔 R$）。                       | -      |
| `pix_key` *                | string     | 付款目标 Pix 键。                                           | 77     |
| `qr_code_type` *           | enumerator | 初始收费的 QR 码类型。                                      | [Enumeradores qr_code_type](#enumeradores-qr_code_type) |
| `additional_data` *        | array      | 与收费相关的附加信息列表（如利息、罚款）。                  | [Objetos additional_data](#obj-additional_data) |
| `fine_amount`              | number     | 付款逾期时的罚款金额。                                      | -      |
| `interest_amount`          | number     | 付款逾期时的利息金额。                                      | -      |
| `expiration_date` *        | string     | 初始收费到期日期（ISO 8601 格式，如 "2023-03-25"）。        | -      |
| `max_payment_days`         | integer    | 到期后可接受付款的最大天数。                                | -      |
| `rebate_amount`            | number     | 提前付款折扣金额。                                          | -      |
| `discounts`                | array      | 适用的附加折扣列表（如有）。                                | -      |
| `receiver_conciliation_id` | string     | 接收方付款对账的唯一标识符。                                | 32     |

### Enumeradores qr_code_type

| 枚举值             | 描述                   |
|--------------------|------------------------|
| `dynamic_instant`  | 即时付款动态 QR 码（立即到期）。   |
| `dynamic_term`     | 具有定义截止日期的动态 QR 码（未来到期）。 |

### Objeto additional_data

| 字段       | 类型   | 描述                               |
|------------|--------|------------------------------------|
| `key_name` | string | 附加信息字段名称（如 "Juros e Multa"）。|
| `value`    | string | 附加信息的值或描述。               |

## 响应

STATUS 200

:::caution 注意
当付款用户收到通知时，可以选择调度 Pix 或立即付款。如果付款人立即付款，将发送包含已填写信息的 `baas.automatic_pix.outgoing_recurrence.status_change` 类型 Webhook；如果是调度，相关值将为 `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

| 字段                   | 类型       | 描述                                       | 字符数 |
|------------------------|------------|--------------------------------------------|--------|
| `request_control_key`  | uuid       | 客户端发送的请求控制键。                   | 36     |
| `recurrence_key`       | uuid       | 订阅定期付款的唯一标识键。                 | 36     |
| `recurrence_status`    | enumerator | 定期付款的当前状态。                       | [Enumeradores recurrence_status](#enumeradores-recurrence_status) |
| `qr_code_data`         | object     | QR 码数据。                                | [Objeto qr_code_data](#objeto-qr_code_data) |
| `initial_payment_data` | object     | 已启动付款的信息。                         | [Objeto initial_payment_data response](#objeto-initial-payment-response) |
| `created_at`           | string     | 定期付款创建的日期和时间（ISO 8601 格式）。 | -      |

### Objeto qr_code_data

| 字段             | 类型   | 描述                  | 字符数 |
|------------------|--------|-----------------------|--------|
| `qr_code_url`    | string | QR 码复制粘贴的 URL。 | -      |
| `qr_code_key`    | uuid   | QR 码的唯一标识键。   | 36     |
| `qr_code_image`  | string | QR 码图像 Base64。    | -      |

### Objeto initial_payment_data（响应）

| 字段                       | 类型   | 描述                             | 字符数 |
|----------------------------|--------|----------------------------------|--------|
| `receiver_conciliation_id` | string | 接收方付款对账的唯一标识符。     | 32     |

### Enumeradores recurrence_status

| 枚举值                  | 描述               |
|-------------------------|--------------------|
| `pending_confirmation`  | 定期付款待确认     |
| `active`                | 定期付款已激活     |
| `cancelled`             | 定期付款已取消     |
| `suspended`             | 定期付款已暂停     |
| `expired`               | 定期付款已到期     |

STATUS 4XX

Response Error

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

| HTTP 状态码 | QI 代码<br/>`code` | 标题<br/>`title`              | 描述（英文）<br/>`description`                                                | 描述（葡文）<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.              |

---

# 创建定期付款（旅程 2）

URL: /zh-Hans/documentation/baas/pix_automatico/recebedor/journey_two

> 旅程 2 — 仅含定期付款数据的 QR 码

概述
是什么 仅呈现定期付款数据供付款人授权的 QR 码，无需立即收费。
适用场景 无初始收费的入驻；用于销售点、柜台、屏幕或印刷材料。
如何运作 付款人扫描 QR 码 → 在应用中查看定期付款数据 → 授权 → 可安排未来收费。
优势 通过 QR 码快速启用；可大量低摩擦地获取客户，且 QR 码可重复用于新定期付款。

## 请求

ENDPOINT /account/ account_key /outgoing_recurrence/journey_two
方法 POST

### 请求 Path Params

| 字段            | 类型  | 描述                 | 字符数 |
|-----------------|-------|----------------------|--------|
| `account_key` * | uuid4 | 账户的唯一标识键。   | 36     |

### Request Body

Request Body: 创建定期付款（旅程 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

| 字段                        | 类型       | 描述                                                                 | 字符数 |
|-----------------------------|------------|----------------------------------------------------------------------|--------|
| `request_control_key` *     | uuid       | 客户端使用的 uuid4 格式请求唯一标识键。                              | 36     |
| `periodicity` *             | enumerator | 与订阅定期付款关联的周期类型。                                       | [Enumeradores periodicity](#enumeradores-periodicity) |
| `minimum_recurrence_amount` | number     | 可变金额定期付款的最低交易金额（以分为单位）。                       | -      |
| `start_date` *              | string     | 定期付款开始日期（ISO 8601 格式，如 "2025-07-01"）。                | -      |
| `end_date`                  | string     | 定期付款结束日期；无限期情况发送 null。                              | -      |
| `pix_message` *             | string     | 随 Pix 交易一起发送的消息。                                          | 140    |
| `debtor_data` *             | Object     | 债务人（订阅者）数据。                                               | [Objeto debtor_data](#objeto-debtor_data) |
| `retry_configuration` *     | Object     | 未完成交易的重试配置。                                               | [Objeto retry_configuration](#objeto-retry_configuration) |
| `settlement_date_type` *    | enumerator | 结算日期调整类型。                                                   | [Enumeradores settlement_date_type](#enumeradores-settlement_date_type) |
| `recurrence_type` *         | enumerator | 定期付款类型。                                                       | [Enumeradores recurrence_type](#enumeradores-recurrence_type) |

:::caution 注意
`minimum_recurrence_amount` 字段为可选字段，仅适用于可变金额定期付款。若为固定金额定期付款，应发送 `recurrence_amount` 字段及定期付款金额。`recurrence_type` 枚举值也应与定期付款类型（固定金额或可变金额）对应。
:::

### Enumeradores periodicity

| 枚举值        | 描述     |
|---------------|----------|
| `weekly`      | 每周定期 |
| `monthly`     | 每月定期 |
| `quarterly`   | 每季定期 |
| `semiannual`  | 每半年定期|
| `annual`      | 每年定期 |

### Enumeradores settlement_date_type

| 枚举值           | 描述     |
|------------------|----------|
| `workdays`       | 工作日   |
| `calendar_days`  | 日历天数 |

### Enumeradores recurrence_type

| 枚举值            | 描述           |
|-------------------|----------------|
| `fixed_amount`    | 固定金额定期付款 |
| `variable_amount` | 可变金额定期付款 |

### Objeto debtor_data

| 字段                | 类型   | 描述                       | 字符数 |
|---------------------|--------|----------------------------|--------|
| `name` *            | string | 订阅者姓名。               | 50     |
| `email` *           | string | 订阅者电子邮件。           | 100    |
| `document_number` * | string | 订阅者 CPF 或 CNPJ。       | 14     |
| `contract_id`       | string | 订阅者合同标识符。         | 100    |
| `address` *         | Object | 订阅者地址。               | [Objeto address](#objeto-address) |

### Objeto address

| 字段           | 类型   | 描述       | 字符数 |
|----------------|--------|------------|--------|
| `street`       | string | 街道。     | -      |
| `state`        | string | 州。       | -      |
| `city`         | string | 城市。     | -      |
| `neighborhood` | string | 街区。     | -      |
| `number`       | string | 门牌号。   | -      |
| `postal_code`  | string | 邮政编码。 | -      |
| `complement`   | string | 补充信息。 | -      |

### Objeto retry_configuration

| 字段            | 类型    | 描述             | 字符数 |
|-----------------|---------|------------------|--------|
| `retry_allowed` | boolean | 是否允许重试。   | -      |
| `retry_rule`    | Object  | 重试规则。       | [Objeto retry_rule](#objeto-retry_rule) |

### Objeto retry_rule

| 字段           | 类型   | 描述               | 字符数 |
|----------------|--------|--------------------|--------|
| `first_retry`  | Object | 第 1 次重试配置。  | [Objeto retry_detail](#objeto-retry_detail) |
| `second_retry` | Object | 第 2 次重试配置。  | [Objeto retry_detail](#objeto-retry_detail) |
| `third_retry`  | Object | 第 3 次重试配置。  | [Objeto retry_detail](#objeto-retry_detail) |

### Objeto retry_detail

| 字段   | 类型   | 描述         | 字符数 |
|--------|--------|--------------|--------|
| `day`  | string | 重试日期。   | -      |

## 响应

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

| 字段                  | 类型       | 描述                                       | 字符数 |
|-----------------------|------------|--------------------------------------------|--------|
| `request_control_key` | uuid       | 客户端发送的请求控制键。                   | 36     |
| `recurrence_key`      | uuid       | 订阅定期付款的唯一标识键。                 | 36     |
| `recurrence_status`   | enumerator | 定期付款的当前状态。                       | [Enumeradores recurrence_status](#enumeradores-recurrence_status) |
| `qr_code_data`        | object     | QR 码数据。                                | [Objeto qr_code_data](#objeto-qr_code_data) |
| `created_at`          | string     | 定期付款创建的日期和时间（ISO 8601 格式）。 | -      |

### Objeto qr_code_data

| 字段             | 类型   | 描述                  | 字符数 |
|------------------|--------|-----------------------|--------|
| `qr_code_url`    | string | QR 码复制粘贴的 URL。 | -      |
| `qr_code_key`    | uuid   | QR 码的唯一标识键。   | 36     |
| `qr_code_image`  | string | QR 码图像 Base64。    | -      |

### Enumeradores recurrence_status

| 枚举值                  | 描述               |
|-------------------------|--------------------|
| `pending_confirmation`  | 定期付款待确认     |
| `active`                | 定期付款已激活     |
| `cancelled`             | 定期付款已取消     |
| `suspended`             | 定期付款已暂停     |
| `expired`               | 定期付款已到期     |

STATUS 4XX

Response Error

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

| HTTP 状态码 | QI 代码<br/>`code` | 标题<br/>`title`              | 描述（英文）<br/>`description`                                                | 描述（葡文）<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.              |

---

# 列出请求方的定期付款

URL: /zh-Hans/documentation/baas/pix_automatico/recebedor/listar_recorrencias_de_um_requester

## 请求

ENDPOINT /outgoing_recurrences
方法 GET

### Query Params

| 字段                          | 类型       | 描述                                                                                    | 字符数 |
|-------------------------------|------------|-----------------------------------------------------------------------------------------|--------|
| `outgoing_recurrence_status`  | enumerador | 按状态筛选定期付款（`approved`、`pending`、`rejected`、`pending_confirmation`）。       | 30     |
| `page`                        | integer    | 要返回的页码（分页）。                                                                  | -      |
| `page_size`                   | integer    | 每页的项目数（分页）。                                                                  | -      |

---

## 响应

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,
        "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

| 字段                   | 类型   | 描述                                     | 字符数 |
|------------------------|--------|------------------------------------------|--------|
| `outgoing_recurrences` | array  | 自动定期付款对象列表。                   | [Array outgoing_recurrences](#array-outgoing_recurrences) |
| `pagination`           | object | 包含结果页面信息的分页对象。             | [Objeto pagination](#objeto-pagination) |

---

### Array outgoing_recurrences

| 字段                           | 类型       | 描述                                                              | 字符数 |
|--------------------------------|------------|-------------------------------------------------------------------|--------|
| `request_control_key`          | uuidv4     | 请求控制的唯一键。                                                | 36     |
| `outgoing_recurrence_key`      | uuidv4     | 自动定期付款标识符。                                              | 36     |
| `account_key`                  | uuidv4     | 账户的唯一标识键。                                                | 36     |
| `outgoing_recurrence_status`   | string     | 定期付款的当前状态（`approved`、`pending`、`rejected` 等）。      | 30     |
| `periodicity`                  | enumerator | 定期付款的周期。                                                  | [Enumeradores periodicity](#enumeradores-periodicity) |
| `journey_type`                 | enumerator | 自动定期付款的旅程类型。                                          | [Enumeradores journey_type](#enumeradores-journey_type) |
| `start_date`                   | string     | 定期付款开始日期（ISO 8601 格式，如 `2025-06-10`）。             | 10     |
| `end_date`                     | string     | 定期付款结束日期（ISO 8601 格式）或 null（如为无限期）。          | 10 或 null |
| `outgoing_recurrence_data`     | object     | 汇集订阅参数和补充数据的对象。                                    | [Objeto outgoing_recurrence_data](#objeto-outgoing_recurrence_data) |

---

### Objeto outgoing_recurrence_data

| 字段                        | 类型       | 描述                                             | 字符数 |
|-----------------------------|------------|--------------------------------------------------|--------|
| `minimum_recurrence_amount` | number     | 可变金额定期付款中的最低预期金额。               | -      |
| `recurrence_amount`         | number     | 定期付款金额（固定金额；可变时为 null）。        | -      |
| `retry_configuration`       | object     | 未完成定期付款的重试配置。                       | [Objeto retry_configuration](#objeto-retry_configuration) |
| `debtor_data`               | object     | 债务人（订阅者）数据。                           | [Objeto debtor_data](#objeto-debtor_data) |
| `qr_code_data`              | object     | 为付款生成的 QR 码数据（如有）。                | [Objeto qr_code_data](#objeto-qr_code_data) |
| `initial_payment_data`      | object     | 初始收费数据。                                   | [Objeto initial_payment_data](#objeto-initial_payment_data) |
| `pix_message`               | string     | 随 Pix 交易一起发送的消息。                      | 140    |
| `settlement_date_type`      | enumerator | 结算日期调整类型。                               | [Enumeradores settlement_date_type](#enumeradores-settlement_date_type) |

---

### Objeto pagination

| 字段              | 类型    | 描述                     | 字符数 |
|-------------------|---------|--------------------------|--------|
| `page`            | integer | 返回的页码。             | -      |
| `page_size`       | integer | 每页的项目数。           | -      |
| `number_of_pages` | integer | 总页数。                 | -      |

---

### Enumeradores periodicity

| 枚举值        | 描述     |
|---------------|----------|
| `weekly`      | 每周定期 |
| `monthly`     | 每月定期 |
| `quarterly`   | 每季定期 |
| `semiannual`  | 每半年定期|
| `annual`      | 每年定期 |

---

### Enumeradores journey_type

| 枚举值          | 描述                       |
|-----------------|----------------------------|
| `journey_one`   | 银行应用内直接通知         |
| `journey_two`   | 定期收费的 QR 码体验       |
| `journey_three` | 即时付款 + QR 码定期付款   |
| `journey_four`  | Pix 操作后的定期授权       |

---

### Enumeradores settlement_date_type

| 枚举值           | 描述       |
|------------------|------------|
| `workdays`       | 工作日     |
| `calendar_days`  | 日历天数   |

---

### Enumeradores qr_code_type

| 枚举值             | 描述                   |
|--------------------|------------------------|
| `dynamic_instant`  | 即时付款动态 QR 码     |
| `dynamic_term`     | 未来到期付款动态 QR 码 |

STATUS 4XX

Response Error

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

| HTTP 状态码 | QI 代码<br/>`code` | 标题<br/>`title`       | 描述（英文）<br/>`description`                             | 描述（葡文）<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.                    |

---

# 列出账户的定期付款

URL: /zh-Hans/documentation/baas/pix_automatico/recebedor/listar_recorrencias_de_uma_conta

## 请求

ENDPOINT /account/ ACCOUNT_KEY /outgoing_recurrences
方法 GET

### Query Params

| 字段                          | 类型       | 描述                                                                                    | 字符数 |
|-------------------------------|------------|-----------------------------------------------------------------------------------------|--------|
| `outgoing_recurrence_status`  | enumerador | 按状态筛选定期付款（`approved`、`pending`、`rejected`、`pending_confirmation`）。       | 30     |
| `page`                        | integer    | 要返回的页码（分页）。                                                                  | -      |
| `page_size`                   | integer    | 每页的项目数（分页）。                                                                  | -      |

---

## 响应

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",
          "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

| 字段                   | 类型   | 描述                                     | 字符数 |
|------------------------|--------|------------------------------------------|--------|
| `outgoing_recurrences` | array  | 自动定期付款对象列表。                   | [Array outgoing_recurrences](#array-outgoing_recurrences) |
| `pagination`           | object | 包含结果页面信息的分页对象。             | [Objeto pagination](#objeto-pagination) |

---

### Array outgoing_recurrences

| 字段                           | 类型       | 描述                                                              | 字符数 |
|--------------------------------|------------|-------------------------------------------------------------------|--------|
| `request_control_key`          | uuidv4     | 请求控制的唯一键。                                                | 36     |
| `outgoing_recurrence_key`      | uuidv4     | 自动定期付款标识符。                                              | 36     |
| `outgoing_recurrence_status`   | string     | 定期付款的当前状态（`approved`、`pending`、`rejected` 等）。      | 30     |
| `periodicity`                  | enumerator | 定期付款的周期。                                                  | [Enumeradores periodicity](#enumeradores-periodicity) |
| `journey_type`                 | enumerator | 自动定期付款的旅程类型。                                          | [Enumeradores journey_type](#enumeradores-journey_type) |
| `start_date`                   | string     | 定期付款开始日期（ISO 8601 格式，如 `2025-06-10`）。             | 10     |
| `end_date`                     | string     | 定期付款结束日期（ISO 8601 格式）或 null（如为无限期）。          | 10 或 null |
| `outgoing_recurrence_data`     | object     | 汇集订阅参数和补充数据的对象。                                    | [Objeto outgoing_recurrence_data](#objeto-outgoing_recurrence_data) |

---

### Objeto outgoing_recurrence_data

| 字段                        | 类型       | 描述                                             | 字符数 |
|-----------------------------|------------|--------------------------------------------------|--------|
| `minimum_recurrence_amount` | number     | 可变金额定期付款中的最低预期金额。               | -      |
| `recurrence_amount`         | number     | 定期付款金额（固定金额；可变时为 null）。        | -      |
| `retry_configuration`       | object     | 未完成定期付款的重试配置。                       | [Objeto retry_configuration](#objeto-retry_configuration) |
| `debtor_data`               | object     | 债务人（订阅者）数据。                           | [Objeto debtor_data](#objeto-debtor_data) |
| `qr_code_data`              | object     | 为付款生成的 QR 码数据（如有）。                | [Objeto qr_code_data](#objeto-qr_code_data) |
| `initial_payment_data`      | object     | 初始收费数据。                                   | [Objeto initial_payment_data](#objeto-initial_payment_data) |
| `pix_message`               | string     | 随 Pix 交易一起发送的消息。                      | 140    |
| `settlement_date_type`      | enumerator | 结算日期调整类型。                               | [Enumeradores settlement_date_type](#enumeradores-settlement_date_type) |

---

### Objeto retry_configuration

| 字段            | 类型    | 描述             | 字符数 |
|-----------------|---------|------------------|--------|
| `retry_allowed` | boolean | 是否启用重试。   | -      |
| `retry_rule`    | object  | 重试的详细规则。 | [Objeto retry_rule](#objeto-retry_rule) |

---

### Objeto retry_rule

| 字段           | 类型   | 描述               | 字符数 |
|----------------|--------|--------------------|--------|
| `first_retry`  | object | 第 1 次重试配置。  | [Objeto retry_detail](#objeto-retry_detail) |
| `second_retry` | object | 第 2 次重试配置。  | [Objeto retry_detail](#objeto-retry_detail) |
| `third_retry`  | object | 第 3 次重试配置。  | [Objeto retry_detail](#objeto-retry_detail) |

---

### Objeto retry_detail

| 字段   | 类型   | 描述         | 字符数 |
|--------|--------|--------------|--------|
| `day`  | string | 重试日期。   | -      |
| `time` | string | 重试时间。   | -      |

---

### Objeto debtor_data

| 字段              | 类型   | 描述             | 字符数 |
|-------------------|--------|------------------|--------|
| `name`            | string | 订阅者姓名。     | 50     |
| `email`           | string | 订阅者电子邮件。 | 100    |
| `document_number` | string | CPF 或 CNPJ。   | 14     |
| `address`         | object | 订阅者地址。     | [Objeto address](#objeto-address) |
| `account_data`    | object | 银行数据。       | [Objeto account_data](#objeto-account_data) |

---

### Objeto address

| 字段          | 类型   | 描述       | 字符数 |
|---------------|--------|------------|--------|
| `city`        | string | 城市。     | -      |
| `postal_code` | string | 邮政编码。 | -      |
| `uf`          | string | 州（缩写）。| -     |
| `street`      | string | 街道。     | -      |

---

### Objeto account_data

| 字段             | 类型   | 描述                 | 字符数 |
|------------------|--------|----------------------|--------|
| `account_number` | string | 账户号码。           | -      |
| `account_digit`  | string | 账户校验位。         | -      |
| `account_branch` | string | 支行。               | -      |
| `ispb`           | string | 金融机构 ISPB。      | -      |

---

### Objeto qr_code_data

| 字段             | 类型   | 描述                  | 字符数 |
|------------------|--------|-----------------------|--------|
| `qr_code_key`    | string | 生成 QR 码的标识符。  | -      |
| `qr_code_url`    | string | QR 码查看 URL。       | -      |
| `qr_code_image`  | string | QR 码图像（Base64）。 | -      |

---

### Objeto initial_payment_data

| 字段                       | 类型     | 描述                                         | 字符数 |
|----------------------------|----------|----------------------------------------------|--------|
| `amount`                   | number   | 初始收费的主要金额（巴西雷亚尔 R$）。        | -      |
| `pix_key`                  | string   | 初始付款目标 Pix 键。                        | 77     |
| `qr_code_type`             | enum     | 初始收费的 QR 码类型。                       | [Enumeradores qr_code_type](#enumeradores-qr_code_type) |
| `additional_data`          | array    | 与收费相关的附加信息列表。                   | [Array de objects additional_data](#array-additional_data) |
| `fine_amount`              | number   | 付款逾期时的罚款金额。                       | -      |
| `interest_amount`          | number   | 付款逾期时的利息金额。                       | -      |
| `expiration_date`          | string   | 初始收费到期日期（ISO 8601 格式）。          | 10     |
| `max_payment_days`         | integer  | 到期后的最大受理天数。                       | -      |
| `rebate_amount`            | number   | 提前付款折扣金额。                           | -      |
| `discounts`                | array    | 附加折扣列表。                               | -      |
| `receiver_conciliation_id` | string   | 接收方付款对账标识符。                       | 35     |
| `transaction_data`         | object   | 与初始收费相关的交易详情。                   | [Objeto transaction_data](#objeto-transaction_data) |

---

### Array additional_data

| 字段       | 类型   | 描述                               | 字符数 |
|------------|--------|------------------------------------|--------|
| `key_name` | string | 附加信息名称（如"Juros e Multa"）。| 140    |
| `value`    | string | 附加信息的值或描述。               | 140    |

---

### Objeto transaction_data

| 字段                | 类型   | 描述                  | 字符数 |
|---------------------|--------|-----------------------|--------|
| `transaction_key`   | string | 交易唯一键。          | 36     |
| `pix_transfer_key`  | string | Pix 转账标识符。      | 36     |
| `end_to_end_id`     | string | Pix 端到端标识符。    | 32     |

---

### Objeto pagination

| 字段              | 类型    | 描述                     | 字符数 |
|-------------------|---------|--------------------------|--------|
| `page`            | integer | 返回的页码。             | -      |
| `page_size`       | integer | 每页的项目数。           | -      |
| `number_of_pages` | integer | 总页数。                 | -      |

---

### Enumeradores periodicity

| 枚举值        | 描述     |
|---------------|----------|
| `weekly`      | 每周定期 |
| `monthly`     | 每月定期 |
| `quarterly`   | 每季定期 |
| `semiannual`  | 每半年定期|
| `annual`      | 每年定期 |

---

### Enumeradores journey_type

| 枚举值          | 描述                       |
|-----------------|----------------------------|
| `journey_one`   | 银行应用内直接通知         |
| `journey_two`   | 定期收费的 QR 码体验       |
| `journey_three` | 即时付款 + QR 码定期付款   |
| `journey_four`  | Pix 操作后的定期授权       |

---

### Enumeradores settlement_date_type

| 枚举值           | 描述       |
|------------------|------------|
| `workdays`       | 工作日     |
| `calendar_days`  | 日历天数   |

---

### Enumeradores qr_code_type

| 枚举值             | 描述                   |
|--------------------|------------------------|
| `dynamic_instant`  | 即时付款动态 QR 码     |
| `dynamic_term`     | 未来到期付款动态 QR 码 |

STATUS 4XX

Response Error

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

| HTTP 状态码 | QI 代码<br/>`code` | 标题<br/>`title`       | 描述（英文）<br/>`description`                             | 描述（葡文）<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.                    |

---

# 场景模拟

URL: /zh-Hans/documentation/baas/pix_automatico/recebedor/simulacao

在沙盒环境中模拟 automatic-pix-api 收款方流程的完整指南。本指南包括完整测试流程所需的模拟端点和真实端点。

:::caution 重要前提条件
在执行任何模拟之前，您**必须**使用可用的授权流程之一创建循环扣款。模拟只模拟 SPI 的响应，但循环扣款需要在系统中存在。

**请查阅创建流程：**
- [流程1 - 推送通知](./journey_one.md)
- [流程2 - 二维码（仅循环扣款）](./journey_two.md)
- [流程3 - 二维码（含首次付款）](./journey_three.md)
- [流程4 - 二维码（含首次付款和可变金额）](./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;
  }
}
`}

完整模拟流程
Pix 自动扣款端到端测试 - 沙盒环境
SANDBOX

1
创建循环扣款
真实
任何模拟前的 必要步骤 。选择四种可用流程之一（流程1：推送通知，流程2-4：具有不同配置的二维码）。创建后，保存返回的 outgoing_recurrence_spi_id 。
可用流程： 流程1（推送），流程2（二维码 - 循环扣款），流程3（二维码 + 首次付款），流程4（二维码 + 付款 + 可变金额）

2
批准循环扣款
模拟
模拟 SPI 在收款方流程的不同旅程中发送给 automatic-pix-api 的循环扣款状态更新。使用端点 /mock/outgoing_recurrence/OUTGOING_RECURRENCE_SPI_ID 将状态更新为 pending_confirmation ，然后更新为 approved 。
注意： 在流程2、3和4中，批准时还需要发送账户数据（ account_data ）。在流程3和4中，还需要包含首次付款信息。

3
处理付款订单
模拟
通过端点 /mock/process_payment_orders 模拟付款订单处理。此步骤自动创建对账批次，并将批次创建 webhook 发送到您配置的 URL。
发生了什么： 自动创建订单，根据 reference_date 和循环扣款类型创建或更新对账批次，并触发创建 webhook。

4
查询和对账订单
真实
真实步骤（非模拟）： 查询上一步创建的对账批次，获取 receiver_conciliation_id 和 payment_order_key 。对于 variable_amount 类型的循环扣款，您必须更新付款订单的具体金额。
重要： 此步骤对于 variable_amount 循环扣款是必须的。不更新金额，订单将不会被处理。对于 fixed_amount ，此步骤不是必要的。

5
更新执行日期
模拟
将付款订单的 next_retry_execution_datetime 更新为当前日期，允许立即处理尝试。使用端点 /mock/payment_order/PAYMENT_ORDER_KEY/update_next_retry_execution_datetime 。
仅在沙盒中可用。 此步骤是推进流程并立即处理付款尝试所必需的。

6
处理付款尝试
模拟
通过端点 /mock/process_payment_order_attempts 模拟付款尝试处理。创建自动 PIX 流程所需的尝试，为系统接收入账 PIX 模拟或拒绝做准备。
仅在沙盒中可用。 此步骤后，您可以模拟接收 PIX（步骤7）或拒绝（步骤8）。

结果模拟
  
付款
        7. 模拟入账 Pix
        模拟通过 PIX 成功接收付款
    
拒绝
        7. 模拟拒绝
        模拟付款尝试被拒绝

{`
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);
  });
}
`}

---
## 前提条件：创建循环扣款

:::danger 必须
**此步骤是必须的**，在任何模拟之前。根据您的需求选择循环扣款创建流程之一。
:::

### 选择您的流程

| 流程 | 描述 | 链接 |
|------|------|------|
| **流程1** | 推送通知 - 通过通知授权 | [创建循环扣款：流程1](./journey_one.md) |
| **流程2** | 二维码 - 仅循环扣款授权 | [创建循环扣款：流程2](./journey_two.md) |
| **流程3** | 二维码 - 循环扣款 + 首次付款 | [创建循环扣款：流程3](./journey_three.md) |
| **流程4** | 二维码 - 循环扣款 + 首次付款 + 可变金额 | [创建循环扣款：流程4](./journey_four.md) |

:::info 重要信息
创建循环扣款后，保存返回的 `outgoing_recurrence_spi_id`。模拟时将需要它。
:::

---

## 步骤1：循环扣款更新模拟（模拟）

:::caution 前提条件
**在此步骤之前**，您必须：
1. 使用[创建流程](#前提条件创建循环扣款)之一创建循环扣款
2. 获取创建的循环扣款的 `outgoing_recurrence_spi_id`
:::

此端点模拟 SPI 在收款方流程的不同旅程中发送给 automatic-pix-api 的循环扣款状态更新。

### 请求

ENDPOINT /mock/outgoing_recurrence/ OUTGOING_RECURRENCE_SPI_ID
方法 PATCH

请求体：流程1 - 付款方 PSP 接收请求

```json
{
  "outgoing_recurrence_status": "pending_confirmation"
}
```

请求体：流程1 - 付款方 PSP 接收请求确认

```json
{
  "outgoing_recurrence_status": "approved"
}
```

请求体：流程2、3和4 - 付款方 PSP 接收请求

```json
{
  "outgoing_recurrence_status": "pending_confirmation"
}
```

请求体：流程2 - 付款方 PSP 接收请求确认

```json
{
  "outgoing_recurrence_status": "approved",
  "account_data": {
    "account_number": "123456",
    "account_digit": "7",
    "account_branch": "0001",
    "ispb": "31872495"
  }
}
```

请求体：流程3和4 - 付款方 PSP 接收请求确认

```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
}
```

### 路径参数

| 字段                            | 类型   | 描述                          | 最大字符数 |
|---------------------------------|--------|-------------------------------|------------|
| **outgoing_recurrence_spi_id*** | string | 出站循环扣款的 SPI 标识符      | 50         |

### 请求体对象

| 字段                             | 类型   | 描述                                    | 最大字符数 |
|----------------------------------|--------|-----------------------------------------|------------|
| **outgoing_recurrence_status*** | string | 出站循环扣款状态                         | 50         |
| **account_data**                | object | 账户数据（仅流程2、3和4）               | -          |

### account_data 对象

| 字段               | 类型   | 描述                 | 最大字符数 |
|--------------------|--------|----------------------|------------|
| **account_number*** | string | 账户号码              | 20         |
| **account_digit***  | string | 账户校验位            | 1          |
| **account_branch*** | string | 机构代码              | 6          |
| **ispb***           | string | 金融机构 ISPB 代码    | 8          |

### outgoing_recurrence_status 枚举

| 枚举值                  | 描述         |
|------------------------|--------------|
| **pending_confirmation** | 待确认       |
| **approved**            | 已批准       |

:::info 流程说明
- **流程1**：仅更新状态，不含账户数据
- **流程2**：先仅更新状态，然后更新状态 + 账户数据（仅循环扣款批准）
- **流程3和4**：先仅更新状态，然后更新状态 + 账户数据 + 首次付款数据
:::

:::tip 下一步
批准循环扣款后，继续[步骤3：处理付款订单](#步骤3处理付款订单模拟)
:::

---

## 步骤2：循环扣款取消模拟（模拟 - 可选）

:::caution 前提条件
**在此步骤之前**，您必须：
1. 创建循环扣款
2. 批准循环扣款（[步骤1](#步骤1循环扣款更新模拟)）
:::

此端点模拟由 SPI 触发的出站循环扣款取消。

### 请求

ENDPOINT /mock/outgoing_recurrence/ OUTGOING_RECURRENCE_SPI_ID /cancel
方法 PATCH

:::info 无载荷
此端点没有请求体（载荷）。只需要路径参数。
:::

### 路径参数

| 字段                            | 类型   | 描述                          | 最大字符数 |
|---------------------------------|--------|-------------------------------|------------|
| **outgoing_recurrence_spi_id*** | string | 出站循环扣款的 SPI 标识符      | 50         |

---

## 步骤3：处理付款订单（模拟）

:::caution 前提条件
**在此步骤之前**，您必须：
1. 创建循环扣款
2. 批准循环扣款（[步骤1](#步骤1循环扣款更新模拟)）
:::

此端点模拟付款订单处理，将相应地创建对账批次并发送这些批次的创建 Webhook。

### 请求

ENDPOINT /mock/process_payment_orders
方法 PATCH

:::info 无载荷
此端点没有请求体（载荷）。模拟将自动执行。
:::

:::info 此步骤发生了什么？
1. **付款订单由系统自动创建**
2. **对账批次被创建或更新**（`payment_order_conciliation_batch`）
   - 如果 `reference_date` 和循环扣款类型（'fixed_amount' 或 'variable_amount'）已存在开放批次，则将订单添加到其中
   - 否则，创建新批次
3. **批次创建 webhook 发送**到您配置的 URL
:::

:::tip 下一步
处理订单后，您需要在继续之前**查询和对账**付款订单。请参阅[步骤4](#步骤4查询和对账付款订单)。
:::

---

## 步骤4：查询和对账付款订单

:::danger 必要步骤（非模拟）
**这是一个真实步骤**，不是模拟！您需要查询上一步创建的对账批次，获取 `receiver_conciliation_id` 和 `payment_order_key`，这些将在之后使用。
:::

:::caution 前提条件
**在此步骤之前**，您必须：
1. 处理付款订单（[步骤3](#步骤3处理付款订单模拟)）
2. 收到对账批次创建 webhook
:::

### 4.1 - 查询付款批次

要查询已创建的批次，请使用批次查询端点：

**查阅完整文档：**
- [按账户查询付款批次](../conciliacao/consultar_lote_por_conta.md)
- [按请求方查询付款批次](../conciliacao/consultar_lote_requester.md)

:::info 重要信息
在 GET 响应中，您将找到：
- `payment_order_conciliation_batch_key`：批次密钥
- `payment_orders`：批次内的付款订单列表
- `receiver_conciliation_id`：**保存此值！** 将在步骤7中用于模拟入账 PIX
- `payment_order_spi_id`：付款订单的 SPI 标识符
- `payment_order_key`：付款订单的唯一密钥
:::

### 4.2 - 更新付款订单（可变金额必须）

:::warning 重要
**此步骤对于 `variable_amount` 类型的循环扣款是必须的**。对于固定金额（`fixed_amount`）的循环扣款，此步骤不是必要的。
:::

对于可变金额的循环扣款，您**必须**更新付款订单，提供本周期将收取的具体金额：

**查阅完整文档：**
- [更新付款订单](../pagamentos/atualizar_payment_order.md)

ENDPOINT
/account/ ACCOUNT_KEY /outgoing_recurrence/ OUTGOING_RECURRENCE_KEY /payment_order/ PAYMENT_ORDER_KEY
方法
      PATCH

请求体 - 可变金额示例

```json
{
  "transaction_amount": 150.75,
}
```

### 何时为必须？

| 循环扣款类型 | 更新是否必须？ | 原因 |
|-------------|--------------|------|
| **`fixed_amount`** | 否 | 金额在创建循环扣款时已定义 |
| **`variable_amount`** | **是** | 必须在每次执行时提供金额 |

:::info 信息
- **固定循环扣款**：金额在创建时已定义，不需要更新
- **可变循环扣款**：每次付款处理前必须提供金额
- **不更新**：未更新的可变循环扣款将不会被处理
:::

:::tip 下一步
查询批次并更新付款订单（如需要）后，继续[步骤5](#步骤5更新执行日期模拟)。
:::

---

## 步骤5：更新执行日期（模拟）

:::caution 前提条件
**在此步骤之前**，您必须：
1. 处理付款订单（[步骤3](#步骤3处理付款订单模拟)）
2. 查询对账批次（[步骤4](#步骤4查询和对账付款订单)）
3. 获取付款订单的 `payment_order_key`
:::

此端点允许将特定付款订单的 `next_retry_execution_datetime` 更新为当前日期，使订单尝试处理能够立即进行。

:::info 仅限沙盒
此端点**仅在沙盒环境中可用**。
:::

### 请求

ENDPOINT /mock/payment_order/ payment_order_key /update_next_retry_execution_datetime
方法 PATCH

### 路径参数

| 字段                   | 类型  | 描述                      | 最大字符数 |
|------------------------|-------|---------------------------|------------|
| **payment_order_key*** | uuid4 | 付款订单唯一标识键         | 36         |

请求体

```json
{
  "next_retry_execution_datetime": "2025-08-22"
}
```

### 请求体参数

| 字段                               | 类型   | 描述                                   | 最大字符数 |
|------------------------------------|--------|----------------------------------------|------------|
| **next_retry_execution_datetime*** | string | 订单的新执行日期（格式 YYYY-MM-DD）     | 10         |

:::info 目的
此端点将下次尝试的执行日期更新为当前日期，允许系统立即处理付款尝试，这是模拟入账 PIX 接收所必需的。
:::

:::tip 下一步
更新执行日期后，继续[步骤6](#步骤6处理付款尝试模拟)。
:::

---

## 步骤6：处理付款尝试（模拟）

:::caution 前提条件
**在此步骤之前**，您必须：
1. 更新执行日期（[步骤5](#步骤5更新执行日期模拟)）
:::

此端点模拟付款尝试处理，创建自动 PIX 流程所需的尝试。

:::info 仅限沙盒
此端点**仅在沙盒环境中可用**。
:::

### 请求

ENDPOINT /mock/process_payment_order_attempts
方法 PATCH

:::info 无载荷
此端点没有请求体（载荷）。模拟将自动执行。
:::

:::info 目的
此端点根据已更新执行日期的付款订单处理付款尝试，创建模拟入账 PIX 接收所需的尝试。
:::

:::tip 下一步 - 选择您的路径

**成功流程**：继续[步骤7：模拟入账 PIX](#步骤7模拟入账pix)

**拒绝流程**：继续[步骤8：模拟拒绝尝试](#步骤8模拟拒绝的付款尝试模拟)
:::

---

## 步骤7：模拟入账 Pix

:::caution 前提条件
**在此步骤之前**，您必须：
1. 更新执行日期（[步骤5](#步骤5更新执行日期模拟)）
2. 处理付款尝试（[步骤6](#步骤6处理付款尝试模拟)）
3. 从批次获取 `receiver_conciliation_id`（[步骤4](#步骤4查询和对账付款订单)）
4. 获取 `outgoing_recurrence_spi_id` 和 `payment_order_spi_id`
:::

此端点模拟接收将与循环扣款付款订单关联的 Pix。

### 请求

ENDPOINT /mock/automatic_pix/incoming_pix
方法 POST

请求体

```json
{
  "target_account_key": "23a4a2c8-9d82-4ebe-a90d-44fe8d839ec0",
  "amount": 1000.00,
  "receiver_conciliation_id": "7535f0467d9a4af69c4d99408c2fec9d"
}
```

### 请求体对象

| 字段                          | 类型   | 描述                                          | 最大字符数 |
|-------------------------------|--------|-----------------------------------------------|------------|
| **target_account_key***       | string | 目标账户唯一密钥                               | 36         |
| **amount***                   | number | PIX 交易金额                                   | -          |
| **receiver_conciliation_id*** | string | 收款方对账标识（在步骤4获取）                  | 35         |

:::info 信息
此端点模拟完整的入账 Pix 流程，包括：
1. 处理 Pix 转账
2. 使用 `receiver_conciliation_id` 与 automatic-pix 付款订单关联
:::

:::success 流程完成！
恭喜！您已完成成功付款流程。系统处理了：
- 创建循环扣款
- 批准循环扣款
- 创建付款订单和批次
- 处理尝试
- 接收 PIX
:::

---

## 步骤8：模拟拒绝的付款尝试（模拟）

:::caution 前提条件
**在此步骤之前**，您必须：
1. 处理付款订单（[步骤3](#步骤3处理付款订单模拟)）
2. 更新执行日期（[步骤5](#步骤5更新执行日期模拟)）
3. 处理付款尝试（[步骤6](#步骤6处理付款尝试模拟)）
4. 获取 `outgoing_recurrence_spi_id` 和 `payment_order_spi_id`
:::

此端点模拟出站循环扣款中 PIX 付款尝试的拒绝，复制 SPI 拒绝交易时的行为。系统将自动创建付款尝试并模拟被拒绝的 PIX，导致发送尝试状态变更 webhook。

### 请求

ENDPOINT /mock/automatic_pix/outgoing_recurrence/ OUTGOING_RECURRENCE_SPI_ID /payment_order/ PAYMENT_ORDER_SPI_ID
方法 PATCH

请求体：尝试被拒绝

```json
{
  "payment_order_status": "rejected",
  "rejection_information": {
    "bacen_reason_code": "AC06"
  }
}
```

### 路径参数

| 字段                            | 类型   | 描述                          | 最大字符数 |
|---------------------------------|--------|-------------------------------|------------|
| **outgoing_recurrence_spi_id*** | string | 出站循环扣款的 SPI 标识符      | 50         |
| **payment_order_spi_id***      | string | 付款订单的 SPI 标识符          | 50         |

### 请求体对象

| 字段                          | 类型   | 描述                                     | 最大字符数 |
|-------------------------------|--------|------------------------------------------|------------|
| **payment_order_status***     | string | 付款订单状态（始终为 "rejected"）         | 50         |
| **rejection_information***    | object | 拒绝信息                                 | -          |

### rejection_information 对象

| 字段                   | 类型   | 描述                     | 最大字符数 |
|------------------------|--------|--------------------------|------------|
| **bacen_reason_code*** | string | 拒绝的 Bacen 错误代码    | 4          |

### 常见 Bacen 错误代码

| 代码   | 英文描述                                  | 葡萄牙语描述                                     |
|--------|-------------------------------------------|--------------------------------------------------|
| **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 系统运作
1. **拒绝模拟**：系统使用指定的错误代码模拟被拒绝的 PIX
2. **发送 Webhook**：每次被拒绝的尝试，都会发送 webhook `baas.automatic_pix.payment_order_attempt.status_change`
3. **多次尝试**：系统允许最多4次付款尝试。第4次尝试被拒绝后，付款订单状态更改为 "rejected"
:::

:::info 结果 Webhook
每次被拒绝的尝试将生成以下格式的 webhook：
```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"
  }
}
```
:::

### 多次尝试流程

1. **第1次尝试**：付款订单保持 "pending" 状态，尝试状态 "rejected"
2. **第2次尝试**：付款订单保持 "pending" 状态，创建新尝试
3. **第3次尝试**：付款订单保持 "pending" 状态，创建新尝试
4. **第4次尝试**：付款订单更改为 "rejected" 状态（达到最大限制）

---

## 流程摘要

### 完整成功流程

| 步骤 | 描述 | 流程类型 | 文档 |
|------|------|----------|------|
| 0 | 创建循环扣款 | **真实** | [创建流程](#前提条件创建循环扣款) |
| 1 | 批准循环扣款 | 模拟 | [查看详情](#步骤1循环扣款更新模拟) |
| 3 | 处理付款订单 | 模拟 | [查看详情](#步骤3处理付款订单模拟) |
| 4 | 查询和对账订单 | **真实** | [查询批次](../conciliacao/consultar_lote_por_conta.md) |
| 5 | 更新执行日期 | 模拟 | [查看详情](#步骤5更新执行日期模拟) |
| 6 | 处理尝试 | 模拟 | [查看详情](#步骤6处理付款尝试模拟) |
| 7 | 模拟入账 PIX | 模拟 | [查看详情](#步骤7模拟入账pix) |

### 完整拒绝流程

| 步骤 | 描述 | 流程类型 | 文档 |
|------|------|----------|------|
| 0 | 创建循环扣款 | **真实** | [创建流程](#前提条件创建循环扣款) |
| 1 | 批准循环扣款 | 模拟 | [查看详情](#步骤1循环扣款更新模拟) |
| 3 | 处理付款订单 | 模拟 | [查看详情](#步骤3处理付款订单模拟) |
| 4 | 查询和对账订单 | **真实** | [查询批次](../conciliacao/consultar_lote_por_conta.md) |
| 5 | 更新执行日期 | 模拟 | [查看详情](#步骤5更新执行日期模拟) |
| 6 | 处理尝试 | 模拟 | [查看详情](#步骤6处理付款尝试模拟) |
| 8 | 模拟拒绝 | 模拟 | [查看详情](#步骤8模拟拒绝的付款尝试模拟) |

---

## 实用链接

### 循环扣款管理
- [查询循环扣款](./consultar_recorrencia.md)
- [通过二维码查询循环扣款](./consultar_recorrencia_receiver.md)
- [列出账户的循环扣款](./listar_recorrencias_de_uma_conta.md)
- [取消循环扣款](./cancelar_recorrencia.md)

### 付款管理
- [列出付款订单](../pagamentos/listar_account_payment_orders.md)
- [查询付款订单](../pagamentos/consultar_payment_order.md)
- [更新付款订单](../pagamentos/atualizar_payment_order.md)
- [取消付款订单](../pagamentos/cancelar_payment_order.md)

### 对账批次
- [按账户查询批次](../conciliacao/consultar_lote_por_conta.md)
- [按请求方查询批次](../conciliacao/consultar_lote_requester.md)
- [列出批次付款](../conciliacao/listar_payment_orders.md)
- [对账 Webhooks](../conciliacao/webhooks.md)

### Webhooks
- [收款用户 Webhooks](./webhooks.md)
- [对账批次 Webhooks](../conciliacao/webhooks.md)

---

# Pix 自动支付 Webhooks

URL: /zh-Hans/documentation/baas/pix_automatico/recebedor/webhooks

Webhook 通知对于正确处理与 Pix 自动支付相关的异步事件至关重要，尤其是不同旅程类型的定期付款授权和执行。

:::danger 注意！
QI Tech 的 Webhooks 不应以限制性方式映射。
我们 API 返回的 Webhook 载荷中可能会添加额外字段。
:::

## 定期付款状态 Webhook

此 Webhook 用于报告 Pix 自动支付授权和定期付款周期的状态变更，区分不同的旅程类型。

### Webhook Request Body

### 旅程 1 – journey_one

Request Body: 旅程 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"
  }
}
```

### 旅程 2 – journey_two

Request Body: 旅程 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
    }
}
```

### 旅程 3 – journey_three

Request Body: 旅程 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
        }
    }
}
```

### 旅程 4 – journey_four

Request Body: 旅程 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 注意
当付款用户收到通知时，可以选择调度 Pix 或立即进行转账。如果付款人立即付款，将发送包含已填写信息的 `baas.automatic_pix.outgoing_recurrence.status_change` 类型 Webhook；如果是调度，相关值将为 `null`。
:::

### Webhook Body Params

| 字段            | 类型   | 描述                                                                                      | 字符数 |
|-----------------|--------|-------------------------------------------------------------------------------------------|--------|
| `event_type` *  | string | 报告的事件类型（如 `baas.automatic_pix.outgoing_recurrence.status_change`）。             | 100    |
| `origin_key` *  | string | 事件的唯一来源标识符（UUID）。                                                            | 36     |
| `data` *        | Object | 包含自动定期付款详情的主对象。                                                            | [Objeto data](#objeto-data) |

---

### Objeto data

| 字段                              | 类型       | 描述                                                               | 字符数 |
|-----------------------------------|------------|--------------------------------------------------------------------|--------|
| `request_control_key` *           | string     | 请求的唯一控制键（UUID4）。                                        | 36     |
| `outgoing_recurrence_key` *       | string     | 自动定期付款的唯一标识符（UUID）。                                 | 36     |
| `outgoing_recurrence_status` *    | string     | 定期付款的状态（如 `approved`、`pending`、`rejected` 等）。        | 30     |
| `journey_type` *                  | enumerator | Pix 自动支付授权的对应旅程类型（`journey_one`、`journey_two` 等）。| [Enumeradores journey_type](#enumeradores-journey_type) |
| `outgoing_recurrence_data` *      | Object     | 包含定期付款和旅程特定信息的对象。                                 | [Objeto outgoing_recurrence_data](#objeto-outgoing_recurrence_data) |
| `payment_conciliation_batch_key`  | string     | 付款对账的分组标识符。可以为 null。                               | 36 或 null |
| `qr_code_initial_payment_data`    | Object     | （旅程 3 和 4）初始 QR 码付款数据详情（如有）。                   | [Objeto qr_code_initial_payment_data](#objeto-qr_code_initial_payment_data) |

---

### Objeto outgoing_recurrence_data

| 字段                              | 类型   | 描述                                                     | 字符数 |
|-----------------------------------|--------|----------------------------------------------------------|--------|
| `minimum_recurrence_amount`       | number | 授权定期付款的最低金额。                                 | -      |
| `recurrence_amount`               | number | 定期付款总金额（不适用时可为 null）。                    | -      |
| `qr_code_initial_payment_data`    | Object | （旅程 3）使用 QR 码时初始付款的详细数据。               | [Objeto qr_code_initial_payment_data](#objeto-qr_code_initial_payment_data) |
| `payment_conciliation_batch_key`  | string | 付款批次/对账标识符。                                    | 36     |

---

### Objeto qr_code_initial_payment_data

| 字段                       | 类型   | 描述                                   | 字符数 |
|----------------------------|--------|----------------------------------------|--------|
| `receiver_conciliation_id` | string | 接收方对账的唯一标识符。               | -      |
| `transaction_data`         | Object | 与初始 QR 码关联的交易详情。           | [Objeto transaction_data](#objeto-transaction_data) |

---

### Objeto transaction_data

| 字段                | 类型   | 描述                          | 字符数 |
|---------------------|--------|-------------------------------|--------|
| `transaction_key`   | string | 交易唯一键。                  | 36     |
| `pix_transfer_key`  | string | 关联 Pix 转账的标识符。       | 36     |
| `end_to_end_id`     | string | Pix 端到端标识符。            | 32     |

---

### Enumeradores journey_type

| 枚举值          | 描述                       |
|-----------------|----------------------------|
| `journey_one`   | 银行应用内直接通知         |
| `journey_two`   | 定期收费的 QR 码体验       |
| `journey_three` | 即时付款 + QR 码定期付款   |
| `journey_four`  | Pix 操作后的定期授权       |

## 付款订单状态 Webhook

此 Webhook 用于报告 Pix 自动支付付款订单的状态变更，包括取消、已付款和拒绝。

### Webhook Request Body

### 状态：已取消（cancelled）

Request Body: 付款订单已取消

```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"
  }
}
```

### 状态：已付款（paid）

Request Body: 付款订单已付款

```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"
  }
}
```

### 状态：已拒绝（rejected）

Request Body: 付款订单已拒绝

```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 信息
被拒绝的付款订单在达到最大重试次数后发送（如定期付款允许重试）。此时，`transaction_key` 和 `incoming_pix_transfer_key` 字段不包含在载荷中。
:::

### Webhook Body Params - Payment Order

| 字段            | 类型   | 描述                                                                              | 字符数 |
|-----------------|--------|-----------------------------------------------------------------------------------|--------|
| `event_type` *  | string | 报告的事件类型（`baas.automatic_pix.payment_order.status_change`）。              | 100    |
| `origin_key` *  | string | 事件的唯一来源标识符（付款订单的 UUID）。                                         | 36     |
| `data` *        | Object | 包含付款订单详情的主对象。                                                        | [Objeto data](#objeto-data-payment-order) |

---

### Objeto data (Payment Order)

| 字段                                    | 类型   | 描述                                                                              | 字符数 |
|-----------------------------------------|--------|-----------------------------------------------------------------------------------|--------|
| `payment_order_key` *                   | string | 付款订单的唯一键（UUID）。                                                        | 36     |
| `payment_order_spi_id` *                | string | 付款订单的 SPI 标识符。                                                           | 29     |
| `outgoing_recurrence_key` *             | string | 关联的自动定期付款的唯一标识符（UUID）。                                          | 36     |
| `payment_order_status` *                | string | 付款订单状态（`cancelled`、`paid`、`rejected`）。                                 | 30     |
| `receiver_conciliation_id` *            | string | 接收方对账标识符（UUID）。                                                        | 36     |
| `transaction_amount` *                  | number | 付款订单的交易金额。                                                              | -      |
| `payment_order_conciliation_batch_key` *| string | 关联的对账批次标识符（UUID）。                                                    | 36     |
| `transaction_key`                       | string | 交易唯一键（仅出现在 `cancelled` 和 `paid` 状态时）。                            | 36     |
| `incoming_pix_transfer_key`             | string | 入账 Pix 转账标识符（仅出现在 `cancelled` 和 `paid` 状态时）。                   | 36     |
| `paid_at`                               | string | 付款日期和时间（仅出现在 `paid` 状态时，ISO 8601 格式）。                         | -      |

---

### Enumeradores payment_order_status

| 枚举值        | 描述                       |
|---------------|----------------------------|
| `cancelled`   | 付款订单被付款方或接收方取消。 |
| `paid`        | 付款订单成功执行。          |
| `rejected`    | 付款订单在重试耗尽后被拒绝。 |

## 付款订单尝试状态 Webhook

此 Webhook 用于报告 Pix 自动支付付款订单执行尝试的状态变更，尤其是拒绝尝试及拒绝原因。

### Webhook Request Body

### 状态：已拒绝（rejected）

Request Body: 付款订单尝试已拒绝

```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 信息
每当付款订单的执行尝试被 SPI 拒绝时，都会发送此 Webhook。根据定期付款配置和拒绝原因，付款订单可能会有新的尝试。`reason` 字段包含基于 Bacen 错误代码的拒绝原因描述。
:::

### Webhook Body Params - Payment Order Attempt

| 字段            | 类型   | 描述                                                                                       | 字符数 |
|-----------------|--------|--------------------------------------------------------------------------------------------|--------|
| `event_type` *  | string | 报告的事件类型（`baas.automatic_pix.payment_order_attempt.status_change`）。               | 100    |
| `origin_key` *  | string | 事件的唯一来源标识符（付款订单的 UUID）。                                                  | 36     |
| `data` *        | Object | 包含付款订单尝试详情的主对象。                                                             | [Objeto data](#objeto-data-payment-order-attempt) |

---

### Objeto data (Payment Order Attempt)

| 字段                              | 类型   | 描述                                                                   | 字符数 |
|-----------------------------------|--------|------------------------------------------------------------------------|--------|
| `request_control_key` *           | string | 请求的唯一控制键（付款订单的 UUID）。                                  | 36     |
| `payment_order_key` *             | string | 关联的付款订单的唯一键（UUID）。                                       | 36     |
| `payment_order_attempt_key` *     | string | 付款尝试的唯一键（UUID）。                                             | 36     |
| `payment_order_status` *          | string | 付款订单的当前状态（`pending`、`accepted`、`cancelled` 等）。          | 30     |
| `payment_order_attempt_status` *  | string | 付款尝试的状态（`rejected`）。                                         | 30     |
| `transaction_amount` *            | number | 付款尝试的交易金额。                                                   | -      |
| `reason` *                        | string | 尝试拒绝原因（基于 Bacen 错误代码的错误描述）。                        | 200    |
| `outgoing_recurrence_key` *       | string | 关联的自动定期付款的唯一标识符（UUID）。                               | 36     |

---

### Enumeradores payment_order_attempt_status

| 枚举值        | 描述                       |
|---------------|----------------------------|
| `rejected`    | 付款尝试因特定错误被 SPI 拒绝。 |

## 未结算的付款订单尝试 Webhook

此 Webhook 用于通知付款订单尝试已被接受但未在预期时间内结算。

### Webhook Request Body

Request Body: 未结算的付款订单尝试

```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

| 字段                                    | 类型   | 描述                                               | 最大字符数 |
|-----------------------------------------|--------|---------------------------------------------------|------------|
| `webhook_type`                          | string | 定义报告事件类型的枚举值。                        | 100        |
| `webhook_datetime`                      | string | Webhook 发送日期和时间。                          | 20         |
| `payment_order_key`                     | uuid4  | 付款订单的唯一标识键。                            | 36         |
| `payment_order_spi_id`                  | string | SPI 中付款订单的标识符。                          | 50         |
| `outgoing_recurrence_key`               | uuid4  | 关联的出账定期付款的唯一标识键。                  | 36         |
| `payment_order_status`                  | string | 付款订单的当前状态。                              | [Enumeradores payment_order_status](#enumeradores-payment_order_status) |
| `receiver_conciliation_id`              | string | 接收方对账标识。                                  | 36         |
| `transaction_amount`                    | number | 付款订单的交易金额。                              | -          |
| `payment_order_conciliation_batch_key`  | uuid4  | 关联的对账批次的唯一标识键。                      | 36         |
| `payment_order_attempt_key`             | uuid4  | 付款订单尝试的唯一标识键。                        | 36         |
| `payment_order_attempt_status`          | string | 付款订单尝试的状态。                              | [Enumeradores payment_order_attempt_status](#enumeradores-payment_order_attempt_status) |
| `due_date`                              | string | 付款订单尝试的到期日期（YYYY-MM-DD 格式）。       | 10         |
| `end_to_end_id`                         | string | SPI 内 Pix 交易的幂等键。                         | 32         |

### Enumeradores payment_order_status

| 枚举值                 | 描述               |
|------------------------|--------------------|
| `pending_conciliation` | 等待对账。         |
| `pending`              | 待付款。           |
| `paid`                 | 成功付款。         |
| `rejected`             | 已拒绝，不会处理。 |
| `cancelled`            | 付款前已取消。     |

### Enumeradores payment_order_attempt_status

| 枚举值          | 描述                             |
|-----------------|----------------------------------|
| `sent`          | 付款尝试已发送。                 |
| `accepted`      | 付款尝试已接受。                 |
| `rejected`      | 付款尝试因特定错误被 SPI 拒绝。  |
| `not_liquidated`| 付款尝试已接受但未在预期时间内结算。|

---

# 批准双因素身份验证交易

URL: /zh-Hans/documentation/baas/pix/2fa_v2/aprovar_transacao_pix_2fa

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_transfer/ PIX_TRANSFER_KEY /validate_token
MÉTODO PUT

### 路径参数

| 字段              | 类型   | 描述                                      | 字符数 |
|-------------------|--------|------------------------------------------------|------------|
| `account_key`      | uuidv4 | 账户唯一标识键。         | 36         |
| `pix_transfer_key` | uuidv4 | Pix 交易唯一标识键。 | 36         |

## 通过 Email 和 SMS 进行身份验证

Request Body

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

## 通过设备进行身份验证

要批准并完成设备身份验证，请求必须以空 payload 发送。验证在内部进行，请求体中不需要额外信息。需要注意的是，此端点只能在[交易申请](./solicitacao_de_transacao_pix_2fa.md)发起后使用。

Request Body

```json
{

}
```

## Body 参数

| 字段     | 类型   | 描述                                                             | 字符数 |
|-----------|--------|-----------------------------------------------------------------------|------------|
| `token`   | string | 发送给账户交易审批人的身份验证代码，**SMS 或 email TFA 必填**| 6          | 

## Response

STATUS 201

Response Body: 转账已发送

```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: 转账待处理

```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: 转账已拒绝

```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": {}
}
```

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                 | 描述（英文）<br/>`description`                                                                                       | 描述（葡文）<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                      | 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.                                                                         |
| 400                      | PXT000109            | Bad Request                                        | request_control_key \{request_control_key\} already in use                                                              | request_control_key \{request_control_key\} já utilizada                                                               |
| 400                      | PXT000189            | Token Required                                | A token is required for SMS or email validation.                    | Um token é necessário para validação via SMS ou email.             |

---

# 双因素认证简介

URL: /zh-Hans/documentation/baas/pix/2fa_v2/introducao_a_transacao_pix_2fa

在此类交易中，需要通过向具有贷方账户转账审批权限的人员发送令牌来确认付款。

配置为使用双因素认证的集成合作方发起 Pix 交易请求的方式与[执行 Pix 交易](/documentation/baas/pix/realizar_transferencia)中描述的方式类似。区别在于增加了 `tfa_info` 对象，包含审批人信息和联系方式，以及成功请求的状态始终为 **pending_2fa_approval**。

对于[批量 Pix 交易](/documentation/baas/pix/batch/solicitacao_de_transacao_em_lote_pix)同样适用。

## 带授权的 Pix 交易流程

成功的 Pix 交易将遵循以下流程：
发起 [Pix 交易请求](/documentation/baas/pix/2fa_v2/solicitacao_de_transacao_pix_2fa)，同步接收状态为 **pending_2fa_approval** 的响应以及 `pix_transfer_key` 的值。
指定的审批人将收到一个由数字组成的 6 位 `token`。
请求方使用 `pix_transfer_key` 和 `token` 进行 [Pix 交易确认](/documentation/baas/pix/2fa_v2/aprovar_transacao_pix_2fa)。
转账将以同步或异步方式完成，具体取决于集成合作方的配置。
## 注意事项
每笔交易的 `token` 验证最大尝试次数为 5 次。达到此限制时，交易将自动进入拒绝状态（**rejected**）。
每个 `token` 的最大有效时长为 5 分钟。
交易的 `token` 可以重新生成并发送给转账审批人。此过程会重置 5 分钟计时器，但不会重置无效尝试次数计数器。之前的 `token` 将失效。
交易一旦批准，将以同步或异步方式完成，具体取决于集成合作方的配置。
向审批人发送 `token` 的通知事件为 **baas.token_validation.pix_transfer.single**。可以[自定义](/documentation/notificacoes/template)发送的消息。
已实现的令牌发送方式（`contact_type`）为 **sms** 和 **email**。

---

# 申请退还已收到的 Pix

URL: /zh-Hans/documentation/baas/pix/2fa_v2/solicitacao_de_devolucao_pix

Pix 退款可在收到后 90 天内进行。

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_transfer/ PIX_TRANSFER_KEY /reversal
MÉTODO POST

### 路径参数

| 字段                | 类型   | 描述                                                        | 字符数 |
|----------------------|--------|------------------------------------------------------------------|------------|
| `account_key` *      | uuidv4 | 账户唯一标识键。                           | 36         |
| `pix_transfer_key` * | uuidv4 | QI 系统中 Pix 转账的唯一标识键。 | 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_control_key` * | uuidv4 | 请求唯一性键。                                               | 36                                                            |
| `reversal_amount` *     | number | 退款金额。                                                             | 11                                                            |
| `reversal_reason` *     | string | 退款原因。                                                            | **[reversal_reason 枚举值](#enumerador-reversal_reason)** |
| `reversal_message`      | string | 退款消息。                                                          | 140                                                           |
| `tfa_info`*             | Object | 包含账户审批人文件号码和联系方式的对象。 | **[tfa_info 对象](#objeto-tfa_info)**                       |

### reversal_reason 枚举值

| 枚举值         | 描述                                     |
|--------------------|-----------------------------------------------|
| **client_request** | 账户持有人申请的情况。 |
| **reconciliation** | 因操作错误进行对账。 |

### tfa_info 对象

| 字段                       | 类型   | 描述                                                                           | 字符数 |
|-----------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `approver_document_number`* | string | 账户审批人的文件号码。                                  | 11         | 
| `contact_type`*             | string | 与账户审批人的联系方式，可以是 **sms** 或 **email** |            |

## Response

STATUS 202

Response Body: 退款已申请

```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

| 字段                 | 类型       | 描述                                                       | 字符数                                                |
|-----------------------|------------|-----------------------------------------------------------------|-----------------------------------------------------------|
| `reversal_status`     | enumerator | 退款交易状态枚举值。                 | [reversal_status 枚举值](#enumerador-reversal_status) |
| `transfer_amount`     | number     | 退款转账金额。                            | 11                                                        |
| `pix_transfer_key`    | uuidv4     | 退款中执行的 Pix 交易键。                  | 36                                                        |
| `request_control_key` | uuidv4     | 客户使用的请求唯一标识键。 | 36                                                        |
| `created_at`          | string     | 退款日期和时间。                                       | 10                                                        |

### reversal_status 枚举值

| 枚举值               | 描述                                                |
|--------------------------|----------------------------------------------------------|
| **sent**                 | Pix 转账已成功完成。                 |
| **pending**              | Pix 转账待处理。                              |
| **pending_2fa_approval** | Pix 转账待双因素审批 |
| **rejected**             | Pix 转账已拒绝。                             |

STATUS 4xx

Response Body: 退款已拒绝

```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 信息
除了之前列出的 [Pix 转账](/documentation/baas/pix/realizar_transferencia) 错误外，Pix 退款还可能返回以下错误。
:::

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                   | 描述（英文）<br/>`description`                                      | 描述（葡文）<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                                        |

---

# 申请为交易重新发送令牌

URL: /zh-Hans/documentation/baas/pix/2fa_v2/solicitacao_de_reenvio_de_token

将为 Pix 交易审批人生成并发送新令牌。如果已超过令牌验证尝试次数上限，则不允许重新发送。

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_transfer/ PIX_TRANSFER_KEY /resend_token
MÉTODO PATCH

### Path Params

| 字段                  | 类型   | 描述                                                         | 字符数 |
|-----------------------|--------|--------------------------------------------------------------|--------|
| `account_key` *       | uuidv4 | 账户的唯一标识键。                                            | 36     |
| `pix_transfer_key` *  | uuidv4 | QI 系统中 Pix 转账的唯一标识键。                              | 36     |

### Body Params

| 字段           | 类型       | 描述                                    | 字符数 |
|----------------|------------|-----------------------------------------|--------|
| `contact_type` | enumerator | 认证令牌的发送方式 | **[Enumerador contact_type](#enumerador-contact_type)** |

:::info 信息
如果未发送 `contact_type`，令牌将以最初请求的方式发送。
:::

| 枚举值     | 描述                     |
|------------|--------------------------|
| **sms**    | 发送至手机的短信          |
| **email**  | 发送至电子邮件            |

## Response

STATUS 202

Response Body: 交易已申请

```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: 转账已拒绝

```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"
    }
  }
}
```

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                           | 描述（英文）<br/>`description`                                          | 描述（葡文）<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                   |

---

# 请求双因素认证交易

URL: /zh-Hans/documentation/baas/pix/2fa_v2/solicitacao_de_transacao_pix_2fa

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_transfer
MÉTODO POST

### Path Params

| 字段          | 类型   | 描述                               | 字符数 |
|---------------|--------|------------------------------------|--------|
| `account_key` | uuidv4 | 账户的唯一标识键。                  | 36     |

**Chave**
## 通过邮件和短信认证
Request Body: 通过 Pix 密钥转账（短信或邮件 TFA）

```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"
  }
}
```

## 通过设备认证

除了现有的**短信**和**邮件**认证方式外，还可以使用[预先注册的设备](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo)对交易进行认证。此时，`session_id` 需从 **Device Scan** 获取并在 `tfa_info` 中发送。
Request Body: 通过 Pix 密钥转账（设备 TFA）

```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

| 字段                    | 类型       | 描述                                                                                                                                                                                                                                               | 字符数                                 |
|-------------------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------|
| `request_control_key` * | uuidv4     | 客户使用的请求唯一标识键，uuid v4 格式。                                                                                                                                                                                                            | 36                                     | 
| `pix_transfer_type` *   | enumerator | 要执行的 Pix 类型。密钥转账时应为 **key**。                                                                                                                                                                                                          | **key**                                |
| `target_pix_key` *      | string     | 目标账户的 Pix 密钥。                                                                                                                                                                                                                               | 100                                    |
| `transaction_amount` *  | number     | 转账金额。                                                                                                                                                                                                                                          | 10                                     |
| `end_to_end_id` *       | string     | SPI（即时支付系统）内 Pix 交易的幂等键。此键在 Pix 密钥查询中返回。仅当 `pix_transfer_type` 为 **key**、**static_qr_code** 或 **static_qr_code** 时发送 | 32                                     |
| `pix_message`           | string     | 随 Pix 转账发送的消息。                                                                                                                                                                                                                              | 140                                    |
| `tfa_info`*             | Object     | 包含账户审批人文件及联系方式的对象。                                                                                                                                                                                                                 | **[Objeto tfa_info](#objeto-tfa_info)** |

**Manual**
## 通过邮件和短信认证
Request Body: 手动转账（短信或邮件 TFA）

```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"
  }
}
```

## 通过设备认证

除了现有的**短信**和**邮件**认证方式外，还可以使用[预先注册的设备](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo)对交易进行认证。此时，`session_id` 需从 **Device Scan** 获取并在 `tfa_info` 中发送。

Request Body: 手动转账（设备 TFA）

```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

| 字段                    | 类型       | 描述                                                                                            | 字符数                                              |
|-------------------------|------------|------------------------------------------------------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | uuidv4     | 客户使用的请求唯一标识键，uuid v4 格式。                                                         | 36                                                  | 
| `pix_transfer_type` *   | enumerator | Pix 转账类型。                                                                                   | **manual**                                          |
| `target_account` *      | Object     | 目标账户 - 仅在 `pix_transfer_type` 为 **manual** 时发送。 | **[Objeto target_account](#objeto-target_account)** | 10 |
| `transaction_amount` *  | number     | 转账金额。                                                                                       | 10                                                  |
| `pix_message`           | string     | 随 Pix 转账发送的消息。                                                                          | 140                                                 |
| `tfa_info`*             | Object     | 包含账户审批人文件及联系方式的对象。                                                              | **[Objeto tfa_info](#objeto-tfa_info)**             |

### Objeto target_account

| 字段                      | 类型       | 描述                                             | 字符数                                                   |
|---------------------------|------------|--------------------------------------------------|----------------------------------------------------------|
| `account_branch` *        | string     | 账户机构编号。                                    | 4                                                        |
| `account_digit` *         | string     | 账户数字。                                        | 1                                                        |
| `account_number` *        | string     | 账户号码。                                        | 20                                                       |
| `owner_document_number` * | string     | 账户持有人 CPF 或 CNPJ（仅数字）。                 | 14                                                       |
| `owner_name` *            | string     | 账户持有人姓名。                                   | 150                                                      |
| `account_type`*           | enumerator | 账户类型。                                        | **[Enumerador account_type](#enumerador-account_type)**  |
| `ispb` *                  | string     | 金融机构 8 位识别码（ISPB）。                      | 8                                                        |

### Enumerador account_type

| 枚举值               | 描述           |
|----------------------|----------------|
| **checking_account** | 支票账户       |
| **salary_account**   | 薪资账户       |
| **saving_account**   | 储蓄账户       |
| **payment_account**  | 付款账户       |

**Qr Code**
## 通过邮件和短信认证
Request Body: 通过 QR Code 转账（短信或邮件 TFA）

```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"
  }
}
```

## 通过设备认证

除了现有的**短信**和**邮件**认证方式外，还可以使用[预先注册的设备](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo)对交易进行认证。此时，`session_id` 需从 **Device Scan** 获取并在 `tfa_info` 中发送。

Request Body: 通过 QR Code 转账（设备 TFA）

```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

| 字段                       | 类型       | 描述                                                                                                                                                                                                                                                 | 字符数                                    |
|----------------------------|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|
| `request_control_key`*     | uuidv4     | 客户使用的请求唯一标识键，uuid v4 格式。                                                                                                                                                                                                               | 36                                        | 
| `pix_transfer_type`*       | enumerator | Pix 转账类型。                                                                                                                                                                                                                                         | **static_qr_code** 或 **dynamic_qr_code** |
| `target_pix_key`*          | string     | 目标账户的 Pix 密钥。                                                                                                                                                                                                                                   | 100                                       |
| `receiver_conciliation_id` | string     | 收款方对账标识。                                                                                                                                                                                                                                         | 35                                        |
| `transaction_amount`*      | number     | 转账金额。                                                                                                                                                                                                                                               | 10                                        |
| `end_to_end_id`*           | string     | SPI（即时支付系统）内 Pix 交易的幂等键。此键在 Pix 密钥查询中返回。仅当 `pix_transfer_type` 为 **key**、**static_qr_code** 或 **static_qr_code** 时发送。 | 32                                        |
| `pix_message`              | string     | 随 Pix 转账发送的消息。                                                                                                                                                                                                                                  | 140                                       |
| `tfa_info`*                | Object     | 包含账户审批人文件及联系方式的对象。                                                                                                                                                                                                                     | **[Objeto tfa_info](#objeto-tfa_info)**   |

:::info 注意
`end_to_end_id` 在[解码 Pix QR Code](/documentation/pix/decodificar_qr_code) 时返回，使用 Pix 复制粘贴的 URI。
:::

### Objeto tfa_info

| 字段                        | 类型   | 描述                                                                              | 字符数 |
|-----------------------------|--------|-----------------------------------------------------------------------------------|--------|
| `approver_document_number`* | string | 账户审批人的文件编号。                                                             | 11     | 
| `session_id`| string | 设备会话的唯一标识键，UUID v4 格式（设备 TFA 时为必填项）。 | 36 |
| `contact_type`*             | string | 与账户审批人的联系方式，可以是 **sms**、**email** 或 **device** |            |

:::danger 注意
查询的 `end_to_end_id` 必须以发起转账的账户名义完成！
:::

:::danger 注意
一个 `end_to_end_id` 只能用于一笔转账，无论转账是否成功。
:::

## Response

STATUS 202

Response Body: 交易已申请

```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: 转账已拒绝

```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": {}
}
```

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                 | 描述（英文）<br/>`description`                                                                                                          | 描述（葡文）<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                      | 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                      | PXT000188            | Session ID needed | A session_id must be provided token                      | Uma session_id deve ser fornecida                |

---

# 批准带双因素身份验证的 Pix 交易预约

URL: /zh-Hans/documentation/baas/pix/agendamento/aprovacao_de_agendamento_2fa

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_schedule/ SCHEDULE_KEY /validate_token
MÉTODO PUT

### 路径参数

| 字段           | 类型   | 描述                              | 字符数 |
|----------------|--------|--------------------------------------|------------|
| `account_key`  | uuidv4 | 账户唯一标识键。      | 36         |
| `schedule_key` | uuidv4 | 预约唯一标识键。 | 36         |

## 通过邮件和短信进行身份验证

Request Body

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

## 通过设备进行身份验证

要批准并完成设备身份验证，请求必须发送空 payload。验证在内部进行，无需在请求正文中提供额外信息。请注意，仅在[预约请求](./solicitacao_de_agendamento_2fa.md)已启动后才应使用此端点。

Request Body

```json
{

}
```

### Body 参数

| 字段     | 类型   | 描述                                                                             | 字符数 |
|----------|--------|----------------------------------------------------------------------------------|--------|
| `token`  | string | 发送给账户交易审批人的身份验证码 **通过短信或邮件进行 TFA 时必填**               | 6      |

## Response

STATUS 201

Response Body: 预约已审批

```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": {}
}
```

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                             | 描述（英文）<br/>`description`                                          | 描述（葡文）<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.                               |

---

# 批准带双因素身份验证的批量 Pix 交易预约

URL: /zh-Hans/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

### 路径参数

| 字段                 | 类型   | 描述                                  | 字符数 |
|----------------------|--------|----------------------------------------------|------------|
| `account_key`        | uuidv4 | 账户唯一标识键。          | 36         |
| `schedule_batch_key` | uuidv4 | 批量预约唯一标识键。 | 36         |

## 通过邮件和短信进行身份验证

Request Body

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

## 通过设备进行身份验证

要批准并完成设备身份验证，请求必须发送空 payload。验证在内部进行，无需在请求正文中提供额外信息。请注意，仅在[批量预约请求](./solicitacao_de_agendamento_em_lote_2fa.md)已启动后才应使用此端点。

Request Body

```json
{

}
```

### Body 参数

| 字段     | 类型   | 描述                                                                             | 字符数 |
|----------|--------|----------------------------------------------------------------------------------|--------|
| `token`  | string | 发送给账户交易审批人的身份验证码 **通过短信或邮件进行 TFA 时必填**               | 6      |

## Response

STATUS 201

Response Body: 预约已审批

```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": {}
}
```

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                             | 描述（英文）<br/>`description`                                          | 描述（葡文）<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.                               |

---

# 取消批量 Pix 交易预约

URL: /zh-Hans/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

### 路径参数

| 字段                 | 类型   | 描述                                      | 字符数 |
|----------------------|--------|------------------------------------------------|------------|
| `account_key`        | uuidv4 | 账户唯一标识键。              | 36         |
| `schedule_batch_key` | uuidv4 | 批量预约唯一标识键。 | 36         |

### Response

STATUS 200

Response Body: 预约已取消

```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": {}
}
```

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                    | 描述（英文）<br/>`description`                                                                                                    | 描述（葡文）<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                                                                                      |

---

# 查询预约批次中的预约列表

URL: /zh-Hans/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

### 路径参数

| 字段                 | 类型   | 描述                                        | 字符数 |
|----------------------|--------|--------------------------------------------------|------------|
| `account_key`        | uuidv4 | 账户唯一标识键。              | 36         |
| `schedule_batch_key` | uuidv4 | 预约批次唯一标识键。 | 36         |

### Query 参数

| 字段                  | 类型    | 描述                                                                | 字符数             |
|-----------------------|---------|--------------------------------------------------------------------------|--------------------|
| `request_control_key` | uuidv4  | 客户请求唯一标识键。        | 36                 |
| `schedule_status`     | string  | 预约状态。可以以列表形式发送。               |  **[schedule_status 枚举值](#enumerador-schedule_status)** |
| `page`                | integer | 请求的页码，默认为 1。                             |                    |
| `page_size`           | integer | 查询请求的页面大小，默认及最大值为 30。 | 最大值为 30 |

### schedule_status 枚举值

| 枚举值                     | 描述                                                                                      |
|----------------------------|------------------------------------------------------------------------------------------------|
| **scheduled**              | 交易已预约                                                                             |
| **sent**                   | 预约已完成并成功发送。最终状态                                      |
| **rejected**               | 预约在创建或执行期间被拒绝。最终状态                                |
| **cancelled**              | 应客户申请取消预约。最终状态                                 |
| **pending_2fa_approval**   | 待双因素身份验证审批                                         |
| **pending_creation**       | 预约正在创建中（批量预约的过渡状态）               |
| **waiting_batch_approval** | 预约已创建并关联到批次，等待双因素身份验证审批 |

### 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
  }
}

```

---

# 查询账户的预约批次列表

URL: /zh-Hans/documentation/baas/pix/agendamento/batch/consulta_de_agendamentos_em_lote_de_uma_conta

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_schedule_batches
MÉTODO GET

### 路径参数

| 字段         | 类型   | 描述                    | 字符数 |
|---------------|--------|------------------------------|------------|
| `account_key` | uuidv4 | 账户唯一标识键。 | 36         |

### Query 参数

| 字段                    | 类型    | 描述                                                                | 字符数             |
|-------------------------|---------|--------------------------------------------------------------------------|--------------------|
| `request_control_key`   | uuidv4  | 客户请求唯一标识键。        | 36                 |
| `schedule_batch_status` | string  | 预约批次状态。可以以列表形式发送。         | 20                 |
| `page`                  | integer | 请求的页码，默认为 1。                             |                    |
| `page_size`             | integer | 查询请求的页面大小，默认及最大值为 30。 | 最大值为 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
  }
}

```

# 查询账户的预约批次

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_schedule_batch/ SCHEDULE_BATCH_KEY
MÉTODO GET

### 路径参数

| 字段                 | 类型   | 描述                                        | 字符数 |
|----------------------|--------|--------------------------------------------------|------------|
| `account_key`        | uuidv4 | 账户唯一标识键。              | 36         |
| `schedule_batch_key` | uuidv4 | 预约批次唯一标识键。 | 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"
}
```

---

# 申请批量 Pix 交易预约

URL: /zh-Hans/documentation/baas/pix/agendamento/batch/solicitacao_de_agendamento_em_lote

QI Tech 提供通过单次调用执行多个 Pix 定期交易的功能。在此系统中，预约以异步方式进行。如果初始调用返回 **http status 4xx**，则不会执行任何预约。申请后，集成合作伙伴将针对创建时被拒绝的每个 **pix_schedule** 收到一个 webhook。

## 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

| 字段          | 类型   | 描述                   | 字符数 |
|---------------|--------|------------------------|--------|
| `account_key` | uuidv4 | 账户的唯一标识键。      | 36     |

### Body Params

| 字段                    | 类型   | 描述                                                               | 字符数                                                   |
|-------------------------|--------|--------------------------------------------------------------------|----------------------------------------------------------|
| `request_control_key` * | uuidv4 | 客户使用的请求唯一标识键，uuid v4 格式。                            | 36                                                       | 
| `pix_schedules` *       | array  | 关联到批次的 pix_schedule 对象列表。                               | **[Objeto pix_schedule](#objeto-pix_schedule)** 列表     |

### Objeto pix_schedule

| 字段                       | 类型       | 描述                                                                                                                                                                                                                                                 | 字符数                                                            |
|----------------------------|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `request_control_key`*     | uuidv4     | 客户使用的请求唯一标识键，uuid v4 格式。                                                                                                                                                                                                               | 36                                                                | 
| `pix_transfer_type`*       | enumerator | Pix 转账类型。                                                                                                                                                                                                                                         | **[Enumerador pix_transfer_type](#enumerador-pix_transfer_type)** |
| `target_pix_key`           | string     | 目标账户的 Pix 密钥。                                                                                                                                                                                                                                   | 100                                                               |
| `receiver_conciliation_id` | string     | 收款方对账标识。                                                                                                                                                                                                                                         | 35                                                                |
| `target_account` *         | Object     | 目标账户 - 仅在 `pix_transfer_type` 为 **manual** 时发送。 | **[Objeto target_account](#objeto-target_account)**               |
| `transaction_amount`*      | number     | 转账金额。                                                                                                                                                                                                                                               | 10                                                                |
| `end_to_end_id`            | string     | SPI（即时支付系统）内 Pix 交易的幂等键。此键在 Pix 密钥查询中返回。仅当 `pix_transfer_type` 为 **key**、**static_qr_code** 或 **static_qr_code** 时发送。 | 32                                                                |
| `pix_message`              | string     | 随 Pix 转账发送的消息。                                                                                                                                                                                                                                  | 140                                                               |

### Objeto target_account

| 字段                      | 类型       | 描述                                             | 字符数                                                   |
|---------------------------|------------|--------------------------------------------------|----------------------------------------------------------|
| `account_branch` *        | string     | 账户机构编号。                                    | 6                                                        |
| `account_digit` *         | string     | 账户数字。                                        | 1                                                        |
| `account_number` *        | string     | 账户号码。                                        | 20                                                       |
| `owner_document_number` * | string     | 账户持有人 CPF 或 CNPJ（仅数字）。                 | 14                                                       |
| `owner_name` *            | string     | 账户持有人姓名。                                   | 150                                                      |
| `account_type`*           | enumerator | 账户类型。                                        | **[Enumerador account_type](#enumerador-account_type)**  |
| `ispb` *                  | string     | 金融机构 8 位识别码（ISPB）。                      | 8                                                        |

### Enumerador account_type

| 枚举值               | 描述           |
|----------------------|----------------|
| **checking_account** | 支票账户       |
| **salary_account**   | 薪资账户       |
| **saving_account**   | 储蓄账户       |
| **payment_account**  | 付款账户       |

### Enumerador pix_transfer_type

| 枚举值               | 描述                                                                                                                                                                                                          |
|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **manual**           | 使用目标账户数据的 Pix。必须发送 `target_account`                                                                                                                                                              |
| **key**              | 使用 Pix 密钥的 Pix。必须发送 `target_pix_key`。如果已执行，建议发送 [Pix 密钥查询](/documentation/pix_indireto/movimentacoes/consultar_chave_pix) 的 `end_to_end_id`                                         |
| **static_qr_code**   | 使用静态 QR Code 的 Pix。必须发送 [QR code 解码](/documentation/pix/decodificar_qr_code) 返回的 `end_to_end_id`                                                                                               |
| **dynamic_qr_code**  | 使用动态 QR Code 的 Pix。必须发送 [QR code 解码](/documentation/pix/decodificar_qr_code) 返回的 `end_to_end_id`                                                                                               |

## Response

STATUS 201

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"
}
```

### Enumerador schedule_batch_status

| 枚举值                    | 描述                                       |
|---------------------------|--------------------------------------------|
| **created**               | 批量预约已创建                              |
| **approved**              | 批量预约已批准                              |
| **rejected**              | 批量预约已拒绝                              |
| **pending_2fa_approval**  | 批量预约待双因素认证批准                    |

STATUS 4xx

Response Body: Error

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                     | 描述（英文）<br/>`description`                                                                                                   | 描述（葡文）<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                                                          |

---

# 申请批量 Pix 交易预约（双因素认证）

URL: /zh-Hans/documentation/baas/pix/agendamento/batch/solicitacao_de_agendamento_em_lote_2fa

QI Tech 提供通过单次调用执行多个 Pix 定期交易的功能。在此系统中，预约以异步方式进行。如果初始调用返回 **http status 4xx**，则不会执行任何预约。申请后，集成合作伙伴将针对创建时被拒绝的每个 **pix_schedule** 收到一个 webhook。

此类预约需要通过向贷方账户中具有交易审批权限的人员发送令牌来确认付款计划。

配置为使用双因素认证的集成合作伙伴发起的批量 Pix 预约申请方式与[申请批量 Pix 预约交易](/documentation/baas/pix/agendamento/solicitacao_de_agendamento_em_lote)中描述的方式类似。区别在于添加了 `tfa_info` 对象，该对象包含转账审批人的信息和联系方式，以及成功申请的状态始终为 **pending_2fa_approval**。

发送 `token` 给审批人的通知事件为 **baas.token_validation.pix_transfer.schedule.batch**。可以[自定义](/documentation/notificacoes/template)发送的消息。

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_schedule_batch
MÉTODO POST

## 通过邮件和短信进行身份验证

Request Body: 通过短信或邮件进行 TFA 的批量预约

```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"
    }
  ]
}
```

## 通过设备进行身份验证

除了现有的 **sms** 和 **email** 身份验证方式外，还可以使用[预先注册的设备](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo)对交易进行身份验证。在这种情况下，需要从 **Device Scan** 中获取 `session_id` 并在 `tfa_info` 中发送。

Request Body: 通过设备进行 TFA 的批量预约

```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

| 字段          | 类型   | 描述                   | 字符数 |
|---------------|--------|------------------------|--------|
| `account_key` | uuidv4 | 账户的唯一标识键。      | 36     |

### Body Params

| 字段                    | 类型   | 描述                                                               | 字符数                                                   |
|-------------------------|--------|--------------------------------------------------------------------|----------------------------------------------------------|
| `request_control_key` * | uuidv4 | 客户使用的请求唯一标识键，uuid v4 格式。                            | 36                                                       | 
| `pix_schedules` *       | array  | 关联到批次的 pix_schedule 对象列表。                               | **[Objeto pix_schedule](#objeto-pix_schedule)** 列表     |
| `tfa_info`*             | Object | 包含账户审批人文件及联系方式的对象。                               | **[Objeto tfa_info](#objeto-tfa_info)**                  |

### Objeto tfa_info

| 字段                          | 类型   | 描述                                                              | 字符数 |
|-------------------------------|--------|-------------------------------------------------------------------|--------|
| `approver_document_number` *  | string | 账户审批人的文件编号。                                            | 11     |
| `session_id`                  | string | 设备会话唯一标识键，UUID v4 格式（设备 TFA 必填）。               | 36     |
| `contact_type` *              | string | 与账户审批人的联系方式，可以是 **sms**、**email** 或 **device**   |        |

### Objeto pix_schedule

| 字段                       | 类型       | 描述                                                                                                                                                                                                                                                 | 字符数                                                            |
|----------------------------|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `request_control_key`*     | uuidv4     | 客户使用的请求唯一标识键，uuid v4 格式。                                                                                                                                                                                                               | 36                                                                | 
| `pix_transfer_type`*       | enumerator | Pix 转账类型。                                                                                                                                                                                                                                         | **[Enumerador pix_transfer_type](#enumerador-pix_transfer_type)** |
| `target_pix_key`           | string     | 目标账户的 Pix 密钥。                                                                                                                                                                                                                                   | 100                                                               |
| `receiver_conciliation_id` | string     | 收款方对账标识。                                                                                                                                                                                                                                         | 35                                                                |
| `target_account` *         | Object     | 目标账户 - 仅在 `pix_transfer_type` 为 **manual** 时发送。 | **[Objeto target_account](#objeto-target_account)**               |
| `transaction_amount`*      | number     | 转账金额。                                                                                                                                                                                                                                               | 10                                                                |
| `end_to_end_id`            | string     | SPI（即时支付系统）内 Pix 交易的幂等键。此键在 Pix 密钥查询中返回。仅当 `pix_transfer_type` 为 **key**、**static_qr_code** 或 **static_qr_code** 时发送。 | 32                                                                |
| `pix_message`              | string     | 随 Pix 转账发送的消息。                                                                                                                                                                                                                                  | 140                                                               |

### Objeto target_account

| 字段                      | 类型       | 描述                                             | 字符数                                                   |
|---------------------------|------------|--------------------------------------------------|----------------------------------------------------------|
| `account_branch` *        | string     | 账户机构编号。                                    | 6                                                        |
| `account_digit` *         | string     | 账户数字。                                        | 1                                                        |
| `account_number` *        | string     | 账户号码。                                        | 20                                                       |
| `owner_document_number` * | string     | 账户持有人 CPF 或 CNPJ（仅数字）。                 | 14                                                       |
| `owner_name` *            | string     | 账户持有人姓名。                                   | 150                                                      |
| `account_type`*           | enumerator | 账户类型。                                        | **[Enumerador account_type](#enumerador-account_type)**  |
| `ispb` *                  | string     | 金融机构 8 位识别码（ISPB）。                      | 8                                                        |

### Enumerador account_type

| 枚举值               | 描述           |
|----------------------|----------------|
| **checking_account** | 支票账户       |
| **salary_account**   | 薪资账户       |
| **saving_account**   | 储蓄账户       |
| **payment_account**  | 付款账户       |

### Enumerador pix_transfer_type

| 枚举值               | 描述                                                                                                                                                                                                          |
|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **manual**           | 使用目标账户数据的 Pix。必须发送 `target_account`                                                                                                                                                              |
| **key**              | 使用 Pix 密钥的 Pix。必须发送 `target_pix_key`。如果已执行，建议发送 [Pix 密钥查询](/documentation/pix_indireto/movimentacoes/consultar_chave_pix) 的 `end_to_end_id`                                         |
| **static_qr_code**   | 使用静态 QR Code 的 Pix。必须发送 [QR code 解码](/documentation/pix/decodificar_qr_code) 返回的 `end_to_end_id`                                                                                               |
| **dynamic_qr_code**  | 使用动态 QR Code 的 Pix。必须发送 [QR code 解码](/documentation/pix/decodificar_qr_code) 返回的 `end_to_end_id`                                                                                               |

## Response

STATUS 202

Response Body: 批量预约已批准

```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

| 枚举值                    | 描述                                       |
|---------------------------|--------------------------------------------|
| **created**               | 批量预约已创建                              |
| **approved**              | 批量预约已批准                              |
| **rejected**              | 批量预约已拒绝                              |
| **pending_2fa_approval**  | 批量预约待双因素认证批准                    |

STATUS 4xx

Response Body: Error

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                     | 描述（英文）<br/>`description`                                                                                                   | 描述（葡文）<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                                                          |

---

# 申请重发批量预约令牌

URL: /zh-Hans/documentation/baas/pix/agendamento/batch/solicitacao_de_reenvio_de_token_para_agendamento_em_lote_2fa

将为 Pix 预约审批人生成并重发新令牌。若令牌验证尝试次数已超过上限，则不允许重发。

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_schedule_batch/ SCHEDULE_BATCH_KEY /resend_token
MÉTODO PATCH

### 路径参数

| 字段                 | 类型   | 描述                                  | 字符数 |
|----------------------|--------|----------------------------------------------|------------|
| `account_key`        | uuidv4 | 账户唯一标识键。          | 36         |
| `schedule_batch_key` | uuidv4 | 批量预约唯一标识键。 | 36         |

### Body 参数

| 字段           | 类型       | 描述                         | 字符数                                              |
|----------------|------------|----------------------------------|---------------------------------------------------------|
| `contact_type` | enumerator | 身份验证令牌的发送方式。 | **[contact_type 枚举值](#enumerador-contact_type)** |

:::info 说明
若未发送 `contact_type`，令牌将通过最初申请时指定的方式发送。
:::

| 枚举值     | 描述                       |
|------------|---------------------------------------------------|
| **sms**    | 通过手机短信发送 |
| **email**  | 通过电子邮件发送             |

## Response

STATUS 202

Response Body: 批量预约已申请

```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: 转账被拒绝

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                             | 描述（英文）<br/>`description`                                          | 描述（葡文）<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 |

---

# 取消 Pix 交易预约

URL: /zh-Hans/documentation/baas/pix/agendamento/cancelamento_de_agendamento

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_schedule/ SCHEDULE_KEY /cancel
MÉTODO PATCH

### Path Params

| 字段           | 类型   | 描述                     | 字符数 |
|----------------|--------|--------------------------|--------|
| `account_key`  | uuidv4 | 账户的唯一标识键。        | 36     |
| `schedule_key` | uuidv4 | 预约的唯一标识键         | 36     |

### Response

STATUS 200

Response Body: 预约已取消

```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": {}
}
```

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                           | 描述（英文）<br/>`description`                                                    | 描述（葡文）<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  |

---

# 查询 Pix 交易预约

URL: /zh-Hans/documentation/baas/pix/agendamento/consulta_de_agendamento

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_schedule/ SCHEDULE_KEY
MÉTODO GET

### Path Params

| 字段           | 类型   | 描述                     | 字符数 |
|----------------|--------|--------------------------|--------|
| `account_key`  | uuidv4 | 账户的唯一标识键。        | 36     |
| `schedule_key` | uuidv4 | 预约的唯一标识键         | 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"
}

```

---

# 查询账户的 Pix 交易预约列表

URL: /zh-Hans/documentation/baas/pix/agendamento/consulta_de_agendamentos_de_uma_conta

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_schedules
MÉTODO GET

### Path Params

| 字段           | 类型   | 描述                     | 字符数 |
|----------------|--------|--------------------------|--------|
| `account_key`  | uuidv4 | 账户的唯一标识键。        | 36     |

### Query Params

| 字段                  | 类型    | 描述                                                             | 字符数             |
|-----------------------|---------|------------------------------------------------------------------|--------------------|
| `request_control_key` | uuidv4  | 客户使用的请求唯一标识键。                                        | 36                 |
| `schedule_status`     | string  | 预约状态。可以以列表形式发送。                                    | **[Enumerador schedule_status](#enumerador-schedule_status)** |
| `page`                | integer | 请求的页码。默认为 1                                              |                    |
| `page_size`           | integer | 查询中请求的页面大小。默认及最大值为 30                           | 最大值为 30        |

### Enumerador schedule_status

| 枚举值                        | 描述                                             |
|-------------------------------|--------------------------------------------------|
| **scheduled**                 | 交易已预约                                       |
| **sent**                      | 预约完成并成功发送。最终状态                      |
| **rejected**                  | 预约在创建或执行期间被拒绝。最终状态              |
| **cancelled**                 | 应客户申请取消预约。最终状态                      |
| **pending_2fa_approval**      | 待双因素认证批准                                 |
| **pending_creation**          | 预约正在创建（批量预约的过渡状态）                |
| **waiting_batch_approval**    | 预约已创建并关联到批次，等待双因素认证批准        |

### 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: /zh-Hans/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                                                          |

---

# 简介

URL: /zh-Hans/documentation/baas/pix/agendamento/introducao

通过本节介绍的接口，集成合作伙伴可以申请 Pix 类型的交易预约。利用此功能，可以针对特定账户创建、列出和取消预约。

## 注意事项

- 预约日期以巴西利亚时间（BRT 或 UTC/GMT -03:00）为准
- 交易将从 BRT 时间 8 点开始尝试执行
- 因余额不足而失败的交易将每隔 1 小时重试，最多重试 3 次
- 对于 **key**、**static_qr_code** 和 **dynamic_qr_code** 类型的交易，在交易完成之前，将对 Pix 密钥进行新的核实，以确保目标账户未被更改。如果发现任何差异，预约将被拒绝（**rejected**）
- 集成合作伙伴将收到一个 webhook，通知预约的成功或拒绝
- 无法预约即时 **dynamic_qr_code**
- 预约转账会消耗 Pix 交易限额

## Pix Schedule Status

| 枚举值                        | 描述                                             |
|-------------------------------|--------------------------------------------------|
| **scheduled**                 | 交易已预约                                       |
| **sent**                      | 预约完成并成功发送。最终状态                      |
| **rejected**                  | 预约在创建或执行期间被拒绝。最终状态              |
| **cancelled**                 | 应客户申请取消预约。最终状态                      |
| **pending_2fa_approval**      | 待双因素认证批准                                 |
| **pending_creation**          | 预约正在创建（批量预约的过渡状态）                |
| **waiting_batch_approval**    | 预约已创建并关联到批次，等待双因素认证批准        |

## Schedule Transfers

在预约当天，对目标账户进行一致性验证后，将尝试执行 Pix 交易。此时会生成一个 **pix_transfer**，并将其添加到 `schedule_transfers` 列表中。最多尝试 3 次 Pix 交易。

### Schedule Transfer Object

| 字段                  | 类型   | 描述                                                                       | 字符数                                                              |
|-----------------------|--------|----------------------------------------------------------------------------|---------------------------------------------------------------------|
| `pix_transfer_key`    | uuidv4 | QI 系统中 Pix 转账的唯一标识键。                                            | 36                                                                  |
| `end_to_end_id` *     | string | SPI（即时支付系统）内 Pix 交易的幂等键                                      | 32                                                                  |
| `pix_transfer_status` | string | 交易状态。                                                                  | [Enumeradores pix_transfer_status](#enumerador-pix-transfer-status) |
| `created_at`          | string | 交易创建日期和时间。                                                         | 20                                                                  |

### Enumerador Pix Transfer Status

| 枚举值        | 描述                             |
|---------------|----------------------------------|
| **sent**      | 交易成功发送。最终状态            |
| **rejected**  | 交易在执行期间被拒绝。最终状态    |
| **pending**   | 交易待完成。过渡状态              |

---

# 双因素身份验证简介

URL: /zh-Hans/documentation/baas/pix/agendamento/introducao_a_agendamento_2fa

此类预约需要通过发送给账户授权审批人的令牌来确认付款计划。

配置为使用双因素身份验证的集成合作伙伴申请 Pix 预约的方式，与[申请 Pix 交易预约](/documentation/baas/pix/agendamento/solicitacao_de_agendamento)中所述的方式类似。区别在于需要额外添加 `tfa_info` 对象，其中包含转账审批人信息和联系方式，且成功申请后的状态始终为 **pending_2fa_approval**。

[Pix 批量交易](/documentation/baas/pix/batch/solicitacao_de_transacao_em_lote_pix)同样适用上述规则。

## 带授权的 Pix 预约流程

成功的 Pix 预约将遵循以下流程：
发出 [Pix 交易申请](/documentation/baas/pix/agendamento/solicitacao_de_agendamento_2fa)，同步接收状态为 **pending_2fa_approval** 以及 `schedule_key` 值的响应。
指定审批人将收到一个由数字组成的 6 位 `token`。
申请人使用 `schedule_key` 和 `token` 进行 [Pix 交易确认](/documentation/baas/pix/agendamento/aprovacao_de_agendamento_2fa)。
预约状态将更新为 **scheduled**。

## 注意事项

每个预约的 `token` 验证最多尝试 5 次。达到上限后，预约将自动置为拒绝（**rejected**）状态。
每个 `token` 的最长有效期为 5 分钟。
可以为预约重新生成并向转账审批人重发 `token`。此操作将重置 5 分钟计时器，但不重置无效尝试次数计数器。之前的 `token` 将失效。
向审批人发送 `token` 的通知事件为 **baas.token_validation.pix_transfer.schedule.single**。可以[自定义](/documentation/notificacoes/template)发送的消息内容。
已实现的令牌发送方式（`contact_type`）包括 **sms** 和 **email**。

---

# 申请 Pix 交易预约

URL: /zh-Hans/documentation/baas/pix/agendamento/solicitacao_de_agendamento

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_schedule
MÉTODO POST

### Path Params

| 字段          | 类型   | 描述                   | 字符数 |
|---------------|--------|------------------------|--------|
| `account_key` | uuidv4 | 账户的唯一标识键。      | 36     |

**Chave**

Request Body: 通过 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

| 字段                    | 类型       | 描述                                                                                                                                                                                                                              | 字符数     |
|-------------------------|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuidv4     | 客户使用的请求唯一标识键，uuid v4 格式。                                                                                                                                                                                           | 36         | 
| `pix_transfer_type` *   | enumerator | 要执行的 Pix 类型。密钥转账时应为 **key**。                                                                                                                                                                                        | **key**    |
| `target_pix_key` *      | string     | 目标账户的 Pix 密钥。                                                                                                                                                                                                              | 100        |
| `transaction_amount` *  | number     | 转账金额。                                                                                                                                                                                                                         | 10         |
| `end_to_end_id` *       | string     | SPI（即时支付系统）内 Pix 交易的幂等键。此键在 Pix 密钥查询中返回。仅当 `pix_transfer_type` 为 **key**、**static_qr_code** 或 **static_qr_code** 时发送 | 32         |
| `pix_message`           | string     | 随 Pix 转账发送的消息。                                                                                                                                                                                                            | 140        |
| `schedule_date`*        | string     | 执行交易的日期。                                                                                                                                                                                                                    | 10         |

**Manual**
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",
  "schedule_date": "2024-12-01"
}
```

### Body Params

| 字段                    | 类型       | 描述                                                                                            | 字符数                                              |
|-------------------------|------------|------------------------------------------------------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | uuidv4     | 客户使用的请求唯一标识键，uuid v4 格式。                                                         | 36                                                  | 
| `pix_transfer_type` *   | enumerator | Pix 转账类型。                                                                                   | **manual**                                          |
| `target_account` *      | Object     | 目标账户 - 仅在 `pix_transfer_type` 为 **manual** 时发送。 | **[Objeto target_account](#objeto-target_account)** |
| `transaction_amount` *  | number     | 转账金额。                                                                                       | 10                                                  |
| `pix_message`           | string     | 随 Pix 转账发送的消息。                                                                          | 140                                                 |
| `schedule_date`*        | string     | 执行交易的日期。                                                                                  | 10                                                  |

### Objeto target_account

| 字段                      | 类型       | 描述                                             | 字符数                                                   |
|---------------------------|------------|--------------------------------------------------|----------------------------------------------------------|
| `account_branch` *        | string     | 账户机构编号。                                    | 4                                                        |
| `account_digit` *         | string     | 账户数字。                                        | 1                                                        |
| `account_number` *        | string     | 账户号码。                                        | 20                                                       |
| `owner_document_number` * | string     | 账户持有人 CPF 或 CNPJ（仅数字）。                 | 14                                                       |
| `owner_name` *            | string     | 账户持有人姓名。                                   | 150                                                      |
| `account_type`*           | enumerator | 账户类型。                                        | **[Enumerador account_type](#enumerador-account_type)**  |
| `ispb` *                  | string     | 金融机构 8 位识别码（ISPB）。                      | 8                                                        |

### Enumerador account_type

| 枚举值               | 描述           |
|----------------------|----------------|
| **checking_account** | 支票账户       |
| **salary_account**   | 薪资账户       |
| **saving_account**   | 储蓄账户       |
| **payment_account**  | 付款账户       |

**Qr Code**

Request Body: 通过 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

| 字段                       | 类型       | 描述                                                                                                                                                                                                                                                 | 字符数                                    |
|----------------------------|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|
| `request_control_key`*     | uuidv4     | 客户使用的请求唯一标识键，uuid v4 格式。                                                                                                                                                                                                               | 36                                        | 
| `pix_transfer_type`*       | enumerator | Pix 转账类型。                                                                                                                                                                                                                                         | **static_qr_code** 或 **dynamic_qr_code** |
| `target_pix_key`*          | string     | 目标账户的 Pix 密钥。                                                                                                                                                                                                                                   | 100                                       |
| `receiver_conciliation_id` | string     | 收款方对账标识。                                                                                                                                                                                                                                         | 35                                        |
| `transaction_amount`*      | number     | 转账金额。                                                                                                                                                                                                                                               | 10                                        |
| `end_to_end_id`*           | string     | SPI（即时支付系统）内 Pix 交易的幂等键。此键在 Pix 密钥查询中返回。仅当 `pix_transfer_type` 为 **key**、**static_qr_code** 或 **static_qr_code** 时发送。 | 32                                        |
| `pix_message`              | string     | 随 Pix 转账发送的消息。                                                                                                                                                                                                                                  | 140                                       |

:::info 注意
`end_to_end_id` 在[解码 Pix QR Code](/documentation/pix/decodificar_qr_code) 时返回，使用 Pix 复制粘贴的 URI。
:::

:::danger 注意
查询的 `end_to_end_id` 必须以发起转账的账户名义完成！
:::

:::danger 注意
一个 `end_to_end_id` 只能用于一笔转账，无论转账是否成功。
:::

## Response

STATUS 201

Response Body: 预约已创建

```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": {}
}
```

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                     | 描述（英文）<br/>`description`                                                                                                       | 描述（葡文）<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            |

---

# 申请双因素认证的 Pix 交易预约

URL: /zh-Hans/documentation/baas/pix/agendamento/solicitacao_de_agendamento_2fa

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_schedule
MÉTODO POST

### Path Params

| 字段          | 类型   | 描述                   | 字符数 |
|---------------|--------|------------------------|--------|
| `account_key` | uuidv4 | 账户的唯一标识键。      | 36     |

**Chave**

## 通过邮件和短信进行身份验证

Request Body: 通过短信或邮件进行 TFA 的 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",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  }
}
```

## 通过设备进行身份验证

除了现有的 **sms** 和 **email** 身份验证方式外，还可以使用[预先注册的设备](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo)对交易进行身份验证。在这种情况下，需要从 **Device Scan** 中获取 `session_id` 并在 `tfa_info` 中发送。

Request Body: 通过设备进行 TFA 的 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",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
    "contact_type": "device"
  }
}
```

### Body Params

| 字段                    | 类型       | 描述                                                                                                                                                                                                                              | 字符数                                  |
|-------------------------|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------|
| `request_control_key` * | uuidv4     | 客户使用的请求唯一标识键，uuid v4 格式。                                                                                                                                                                                           | 36                                      | 
| `pix_transfer_type` *   | enumerator | 要执行的 Pix 类型。密钥转账时应为 **key**。                                                                                                                                                                                        | **key**                                 |
| `target_pix_key` *      | string     | 目标账户的 Pix 密钥。                                                                                                                                                                                                              | 100                                     |
| `transaction_amount` *  | number     | 转账金额。                                                                                                                                                                                                                         | 10                                      |
| `end_to_end_id` *       | string     | SPI（即时支付系统）内 Pix 交易的幂等键。此键在 Pix 密钥查询中返回。仅当 `pix_transfer_type` 为 **key**、**static_qr_code** 或 **static_qr_code** 时发送 | 32                                      |
| `pix_message`           | string     | 随 Pix 转账发送的消息。                                                                                                                                                                                                            | 140                                     |
| `schedule_date`*        | string     | 执行交易的日期。                                                                                                                                                                                                                    | 10                                      |
| `tfa_info`*             | Object     | 包含账户审批人文件及联系方式的对象。                                                                                                                                                                                                | **[Objeto tfa_info](#objeto-tfa_info)** |

**Manual**

## 通过邮件和短信进行身份验证

Request Body: 通过短信或邮件进行 TFA 的手动转账预约

```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"
  }
}
```

## 通过设备进行身份验证

除了现有的 **sms** 和 **email** 身份验证方式外，还可以使用[预先注册的设备](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo)对交易进行身份验证。在这种情况下，需要从 **Device Scan** 中获取 `session_id` 并在 `tfa_info` 中发送。

Request Body: 通过设备进行 TFA 的手动转账预约

```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

| 字段                    | 类型       | 描述                                                                                            | 字符数                                              |
|-------------------------|------------|------------------------------------------------------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | uuidv4     | 客户使用的请求唯一标识键，uuid v4 格式。                                                         | 36                                                  | 
| `pix_transfer_type` *   | enumerator | Pix 转账类型。                                                                                   | **manual**                                          |
| `target_account` *      | Object     | 目标账户 - 仅在 `pix_transfer_type` 为 **manual** 时发送。 | **[Objeto target_account](#objeto-target_account)** |
| `transaction_amount` *  | number     | 转账金额。                                                                                       | 10                                                  |
| `pix_message`           | string     | 随 Pix 转账发送的消息。                                                                          | 140                                                 |
| `schedule_date`*        | string     | 执行交易的日期。                                                                                  | 10                                                  |
| `tfa_info`*             | Object     | 包含账户审批人文件及联系方式的对象。                                                              | **[Objeto tfa_info](#objeto-tfa_info)**             |

### Objeto target_account

| 字段                      | 类型       | 描述                                             | 字符数                                                   |
|---------------------------|------------|--------------------------------------------------|----------------------------------------------------------|
| `account_branch` *        | string     | 账户机构编号。                                    | 4                                                        |
| `account_digit` *         | string     | 账户数字。                                        | 1                                                        |
| `account_number` *        | string     | 账户号码。                                        | 20                                                       |
| `owner_document_number` * | string     | 账户持有人 CPF 或 CNPJ（仅数字）。                 | 14                                                       |
| `owner_name` *            | string     | 账户持有人姓名。                                   | 150                                                      |
| `account_type`*           | enumerator | 账户类型。                                        | **[Enumerador account_type](#enumerador-account_type)**  |
| `ispb` *                  | string     | 金融机构 8 位识别码（ISPB）。                      | 8                                                        |

### Enumerador account_type

| 枚举值               | 描述           |
|----------------------|----------------|
| **checking_account** | 支票账户       |
| **salary_account**   | 薪资账户       |
| **saving_account**   | 储蓄账户       |
| **payment_account**  | 付款账户       |

**Qr Code**

## 通过邮件和短信进行身份验证

Request Body: 通过短信或邮件进行 TFA 的 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",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  }
}
```

## 通过设备进行身份验证

除了现有的 **sms** 和 **email** 身份验证方式外，还可以使用[预先注册的设备](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo)对交易进行身份验证。在这种情况下，需要从 **Device Scan** 中获取 `session_id` 并在 `tfa_info` 中发送。

Request Body: 通过设备进行 TFA 的 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",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
    "contact_type": "device"
  }
}
```

### Body Params

| 字段                       | 类型       | 描述                                                                                                                                                                                                                                                 | 字符数                                    |
|----------------------------|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|
| `request_control_key`*     | uuidv4     | 客户使用的请求唯一标识键，uuid v4 格式。                                                                                                                                                                                                               | 36                                        | 
| `pix_transfer_type`*       | enumerator | Pix 转账类型。                                                                                                                                                                                                                                         | **static_qr_code** 或 **dynamic_qr_code** |
| `target_pix_key`*          | string     | 目标账户的 Pix 密钥。                                                                                                                                                                                                                                   | 100                                       |
| `receiver_conciliation_id` | string     | 收款方对账标识。                                                                                                                                                                                                                                         | 35                                        |
| `transaction_amount`*      | number     | 转账金额。                                                                                                                                                                                                                                               | 10                                        |
| `end_to_end_id`*           | string     | SPI（即时支付系统）内 Pix 交易的幂等键。此键在 Pix 密钥查询中返回。仅当 `pix_transfer_type` 为 **key**、**static_qr_code** 或 **static_qr_code** 时发送。 | 32                                        |
| `pix_message`              | string     | 随 Pix 转账发送的消息。                                                                                                                                                                                                                                  | 140                                       |
| `tfa_info`*                | Object     | 包含账户审批人文件及联系方式的对象。                                                                                                                                                                                                                     | **[Objeto tfa_info](#objeto-tfa_info)**   |

:::info 注意
`end_to_end_id` 在[解码 Pix QR Code](/documentation/pix/decodificar_qr_code) 时返回，使用 Pix 复制粘贴的 URI。
:::

### Objeto tfa_info

| 字段                          | 类型   | 描述                                                              | 字符数 |
|-------------------------------|--------|-------------------------------------------------------------------|--------|
| `approver_document_number` *  | string | 账户审批人的文件编号。                                            | 11     |
| `session_id`                  | string | 设备会话唯一标识键，UUID v4 格式（设备 TFA 必填）。               | 36     |
| `contact_type` *              | string | 与账户审批人的联系方式，可以是 **sms**、**email** 或 **device**   |        |

:::danger 注意
查询的 `end_to_end_id` 必须以发起转账的账户名义完成！
:::

:::danger 注意
一个 `end_to_end_id` 只能用于一笔转账，无论转账是否成功。
:::

## Response

STATUS 201

Response Body: 预约已创建

```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": {}
}
```

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                     | 描述（英文）<br/>`description`                                                                                                   | 描述（葡文）<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                                                                                         |

---

# 申请为预约重新发送令牌

URL: /zh-Hans/documentation/baas/pix/agendamento/solicitacao_de_reenvio_de_token_para_agendamento_2fa

将为 Pix 预约审批人生成并发送新令牌。如果已超过令牌验证尝试次数上限，则不允许重新发送。

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_schedule/ SCHEDULE_KEY /resend_token
MÉTODO PATCH

### Path Params

| 字段           | 类型   | 描述                       | 字符数 |
|----------------|--------|----------------------------|--------|
| `account_key`  | uuidv4 | 账户的唯一标识键。          | 36     |
| `schedule_key` | uuidv4 | 预约的唯一标识键。          | 36     |

### Body Params

| 字段           | 类型       | 描述                       | 字符数 |
|----------------|------------|----------------------------|--------|
| `contact_type` | enumerator | 认证令牌的发送方式 | **[Enumerador contact_type](#enumerador-contact_type)** |

:::info 信息
如果未发送 `contact_type`，令牌将以最初请求的方式发送。
:::

| 枚举值     | 描述                     |
|------------|--------------------------|
| **sms**    | 发送至手机的短信          |
| **email**  | 发送至电子邮件            |

## Response

STATUS 202

Response Body: 交易已申请

```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: 转账已拒绝

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                             | 描述（英文）<br/>`description`                                          | 描述（葡文）<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                       |

---

# Pix 预约完成 Webhook

URL: /zh-Hans/documentation/baas/pix/agendamento/webhook_de_conclusao_de_agendamento

Pix 预约完成后，将向集成合作伙伴发送一个包含结果的 webhook。

:::danger 注意！
QI Tech 的 webhook 不应进行严格的字段映射。我们 API 返回的 webhook 载荷中可能包含额外字段。
:::

### Webhook Request Body

Request Body: 预约已完成并发送

```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: 预约已完成并被拒绝

```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

| 字段                  | 类型   | 描述                                                               | 最大字符数                                                             |
|-----------------------|--------|--------------------------------------------------------------------|------------------------------------------------------------------------|
| `webhook_type`        | string | 定义所报告事件类型的枚举器                                          | 23                                                                     |
| `webhook_datetime`    | string | webhook 发送的日期和时间                                            | 20                                                                     |
| `transaction_amount`  | number | 转账金额                                                            | 10                                                                     |
| `target_account`      | object | 预约的目标账户                                                      | **[Objeto target_account](#objeto-target_account)**                    |
| `schedule_transfers`  | array  | 预约执行的转账尝试列表                                              | **[Objeto schedule_transfer](#schedule-transfer-object)** 列表        |
| `schedule_status`     | string | 预约状态                                                            | **[Enumerador schedule_status](#pix-schedule-status)**                 |
| `schedule_key`        | string | 预约的唯一标识键                                                    | 36                                                                     |
| `schedule_date`       | string | 执行交易的日期。                                                    | 10                                                                     |
| `request_control_key` | uuidv4 | 客户使用的请求唯一标识键，uuid v4 格式。                             | 36                                                                     |
| `rejection_info`      | object | 包含拒绝事件信息的对象                                              |                                                                        |
| `rejection_reason`    | string | 拒绝原因                                                            | **[Enumeradores rejection_reason](#enumeradores-rejection_reason)**    |
| `pix_message`         | string | 随 Pix 转账发送的消息                                               | 140                                                                    |
| `updated_at`          | string | 预约最后更新的日期和时间。                                           | 20                                                                     |
| `created_at`          | string | 预约创建的日期和时间。                                               | 20                                                                     |

## Pix Schedule Status

| 枚举值                        | 描述                                             |
|-------------------------------|--------------------------------------------------|
| **scheduled**                 | 交易已预约                                       |
| **sent**                      | 预约完成并成功发送。最终状态                      |
| **rejected**                  | 预约在创建或执行期间被拒绝。最终状态              |
| **cancelled**                 | 应客户申请取消预约。最终状态                      |
| **pending_2fa_approval**      | 待双因素认证批准                                 |
| **pending_creation**          | 预约正在创建（批量预约的过渡状态）                |
| **waiting_batch_approval**    | 预约已创建并关联到批次，等待双因素认证批准        |

### Schedule Transfer Object

| 字段                  | 类型   | 描述                                                                       | 字符数                                                              |
|-----------------------|--------|----------------------------------------------------------------------------|---------------------------------------------------------------------|
| `pix_transfer_key`    | uuidv4 | QI 系统中 Pix 转账的唯一标识键。                                            | 36                                                                  |
| `end_to_end_id` *     | string | SPI（即时支付系统）内 Pix 交易的幂等键                                      | 32                                                                  |
| `pix_transfer_status` | string | 交易状态。                                                                  | [Enumeradores pix_transfer_status](#enumerador-pix-transfer-status) |
| `created_at`          | string | 交易创建日期和时间。                                                         | 20                                                                  |

### Enumerador Pix Transfer Status

| 枚举值        | 描述                             |
|---------------|----------------------------------|
| **sent**      | 交易成功发送。最终状态            |
| **rejected**  | 交易在执行期间被拒绝。最终状态    |
| **pending**   | 交易待完成。过渡状态              |

### Objeto target_account

| 字段                    | 类型       | 描述                                                 | 字符数                                                            |
|-------------------------|------------|------------------------------------------------------|-------------------------------------------------------------------|
| `account_branch`        | string     | 账户机构编号                                          | 6                                                                 |
| `account_digit`         | string     | 账户数字                                              | 1                                                                 |
| `account_number`        | string     | 账户号码                                              | 20                                                                |
| `owner_document_number` | string     | 账户持有人 CPF 或 CNPJ（仅数字）                       | 14                                                                |
| `owner_name`            | string     | 账户持有人姓名                                        | 150                                                               |
| `owner_person_type`     | enumerator | 标识所发送账户的持有人是自然人还是法人的识别器           | **[Enumerador owner_person_type](#enumerador-owner_person_type)** |
| `account_type`          | enumerator | 账户类型                                              | **[Enumerador account_type](#enumerador-account_type)**           |
| `ispb`                  | string     | 在巴西央行准备金转账系统中识别银行的八位代码             | 8                                                                 |
| `pix_key`               | string     | 预约目标的 Pix 密钥                                   | 100                                                               |

### Enumerador owner_person_type

| 枚举值        | 描述           |
|---------------|----------------|
| **natural**   | 自然人（个人）  |
| **legal**     | 法人（企业）    |

### Enumerador account_type

| 枚举值               | 描述           |
|----------------------|----------------|
| **checking_account** | 支票账户       |
| **salary_account**   | 薪资账户       |
| **saving_account**   | 储蓄账户       |
| **payment_account**  | 付款账户       |

### Enumeradores rejection_reason

| 枚举值                                                | 描述                                         |
|-------------------------------------------------------|----------------------------------------------|
| `target_creation_error`                               | 预约创建错误                                 |
| `limit_date_for_approval_surpassed`                   | 超过批准的最后期限                            |
| `limit_date_for_batch_approval_surpassed`             | 超过批量批准的最后期限                        |
| `max_tries_exceeded`                                  | 超过最大尝试次数                              |
| `rejection_by_transfer`                               | 因转账被拒绝                                  |
| `target_change`                                       | 目标账户已变更                                |
| `invalid_pix_key`                                     | 无效的 Pix 密钥                              |
| `max_token_validation_attempts_exceeded`              | 超过令牌验证最大尝试次数                      |
| `error_sending_token`                                 | 发送令牌时出错                                |
| `max_token_validation_attempts_exceeded_for_batch`    | 超过批量令牌验证最大尝试次数                  |

---

# 批准带双因素身份验证的批量交易

URL: /zh-Hans/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

### 路径参数

| 字段                     | 类型   | 描述                                       | 字符数 |
|--------------------------|--------|-----------------------------------------------|------------|
| `account_key`            | uuidv4 | 账户唯一标识键。            | 36         |
| `pix_transfer_batch_key` | uuidv4 | 批量 Pix 交易唯一标识键。 | 36         |

## 通过邮件和短信进行身份验证

Request Body

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

## 通过设备进行身份验证

要批准并完成设备身份验证，请求必须发送空 payload。验证在内部进行，无需在请求正文中提供额外信息。请注意，仅在[批量交易请求](./solicitacao_de_transacao_em_lote_pix_2fa.md)已启动后才应使用此端点。

Request Body

```json
{

}
```

### Body 参数

| 字段     | 类型   | 描述                                                                             | 字符数 |
|----------|--------|----------------------------------------------------------------------------------|--------|
| `token`  | string | 发送给账户交易审批人的身份验证码 **通过短信或邮件进行 TFA 时必填**               | 6      |

## Response

STATUS 201

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"
}
```

STATUS 4xx

Response Body: 转账被拒绝

```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": {}
}
```

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                             | 描述（英文）<br/>`description`                                                                                    | 描述（葡文）<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.                               |

---

# Pix 批量交易简介

URL: /zh-Hans/documentation/baas/pix/batch/introducao_a_transacao_em_lote_pix

QI Tech 提供通过单次调用执行多个 Pix 交易的功能。在此系统中，交易以异步方式进行。如果初始调用返回 **http status 4xx**，则不会执行任何交易。申请后，集成合作伙伴将针对每笔交易收到一个 webhook，通知尝试的最终状态，可能为 **rejected** 或 **sent**。

## 双因素认证

与 Pix 交易一样，配置了双因素认证的集成合作伙伴必须发送带有联系信息和令牌发送方式的 `tfa_info` 对象。

---

# 查询账户批次中的交易列表

URL: /zh-Hans/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

### 路径参数

| 字段                     | 类型   | 描述                                    | 字符数 |
|--------------------------|--------|---------------------------------------------|------------|
| `account_key`            | uuidv4 | 账户唯一标识键。         | 36         |
| `pix_transfer_batch_key` | uuidv4 | 批量交易唯一标识键。 | 36         |

### Query 参数

| 字段                        | 类型    | 描述                                                                | 字符数                                                            |
|-----------------------------|---------|--------------------------------------------------------------------------|--------------------------------------------------------------------|
| `request_control_key`       | uuidv4  | 客户请求唯一标识键。         | 36                                                                |
| `pix_transfer_batch_status` | string  | Pix 交易状态。                                                   | [pix_transfer_status 枚举值](#enumerador-pix_transfer_status) |
| `page`                      | integer | 请求的页码，默认为 1。                             |                                                                   |
| `page_size`                 | integer | 查询请求的页面大小，默认及最大值为 30。 | 最大值为 30                                                |

### pix_transfer_status 枚举值

| 枚举值                   | 描述                                     |
|--------------------------|----------------------------------------------------------|
| **sent**                 | Pix 转账成功。                 |
| **pending**              | Pix 转账待处理。                              |
| **pending_2fa_approval** | Pix 转账待双因素身份验证审批。 |
| **rejected**             | Pix 转账被拒绝。                             |

### 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
  }
}

```

---

# 列出账户的批量 Pix 交易

URL: /zh-Hans/documentation/baas/pix/batch/listar_transacoes_em_lote_pix_de_uma_conta

## 请求

ENDPOINT /account/ ACCOUNT_KEY /pix_transfer_batches
方法 GET

### Path Params

| 字段          | 类型   | 描述                     | 字符数 |
|---------------|--------|--------------------------|--------|
| `account_key` | uuidv4 | 账户的唯一标识键。       | 36     |

### Query Params

| 字段                  | 类型    | 描述                                                | 字符数             |
|-----------------------|---------|-----------------------------------------------------|--------------------|
| `request_control_key` | uuidv4  | 客户端使用的请求唯一标识键。                        | 36                 |
| `date_from`           | string  | 开始日期。格式 "YYYY-MM-DD"                         |                    |
| `date_to`             | string  | 结束日期。格式 "YYYY-MM-DD"                         |                    |
| `page`                | integer | 请求的页码。默认值为 1                              |                    |
| `page_size`           | integer | 查询中请求的每页大小。默认值和最大值均为 30         | 最大值为 30        |

### 响应

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
  }
}

```

# 查询批量交易

## 请求

ENDPOINT /account/ ACCOUNT_KEY /pix_transfer_batch/ PIX_TRANSFER_BATCH_KEY
方法 GET

### Path Params

| 字段                     | 类型   | 描述                       | 字符数 |
|--------------------------|--------|----------------------------|--------|
| `account_key`            | uuidv4 | 账户的唯一标识键。         | 36     |
| `pix_transfer_batch_key` | uuidv4 | 批量交易的唯一标识键。     | 36     |

### 响应

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"
}
```

---

# 申请为批量 Pix 交易重新发送令牌

URL: /zh-Hans/documentation/baas/pix/batch/solicitacao_de_reenvio_de_token_para_lote

将生成一个新令牌并发送给账户交易审批人。如果令牌验证尝试次数已达上限，则不允许重新发送。

## 请求

ENDPOINT /account/ ACCOUNT_KEY /pix_transfer_batch/ PIX_TRANSFER_BATCH_KEY /resend_token
方法 PATCH

### Path Params

| 字段                       | 类型   | 描述                       | 字符数 |
|----------------------------|--------|----------------------------|--------|
| `account_key` *            | uuidv4 | 账户的唯一标识键。         | 36     |
| `pix_transfer_batch_key` * | uuidv4 | 批量交易的唯一标识键。     | 36     |

Request Body

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

### Body Params

| 字段           | 类型       | 描述                        | 字符数 |
|----------------|------------|-----------------------------|--------|
| `contact_type` | enumerator | 认证令牌的发送方式 | **[Enumerador contact_type](#enumerador-contact_type)** |

:::info 信息
如果未发送 `contact_type`，令牌将以原始申请的方式发送。
:::

| 枚举值     | 描述                     |
|------------|--------------------------|
| **sms**    | 通过手机短信发送         |
| **email**  | 通过电子邮件发送         |

## 响应

STATUS 202

Response Body: 交易已申请

```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: 转账被拒绝

```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"
    }
  }
}
```

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                             | 描述（英文）<br/>`description`                                                                           | 描述（葡文）<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                                                   |

---

# 执行批量 Pix 交易

URL: /zh-Hans/documentation/baas/pix/batch/solicitacao_de_transacao_em_lote_pix

QI Tech 提供通过单次调用执行多笔 Pix 交易的功能。在该系统中，交易以异步方式执行。如果初始调用返回 **http status 4xx**，则所有交易均不会执行。提交申请后，集成合作伙伴将收到每笔交易的 webhook，告知尝试的最终状态，可能为 **rejected** 或 **sent**。

## 请求

ENDPOINT /account/ ACCOUNT_KEY /pix_transfer_batch
方法 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

| 字段          | 类型   | 描述                     | 字符数 |
|---------------|--------|--------------------------|--------|
| `account_key` | uuidv4 | 账户的唯一标识键。       | 36     |

### Body Params

| 字段                    | 类型   | 描述                                                          | 字符数                                                   |
|-------------------------|--------|---------------------------------------------------------------|----------------------------------------------------------|
| `request_control_key` * | uuidv4 | 客户端使用的 uuid v4 格式请求唯一标识键。                    | 36                                                       |
| `pix_transfers` *       | array  | 与批次关联的 pix_transfer 对象列表。                         | 列表，见 **[Objeto pix_transfer](#objeto-pix_transfer)** |

### Objeto pix_transfer

| 字段                       | 类型       | 描述                                                                                                                                                                                | 字符数                                                            |
|----------------------------|------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `request_control_key` *    | uuidv4     | 客户端使用的 uuid v4 格式请求唯一标识键。                                                                                                                                           | 36                                                                |
| `pix_transfer_type` *      | enumerator | 要执行的 Pix 类型。                                                                                                                                                                 | **[Enumerador pix_transfer_type](#enumerador-pix_transfer_type)** |
| `target_pix_key`           | string     | 接收交易的账户 Pix 键。                                                                                                                                                             | 100                                                               |
| `target_account`           | Object     | 目标账户 - 仅在 `pix_transfer_type` 为 **manual** 的转账中发送。                                                                                                                   | **[Objeto target_account](#objeto-target_account)**               |
| `receiver_conciliation_id` | string     | 接收方对账标识。                                                                                                                                                                    | 35                                                                |
| `transaction_amount` *     | number     | 转账金额。                                                                                                                                                                          | 10                                                                |
| `end_to_end_id`            | string     | SPI（即时支付系统）内 Pix 交易的幂等键。该键在 Pix 键查询中返回。仅当 `pix_transfer_type` 为 **key**、**static_qr_code** 或 **dynamic_qr_code** 时发送。                           | 32                                                                |
| `pix_message`              | string     | 随 Pix 转账一起发送的消息。                                                                                                                                                         | 140                                                               |

### Objeto target_account

| 字段                      | 类型       | 描述                                     | 字符数                                                  |
|---------------------------|------------|------------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string     | 账户支行。                               | 4                                                       |
| `account_digit` *         | string     | 账户校验位。                             | 1                                                       |
| `account_number` *        | string     | 账户号码。                               | 20                                                      |
| `owner_document_number` * | string     | 账户持有人的 CPF 或 CNPJ（仅数字）。    | 14                                                      |
| `owner_name` *            | string     | 账户持有人姓名。                         | 150                                                     |
| `account_type`*           | enumerator | 账户类型。                               | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string     | 基于金融机构 CNPJ 的代码（8位数字）。   | 8                                                       |

### Enumerador account_type

| 枚举值               | 描述         |
|----------------------|--------------|
| **checking_account** | 支票账户     |
| **salary_account**   | 工资账户     |
| **saving_account**   | 储蓄账户     |
| **payment_account**  | 支付账户     |

### Enumerador pix_transfer_type

| 枚举值              | 描述                                                                                                                                                                                                                  |
|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **manual**          | 使用目标账户数据进行 Pix 转账。必须发送 `target_account`                                                                                                                                                               |
| **key**             | 使用 Pix 键进行 Pix 转账。必须发送 `target_pix_key`。如果已执行 Pix 键[查询](/documentation/pix_indireto/movimentacoes/consultar_chave_pix)，建议发送 `end_to_end_id`                                                 |
| **static_qr_code**  | 使用静态 QR 码进行 Pix 转账。必须发送[QR 码解码](/documentation/pix/decodificar_qr_code)返回的 `end_to_end_id`                                                                                                        |
| **dynamic_qr_code** | 使用动态 QR 码进行 Pix 转账。必须发送[QR 码解码](/documentation/pix/decodificar_qr_code)返回的 `end_to_end_id`                                                                                                        |

## 响应

STATUS 201

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"
}
```

### Enumerador pix_transfer_batch_status

| 枚举值                   | 描述                                         |
|--------------------------|----------------------------------------------|
| **approved**             | 批量转账已批准，交易正在执行中。             |
| **rejected**             | 批量转账已拒绝                               |
| **pending_2fa_approval** | 批量转账待人工审批                           |

STATUS 4xx

Response Body: 转账被拒绝

```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 信息
之前为 [Pix 转账](/documentation/baas/pix/realizar_transferencia)列出的错误也可能由此端点返回。
:::

---

# 执行双因素认证批量 Pix 交易

URL: /zh-Hans/documentation/baas/pix/batch/solicitacao_de_transacao_em_lote_pix_2fa

QI Tech 提供通过单次调用执行多笔 Pix 交易的功能。在该系统中，交易以异步方式执行。如果初始调用返回 **http status 4xx**，则所有交易均不会执行。提交申请后，集成合作伙伴将收到每笔交易的 webhook，告知尝试的最终状态，可能为 **rejected** 或 **sent**。

此类交易需要通过发送给贷方账户交易审批人的令牌来确认付款。

配置为使用双因素认证的集成合作伙伴的 Pix 交易申请方式与[执行批量 Pix 交易](/documentation/baas/pix/batch/solicitacao_de_transacao_em_lote_pix)中描述的类似。区别在于添加了 `tfa_info` 对象（包含账户审批人信息和联系方式），以及成功申请的状态将始终为 **pending_2fa_approval**。

向审批人发送 `token` 的通知事件为 **baas.token_validation.pix_transfer.batch**。可以[自定义](/documentation/notificacoes/template)发送的消息。

## 请求

ENDPOINT /account/ ACCOUNT_KEY /pix_transfer_batch
方法 POST

## 通过邮件和短信进行身份验证

Request Body: 通过短信或邮件进行 TFA 的批量转账

```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"
    }
  ]
}
```

## 通过设备进行身份验证

除了现有的 **sms** 和 **email** 身份验证方式外，还可以使用[预先注册的设备](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo)对交易进行身份验证。在这种情况下，需要从 **Device Scan** 中获取 `session_id` 并在 `tfa_info` 中发送。

Request Body: 通过设备进行 TFA 的批量转账

```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

| 字段          | 类型   | 描述                     | 字符数 |
|---------------|--------|--------------------------|--------|
| `account_key` | uuidv4 | 账户的唯一标识键。       | 36     |

### Body Params

| 字段                    | 类型   | 描述                                                          | 字符数                                                   |
|-------------------------|--------|---------------------------------------------------------------|----------------------------------------------------------|
| `request_control_key` * | uuidv4 | 客户端使用的 uuid v4 格式请求唯一标识键。                    | 36                                                       |
| `pix_transfers` *       | array  | 与批次关联的 pix_transfer 对象列表。                         | 列表，见 **[Objeto pix_transfer](#objeto-pix_transfer)** |
| `tfa_info`*             | Object | 包含账户审批人文件和联系方式的对象。                         | **[Objeto tfa_info](#objeto-tfa_info)**                  |

### Objeto tfa_info

| 字段                          | 类型   | 描述                                                              | 字符数 |
|-------------------------------|--------|-------------------------------------------------------------------|--------|
| `approver_document_number` *  | string | 账户审批人的文件编号。                                            | 11     |
| `session_id`                  | string | 设备会话唯一标识键，UUID v4 格式（设备 TFA 必填）。               | 36     |
| `contact_type` *              | string | 与账户审批人的联系方式，可以是 **sms**、**email** 或 **device**   |        |

### Objeto pix_transfer

| 字段                       | 类型       | 描述                                                                                                                                                                                | 字符数                                                            |
|----------------------------|------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `request_control_key` *    | uuidv4     | 客户端使用的 uuid v4 格式请求唯一标识键。                                                                                                                                           | 36                                                                |
| `pix_transfer_type` *      | enumerator | 要执行的 Pix 类型。                                                                                                                                                                 | **[Enumerador pix_transfer_type](#enumerador-pix_transfer_type)** |
| `target_pix_key`           | string     | 接收交易的账户 Pix 键。                                                                                                                                                             | 100                                                               |
| `target_account`           | Object     | 目标账户 - 仅在 `pix_transfer_type` 为 **manual** 的转账中发送。                                                                                                                   | **[Objeto target_account](#objeto-target_account)**               |
| `receiver_conciliation_id` | string     | 接收方对账标识。                                                                                                                                                                    | 35                                                                |
| `transaction_amount` *     | number     | 转账金额。                                                                                                                                                                          | 10                                                                |
| `end_to_end_id`            | string     | SPI（即时支付系统）内 Pix 交易的幂等键。该键在 Pix 键查询中返回。仅当 `pix_transfer_type` 为 **key**、**static_qr_code** 或 **dynamic_qr_code** 时发送。                           | 32                                                                |
| `pix_message`              | string     | 随 Pix 转账一起发送的消息。                                                                                                                                                         | 140                                                               |

### Objeto target_account

| 字段                      | 类型       | 描述                                     | 字符数                                                  |
|---------------------------|------------|------------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string     | 账户支行。                               | 4                                                       |
| `account_digit` *         | string     | 账户校验位。                             | 1                                                       |
| `account_number` *        | string     | 账户号码。                               | 20                                                      |
| `owner_document_number` * | string     | 账户持有人的 CPF 或 CNPJ（仅数字）。    | 14                                                      |
| `owner_name` *            | string     | 账户持有人姓名。                         | 150                                                     |
| `account_type`*           | enumerator | 账户类型。                               | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string     | 基于金融机构 CNPJ 的代码（8位数字）。   | 8                                                       |

### Enumerador account_type

| 枚举值               | 描述         |
|----------------------|--------------|
| **checking_account** | 支票账户     |
| **salary_account**   | 工资账户     |
| **saving_account**   | 储蓄账户     |
| **payment_account**  | 支付账户     |

### Enumerador pix_transfer_type

| 枚举值              | 描述                                                                                                                                                                                                                  |
|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **manual**          | 使用目标账户数据进行 Pix 转账。必须发送 `target_account`                                                                                                                                                               |
| **key**             | 使用 Pix 键进行 Pix 转账。必须发送 `target_pix_key`。如果已执行 Pix 键[查询](/documentation/pix_indireto/movimentacoes/consultar_chave_pix)，建议发送 `end_to_end_id`                                                 |
| **static_qr_code**  | 使用静态 QR 码进行 Pix 转账。必须发送[QR 码解码](/documentation/pix/decodificar_qr_code)返回的 `end_to_end_id`                                                                                                        |
| **dynamic_qr_code** | 使用动态 QR 码进行 Pix 转账。必须发送[QR 码解码](/documentation/pix/decodificar_qr_code)返回的 `end_to_end_id`                                                                                                        |

## 响应

STATUS 201

Response Body: 批量转账已申请

```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

| 枚举值                   | 描述                                             |
|--------------------------|--------------------------------------------------|
| **approved**             | 批量转账已批准，交易正在执行中。                 |
| **rejected**             | 批量转账已拒绝                                   |
| **pending_2fa_approval** | 批量预约待双因素认证审批                         |

STATUS 4xx

Response Body: 转账被拒绝

```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 信息
之前为 [Pix 转账](/documentation/baas/pix/realizar_transferencia)列出的错误以及以下错误也可能由此端点返回。
:::

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                   | 描述（英文）<br/>`description`                                        | 描述（葡文）<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                |

---

# 在巴西中央银行查询 Pix 键数据

URL: /zh-Hans/documentation/baas/pix/consultar_chave_pix

## 请求

ENDPOINT /pix_key/ PIX_KEY
方法 GET

### 请求 Path Params

| 字段        | 类型   | 描述                    | 字符数 |
|-------------|--------|-------------------------|--------|
| `pix_key` * | string | 待查询的 Pix 键。       | 77     |

:::info Pix 键类型
"pix_key" 可以是 CPF、CNPJ、电子邮件、手机号码或随机键（UUID），格式如下：

**CPF**：11位整数。

**CNPJ**：14位整数。

**电子邮件**：包含至少一个"@"的文本。

**手机号码**：包含以下值的文本："+55" + "手机区号" + "最少8位最多9位的手机号码整数"。例如："+5511987654321"。

**随机键**：UUID4。
:::

### 请求 Query Params

| 字段              | 类型   | 描述                                                                                                                                              | 字符数    |
|-------------------|--------|---------------------------------------------------------------------------------------------------------------------------------------------------|-----------|
| `account_key` *   | uuidv4 | 账户的唯一标识键。                                                                                                                                | 36        |
| `document_number` | string | Pix 键持有人的 CPF/CNPJ。传递此参数时，将返回 `is_pix_key_owner` 字段，布尔值表示所提供的 CPF/CNPJ 是否与 Pix 键持有人的相同。 | 14 或 11  |

:::info 查询令牌使用
为使 Pix 键查询令牌从账户持有人处扣除，必须发送 `account_key`。
如果未发送 account_key，令牌将从集成合作伙伴的文件编号中扣除。
:::

## 响应

STATUS 200

Response Body: 活跃键

```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"
}
```

| 字段                           | 类型    | 描述                                                                                                                                                                                                                                         | 最大字符数                                                        |
|--------------------------------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `bank_code`                    | string  | 注册 Pix 键的银行代码。对于没有银行代码的机构，可能返回 null。                                                                                                                                                                              | 3                                                                 |
| `end_to_end_id`                | string  | 在巴西中央银行查询 Pix 键的唯一标识符。应在 Pix 转账中发送，以便回收查询时消耗的令牌。                                                                                                                                                      | 32                                                                |
| `financial_institution`        | string  | 注册 Pix 键的金融机构名称。                                                                                                                                                                                                                  | 200                                                               |
| `is_pix_key_owner`             | boolean | 如果请求中传递了 `document_number` 参数，则返回布尔值。该字段表示 `document_number` 参数中提供的 CPF/CNPJ 是否与 Pix 键持有人的相同。如果未提供 `document_number` 参数，则返回 null。                                                     | -                                                                 |
| `ispb`                         | string  | 持有 Pix 键的参与方 ISPB。                                                                                                                                                                                                                   | 8                                                                 |
| `owner_masked_document_number` | string  | Pix 键持有人的掩码 CPF 或 CNPJ 号码。                                                                                                                                                                                                        | 14                                                                |
| `owner_name`                   | string  | Pix 键持有人姓名。                                                                                                                                                                                                                           | 120                                                               |
| `owner_person_type`            | enum    | Pix 键持有人的法律性质。                                                                                                                                                                                                                     | [Enumeradores Owner Person Type](#enumeradores-owner_person_type) |
| `owner_trading_name`           | string  | Pix 键持有人的商业名称（仅适用于 `owner_person_type=legal`）。                                                                                                                                                                              | 100                                                               |
| `pix_key`                      | string  | Pix 键。                                                                                                                                                                                                                                     | -                                                                 |

### Enumeradores account_type

| 枚举值              | 描述         |
|---------------------|--------------|
| `payment`           | 支付账户     |
| `checking`          | 支票账户     |
| `savings`           | 储蓄账户     |
| `saving`            | 储蓄账户     |
| `salary`            | 工资账户     |
| `saving_account`    | 储蓄账户     |
| `payment_account`   | 支付账户     |
| `checking_account`  | 支票账户     |
| `salary_account`    | 工资账户     |
| `escrow`            | 托管账户     |

:::info
由于不同机构返回的信息不同，不同的枚举值可能表示同一种账户类型。
:::

### Enumeradroes owner_person_type

| 枚举值     | 描述   |
|------------|--------|
| `natural`  | string |
| `legal`    | string |

STATUS 4XX

Response Body

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

| HTTP 状态码 | QI 代码<br/>`code` | 标题<br/>`title`             | 描述（英文）<br/>`Description`                                      | 描述（葡文）<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                      |

---

# 查询转账

URL: /zh-Hans/documentation/baas/pix/consultar_transferencias

## 通过 pix_transfer_key 查询 Pix 交易

### 请求

ENDPOINT /account/ ACCOUNT_KEY /pix_transfer/ PIX_TRANSFER_KEY / PIX_TRANSFER_DIRECTION
方法 GET

### Path Params

| 字段                       | 类型       | 描述                                        | 字符数                                                                      |
|----------------------------|------------|---------------------------------------------|-----------------------------------------------------------------------------|
| `pix_transfer_direction` * | enumerator | 交易方向指示（入账或出账）。                | [Enumeradores pix_transfer_direction](#enumeradores-pix_transfer_direction) |
| `account_key` *            | uuidv4     | QI 账户的唯一标识键。                       | 36                                                                          |
| `pix_transfer_key` *       | uuidv4     | Pix 转账的唯一标识键。                      | 36                                                                          |

### Enumeradores pix_transfer_direction

| 枚举值       | 描述           |
|--------------|----------------|
| **incoming** | 入账 Pix 转账  |
| **outgoing** | 出账 Pix 转账  |

### 响应

STATUS 200

Response Body: 已发送转账 (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: 已拒绝转账 (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: 已发送退款 (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: 已收到转账 (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: 已收到退款 (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: 人工审核中的转账 (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: 被审核拒绝的转账 (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: 已拒绝转账 (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": {}
}
```

| HTTP 状态码 | QI 代码<br/>`code` | 标题<br/>`title`                            | 描述（英文）<br/>`Description`                      | 描述（葡文）<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                         |

---

# Pix Transfer 错误表

URL: /zh-Hans/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 状态码 | 错误代码   | 标题                                                                    | 描述                                                                                                                                                                                                 | 翻译                                                                                                                                                                                                                                        |
|-------------|------------|-------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 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                                                                                                                                               |

---

# 列出账户的转账记录

URL: /zh-Hans/documentation/baas/pix/listar_transferencias

## 请求

ENDPOINT /account/ ACCOUNT_KEY /pix_transfers
方法 GET

### Path Params

| 字段            | 类型   | 描述                       | 字符数 |
|-----------------|--------|----------------------------|--------|
| `account_key` * | uuidv4 | QI 账户的唯一标识键        | 36     |

### Query Params

| 字段                     | 类型       | 描述                                                                                          | 字符数                                                                      |
|--------------------------|------------|-----------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| `pix_transfer_direction` | enumerator | 交易方向指示（入账或出账）。如果未发送，则默认为 **outgoing**                                | [Enumeradores pix_transfer_direction](#enumeradores-pix_transfer_direction) |
| `request_control_key`    | uuidv4     | 客户端使用的请求唯一标识键。                                                                  | 36                                                                          |
| `end_to_end_id`          | string     | Pix 交易的幂等键                                                                              | 32                                                                          |
| `transaction_key`        | uuidv4     | 账户交易的标识键                                                                              | 36                                                                          |
| `order_by`  | string  | "asc" 表示升序，"desc" 表示降序。默认为 "asc" |
| `date_from`              | string     | 开始日期。格式 "YYYY-MM-DD"                                                                   |                                                                             |
| `date_to`                | string     | 结束日期。格式 "YYYY-MM-DD"                                                                   |                                                                             |
| `page`                   | integer    | 请求的页码。默认值为 1                                                                        |                                                                             |
| `page_size`              | integer    | 查询中请求的每页大小。默认值和最大值均为 30                                                   | 最大值为 30                                                                 |

### Enumeradores pix_transfer_direction

| 枚举值       | 描述           |
|--------------|----------------|
| **incoming** | 入账 Pix 转账  |
| **outgoing** | 出账 Pix 转账  |

## 响应

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": {}
}
```

| HTTP 状态码 | QI 代码<br/>`code` | 标题<br/>`title`                            | 描述（英文）<br/>`Description`                      | 描述（葡文）<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                         |

---

# 执行 Pix 交易

URL: /zh-Hans/documentation/baas/pix/realizar_transferencia

## 请求

ENDPOINT /account/ ACCOUNT_KEY /pix_transfer
方法 POST

## Path Params

| 字段          | 类型   | 描述                     | 字符数 |
|---------------|--------|--------------------------|--------|
| `account_key` | uuidv4 | 账户的唯一标识键。       | 36     |

## 通过 Pix 键转账

Request Body: 通过 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

| 字段                    | 类型       | 描述                                                                                                                                                                                | 字符数     |
|-------------------------|------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuidv4     | 客户端使用的 uuid v4 格式请求唯一标识键。                                                                                                                                           | 36         |
| `pix_transfer_type` *   | enumerator | 要执行的 Pix 类型。通过键转账时应为 **key**。                                                                                                                                       | "key"      |
| `target_pix_key` *      | string     | 接收交易的账户 Pix 键。                                                                                                                                                             | 100        |
| `transaction_amount` *  | number     | 转账金额。                                                                                                                                                                          | 10         |
| `end_to_end_id` *       | string     | SPI（即时支付系统）内 Pix 交易的幂等键。该键在 Pix 键查询中返回。仅当 `pix_transfer_type` 为 **key**、**static_qr_code** 或 **dynamic_qr_code** 时发送。                           | 32         |
| `pix_message`           | string     | 随 Pix 转账一起发送的消息。                                                                                                                                                         | 140        |

## 手动转账 - 使用账户数据

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

| 字段                    | 类型       | 描述                                                                   | 字符数                                              |
|-------------------------|------------|------------------------------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | uuidv4     | 客户端使用的 uuid v4 格式请求唯一标识键。                              | 36                                                  |
| `pix_transfer_type` *   | enumerator | Pix 转账类型。                                                         | **manual**                                          |
| `target_account` *      | Object     | 目标账户 - 仅在 `pix_transfer_type` 为 **manual** 的转账中发送。      | **[Objeto target_account](#objeto-target_account)** |
| `transaction_amount` *  | number     | 转账金额。                                                             | 10                                                  |
| `pix_message`           | string     | 随 Pix 转账一起发送的消息。                                            | 140                                                 |

### Objeto target_account

| 字段                      | 类型       | 描述                                     | 字符数                                                  |
|---------------------------|------------|------------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string     | 账户支行。                               | 4                                                       |
| `account_digit` *         | string     | 账户校验位。                             | 1                                                       |
| `account_number` *        | string     | 账户号码。                               | 20                                                      |
| `owner_document_number` * | string     | 账户持有人的 CPF 或 CNPJ（仅数字）。    | 14                                                      |
| `owner_name` *            | string     | 账户持有人姓名。                         | 150                                                     |
| `account_type`*           | enumerator | 账户类型。                               | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string     | 基于金融机构 CNPJ 的代码（8位数字）。   | 8                                                       |

### Enumerador account_type

| 枚举值               | 描述         |
|----------------------|--------------|
| **checking_account** | 支票账户     |
| **salary_account**   | 工资账户     |
| **saving_account**   | 储蓄账户     |
| **payment_account**  | 支付账户     |

## 通过 Pix QR 码转账

用于 Pix QR 码付款交易的数据必须通过使用 Pix 复制粘贴 URI 来[解码 Pix QR 码](/documentation/pix/decodificar_qr_code)获得。

I - "end_to_end_id" 字段必须与解码动态 QR 码返回的相同值。
II - 在 "transaction_amount" 字段中填写解码动态 QR 码时 "qr_code_data.amount" 字段返回的相同值；
III - 将 "pix_transfer_type" 字段更改为相应枚举值（**static_qr_code** 或 **dynamic_qr_code**），以请求付款。
IV - "receiver_conciliation_id" 字段必须与解码动态 QR 码返回的相同值。

Request Body: 通过 QR 码转账

```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

| 字段                       | 类型       | 描述                                                                                                                                                                                         | 字符数                                    |
|----------------------------|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|
| `request_control_key` *    | uuidv4     | 客户端使用的 uuid v4 格式请求唯一标识键。                                                                                                                                                    | 36                                        |
| `pix_transfer_type` *      | enumerator | Pix 转账类型。                                                                                                                                                                               | **static_qr_code** 或 **dynamic_qr_code** |
| `target_pix_key` *         | string     | 接收交易的账户 Pix 键。                                                                                                                                                                      | 100                                       |
| `receiver_conciliation_id` | string     | 接收方对账标识。                                                                                                                                                                             | 35                                        |
| `transaction_amount` *     | number     | 转账金额。                                                                                                                                                                                   | 10                                        |
| `end_to_end_id` *          | string     | SPI（即时支付系统）内 Pix 交易的幂等键。该键在 [Pix 键查询](/documentation/pix/consultar_chave)中返回。仅当 `pix_transfer_type` 为 **key**、**static_qr_code** 或 **dynamic_qr_code** 时发送。 | 32                                        |
| `pix_message`              | string     | 随 Pix 转账一起发送的消息。                                                                                                                                                                  | 140                                       |

:::danger 警告
查询的 `end_to_end_id` 必须是以将发起交易的账户名义进行的！
:::

:::danger 警告
一个 `end_to_end_id` 只能用于一次转账，无论该转账是否成功。
:::

## 响应

STATUS 201

Response Body: 已发送转账

```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: 待处理转账

```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 信息
如果返回 **HTTP Status 202** 且 `pix_transfer_status` 字段值为 **pending**，则不应重试 Pix 申请。

该转账将被重新处理。需要通过[查询 Pix 转账](#consultar-transação-pix)来检查转账状态。
:::

STATUS 4xx

Response Body: 转账被拒绝

```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": {}
}
```

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                   | 描述（英文）<br/>`description`                                                                                          | 描述（葡文）<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                                        |

---

# 申请已收 Pix 的退款

URL: /zh-Hans/documentation/baas/pix/solicitar_devolucao

Pix 退款可在收到后 90 天内执行。

## 请求

ENDPOINT /account/ ACCOUNT_KEY /pix_transfer/ PIX_TRANSFER_KEY /reversal
方法 POST

### Path Params

| 字段                  | 类型   | 描述                                               | 字符数 |
|-----------------------|--------|----------------------------------------------------|--------|
| `account_key` *       | uuidv4 | 账户的唯一标识键。                                 | 36     |
| `pix_transfer_key` *  | uuidv4 | QI 系统中 Pix 转账的唯一标识键。                  | 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

| 字段                    | 类型   | 描述             | 字符数                                                        |
|-------------------------|--------|------------------|---------------------------------------------------------------|
| `request_control_key` * | uuidv4 | 请求唯一键。     | 36                                                            |
| `reversal_amount` *     | number | 退款金额。       | 11                                                            |
| `reversal_reason` *     | string | 退款原因。       | **[Enumerador reversal_reason](#enumerador-reversal_reason)** |
| `reversal_message`      | string | 退款消息。       | 140                                                           |

### Enumerador reversal_reason

| 枚举值             | 描述                           |
|--------------------|--------------------------------|
| **client_request** | 由账户所有人申请时。           |
| **reconciliation** | 因操作错误进行对账时。         |

## 响应

STATUS 201

Response Body: 已发送退款

```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: 待处理退款

```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 信息
如果返回 **HTTP Status 202** 且 `pix_transfer_status` 字段值为 **pending**，则不应重试 Pix 申请。

该转账将被重新处理。需要通过[查询 Pix 转账](#consultar-transação-pix)来检查转账状态。
:::

### Response Body

| 字段                  | 类型       | 描述                                                                         | 字符数                                                    |
|-----------------------|------------|------------------------------------------------------------------------------|-----------------------------------------------------------|
| `reversal_status`     | enumerator | 退款交易状态枚举。                                                           | [Enumerador reversal_status](#enumerador-reversal_status) |
| `transfer_amount`     | number     | 退款转账金额。                                                               | 11                                                        |
| `pix_transfer_key`    | uuidv4     | 退款执行的 Pix 交易键。                                                      | 36                                                        |
| `end_to_end_id`       | string     | SPI（即时支付系统）内 Pix 交易的幂等键                                      | 32                                                        |
| `request_control_key` | uuidv4     | 客户端使用的请求唯一标识键。                                                 | 36                                                        |
| `created_at`          | string     | 退款日期和时间。                                                             | 10                                                        |

### Enumerador reversal_status

| 枚举值       | 描述                     |
|--------------|--------------------------|
| **sent**     | Pix 转账成功。           |
| **pending**  | Pix 转账待处理。         |
| **rejected** | Pix 转账已拒绝。         |

STATUS 4xx

Response Body: 退款被拒绝

```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 信息
除了之前为 [Pix 转账](/documentation/baas/pix/realizar_transferencia)列出的错误外，Pix 退款还可能返回以下错误。
:::

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                     | 描述（英文）<br/>`description`                                         | 描述（葡文）<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: /zh-Hans/documentation/baas/pix/webhooks

由于转账以异步方式进行，正确映射和处理发送的 webhooks 至关重要。

:::danger 注意！
QI Tech 的 webhooks 不应以限制性方式映射。
我们 API 返回的 webhook 载荷中可能会添加额外字段。
:::

## 待处理交易的 Webhook

此 Webhook 用于更新在 Pix [发送请求](/documentation/baas/pix/realizar_transferencia)中处于待处理状态（状态 202）的转账状态。

### Webhook Request Body

Request Body: 已发送交易

```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: 已拒绝交易

```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

| 字段                      | 类型   | 描述                                       | 最大字符数 |
|---------------------------|--------|--------------------------------------------|------------|
| `webhook_type`            | string | 定义报告事件类型的枚举值                   | 23         |
| `webhook_datetime`        | string | Webhook 发送日期和时间                     | 20         |
| `request_control_key`     | string | 用于查询已发起请求的 UUID4。               | 36         |
| `pix_transfer_key`        | string | QI 系统中 Pix 转账的标识键                 | 36         |
| `pix_transfer_status`     | string | 交易状态。                                 | 200        |
| `created_at`              | string | 交易创建日期和时间。                       | 20         |
| `error_code`              | string | 交易发生的错误代码                         | 20         |
| `error_description`       | string | 英文错误描述                               | 200        |
| `error_translation`       | string | 翻译为葡萄牙语的错误描述                   | 200        |
| `error_short_description` | string | 错误简短描述                               | 100        |

[//]: # (Break here for new page -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------)

## 入账 Pix 的 Webhook

此 Webhook 用于通知账户收到的 Pix 交易。

### Webhook Request Body

Request Body: 已收到 Pix

```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

```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

```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 预防性冻结
收到 Pix 时，可能会被预防性冻结。在这种情况下，目标账户不会有任何资金入账，并向客户发送状态为 `in_manual_analysis` 的 webhook。Pix 将在最多 72 小时内经过人工审核。审核完成后，入账将被接受或拒绝，入账 Pix 将分别进入 `received` 状态（此时资金将记入客户账户）或 `rejected_by_analysis` 状态。
:::

### Webhook Body Param

| 字段                       | 类型       | 描述                                                                  | 最大字符数                                                        |
|----------------------------|------------|-----------------------------------------------------------------------|-------------------------------------------------------------------|
| `webhook_type`             | string     | 定义报告事件类型的枚举值                                              | 23                                                                |
| `webhook_datetime`         | string     | Webhook 发送日期和时间                                                | 20                                                                |
| `pix_transfer_type`        | enumerator | 执行的 Pix 类型                                                       | **[Enumerador pix_transfer_type](#enumerador-pix_transfer_type)** |
| `target_pix_key`           | string     | 接收交易的账户 Pix 键                                                 | 100                                                               |
| `source_account`           | Object     | 来源账户 - 仅在"manual"类型的交易中发送                              | **[Objeto source_account](#objeto-source_account)**               |
| `transfer_amount`          | number     | 转账金额                                                              | 10                                                                |
| `receiver_conciliation_id` | string     | 接收方对账标识                                                        | 35                                                                |
| `end_to_end_id`            | string     | Pix 交易的幂等键 - 仅当转账类型为 "key" 时发送                       | 32                                                                |
| `pix_message`              | string     | 随 Pix 转账一起发送的消息                                             | 140                                                               |
| `fee_amount`               | number     | 转账金额                                                              | 10                                                                |
| `pix_transfer_status`      | string     | Pix 交易状态                                                          | 10                                                                |
| `account_key`              | string     | QI 账户的唯一标识键                                                   | 36                                                                |
| `pix_transfer_key`         | string     | Pix 转账的唯一标识键                                                  | 36                                                                |
| `error_code`               | string     | 交易发生的错误代码                                                    | 20                                                                |
| `error_description`        | string     | 英文错误描述                                                          | 200                                                               |
| `error_translation`        | string     | 翻译为葡萄牙语的错误描述                                              | 200                                                               |
| `error_short_description`  | string     | 错误简短描述                                                          | 100                                                               |

### Enumerador pix_transfer_type

| 枚举值              | 描述                     |
|---------------------|--------------------------|
| **manual**          | 使用目标账户数据的 Pix   |
| **key**             | 使用 Pix 键的 Pix        |
| **static_qr_code**  | 使用静态 QR 码的 Pix     |
| **dynamic_qr_code** | 使用动态 QR 码的 Pix     |
| **reversal**        | Pix 退款                 |

### Objeto source_account

| 字段                      | 类型       | 描述                                                        | 字符数                                                  |
|---------------------------|------------|-------------------------------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string     | 账户支行                                                    | 6                                                       |
| `account_digit` *         | string     | 账户校验位                                                  | 1                                                       |
| `account_number` *        | string     | 账户号码                                                    | 20                                                      |
| `owner_document_number` * | string     | 账户持有人的 CPF 或 CNPJ（仅数字）                         | 14                                                      |
| `owner_name`              | string     | 账户持有人姓名                                              | 150                                                     |
| `account_type`*           | enumerator | 账户类型                                                    | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string     | 在巴西中央银行准备金转账系统中标识银行的八位代码            | 8                                                       |

### Enumerador account_type

| 枚举值               | 描述         |
|----------------------|--------------|
| **checking_account** | 支票账户     |
| **salary_account**   | 工资账户     |
| **saving_account**   | 储蓄账户     |
| **payment_account**  | 支付账户     |

[//]: # (Break here for new page -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------)

## Pix 退款的 Webhook

此 Webhook 用于通知账户收到的 Pix 退款。

### Webhook Request Body

Request Body: 已收到 Pix

```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

| 字段                             | 类型       | 描述                                                                  | 最大字符数                                                        |
|----------------------------------|------------|-----------------------------------------------------------------------|-------------------------------------------------------------------|
| `webhook_type`                   | string     | 定义报告事件类型的枚举值                                              | 23                                                                |
| `webhook_datetime`               | string     | Webhook 发送日期和时间                                                | 20                                                                |
| `pix_transfer_type`              | enumerator | 执行的 Pix 类型                                                       | **[Enumerador pix_transfer_type](#enumerador-pix_transfer_type)** |
| `target_pix_key`                 | string     | 接收交易的账户 Pix 键                                                 | 100                                                               |
| `source_account`                 | Object     | 来源账户 - 仅在"manual"类型的交易中发送                              | **[Objeto source_account](#objeto-source_account)**               |
| `transfer_amount`                | number     | 转账金额                                                              | 10                                                                |
| `receiver_conciliation_id`       | string     | 接收方对账标识                                                        | 35                                                                |
| `end_to_end_id`                  | string     | Pix 交易的幂等键 - 仅当转账类型为 "key" 时发送                       | 32                                                                |
| `pix_message`                    | string     | 随 Pix 转账一起发送的消息                                             | 140                                                               |
| `fee_amount`                     | number     | 转账金额                                                              | 10                                                                |
| `pix_transfer_status`            | string     | Pix 交易状态                                                          | 10                                                                |
| `account_key`                    | string     | QI 账户的唯一标识键                                                   | 36                                                                |
| `pix_transfer_key`               | string     | Pix 转账的唯一标识键                                                  | 36                                                                |
| `original_outgoing_pix_transfer` | string     | 原始出账 Pix 转账的唯一标识键                                         | 36                                                                |
| `original_end_to_end_id`         | string     | 原始出账 Pix 转账的 end to end ID                                     | 36                                                                |
| `error_code`               | string     | 交易发生的错误代码                                                    | 20                                                                |
| `error_description`        | string     | 英文错误描述                                                          | 200                                                               |
| `error_translation`        | string     | 翻译为葡萄牙语的错误描述                                              | 200                                                               |
| `error_short_description`  | string     | 错误简短描述                                                          | 100                                                               |

### Enumerador pix_transfer_type

| 枚举值              | 描述                     |
|---------------------|--------------------------|
| **manual**          | 使用目标账户数据的 Pix   |
| **key**             | 使用 Pix 键的 Pix        |
| **static_qr_code**  | 使用静态 QR 码的 Pix     |
| **dynamic_qr_code** | 使用动态 QR 码的 Pix     |
| **reversal**        | Pix 退款                 |

### Objeto source_account

| 字段                    | 类型       | 描述                                                        | 字符数                                                  |
|-------------------------|------------|-------------------------------------------------------------|---------------------------------------------------------|
| `account_branch`        | string     | 账户支行                                                    | 6                                                       |
| `account_digit`         | string     | 账户校验位                                                  | 1                                                       |
| `account_number`        | string     | 账户号码                                                    | 20                                                      |
| `owner_document_number` | string     | 账户持有人的 CPF 或 CNPJ（仅数字）                         | 14                                                      |
| `owner_name`            | string     | 账户持有人姓名                                              | 150                                                     |
| `account_type`          | enumerator | 账户类型                                                    | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb`                  | string     | 在巴西中央银行准备金转账系统中标识银行的八位代码            | 8                                                       |

### Enumerador account_type

| 枚举值               | 描述         |
|----------------------|--------------|
| **checking_account** | 支票账户     |
| **salary_account**   | 工资账户     |
| **saving_account**   | 储蓄账户     |
| **payment_account**  | 支付账户     |

---

# baas_configurando_webhooks

URL: /zh-Hans/documentation/baas/primeiros_passos/baas_configurando_webhooks



---

# Configurar IP de Integração

URL: /zh-Hans/documentation/baas/primeiros_passos/baas_configurar_ip_de_integracao



---

# baas_inicio

URL: /zh-Hans/documentation/baas/primeiros_passos/baas_inicio



---

# baas_troca_de_chaves

URL: /zh-Hans/documentation/baas/primeiros_passos/baas_troca_de_chaves



---

# baas_endpoints_de_teste

URL: /zh-Hans/documentation/baas/primeiros_passos/teste_de_autenticacao/baas_endpoints_de_teste



---

# baas_possiveis_erros

URL: /zh-Hans/documentation/baas/primeiros_passos/teste_de_autenticacao/baas_possiveis_erros



---

# baas_teste_de_autenticacao_completo

URL: /zh-Hans/documentation/baas/primeiros_passos/teste_de_autenticacao/baas_teste_de_autenticacao_completo



---

# baas_teste_de_autenticacao_v2

URL: /zh-Hans/documentation/baas/primeiros_passos/teste_de_autenticacao/baas_teste_de_autenticacao_v2



---

# baas_webhook_v2

URL: /zh-Hans/documentation/baas/primeiros_passos/teste_de_autenticacao/baas_webhook_v2



---

# 批准双因素身份验证 TED 交易

URL: /zh-Hans/documentation/baas/ted/2fa/aprovar_transacao_ted_2fa

## 请求

ENDPOINT /account/ ACCOUNT_KEY /ted/ TED_KEY /validate_token
方法 PUT

### Path Params

| 字段          | 类型   | 描述                           | 字符数 |
|---------------|--------|--------------------------------|--------|
| `account_key` | uuidv4 | 账户的唯一标识键。             | 36     |
| `ted_key`     | uuidv4 | TED 转账的唯一标识键           | 36     |

## 通过电子邮件和短信验证

Request Body

```json
{
  "token": "329123"
}
```

## 通过设备验证

要批准并完成设备验证，请求必须以空负载发送。验证在内部发生，无需请求体中的额外信息。需要注意的是，此端点只应在[交易请求](./realizar_transferencia_2fa.md)启动后使用。

Request Body

```json
{

}
```

## Body Params

| 字段    | 类型   | 描述                                                                           | 字符数 |
|---------|--------|--------------------------------------------------------------------------------|--------|
| `token` | string | 发送给账户转账批准人的验证码（**SMS 或电子邮件 TFA 时必填**）                 | 6      | 

## 响应

STATUS 201

Response Body: 已发送转账

```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: 待处理转账

```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: 已拒绝转账

```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 信息
此端点也可能返回[执行 TED](/documentation/baas/ted/realizar_transferencia) 中列出的错误，以及以下错误。
:::

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                             | 描述（英文）<br/>`description`                                          | 描述（葡文）<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.               |

---

# 使用双因素身份验证执行 TED 转账

URL: /zh-Hans/documentation/baas/ted/2fa/realizar_transferencia_2fa

在此类交易中，需要通过发送给账户中具有批准转账权限的人员的令牌来确认付款。

配置为使用双因素身份验证的集成合作伙伴的 TED 交易请求方式与[执行 TED](/documentation/baas/ted/realizar_transferencia) 中描述的方式类似。区别在于添加了 `tfa_info` 对象，其中包含关于转账批准人和联系方式的信息，以及成功请求的状态将始终为 **pending_2fa_approval**。

## 请求

ENDPOINT /account/ ACCOUNT_KEY /ted
方法 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,
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  }
}
```

## 通过设备验证

除现有的 **sms** 和 **email** 验证方式外，还可以使用[预先注册的设备](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo)验证交易。此时，需要从 **Device Scan** 获取 `session_id` 并在 `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

| 字段                    | 类型   | 描述                                             | 字符数                                              |
|-------------------------|--------|--------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | string | 客户使用的 uuid v4 格式的请求唯一标识键。        | 36                                                  |
| `target_account` *      | object | 目标账户                                         | **[Objeto target_account](#objeto-target_account)** | 
| `transaction_amount` *  | float  | 转账金额                                         | 10                                                  |
| `tfa_info` *            | object | 包含账户批准人文件号和联系方式的对象。           | **[Objeto tfa_info](#objeto-tfa_info)**             |

## Objeto target_account

| 字段                      | 类型   | 描述                                    | 字符数                                                    |
|---------------------------|--------|-----------------------------------------|-----------------------------------------------------------|
| `account_branch` *        | string | 银行代码（机构代码）。                  | 4                                                         |
| `account_digit` *         | string | 账户校验码                              | 1                                                         |
| `account_number` *        | string | 账户号码。                              | 20                                                        |
| `owner_document_number` * | string | 账户持有人的 CPF 或 CNPJ（仅数字）。   | 14                                                        |
| `owner_name` *            | string | 账户持有人姓名。                        | 50                                                        |
| `account_type` *          | string | 账户类型。                              | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string | 基于金融机构 CNPJ（8 位数字）。         | 8                                                         |

## Objeto tfa_info

| 字段                        | 类型       | 描述                                                                                        | 字符数 |
|-----------------------------|------------|---------------------------------------------------------------------------------------------|--------|
| `approver_document_number` *| string     | 账户批准人的文件号。                                                                        | 11     | 
| `session_id`                | string     | 设备会话的唯一标识键（UUID v4 格式，设备 TFA 时必填）。                                    | 36     |
| `contact_type` *            | string     | 与账户批准人的联系方式，可为 **sms**、**email** 或 **device**                               |        |

## Enumerador account_type

| 枚举值                 | 翻译     |
|------------------------|----------|
| **checking_account**   | 活期账户 |
| **deposit_account**    | 存款账户 |
| **guaranteed_account** | 担保账户 |
| **investment_account** | 投资账户 |
| **payment_account**    | 付款账户 |
| **saving_account**     | 储蓄账户 |

## 响应

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 信息
此端点也可能返回[执行 TED](/documentation/baas/ted/realizar_transferencia) 中列出的错误，以及以下错误。
:::

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                   | 描述（英文）<br/>`description`                                        | 描述（葡文）<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                                |

---

# 请求重新发送 TED 交易令牌

URL: /zh-Hans/documentation/baas/ted/2fa/solicitacao_de_reenvio_de_token

将生成新令牌并发送给 TED 交易的批准人。如果已超过令牌验证尝试次数限制，将不允许重新发送。

## 请求

ENDPOINT /account/ ACCOUNT_KEY /ted/ TED_KEY /resend_token
方法 PATCH

### Path Params

| 字段            | 类型   | 描述                           | 字符数 |
|-----------------|--------|--------------------------------|--------|
| `account_key` * | uuidv4 | 账户的唯一标识键。             | 36     |
| `ted_key` *     | uuidv4 | TED 转账的唯一标识键           | 36     |

## Body Params

| 字段           | 类型       | 描述                              | 字符数                                                              |
|----------------|------------|-----------------------------------|---------------------------------------------------------------------|
| `contact_type` | enumerator | 验证令牌的发送方式                | **[Enumerador contact_type](#enumerador-contact_type)** |

:::info 信息
如果未发送 `contact_type`，令牌将按原始请求的方式发送。
:::

### Enumerador contact_type

| 枚举值     | 描述           |
|------------|----------------|
| **sms**    | 通过手机短信发送 |
| **email**  | 通过电子邮件发送 |

## 响应

STATUS 202

Response Body: 已请求交易

```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: 已拒绝转账

```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"
    }
  }
}
```

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                             | 描述（英文）<br/>`description`                                          | 描述（葡文）<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                |

---

# 批准双因素身份验证批量交易

URL: /zh-Hans/documentation/baas/ted/batch_2fa/aprovar_transacao_em_lote_ted_2fa

## 请求

ENDPOINT /account/ ACCOUNT_KEY /ted_batch/ TED_BATCH_KEY /validate_token
方法 PUT

### Path Params

| 字段            | 类型   | 描述                             | 字符数 |
|-----------------|--------|----------------------------------|--------|
| `account_key`   | uuidv4 | 账户的唯一标识键。               | 36     |
| `ted_batch_key` | uuidv4 | TED 批量交易的唯一标识键。       | 36     |

## 通过邮件和短信进行身份验证

Request Body

```json
{
  "token": "329123"
}
```

## 通过设备进行身份验证

要批准并完成设备身份验证，请求必须发送空 payload。验证在内部进行，无需在请求正文中提供额外信息。请注意，仅在[批量交易请求](./solicitacao_de_transacao_em_lote_ted_2fa.md)已启动后才应使用此端点。

Request Body

```json
{

}
```

## Body Params

| 字段     | 类型   | 描述                                                                             | 字符数 |
|----------|--------|----------------------------------------------------------------------------------|--------|
| `token`  | string | 发送给账户转账批准人的验证码 **通过短信或邮件进行 TFA 时必填**                   | 6      |

## 响应

STATUS 201

Response Body: 已批准批次

```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: 已拒绝批次

```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"
    }
  }
}
```

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                             | 描述（英文）<br/>`description`                                                                            | 描述（葡文）<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 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.                               |

---

# 请求重新发送 TED 批量交易令牌

URL: /zh-Hans/documentation/baas/ted/batch_2fa/solicitacao_de_reenvio_de_token_para_lote_ted

将生成新令牌并发送给账户转账批准人。如果已超过令牌验证尝试次数限制，将不允许重新发送。

## 请求

ENDPOINT /account/ ACCOUNT_KEY /ted_batch/ TED_BATCH_KEY /resend_token
方法 PATCH

### Path Params

| 字段              | 类型   | 描述                             | 字符数 |
|-------------------|--------|----------------------------------|--------|
| `account_key` *   | uuidv4 | 账户的唯一标识键。               | 36     |
| `ted_batch_key` * | uuidv4 | 批量交易的唯一标识键。           | 36     |

Request Body

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

## Body Params

| 字段           | 类型       | 描述                              | 字符数                                                  |
|----------------|------------|-----------------------------------|---------------------------------------------------------|
| `contact_type` | enumerator | 验证令牌的发送方式                | **[Enumerador contact_type](#enumerador-contact_type)** |

:::info 信息
如果未发送 `contact_type`，令牌将按原始请求的方式发送。
:::

### Enumerador contact_type

| 枚举值     | 描述           |
|------------|----------------|
| **sms**    | 通过手机短信发送 |
| **email**  | 通过电子邮件发送 |

## 响应

STATUS 202

Response Body: 已请求交易

```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: 已拒绝转账

```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"
    }
  }
}
```

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                             | 描述（英文）<br/>`description`                                          | 描述（葡文）<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 |

---

# 使用双因素身份验证执行 TED 批量交易

URL: /zh-Hans/documentation/baas/ted/batch_2fa/solicitacao_de_transacao_em_lote_ted_2fa

QI Tech 提供通过单次 API 调用执行多笔 TED 交易的功能。在此系统中，交易以异步方式执行。如果初始调用返回 **http status 4xx**，则不会执行任何交易。请求后，集成合作伙伴将为每笔交易收到一个 Webhook，告知尝试的最终状态，可能为 **rejected** 或 **sent**。

在此类交易中，需要通过发送给账户中具有批准转账权限的人员的令牌来确认付款。

配置为使用双因素身份验证的集成合作伙伴的 TED 批量交易请求方式与[执行 TED 批量交易](/documentation/baas/ted/batch/solicitacao_de_transacao_em_lote_ted)中描述的方式类似。区别在于添加了 `tfa_info` 对象，以及成功请求的状态将始终为 **pending_2fa_approval**。

令牌发送至批准人的通知事件为 **baas.token_validation.ted.batch**。可以[自定义](/documentation/notificacoes/template)发送的消息。

## 请求

ENDPOINT /account/ ACCOUNT_KEY /ted_batch
方法 POST

## 通过邮件和短信进行身份验证

Request Body: 通过短信或邮件进行 TFA 的批量转账

```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
    }
  ]
}
```

## 通过设备进行身份验证

除了现有的 **sms** 和 **email** 身份验证方式外，还可以使用[预先注册的设备](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo)对交易进行身份验证。在这种情况下，需要从 **Device Scan** 中获取 `session_id` 并在 `tfa_info` 中发送。

Request Body: 通过设备进行 TFA 的批量转账

```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

| 字段          | 类型   | 描述                   | 字符数 |
|---------------|--------|------------------------|--------|
| `account_key` | uuidv4 | 账户的唯一标识键。     | 36     |

## Body Params

| 字段                    | 类型   | 描述                                             | 字符数                                  |
|-------------------------|--------|--------------------------------------------------|-----------------------------------------|
| `request_control_key` * | uuidv4 | 客户使用的 uuid v4 格式的请求唯一标识键。        | 36                                      | 
| `teds` *                | array  | 与批次关联的 TED 对象列表。                      | 列表 **[Objeto ted](#objeto-ted)**      |
| `tfa_info` *            | Object | 包含账户批准人文件号和联系方式的对象。           | **[Objeto tfa_info](#objeto-tfa_info)** |

## Objeto tfa_info

| 字段                          | 类型   | 描述                                                              | 字符数 |
|-------------------------------|--------|-------------------------------------------------------------------|--------|
| `approver_document_number` *  | string | 账户批准人的文件号。                                              | 11     |
| `session_id`                  | string | 设备会话唯一标识键，UUID v4 格式（设备 TFA 必填）。               | 36     |
| `contact_type` *              | string | 与账户批准人的联系方式，可为 **sms**、**email** 或 **device**     |        |

## Objeto ted

| 字段                    | 类型   | 描述                                             | 字符数                                              |
|-------------------------|--------|--------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | string | 客户使用的 uuid v4 格式的请求唯一标识键。        | 36                                                  |
| `target_account` *      | object | 目标账户                                         | **[Objeto target_account](#objeto-target_account)** | 
| `transaction_amount` *  | float  | 转账金额                                         | 10                                                  |

## Objeto target_account

| 字段                      | 类型   | 描述                                    | 字符数                                                  |
|---------------------------|--------|-----------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string | 银行代码（机构代码）。                  | 4                                                       |
| `account_digit` *         | string | 账户校验码                              | 1                                                       |
| `account_number` *        | string | 账户号码。                              | 20                                                      |
| `owner_document_number` * | string | 账户持有人的 CPF 或 CNPJ（仅数字）。   | 14                                                      |
| `owner_name` *            | string | 账户持有人姓名。                        | 50                                                      |
| `account_type` *          | string | 账户类型。                              | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string | 基于金融机构 CNPJ（8 位数字）。         | 8                                                       |

## Enumerador account_type

| 枚举值                 | 翻译     |
|------------------------|----------|
| **checking_account**   | 活期账户 |
| **deposit_account**    | 存款账户 |
| **guaranteed_account** | 担保账户 |
| **investment_account** | 投资账户 |
| **payment_account**    | 付款账户 |
| **saving_account**     | 储蓄账户 |

## 响应

STATUS 202

Response Body: 已请求批量转账

```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

| 枚举值                   | 描述                               |
|--------------------------|------------------------------------|
| **approved**             | 批量转账已批准，交易正在执行中。   |
| **rejected**             | 批量转账已拒绝                     |
| **pending_2fa_approval** | 批量调度待双因素身份验证批准       |
| **cancelled**            | 批量转账已取消                     |

STATUS 4xx

Response Body: 已拒绝转账

```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"
    }
  }
}
```

:::info 信息
此端点也可能返回 [TED 批量交易](/documentation/baas/ted/solicitacao_de_transacao_em_lote_ted) 中列出的错误，以及以下错误。
:::

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                   | 描述（英文）<br/>`description`                                        | 描述（葡文）<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                |

---

# TED 批量交易简介

URL: /zh-Hans/documentation/baas/ted/batch/introducao_a_transacao_em_lote_ted

QI Tech 提供通过单次 API 调用执行多笔 TED 交易的功能。在此系统中，交易以异步方式执行。如果初始调用返回 **http status 4xx**，则不会执行任何交易。请求后，集成合作伙伴将为每笔交易收到一个 Webhook，告知尝试的最终状态，可能为 **rejected** 或 **sent**。

## 双因素身份验证

与 TED 交易类似，配置了双因素身份验证的集成合作伙伴必须发送包含联系方式和令牌发送信息的 `tfa_info` 对象。

---

# 列出账户批次中的 TED 交易

URL: /zh-Hans/documentation/baas/ted/batch/listar_transacoes_de_um_lote_de_transacoes_ted

## 请求

ENDPOINT /account/ ACCOUNT_KEY /ted_batch/ TED_BATCH_KEY /teds
方法 GET

### Path Params

| 字段            | 类型   | 描述                       | 字符数 |
|-----------------|--------|----------------------------|--------|
| `account_key`   | uuidv4 | 账户的唯一标识键。         | 36     |
| `ted_batch_key` | uuidv4 | 批量交易的唯一标识键。     | 36     |

### Query Params

| 字段                  | 类型    | 描述                                                                    | 字符数                                              |
|-----------------------|---------|-------------------------------------------------------------------------|-----------------------------------------------------|
| `request_control_key` | uuidv4  | 客户使用的请求唯一标识键。                                              | 36                                                  |
| `ted_status`          | string  | TED 交易状态。可作为列表发送。                                          | **[Enumerador ted_status](#enumerador-ted_status)** |
| `date_from`           | string  | 开始日期。格式 "YYYY-MM-DD"                                             | 10                                                  |
| `date_to`             | string  | 结束日期。格式 "YYYY-MM-DD"                                             | 10                                                  |
| `page`                | integer | 请求的页码，默认为 1                                                    |                                                     |
| `page_size`           | integer | 查询中请求的页面大小，默认为 30，最大值为 30                           | 最大值为 30                                         |

## Enumerador ted_status

| 枚举值       | 描述               |
|--------------|--------------------|
| **sent**     | TED 转账成功完成。 |
| **pending**  | TED 转账待处理。   |
| **rejected** | TED 转账已拒绝。   |
| **returned** | TED 转账已退回。   |

### 响应

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
  }
}
```

---

# 列出账户的 TED 批量交易

URL: /zh-Hans/documentation/baas/ted/batch/listar_transacoes_em_lote_ted_de_uma_conta

## 请求

ENDPOINT /account/ ACCOUNT_KEY /ted_batches
方法 GET

### Path Params

| 字段          | 类型   | 描述                   | 字符数 |
|---------------|--------|------------------------|--------|
| `account_key` | uuidv4 | 账户的唯一标识键。     | 36     |

### Query Params

| 字段                  | 类型    | 描述                                                                    | 字符数                                                          |
|-----------------------|---------|-------------------------------------------------------------------------|-----------------------------------------------------------------|
| `request_control_key` | uuidv4  | 客户使用的请求唯一标识键。                                              | 36                                                              |
| `ted_batch_status`    | uuidv4  | TED 批量交易状态。可作为列表发送。                                      | **[Enumerador ted_batch_status](#enumerador-ted_batch_status)** |
| `date_from`           | string  | 开始日期。格式 "YYYY-MM-DD"                                             | 10                                                              |
| `date_to`             | string  | 结束日期。格式 "YYYY-MM-DD"                                             | 10                                                              |
| `page`                | integer | 请求的页码，默认为 1                                                    |                                                                 |
| `page_size`           | integer | 查询中请求的页面大小，默认为 30，最大值为 30                           | 最大值为 30                                                     |

### Enumerador ted_batch_status

| 枚举值                   | 描述                               |
|--------------------------|------------------------------------|
| **approved**             | 批量转账已批准，交易正在执行中。   |
| **rejected**             | 批量转账已拒绝                     |
| **pending_2fa_approval** | 批量调度待双因素身份验证批准       |
| **cancelled**            | 批量转账已取消                     |

### 响应

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
  }
}
```

---

# 执行 TED 批量交易

URL: /zh-Hans/documentation/baas/ted/batch/solicitacao_de_transacao_em_lote_ted

QI Tech 提供通过单次 API 调用执行多笔 TED 交易的功能。在此系统中，交易以异步方式执行。如果初始调用返回 **http status 4xx**，则不会执行任何交易。请求后，集成合作伙伴将为每笔交易收到一个 Webhook，告知尝试的最终状态，可能为 **rejected** 或 **sent**。

## 请求

ENDPOINT /account/ ACCOUNT_KEY /ted_batch
方法 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

| 字段          | 类型   | 描述                   | 字符数 |
|---------------|--------|------------------------|--------|
| `account_key` | uuidv4 | 账户的唯一标识键。     | 36     |

## Body Params

| 字段                    | 类型   | 描述                                             | 字符数                                 |
|-------------------------|--------|--------------------------------------------------|----------------------------------------|
| `request_control_key` * | uuidv4 | 客户使用的 uuid v4 格式的请求唯一标识键。        | 36                                     | 
| `teds` *                | array  | 与批次关联的 TED 对象列表。                      | 列表 **[Objeto ted](#objeto-ted)** |

## Objeto ted

| 字段                    | 类型   | 描述                                             | 字符数                                              |
|-------------------------|--------|--------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | string | 客户使用的 uuid v4 格式的请求唯一标识键。        | 36                                                  |
| `target_account` *      | object | 目标账户                                         | **[Objeto target_account](#objeto-target_account)** | 
| `transaction_amount` *  | float  | 转账金额                                         | 10                                                  |

## Objeto target_account

| 字段                      | 类型   | 描述                                    | 字符数                                                  |
|---------------------------|--------|-----------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string | 银行代码（机构代码）。                  | 4                                                       |
| `account_digit` *         | string | 账户校验码                              | 1                                                       |
| `account_number` *        | string | 账户号码。                              | 20                                                      |
| `owner_document_number` * | string | 账户持有人的 CPF 或 CNPJ（仅数字）。   | 14                                                      |
| `owner_name` *            | string | 账户持有人姓名。                        | 50                                                      |
| `account_type` *          | string | 账户类型。                              | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string | 基于金融机构 CNPJ（8 位数字）。         | 8                                                       |

## Enumerador account_type

| 枚举值                 | 翻译     |
|------------------------|----------|
| **checking_account**   | 活期账户 |
| **deposit_account**    | 存款账户 |
| **guaranteed_account** | 担保账户 |
| **investment_account** | 投资账户 |
| **payment_account**    | 付款账户 |
| **saving_account**     | 储蓄账户 |

## 响应

STATUS 201

Response Body: 已批准批量转账

```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

| 枚举值                   | 描述                               |
|--------------------------|------------------------------------|
| **approved**             | 批量转账已批准，交易正在执行中。   |
| **rejected**             | 批量转账已拒绝                     |
| **pending_2fa_approval** | 批量调度待双因素身份验证批准       |
| **cancelled**            | 批量转账已取消                     |

STATUS 4xx

Response Body: 已拒绝批次

```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 信息
此端点也可能返回 [TED 转账](/documentation/baas/ted/realizar_transferencia) 中列出的错误。
:::

---

# 查询 TED

URL: /zh-Hans/documentation/baas/ted/consultar_ted

## 请求

ENDPOINT /account/ ACCOUNT_KEY /ted/ TED_KEY / TED_DIRECTION
方法 GET

## Request Path Params

| 字段              | 类型   | 描述                                           | 字符数                                                      |
|-------------------|--------|------------------------------------------------|-------------------------------------------------------------|
| `ted_direction` * | string | 指示交易为入账还是出账的过滤器。               | **[Enumerador ted_direction](#enumeradores-ted_direction)** |
| `account_key` *   | uuidv4 | QI 账户的唯一标识键                            | 36                                                          |
| `ted_key` *       | uuidv4 | TED 转账的唯一标识键                           | 36                                                          |

## Enumeradores ted_direction

| 枚举值     | 翻译 |
|------------|------|
| incoming   | 入账 |
| outgoing   | 出账 |

:::caution 注意
仅在请求方对出账交易的出账账户拥有权限（ted_direction 为 outgoing），或对入账交易的入账账户拥有权限（ted_direction 为 incoming）的情况下，才允许查看转账。否则将返回未找到错误。
:::

## 响应

STATUS 200

Response Body: 已拒绝转账（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: 已发送转账（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: 已接收转账（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": {}
}
```

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title` | 描述（英文）<br/>`description`          | 描述（葡文）<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: /zh-Hans/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                                                                                                                                                             |

---

# 列出 TED

URL: /zh-Hans/documentation/baas/ted/listar_teds

## 请求

ENDPOINT /account/ ACCOUNT_KEY /teds
方法 GET

## Path Params

| 字段            | 类型   | 描述                    | 字符数 |
|-----------------|--------|-------------------------|--------|
| `account_key` * | uuidv4 | QI 账户的唯一标识键     | 36     |

## Query Params

| 字段                  | 类型       | 描述                                                                                              | 字符数                                                                      |
|-----------------------|------------|---------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| `ted_direction`       | enumerator | 交易方向指示（入账或出账）。若未发送，默认考虑 **outgoing**（出账）                              | [Enumeradores ted_transfer_direction](#enumeradores-ted_transfer_direction) |
| `request_control_key` | uuidv4     | 客户使用的请求唯一标识键。                                                                        | 36                                                                          |
| `date_from`           | string     | 开始日期。格式 "YYYY-MM-DD"                                                                       |                                                                             |
| `date_to`             | string     | 结束日期。格式 "YYYY-MM-DD"                                                                       |                                                                             |
| `page`                | integer    | 请求的页码，默认为 1                                                                              |                                                                             |
| `page_size`           | integer    | 查询中请求的页面大小，默认为 30，最大值为 30                                                     | 最大值为 30                                                                 |

## Enumeradores ted_transfer_direction

| 枚举值       | 描述         |
|--------------|--------------|
| **incoming** | 入账 TED 转账 |
| **outgoing** | 出账 TED 转账 |

## 响应

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
  }
}
```

---

# 执行 TED 转账

URL: /zh-Hans/documentation/baas/ted/realizar_transferencia

在全国金融系统中，TED 交易的接收不是即时的。在 QI 系统中执行 TED 交易时，将立即返回一个响应，告知错误、拒绝或接受转账。即使转账被设为 `sent` 状态， 接收金融机构 也可能拒绝资金入账并退回金额。在这种情况下，将发送新的 Webhook，状态为 `rejected`，拒绝原因将在 `refusal_reason` 字段中返回。

交易源账户的扣款将立即执行。这并不意味着金额已记入目标账户，原因如上述 TED 交易原则所述。如果发送的交易被拒绝，交易金额将重新记入源账户。

## 请求

ENDPOINT /account/ ACCOUNT_KEY /ted
方法 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

| 字段                    | 类型   | 描述                                             | 字符数                                              |
|-------------------------|--------|--------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | string | 客户使用的 uuid v4 格式的请求唯一标识键。        | 36                                                  |
| `target_account` *      | object | 目标账户                                         | **[Objeto target_account](#objeto-target_account)** | 
| `transaction_amount` *  | float  | 转账金额                                         | 10                                                  |

## Objeto target_account

| 字段                      | 类型   | 描述                                    | 字符数                                                    |
|---------------------------|--------|-----------------------------------------|-----------------------------------------------------------|
| `account_branch` *        | string | 银行代码（机构代码）。                  | 4                                                         |
| `account_digit` *         | string | 账户校验码                              | 1                                                         |
| `account_number` *        | string | 账户号码。                              | 20                                                        |
| `owner_document_number` * | string | 账户持有人的 CPF 或 CNPJ（仅数字）。   | 14                                                        |
| `owner_name` *            | string | 账户持有人姓名。                        | 50                                                        |
| `account_type` *          | string | 账户类型。                              | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string | 基于金融机构 CNPJ（8 位数字）。         | 8                                                         |

## Enumerador account_type

| 枚举值                 | 翻译     |
|------------------------|----------|
| **checking_account**   | 活期账户 |
| **deposit_account**    | 存款账户 |
| **guaranteed_account** | 担保账户 |
| **investment_account** | 投资账户 |
| **payment_account**    | 付款账户 |
| **saving_account**     | 储蓄账户 |

## 响应

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": {}
}
```

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`            | 描述（英文）<br/>`description`                                                                                          | 描述（葡文）<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                                                                |

---

# 批准双因素身份验证 TED 调度

URL: /zh-Hans/documentation/baas/ted/schedule_2fa/aprovacao_de_agendamento_2fa

## 请求

ENDPOINT /account/ ACCOUNT_KEY /ted_schedule/ SCHEDULE_KEY /validate_token
方法 PUT

### Path Params

| 字段           | 类型   | 描述                   | 字符数 |
|----------------|--------|------------------------|--------|
| `account_key`  | uuidv4 | 账户的唯一标识键。     | 36     |
| `schedule_key` | uuidv4 | 调度的唯一标识键。     | 36     |

## 通过邮件和短信进行身份验证

Request Body

```json
{
  "token": "329123"
}
```

## 通过设备进行身份验证

要批准并完成设备身份验证，请求必须发送空 payload。验证在内部进行，无需在请求正文中提供额外信息。请注意，仅在[调度请求](./solicitacao_de_agendamento_2fa.md)已启动后才应使用此端点。

Request Body

```json
{

}
```

## Body Params

| 字段     | 类型   | 描述                                                                             | 字符数 |
|----------|--------|----------------------------------------------------------------------------------|--------|
| `token`  | string | 发送给账户转账批准人的验证码 **通过短信或邮件进行 TFA 时必填**                   | 6      |

## 响应

STATUS 201

Response Body: 已批准调度

```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": {}
}
```

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                             | 描述（英文）<br/>`description`                                                    | 描述（葡文）<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.                               |

---

# 双因素身份验证简介

URL: /zh-Hans/documentation/baas/ted/schedule_2fa/introducao_a_agendamento_2fa

在此类型的调度中，需要通过发送给账户中具有批准转账权限的人员的令牌来确认付款调度。

配置为使用双因素身份验证的集成合作伙伴的 TED 调度请求方式与[请求 TED 调度](/documentation/baas/ted/schedule/solicitacao_de_agendamento) 中描述的方式类似。区别在于添加了 `tfa_info` 对象，以及成功请求的状态将始终为 **pending_2fa_approval**。

TED 批量调度也适用同样规则，详见[请求 TED 批量调度](/documentation/baas/ted/schedule_batch/solicitacao_de_agendamento_em_lote)。

## 使用授权的 TED 调度流程

成功的 TED 调度将遵循以下流程：
执行 [TED 调度请求](/documentation/baas/ted/schedule/solicitacao_de_agendamento_2fa) 并同步接收状态为 **pending_2fa_approval** 和 `schedule_key` 值的响应。
指定的批准人将收到一个 6 位数字令牌。
请求方使用 `schedule_key` 和 `token` 执行 [TED 调度确认](/documentation/baas/ted/schedule/aprovacao_de_agendamento_2fa)。
调度将更新为 **scheduled** 状态。

## 注意事项

- 每个调度的令牌最大验证尝试次数限制为 5 次。达到此限制时，调度将自动设为拒绝（**rejected**）状态。
- 每个令牌的最大有效期为 5 分钟。
- 调度可以更新令牌并将其重新发送给转账批准人。此过程重置 5 分钟计时，但不重置无效尝试计数器。之前的令牌将失效。
- 向批准人发送令牌的通知事件为 **baas.token_validation.ted.schedule.single**。可以[自定义](/documentation/notificacoes/template)发送的消息。
- 已实施的令牌发送方式（`contact_type`）为 **sms** 和 **email**。

---

# 请求双因素身份验证 TED 调度

URL: /zh-Hans/documentation/baas/ted/schedule_2fa/solicitacao_de_agendamento_2fa

## 请求

ENDPOINT /account/ ACCOUNT_KEY /ted_schedule
方法 POST

## 通过邮件和短信进行身份验证

Request Body: 通过短信或邮件进行 TFA 的调度

```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"
  }
}
```

## 通过设备进行身份验证

除了现有的 **sms** 和 **email** 身份验证方式外，还可以使用[预先注册的设备](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo)对交易进行身份验证。在这种情况下，需要从 **Device Scan** 中获取 `session_id` 并在 `tfa_info` 中发送。

Request Body: 通过设备进行 TFA 的调度

```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

| 字段                    | 类型   | 描述                                             | 字符数                                              |
|-------------------------|--------|--------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | string | 客户使用的 uuid v4 格式的请求唯一标识键。        | 36                                                  |
| `target_account` *      | object | 目标账户                                         | **[Objeto target_account](#objeto-target_account)** | 
| `transaction_amount` *  | float  | 转账金额                                         | 10                                                  |
| `schedule_date` *       | string | 执行交易的日期。                                 | 10                                                  |
| `tfa_info` *            | Object | 包含账户批准人文件号和联系方式的对象。           | **[Objeto tfa_info](#objeto-tfa_info)**             |

## Objeto tfa_info

| 字段                          | 类型   | 描述                                                              | 字符数 |
|-------------------------------|--------|-------------------------------------------------------------------|--------|
| `approver_document_number` *  | string | 账户批准人的文件号。                                              | 11     |
| `session_id`                  | string | 设备会话唯一标识键，UUID v4 格式（设备 TFA 必填）。               | 36     |
| `contact_type` *              | string | 与账户批准人的联系方式，可为 **sms**、**email** 或 **device**     |        |

## Objeto target_account

| 字段                      | 类型   | 描述                                    | 字符数                                                  |
|---------------------------|--------|-----------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string | 银行代码（机构代码）。                  | 4                                                       |
| `account_digit` *         | string | 账户校验码                              | 1                                                       |
| `account_number` *        | string | 账户号码。                              | 20                                                      |
| `owner_document_number` * | string | 账户持有人的 CPF 或 CNPJ（仅数字）。   | 14                                                      |
| `owner_name` *            | string | 账户持有人姓名。                        | 50                                                      |
| `account_type` *          | string | 账户类型。                              | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string | 基于金融机构 CNPJ（8 位数字）。         | 8                                                       |

## Enumerador account_type

| 枚举值                 | 翻译     |
|------------------------|----------|
| **checking_account**   | 活期账户 |
| **deposit_account**    | 存款账户 |
| **guaranteed_account** | 担保账户 |
| **investment_account** | 投资账户 |
| **payment_account**    | 付款账户 |
| **saving_account**     | 储蓄账户 |

## 响应

STATUS 202

Response Body: 已创建调度

```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": {}
}
```

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                    | 描述（英文）<br/>`description`                                                             | 描述（葡文）<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                         |

---

# 请求重新发送调度令牌

URL: /zh-Hans/documentation/baas/ted/schedule_2fa/solicitacao_de_reenvio_de_token_para_agendamento_2fa

将生成新令牌并发送给 TED 调度的批准人。如果已超过令牌验证尝试次数限制，将不允许重新发送。

## 请求

ENDPOINT /account/ ACCOUNT_KEY /ted_schedule/ SCHEDULE_KEY /resend_token
方法 PATCH

### Path Params

| 字段           | 类型   | 描述                   | 字符数 |
|----------------|--------|------------------------|--------|
| `account_key`  | uuidv4 | 账户的唯一标识键。     | 36     |
| `schedule_key` | uuidv4 | 调度的唯一标识键。     | 36     |

## Body Params

| 字段           | 类型       | 描述                              | 字符数                                                  |
|----------------|------------|-----------------------------------|---------------------------------------------------------|
| `contact_type` | enumerator | 验证令牌的发送方式                | **[Enumerador contact_type](#enumerador-contact_type)** |

:::info 信息
如果未发送 `contact_type`，令牌将按原始请求的方式发送。
:::

### Enumerador contact_type

| 枚举值     | 描述           |
|------------|----------------|
| **sms**    | 通过手机短信发送 |
| **email**  | 通过电子邮件发送 |

## 响应

STATUS 202

Response Body: 已请求交易

```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: 已拒绝转账

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

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                             | 描述（英文）<br/>`description`                                                    | 描述（葡文）<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      |

---

# 批准双因素身份验证 TED 批量调度

URL: /zh-Hans/documentation/baas/ted/schedule_batch_2fa/aprovacao_de_agendamento_em_lote_2fa

## 请求

ENDPOINT /account/ ACCOUNT_KEY /ted_schedule_batch/ SCHEDULE_BATCH_KEY /validate_token
方法 PUT

### Path Params

| 字段                 | 类型   | 描述                   | 字符数 |
|----------------------|--------|------------------------|--------|
| `account_key`        | uuidv4 | 账户的唯一标识键。     | 36     |
| `schedule_batch_key` | uuidv4 | 批量调度的唯一标识键。 | 36     |

## 通过邮件和短信进行身份验证

Request Body

```json
{
  "token": "329123"
}
```

## 通过设备进行身份验证

要批准并完成设备身份验证，请求必须发送空 payload。验证在内部进行，无需在请求正文中提供额外信息。请注意，仅在[批量调度请求](./solicitacao_de_agendamento_em_lote_2fa.md)已启动后才应使用此端点。

Request Body

```json
{

}
```

## Body Params

| 字段     | 类型   | 描述                                                                             | 字符数 |
|----------|--------|----------------------------------------------------------------------------------|--------|
| `token`  | string | 发送给账户转账批准人的验证码 **通过短信或邮件进行 TFA 时必填**                   | 6      |

## 响应

STATUS 201

Response Body: 已批准批量调度

```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": {}
}
```

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                             | 描述（英文）<br/>`description`                                                                                       | 描述（葡文）<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.                               |

---

# 请求 TED 批量调度（双因素身份验证）

URL: /zh-Hans/documentation/baas/ted/schedule_batch_2fa/solicitacao_de_agendamento_em_lote_2fa

QI Tech 提供通过单次调用执行多个 TED 批量调度的功能。如果初始调用返回 http status 4xx，则不会执行任何调度。

在此类型的调度中，需要通过发送给账户中具有批准转账权限的人员的令牌来确认付款调度。

配置为使用双因素身份验证的集成合作伙伴的 TED 批量调度请求方式与[请求 TED 批量调度](/documentation/baas/ted/schedule/solicitacao_de_agendamento_em_lote) 中描述的方式类似。区别在于添加了 `tfa_info` 对象，以及成功请求的状态将始终为 **pending_2fa_approval**。

向批准人发送令牌的通知事件为 **baas.token_validation.ted.schedule.batch**。可以[自定义](/documentation/notificacoes/template)发送的消息。

## 请求

ENDPOINT /account/ ACCOUNT_KEY /ted_schedule_batch
方法 POST

## 通过邮件和短信进行身份验证

Request Body: 通过短信或邮件进行 TFA 的批量调度

```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"
  }
}
```

## 通过设备进行身份验证

除了现有的 **sms** 和 **email** 身份验证方式外，还可以使用[预先注册的设备](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo)对交易进行身份验证。在这种情况下，需要从 **Device Scan** 中获取 `session_id` 并在 `tfa_info` 中发送。

Request Body: 通过设备进行 TFA 的批量调度

```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

| 字段          | 类型   | 描述               | 字符数 |
|---------------|--------|--------------------|--------|
| `account_key` | uuidv4 | 账户的唯一标识键。 | 36     |

## Body Params

| 字段                    | 类型   | 描述                                             | 字符数                                                   |
|-------------------------|--------|--------------------------------------------------|----------------------------------------------------------|
| `request_control_key` * | uuidv4 | 客户使用的 uuid v4 格式的请求唯一标识键。        | 36                                                       | 
| `ted_schedules` *       | array  | 与批次关联的 ted_schedule 对象列表。             | 列表 **[Objeto ted_schedule](#objeto-ted_schedule)** |
| `tfa_info` *            | Object | 包含账户批准人文件号和联系方式的对象。           | **[Objeto tfa_info](#objeto-tfa_info)**                  |

## Objeto tfa_info

| 字段                          | 类型   | 描述                                                              | 字符数 |
|-------------------------------|--------|-------------------------------------------------------------------|--------|
| `approver_document_number` *  | string | 账户批准人的文件号。                                              | 11     |
| `session_id`                  | string | 设备会话唯一标识键，UUID v4 格式（设备 TFA 必填）。               | 36     |
| `contact_type` *              | string | 与账户批准人的联系方式，可为 **sms**、**email** 或 **device**     |        |

## Objeto ted_schedule

| 字段                    | 类型   | 描述                                             | 字符数                                              |
|-------------------------|--------|--------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | string | 客户使用的 uuid v4 格式的请求唯一标识键。        | 36                                                  |
| `target_account` *      | object | 目标账户                                         | **[Objeto target_account](#objeto-target_account)** | 
| `transaction_amount` *  | float  | 转账金额                                         | 10                                                  |
| `schedule_date` *       | string | 执行交易的日期。                                 | 10                                                  |

## Objeto target_account

| 字段                      | 类型   | 描述                                    | 字符数                                                  |
|---------------------------|--------|-----------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string | 银行代码（机构代码）。                  | 4                                                       |
| `account_digit` *         | string | 账户校验码                              | 1                                                       |
| `account_number` *        | string | 账户号码。                              | 20                                                      |
| `owner_document_number` * | string | 账户持有人的 CPF 或 CNPJ（仅数字）。   | 14                                                      |
| `owner_name` *            | string | 账户持有人姓名。                        | 50                                                      |
| `account_type` *          | string | 账户类型。                              | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string | 基于金融机构 CNPJ（8 位数字）。         | 8                                                       |

## Enumerador account_type

| 枚举值                 | 翻译     |
|------------------------|----------|
| **checking_account**   | 活期账户 |
| **deposit_account**    | 存款账户 |
| **guaranteed_account** | 担保账户 |
| **investment_account** | 投资账户 |
| **payment_account**    | 付款账户 |
| **saving_account**     | 储蓄账户 |

## 响应

STATUS 202

Response Body: 已请求批量调度

```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

| 枚举值                   | 描述                                             |
|--------------------------|--------------------------------------------------|
| **created**              | 批量调度已创建                                   |
| **approved**             | 批量调度已批准                                   |
| **rejected**             | 批量调度已拒绝                                   |
| **pending_2fa_approval** | 批量调度待双因素身份验证批准                     |

STATUS 4xx

Response Body: Error

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

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                    | 描述（英文）<br/>`description`                                                             | 描述（葡文）<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                         |

---

# 请求重新发送 TED 批量调度令牌

URL: /zh-Hans/documentation/baas/ted/schedule_batch_2fa/solicitacao_de_reenvio_de_token_para_agendamento_em_lote_2fa

将生成新令牌并发送给 TED 调度的批准人。如果已超过令牌验证尝试次数限制，将不允许重新发送。

## 请求

ENDPOINT /account/ ACCOUNT_KEY /ted_schedule_batch/ SCHEDULE_BATCH_KEY /resend_token
方法 PATCH

### Path Params

| 字段                 | 类型   | 描述                   | 字符数 |
|----------------------|--------|------------------------|--------|
| `account_key`        | uuidv4 | 账户的唯一标识键。     | 36     |
| `schedule_batch_key` | uuidv4 | 批量调度的唯一标识键。 | 36     |

## Body Params

| 字段           | 类型       | 描述                              | 字符数                                                  |
|----------------|------------|-----------------------------------|---------------------------------------------------------|
| `contact_type` | enumerator | 验证令牌的发送方式                | **[Enumerador contact_type](#enumerador-contact_type)** |

:::info 信息
如果未发送 `contact_type`，令牌将按原始请求的方式发送。
:::

### Enumerador contact_type

| 枚举值     | 描述           |
|------------|----------------|
| **sms**    | 通过手机短信发送 |
| **email**  | 通过电子邮件发送 |

## 响应

STATUS 202

Response Body: 已请求批量调度

```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: 已拒绝转账

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

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                     | 描述（英文）<br/>`description`                                                                                       | 描述（葡文）<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 |

---

# 取消 TED 批量调度

URL: /zh-Hans/documentation/baas/ted/schedule_batch/cancelamento_de_agendamento_em_lote

## 请求

ENDPOINT /account/ ACCOUNT_KEY /ted_schedule_batch/ SCHEDULE_BATCH_KEY /cancel
方法 PATCH

### Path Params

| 字段                 | 类型   | 描述                   | 字符数 |
|----------------------|--------|------------------------|--------|
| `account_key`        | uuidv4 | 账户的唯一标识键。     | 36     |
| `schedule_batch_key` | uuidv4 | 批量调度的唯一标识键   | 36     |

### 响应

STATUS 200

Response Body: 已取消调度

```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": {}
}
```

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                      | 描述（英文）<br/>`description`                                                                                                    | 描述（葡文）<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 |

---

# 列出批量调度中的调度列表

URL: /zh-Hans/documentation/baas/ted/schedule_batch/listar_agendamentos_de_um_lote

## 请求

ENDPOINT /account/ ACCOUNT_KEY /ted_schedule_batch/ SCHEDULE_BATCH_KEY /ted_schedules
方法 GET

### Path Params

| 字段                 | 类型   | 描述                   | 字符数 |
|----------------------|--------|------------------------|--------|
| `account_key`        | uuidv4 | 账户的唯一标识键。     | 36     |
| `schedule_batch_key` | uuidv4 | 批量调度的唯一标识键。 | 36     |

### Query Params

| 字段                  | 类型    | 描述                                                      | 字符数                                                        |
|-----------------------|---------|-----------------------------------------------------------|---------------------------------------------------------------|
| `request_control_key` | uuidv4  | 客户使用的请求唯一标识键。                                | 36                                                            |
| `schedule_status`     | string  | 调度状态。可以以列表形式发送。                            | **[Enumerador schedule_status](#enumerador-schedule_status)** |
| `start_date`          | string  | 查询的开始日期                                            | 10                                                            |
| `end_date`            | string  | 查询的结束日期                                            | 10                                                            |
| `page`                | integer | 请求的页码。默认为 1                                      |                                                               |
| `page_size`           | integer | 查询中请求的页面大小。默认为 30，最大值为 30              | 最大值 30                                                     |

### Enumerador schedule_status

| 枚举值                     | 描述                                                   |
|----------------------------|--------------------------------------------------------|
| **scheduled**              | 交易已调度                                             |
| **sent**                   | 调度已完成并成功发送。最终状态                         |
| **rejected**               | 调度在创建或执行过程中被拒绝。最终状态                 |
| **cancelled**              | 应客户请求取消调度。最终状态                           |
| **pending_2fa_approval**   | 待双因素身份验证批准                                   |
| **pending_creation**       | 调度正在创建中（批量调度的过渡状态）                   |
| **waiting_batch_approval** | 调度已创建并与待双因素身份验证批准的批次关联           |

### 响应

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
  }
}
```

---

# 列出账户的批量调度列表

URL: /zh-Hans/documentation/baas/ted/schedule_batch/listar_agendamentos_em_lote_de_uma_conta

## 请求

ENDPOINT /account/ ACCOUNT_KEY /ted_schedule_batches
方法 GET

### Path Params

| 字段          | 类型   | 描述               | 字符数 |
|---------------|--------|--------------------|--------|
| `account_key` | uuidv4 | 账户的唯一标识键。 | 36     |

### Query Params

| 字段                    | 类型    | 描述                                                      | 字符数                                                                    |
|-------------------------|---------|-----------------------------------------------------------|---------------------------------------------------------------------------|
| `request_control_key`   | uuidv4  | 客户使用的请求唯一标识键。                                | 36                                                                        |
| `schedule_batch_status` | string  | 批量调度状态。可以以列表形式发送。                        | **[Enumerador schedule_batch_status](#enumerador-schedule_batch_status)** |
| `page`                  | integer | 请求的页码。默认为 1                                      |                                                                           |
| `page_size`             | integer | 查询中请求的页面大小。默认为 30，最大值为 30              | 最大值 30                                                                 |

### Enumerador schedule_batch_status

| 枚举值                   | 描述                                             |
|--------------------------|--------------------------------------------------|
| **created**              | 批量调度已创建                                   |
| **approved**             | 批量调度已批准                                   |
| **rejected**             | 批量调度已拒绝                                   |
| **pending_2fa_approval** | 批量调度待双因素身份验证批准                     |

### 响应

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
  }
}
```

---

# 请求 TED 批量调度

URL: /zh-Hans/documentation/baas/ted/schedule_batch/solicitacao_de_agendamento_em_lote

QI Tech 提供通过单次调用执行多个 TED 批量调度的功能。如果初始调用返回 **http status 4xx**，则不会执行任何调度。

## 请求

ENDPOINT /account/ ACCOUNT_KEY /ted_schedule_batch
方法 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

| 字段          | 类型   | 描述               | 字符数 |
|---------------|--------|--------------------|--------|
| `account_key` | uuidv4 | 账户的唯一标识键。 | 36     |

## Body Params

| 字段                    | 类型   | 描述                                             | 字符数                                                   |
|-------------------------|--------|--------------------------------------------------|----------------------------------------------------------|
| `request_control_key` * | uuidv4 | 客户使用的 uuid v4 格式的请求唯一标识键。        | 36                                                       | 
| `ted_schedules` *       | array  | 与批次关联的 ted_schedule 对象列表。             | 列表 **[Objeto ted_schedule](#objeto-ted_schedule)** |

## Objeto ted_schedule

| 字段                    | 类型   | 描述                                             | 字符数                                              |
|-------------------------|--------|--------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | string | 客户使用的 uuid v4 格式的请求唯一标识键。        | 36                                                  |
| `target_account` *      | object | 目标账户                                         | **[Objeto target_account](#objeto-target_account)** | 
| `transaction_amount` *  | float  | 转账金额                                         | 10                                                  |
| `schedule_date` *       | string | 执行交易的日期。                                 | 10                                                  |

## Objeto target_account

| 字段                      | 类型   | 描述                                    | 字符数                                                  |
|---------------------------|--------|-----------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string | 银行代码（机构代码）。                  | 4                                                       |
| `account_digit` *         | string | 账户校验码                              | 1                                                       |
| `account_number` *        | string | 账户号码。                              | 20                                                      |
| `owner_document_number` * | string | 账户持有人的 CPF 或 CNPJ（仅数字）。   | 14                                                      |
| `owner_name` *            | string | 账户持有人姓名。                        | 50                                                      |
| `account_type` *          | string | 账户类型。                              | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string | 基于金融机构 CNPJ（8 位数字）。         | 8                                                       |

## Enumerador account_type

| 枚举值                 | 翻译     |
|------------------------|----------|
| **checking_account**   | 活期账户 |
| **deposit_account**    | 存款账户 |
| **guaranteed_account** | 担保账户 |
| **investment_account** | 投资账户 |
| **payment_account**    | 付款账户 |
| **saving_account**     | 储蓄账户 |

## 响应

STATUS 201

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"
}
```

### Enumerador schedule_batch_status

| 枚举值                   | 描述                                             |
|--------------------------|--------------------------------------------------|
| **created**              | 批量调度已创建                                   |
| **approved**             | 批量调度已批准                                   |
| **rejected**             | 批量调度已拒绝                                   |
| **pending_2fa_approval** | 批量调度待双因素身份验证批准                     |

STATUS 4xx

Response Body: Error

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

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                    | 描述（英文）<br/>`description`                                                             | 描述（葡文）<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                         |

---

# 取消 TED 交易调度

URL: /zh-Hans/documentation/baas/ted/schedule/cancelamento_de_agendamento

## 请求

ENDPOINT /account/ ACCOUNT_KEY /ted_schedule/ SCHEDULE_KEY /cancel
方法 PATCH

### Path Params

| 字段           | 类型   | 描述                   | 字符数 |
|----------------|--------|------------------------|--------|
| `account_key`  | uuidv4 | 账户的唯一标识键。     | 36     |
| `schedule_key` | uuidv4 | 调度的唯一标识键       | 36     |

### 响应

STATUS 200

Response Body: 已取消调度

```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": {}
}
```

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                     | 描述（英文）<br/>`description`                                                    | 描述（葡文）<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                                   |

---

# 查询 TED 交易调度

URL: /zh-Hans/documentation/baas/ted/schedule/consulta_de_agendamento

## 请求

ENDPOINT /account/ ACCOUNT_KEY /ted_schedule/ SCHEDULE_KEY
方法 GET

### Path Params

| 字段           | 类型   | 描述                   | 字符数 |
|----------------|--------|------------------------|--------|
| `account_key`  | uuidv4 | 账户的唯一标识键。     | 36     |
| `schedule_key` | uuidv4 | 调度的唯一标识键       | 36     |

### 响应

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
    }
  ]
}
```

---

# 简介

URL: /zh-Hans/documentation/baas/ted/schedule/introducao

通过本节介绍的端点，集成合作伙伴可以请求调度 TED 类型的交易。使用此功能，可以创建、列出和取消特定账户的调度。

## 注意事项

- 调度日期考虑巴西利亚时间（BRT 或 UTC/GMT -03:00）
- 交易将从 BRT 上午 8 时开始尝试执行
- 交易不能调度到假日或周末
- 因余额不足而失败的交易将在 1 小时后重试，最多 3 次尝试
- 当调度成功或被拒绝时，将向集成合作伙伴发送 Webhook

## Ted Schedule 状态

| 枚举值                     | 描述                                               |
|----------------------------|----------------------------------------------------|
| **scheduled**              | 交易已调度                                         |
| **sent**                   | 调度已完成并成功发送。最终状态                     |
| **rejected**               | 调度在创建或执行过程中被拒绝。最终状态             |
| **cancelled**              | 应客户请求取消调度。最终状态                       |
| **pending_2fa_approval**   | 待双因素身份验证批准                               |
| **waiting_batch_approval** | 调度已创建并与待双因素身份验证批准的批次关联       |

## Schedule Transfers（调度转账）

在调度当天将尝试执行 TED 交易。此时生成一个 **ted** 并添加到 `schedule_transfers` 列表中。最多尝试 3 次 TED 交易。

---

# 列出账户的 TED 交易调度

URL: /zh-Hans/documentation/baas/ted/schedule/listar_agendamentos_de_uma_conta

## 请求

ENDPOINT /account/ ACCOUNT_KEY /ted_schedules
方法 GET

### Path Params

| 字段          | 类型   | 描述                   | 字符数 |
|---------------|--------|------------------------|--------|
| `account_key` | uuidv4 | 账户的唯一标识键。     | 36     |

### Query Params

| 字段                  | 类型    | 描述                                                                    | 字符数                                                        |
|-----------------------|---------|-------------------------------------------------------------------------|---------------------------------------------------------------|
| `request_control_key` | uuidv4  | 客户使用的请求唯一标识键。                                              | 36                                                            |
| `schedule_status`     | string  | 调度状态。可作为列表发送。                                              | **[Enumerador schedule_status](#enumerador-schedule_status)** |
| `page`                | integer | 请求的页码，默认为 1                                                    |                                                               |
| `page_size`           | integer | 查询中请求的页面大小，默认为 30，最大值为 30                           | 最大值为 30                                                   |

### Enumerador schedule_status

| 枚举值                     | 描述                                               |
|----------------------------|----------------------------------------------------|
| **scheduled**              | 交易已调度                                         |
| **sent**                   | 调度已完成并成功发送。最终状态                     |
| **rejected**               | 调度在创建或执行过程中被拒绝。最终状态             |
| **cancelled**              | 应客户请求取消调度。最终状态                       |
| **pending_2fa_approval**   | 待双因素身份验证批准                               |
| **pending_creation**       | 调度正在创建中（批量调度的过渡状态）               |
| **waiting_batch_approval** | 调度已创建并与待双因素身份验证批准的批次关联       |

### 响应

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
  }
}
```

---

# 请求调度 TED 交易

URL: /zh-Hans/documentation/baas/ted/schedule/solicitacao_de_agendamento

## 请求

ENDPOINT /account/ ACCOUNT_KEY /ted_schedule
方法 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

| 字段          | 类型   | 描述                   | 字符数 |
|---------------|--------|------------------------|--------|
| `account_key` | uuidv4 | 账户的唯一标识键。     | 36     |

## Body Params

| 字段                    | 类型   | 描述                                             | 字符数                                              |
|-------------------------|--------|--------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | string | 客户使用的 uuid v4 格式的请求唯一标识键。        | 36                                                  |
| `target_account` *      | object | 目标账户                                         | **[Objeto target_account](#objeto-target_account)** | 
| `transaction_amount` *  | float  | 转账金额                                         | 10                                                  |
| `schedule_date` *       | string | 执行交易的日期。                                 | 10                                                  |

## Objeto target_account

| 字段                      | 类型   | 描述                                    | 字符数                                                  |
|---------------------------|--------|-----------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string | 银行代码（机构代码）。                  | 4                                                       |
| `account_digit` *         | string | 账户校验码                              | 1                                                       |
| `account_number` *        | string | 账户号码。                              | 20                                                      |
| `owner_document_number` * | string | 账户持有人的 CPF 或 CNPJ（仅数字）。   | 14                                                      |
| `owner_name` *            | string | 账户持有人姓名。                        | 50                                                      |
| `account_type` *          | string | 账户类型。                              | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string | 基于金融机构 CNPJ（8 位数字）。         | 8                                                       |

## Enumerador account_type

| 枚举值                 | 翻译     |
|------------------------|----------|
| **checking_account**   | 活期账户 |
| **deposit_account**    | 存款账户 |
| **guaranteed_account** | 担保账户 |
| **investment_account** | 投资账户 |
| **payment_account**    | 付款账户 |
| **saving_account**     | 储蓄账户 |

## 响应

STATUS 201

Response Body: 已创建调度

```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": {}
}
```

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                    | 描述（英文）<br/>`description`                                                             | 描述（葡文）<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                         |

---

# TED 调度完成 Webhook

URL: /zh-Hans/documentation/baas/ted/schedule/webhook_de_conclusao_de_agendamento

TED 调度完成后，将向集成合作伙伴发送包含结果的 Webhook。

:::danger 注意！
QI Tech 的 Webhook 不应严格映射。我们 API 返回的 Webhook 负载中可能包含额外字段。
:::

### Webhook Request Body

Request Body: 调度已完成并发送

```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: 调度已完成并拒绝

```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

| 字段                  | 类型   | 描述                                                              | 最大字符数                                                         |
|-----------------------|--------|-------------------------------------------------------------------|--------------------------------------------------------------------|
| `webhook_type`        | string | 定义正在报告的事件类型的枚举值                                    | 23                                                                 |
| `webhook_datetime`    | string | Webhook 发送的日期和时间                                          | 20                                                                 |
| `request_control_key` | uuidv4 | 客户使用的 uuid v4 格式的请求唯一标识键。                         | 36                                                                 |
| `schedule_key`        | string | 调度的唯一标识键                                                  | 36                                                                 |
| `schedule_batch_key`  | string | 批量调度的唯一标识键                                              | 36                                                                 |
| `schedule_status`     | string | 调度状态                                                          | **[Enumerador schedule_status](#ted-schedule-status)**             |
| `target_account`      | object | 调度的目标账户                                                    | **[Objeto target_account](#objeto-target_account)**                |
| `transaction_amount`  | number | 转账金额                                                          | 10                                                                 |
| `schedule_transfers`  | array  | 调度执行的转账尝试列表                                            | 列表 **[Objeto schedule_transfer](#objeto-schedule-transfer)** |
| `schedule_date`       | string | 执行交易的日期。                                                  | 10                                                                 |
| `rejection_info`      | object | 包含拒绝事件信息的对象                                            |                                                                    |
| `updated_at`          | string | 调度最后更新的日期和时间。                                        | 20                                                                 |
| `created_at`          | string | 调度创建的日期和时间。                                            | 20                                                                 |

## Ted Schedule 状态

| 枚举值                     | 描述                                               |
|----------------------------|----------------------------------------------------|
| **scheduled**              | 交易已调度                                         |
| **sent**                   | 调度已完成并成功发送。最终状态                     |
| **rejected**               | 调度在创建或执行过程中被拒绝。最终状态             |
| **cancelled**              | 应客户请求取消调度。最终状态                       |
| **pending_2fa_approval**   | 待双因素身份验证批准                               |
| **waiting_batch_approval** | 调度已创建并与待双因素身份验证批准的批次关联       |

### Objeto Schedule Transfer

| 字段         | 类型   | 描述                                   | 字符数                                            |
|--------------|--------|----------------------------------------|---------------------------------------------------|
| `ted_key`    | uuidv4 | QI 系统中 TED 转账的唯一标识键。       | 36                                                |
| `ted_status` | string | 交易状态。                             | [Enumeradores ted_status](#enumerador-ted-status) |
| `fee_amount` | number | 转账金额                               | 10                                                |
| `created_at` | string | 交易创建的日期和时间                   | 20                                                |

### Enumerador Ted Status

| 枚举值       | 描述                   |
|--------------|------------------------|
| **sent**     | 交易已成功发送。最终状态 |
| **rejected** | 交易在执行过程中被拒绝。最终状态 |
| **pending**  | 交易待完成。过渡状态   |

### Objeto target_account

| 字段                    | 类型       | 描述                                                         | 字符数                                                            |
|-------------------------|------------|--------------------------------------------------------------|-------------------------------------------------------------------|
| `account_branch`        | string     | 账户银行代码                                                 | 6                                                                 |
| `account_digit`         | string     | 账户校验码                                                   | 1                                                                 |
| `account_number`        | string     | 账户号码                                                     | 20                                                                |
| `owner_document_number` | string     | 账户持有人的 CPF 或 CNPJ（仅数字）                           | 14                                                                |
| `owner_name`            | string     | 账户持有人姓名                                               | 150                                                               |
| `owner_person_type`     | enumerator | 账户持有人是个人还是法人的标识符                             | **[Enumerador owner_person_type](#enumerador-owner_person_type)** |
| `account_type`          | enumerator | 账户类型                                                     | **[Enumerador account_type](#enumerador-account_type)**           |
| `ispb`                  | string     | 8 位数字，用于标识巴西中央银行储备转账系统中的银行           | 8                                                                 |

### Enumerador owner_person_type

| 枚举值      | 描述 |
|-------------|------|
| **natural** | 个人 |
| **legal**   | 法人 |

## Enumerador account_type

| 枚举值                 | 翻译     |
|------------------------|----------|
| **checking_account**   | 活期账户 |
| **deposit_account**    | 存款账户 |
| **guaranteed_account** | 担保账户 |
| **investment_account** | 投资账户 |
| **payment_account**    | 付款账户 |
| **saving_account**     | 储蓄账户 |

---

# TED 发送完成后的 Webhook

URL: /zh-Hans/documentation/baas/ted/webhooks

Webhook 将通知 TED 交易是否已被退回。

## Webhook Request Body

**Webhook Body: TED 已拒绝**

```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 已确认**

```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

| 字段                  | 类型   | 描述                                                              | 最大字符数                                          |
|-----------------------|--------|-------------------------------------------------------------------|-----------------------------------------------------|
| `webhook_type`        | string | 定义正在报告的事件类型的枚举值                                    | 23                                                  |
| `webhook_datetime`    | string | Webhook 发送的日期和时间                                          | 20                                                  |
| `request_control_key` | string | 客户使用的 uuid v4 格式的请求唯一标识键                           | 36                                                  | 
| `ted_key`             | string | TED 转账的唯一标识键                                              | 36                                                  |
| `created_at`          | string | 交易创建的日期和时间                                              | 24                                                  |
| `ted_status`          | string | TED 交易状态                                                      | **[Enumerador ted_status](#enumerador-ted_status)** |
| `transaction_amount`  | number | 转账金额                                                          | 10                                                  |
| `fee_amount`          | number | 转账收取的费用金额                                                | 35                                                  |
| `target_account`      | Object | 目标账户 - 仅在"manual"类型的交易中发送                           | **[Objeto target_account](#objeto-target_account)** |
| `refusal_reason`      | Object | 根据巴西中央银行标准的拒绝原因                                    | **[Objeto refusal_reason](#objeto-refusal_reason)** |

## Enumerador ted_status

| 枚举值        | 描述                 |
|---------------|----------------------|
| **sent**      | TED 转账已成功发送。 |
| **confirmed** | TED 转账成功完成。   |
| **pending**   | TED 转账待处理。     |
| **rejected**  | TED 转账已拒绝。     |
| **returned**  | TED 转账已退回。     |

## Objeto target_account

| 字段                      | 类型   | 描述                                    | 字符数                                                  |
|---------------------------|--------|-----------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string | 银行代码（机构代码）。                  | 4                                                       |
| `account_digit` *         | string | 账户校验码                              | 1                                                       |
| `account_number` *        | string | 账户号码。                              | 20                                                      |
| `owner_document_number` * | string | 账户持有人的 CPF 或 CNPJ（仅数字）。   | 14                                                      |
| `owner_name` *            | string | 账户持有人姓名。                        | 50                                                      |
| `account_type` *          | string | 账户类型。                              | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string | 基于金融机构 CNPJ（8 位数字）。         | 8                                                       |

## Objeto refusal_reason

| 字段            | 类型   | 描述                      | 字符数 |
|-----------------|--------|---------------------------|--------|
| `bacen_code` *  | string | 巴西中央银行拒绝代码      | 3      |
| `enumerator` *  | string | 巴西中央银行拒绝枚举值    | 100    |
| `description` * | string | 巴西中央银行拒绝描述      | 100    |

## Enumerador account_type

| 枚举值             | 翻译     |
|--------------------|----------|
| checking_account   | 活期账户 |
| deposit_account    | 存款账户 |
| guaranteed_account | 担保账户 |
| investment_account | 投资账户 |
| payment_account    | 付款账户 |
| saving_account     | 储蓄账户 |

## 接收 TED 后的 Webhook

Webhook 将通知 TED 交易的最终状态。

## Webhook Request Body

**Request Body: 已接收 TED**

```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

| 字段                  | 类型   | 描述                                                              | 最大字符数                                          |
|-----------------------|--------|-------------------------------------------------------------------|-----------------------------------------------------|
| `webhook_type`        | string | 定义正在报告的事件类型的枚举值                                    | 23                                                  |
| `webhook_datetime`    | string | Webhook 发送的日期和时间                                          | 20                                                  |
| `ted_key`             | string | TED 转账的唯一标识键                                              | 36                                                  |
| `created_at`          | string | 交易创建的日期和时间                                              | 100                                                 |
| `ted_status`          | string | TED 交易状态                                                      | **[Enumerador ted_status](#enumerador-ted_status)** |
| `transaction_amount`  | number | 转账金额                                                          | 10                                                  |
| `fee_amount`          | number | 转账收取的费用金额                                                | 35                                                  |
| `target_account`      | Object | 目标账户 - 仅在"manual"类型的交易中发送                           | **[Objeto target_account](#objeto-target_account)** |
| `refusal_reason`      | Object | 根据巴西中央银行标准的拒绝原因                                    | **[Objeto refusal_reason](#objeto-refusal_reason)** |

## Enumerador ted_status

| 枚举值       | 描述               |
|--------------|--------------------|
| **received** | TED 转账已成功接收。 |
| **pending**  | TED 转账待处理。   |
| **rejected** | TED 转账已拒绝。   |

## Objeto target_account

| 字段                      | 类型   | 描述                                    | 字符数                                                  |
|---------------------------|--------|-----------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string | 银行代码（机构代码）。                  | 10                                                      |
| `account_digit` *         | string | 账户校验码                              | 10                                                      |
| `account_number` *        | string | 账户号码。                              | 10                                                      |
| `owner_document_number` * | string | 账户持有人的 CPF 或 CNPJ（仅数字）。   | 14                                                      |
| `owner_name` *            | string | 账户持有人姓名。                        | 50                                                      |
| `account_type` *          | string | 账户类型。                              | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string | 基于金融机构 CNPJ（8 位数字）。         | 8                                                       |

## Objeto refusal_reason

| 字段            | 类型   | 描述                      | 字符数 |
|-----------------|--------|---------------------------|--------|
| `bacen_code` *  | string | 巴西中央银行拒绝代码      | 3      |
| `enumerator` *  | string | 巴西中央银行拒绝枚举值    | 100    |
| `description` * | string | 巴西中央银行拒绝描述      | 100    |

## Enumerador account_type

| 枚举值             | 翻译     |
|--------------------|----------|
| checking_account   | 活期账户 |
| deposit_account    | 存款账户 |
| guaranteed_account | 担保账户 |
| investment_account | 投资账户 |
| payment_account    | 付款账户 |
| saving_account     | 储蓄账户 |

---

# baas_consulta_documents

URL: /zh-Hans/documentation/baas/upload_de_documentos/baas_consulta_documents



---

# baas_upload_de_documentos

URL: /zh-Hans/documentation/baas/upload_de_documentos/



---

# 批准票据支付

URL: /zh-Hans/documentation/boletos/2fa/realizar_pagamento_de_um_boleto

要支付票据，需要进行两次调用：

1. 请求转账验证 token：/baas/token_request

2. 批准转账：/baas/movement_validation

:::info
发送的 Token 必须在批准票据支付时提供，且 "***movement_payload***" 必须与请求 Token 时提供的内容相同。
:::

## Request

方法 POST
端点 /baas/movement_validation

Request Body

```json
{
    "token": "358192",
    "movement_payload": {
        "resource_account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
        "digitable_line": "32990001031000699926165000000201993810000003500"
    }
}

```

## Body Params
| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---| ---|
| `token` * | string | 认证 token | 6 |
| `agent_document_number` * | string | 将接收 token 的用户 CPF（仅数字） | 11 | 
| `movement_payload` | Object | 包含转账信息的 payload | **[Objeto movement_payload](#objeto-movement_payload)** | 

### Objeto movement_payload

| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---| ---|
| `resource_account_key` * | uuuidv4 | 将执行支付的账户唯一标识键 | 36 |
| `digitable_line` * | float |  票据可输入行 | 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"
    }
```

---

# 请求票据支付 token

URL: /zh-Hans/documentation/boletos/2fa/solicitar_token_para_pagamento

要支付票据，需要进行两次调用：

1. 请求转账验证 token：/baas/token_request

2. 批准转账：/baas/movement_validation

## Request

- 方法 POST
- 端点 /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
| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---| ---|
| `contact_type` * | string | 发送认证 token 的方式，可通过电子邮件（"email"）或短信（"sms"）发送 | 10 |
| `agent_document_number` * | string | 将接收 token 的用户 CPF（仅数字） | 11 | 
| `movement_payload` | Object | 包含转账信息的 payload | **[Objeto movement_payload](#objeto-movement_payload)** | 

### Objeto movement_payload

| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---| ---|
| `resource_account_key` * | uuuidv4 | 将执行支付的账户唯一标识键 | 36 |
| `digitable_line` * | float |  票据可输入行 | 47 |

## Response

STATUS 200

Response Body
```json
{}
```

---

# 创建钱包

URL: /zh-Hans/documentation/boletos/carteira/criar_carteira

:::danger 重要
要登记 bolePix，账户中必须存在一个有效的随机 PIX 密钥，票据将在该账户中登记。
:::

票据钱包具有唯一识别码（`requester_profile_code`）以及票据支付、核销、抗议等特定默认配置。同一账户可拥有多个票据钱包，允许用户创建具有不同默认配置的多个钱包。这种机制简化了票据的生成，使不同配置的票据可以更快速、自动地生成。

:::info 信息
所有账户在创建时都会自动生成一个带有客户默认配置的票据钱包。该默认配置可通过联系我们的支持团队（suporte.baas@qitech.com.br）进行更改。账户创建后，也可以使用[**费率配置端点**](/documentation/contas/consulta_de_tarifas)修改账户费率。
:::

:::caution 注意！
钱包创建是异步流程。在 CIP/Núclea 批准或拒绝钱包创建后，申请人将通过 [**webhook**](/documentation/boletos/v2/webhooks/carteira) 收到相关结果通知。
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile
MÉTODO POST

### Path parameters

| 字段                    | 类型   | 描述                                                  | 字符数 |
|-------------------------|--------|-------------------------------------------------------|--------|
| `account_key`           | uuidv4 | 账户唯一标识键，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

| 字段                      | 类型    | 描述                                                                         | 字符数 |
|---------------------------|---------|------------------------------------------------------------------------------|--------|
| `request_control_key` *   | uuidv4  | 客户使用的请求唯一标识键，uuid v4 格式                                       | 36     |
| `configuration_data` *    | object  | 钱包默认配置 | **[Objeto configuration_data](#objeto-configuration_data)** |

### Objeto configuration_data

| 字段                         | 类型    | 描述                                                                         | 字符数 |
|------------------------------|---------|------------------------------------------------------------------------------|--------|
| `max_payment_days` *         | integer | 票据到期后可供付款的最大日历天数（最多 365 天）                             | -      |
| `write_off_settings`         | object  | 默认核销配置 | **[Objeto write_off_settings](#objeto-write_off_settings)** |
| `protest_settings`           | object  | 默认抗议配置 | **[Objeto protest_settings](#objeto-protest_settings)** |
| `bankruptcy_protest_settings` | object | 默认破产抗议配置 | **[Objeto bankruptcy_protest_settings](#objeto-bankruptcy_protest_settings)** |
| `fine_settings`              | object  | 默认罚款配置 | **[Objeto fine_setings](#objeto-fine_settings)** |
| `interest_settings`          | object  | 默认利息配置 | **[Objeto interest_settings](#objeto-interest_settings)** |
| `qr_code_settings`           | object  | PIX QR Code 默认配置（用于 bolePix） | **[Objeto qr_code_settings](#objeto-qr_code_settings)** |
| `cnab_settings`              | object  | CNAB 文件默认配置 | **[Objeto cnab_settings](#objeto-cnab_settings)** |

### Objeto write_off_settings

| 字段                      | 类型    | 描述                                        | 字符数 |
|---------------------------|---------|---------------------------------------------|--------|
| `days_to_write_off` *     | integer | 到期后自动核销票据的天数                    | -      |

### Objeto protest_settings
| 字段                      | 类型    | 描述                                        | 字符数 |
|---------------------------|---------|---------------------------------------------|--------|
| `days_to_protest` *       | integer | 到期后自动抗议票据的天数                    | -      |

### Objeto bankruptcy_protest_settings

| 字段                           | 类型    | 描述                                              | 字符数 |
|--------------------------------|---------|---------------------------------------------------|--------|
| `days_to_bankruptcy_protest` * | integer | 到期后自动启动破产抗议流程的天数                  | -      |

### Objeto fine_settings

选项 1：绝对值罚款（`fine_type=absolute`）

| 字段                      | 类型    | 描述                                          | 字符数                                                               |
|---------------------------|---------|-----------------------------------------------|----------------------------------------------------------------------|
| `fine_type` *             | string  | 罚款类型                                      | **[Enumeradores fine_type](#enumeradores-fine_type)**                |
| `fine_amount` *           | float   | 罚款绝对值                                    | -                                                                    |
| `days_to_fine` *          | integer | 到期后开始收取罚款的天数                      | -                                                                    |

选项 2：百分比罚款（`fine_type=percentage`）

| 字段                      | 类型    | 描述                                          | 字符数                                                |
|---------------------------|---------|-----------------------------------------------|-------------------------------------------------------|
| `fine_type` *             | string  | 罚款类型                                      | **[Enumeradores fine_type](#enumeradores-fine_type)** |
| `fine_percentage` *       | integer | 罚款百分比值，1 到 100                        | -                                                     |
| `days_to_fine` *          | integer | 到期后开始收取罚款的天数                      | -                                                     |

### Enumeradores fine_type

| 枚举值             | 描述             |
|--------------------|------------------|
| absolute           | 绝对值           |
| percentage         | 百分比值         |

### Objeto interest_settings

选项 1：使用绝对值利息（`interest_type=calendar_days_daily_amount` 或 `interest_type=workdays_daily_amount`）

| 字段                      | 类型    | 描述                                                          | 字符数                                                                                   |
|---------------------------|---------|---------------------------------------------------------------|------------------------------------------------------------------------------------------|
| `interest_type` *         | string  | 利息类型 | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `interest_amount` *       | float   | 按指定时间单位（工作日或日历日）收取的金额                    | -                                                                                        |
| `days_to_interest` *      | integer | 到期后开始收取利息的天数                                      | -                                                                                        |

选项 2：使用百分比利息（`interest_type=calendar_days_monthly_percentage`）

| 字段                     | 类型    | 描述                                                          | 字符数                                                                                       |
|--------------------------|---------|---------------------------------------------------------------|----------------------------------------------------------------------------------------------|
| `interest_type` *        | string  | 利息类型 | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `interest_percentage` *  | integer | 按指定时间单位（工作日或日历日）收取的百分比                  | -                                                                                            |
| `days_to_interest` *     | integer | 到期后开始收取利息的天数                                      | -                                                                                            |

### Enumeradores interest_type

| 枚举值                             | 描述                                          |
|------------------------------------|-----------------------------------------------|
| calendar_days_daily_amount         | 基于日历日的每日金额                          |
| workdays_daily_amount              | 基于工作日的每日金额                          |
| calendar_days_monthly_percentage   | 基于日历日按月收取的利息百分比               |

### Objeto qr_code_settings

| 字段                              | 类型    | 描述                                              | 字符数 |
|-----------------------------------|---------|---------------------------------------------------|--------|
| `pix_key` *                       | uuidv4  | 随机类型的 PIX 密钥                               | 36     |
| `qr_code_on_discharge_enabled` *  | boolean | 确定 QR Code 信息是否包含在退款文件（CNAB）中     | -      |

:::info 信息
PIX 复制粘贴将在 CNAB 文件的第 029 至 105 位置返回。
:::

:::caution 注意！
若在请求中发送 `qr_code_settings` 对象，该钱包将以生成 bolePix 作为 默认配置 。bolePix 是一种支付与 PIX QR Code 绑定的票据。因此，付款人可以通过票据的可输入行或扫描绑定的 PIX QR Code 进行支付。若通过 QR Code 支付，财务清算将即时完成。关于通知，将发送两个 webhook：一个在 PIX 转账时（支付通知，票据转为 `payment_notice` 状态）；另一个在 CIP/Núclea 确认核销后几秒或几分钟后（已支付，票据转为 `paid` 状态）。
:::

### Objeto cnab_settings

| 字段                              | 类型    | 描述                                              | 字符数 |
|-----------------------------------|---------|---------------------------------------------------|--------|
| `default_bank`                    | string  | 处理 CNAB 文件的默认银行布局                      | **[Enumeradores default_bank](#enumeradores-default_bank)** |
| `preferred_layout`                | string  | CNAB 文件首选布局                                 | **[Enumeradores preferred_layout](#enumeradores-preferred_layout)** |

### Enumeradores default_bank

| 枚举值             | 描述             |
|--------------------|------------------|
| santander          | Banco Santander  |
| itau               | Banco Itaú       |
| bradesco           | Banco Bradesco   |
| qi_scd             | QI SCD           |

### Enumeradores preferred_layout

| 枚举值             | 描述             |
|--------------------|------------------|
| 400                | CNAB 400 布局    |
| 240                | 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

| 字段                       | 类型    | 描述                                                    | 字符数 |
|----------------------------|---------|---------------------------------------------------------|--------------------------------------------------------------|
| `requester_profile_key` *  | uuidv4  | 钱包唯一标识键，uuid v4 格式  | 36      |
| `requester_profile_code` * | string  | 钱包唯一识别码                | 19      |
| `request_control_key` *    | uuidv4  | 客户使用的请求唯一标识键，uuid v4 格式 | 36 |
| `account_key` *            | uuidv4  | 账户唯一标识键，uuid v4 格式 | 36 |
| `requester_profile_status` * | string | 钱包状态 | **[Enumeradores requester_profile_status](#enumeradores-requester_profile_status)** |
| `configuration_data` * | object | 钱包默认配置 | **[Objeto configuration_data](#objeto-configuration_data)** |

### Enumeradores profile_status

| 枚举值                             | 描述                                          |
|------------------------------------|-----------------------------------------------|
| pending                            | 钱包已接受，等待确认                          |

## Error Response

STATUS 4xx

Response Body: Error

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

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                   | 描述（英文）<br/>`description`                                                                                          | 描述（葡文）<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.                                                           |

---

# 编辑钱包

URL: /zh-Hans/documentation/boletos/carteira/editar_carteira

编辑钱包将覆盖票据钱包的默认配置（`configuration_data`）及其所有子对象。

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY
MÉTODO PUT

### Path parameters

| 字段                    | 类型   | 描述                                                  | 字符数 |
|-------------------------|--------|-------------------------------------------------------|--------|
| `account_key`           | uuidv4 | 账户唯一标识键，uuid v4 格式                          | 36     |
| `requester_profile_key` | uuidv4 | 钱包唯一标识键，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

| 字段                         | 类型    | 描述                                                                         | 字符数 |
|------------------------------|---------|------------------------------------------------------------------------------|--------|
| `max_payment_days` *         | integer | 票据到期后可供付款的最大日历天数（最多 365 天）                             | -      |
| `write_off_settings`         | object  | 默认核销配置 | **[Objeto write_off_settings](#objeto-write_off_settings)** |
| `protest_settings`           | object  | 默认抗议配置 | **[Objeto protest_settings](#objeto-protest_settings)** |
| `bankruptcy_protest_settings` | object | 默认破产抗议配置 | **[Objeto bankruptcy_protest_settings](#objeto-bankruptcy_protest_settings)** |
| `fine_settings`              | object  | 默认罚款配置 | **[Objeto fine_setings](#objeto-fine_settings)** |
| `interest_settings`          | object  | 默认利息配置 | **[Objeto interest_settings](#objeto-interest_settings)** |
| `qr_code_settings`           | object  | PIX QR Code 默认配置（用于 bolePix） | **[Objeto qr_code_settings](#objeto-qr_code_settings)** |
| `cnab_settings`              | object  | CNAB 文件默认配置 | **[Objeto cnab_settings](#objeto-cnab_settings)** |

### Objeto write_off_settings

| 字段                      | 类型    | 描述                                        | 字符数 |
|---------------------------|---------|---------------------------------------------|--------|
| `days_to_write_off` *     | integer | 到期后自动核销票据的天数                    | -      |

### Objeto protest_settings
| 字段                      | 类型    | 描述                                        | 字符数 |
|---------------------------|---------|---------------------------------------------|--------|
| `days_to_protest` *       | integer | 到期后自动抗议票据的天数                    | -      |

### Objeto bankruptcy_protest_settings

| 字段                           | 类型    | 描述                                              | 字符数 |
|--------------------------------|---------|---------------------------------------------------|--------|
| `days_to_bankruptcy_protest` * | integer | 到期后自动启动破产抗议流程的天数                  | -      |

### Objeto fine_settings

选项 1：绝对值罚款（`fine_type=absolute`）

| 字段                      | 类型    | 描述                                          | 字符数                                                               |
|---------------------------|---------|-----------------------------------------------|----------------------------------------------------------------------|
| `fine_type` *             | string  | 罚款类型                                      | **[Enumeradores fine_type](#enumeradores-fine_type)**                |
| `fine_amount` *           | float   | 罚款绝对值                                    | -                                                                    |
| `days_to_fine` *          | integer | 到期后开始收取罚款的天数                      | -                                                                    |

选项 2：百分比罚款（`fine_type=percentage`）

| 字段                      | 类型    | 描述                                          | 字符数                                                |
|---------------------------|---------|-----------------------------------------------|-------------------------------------------------------|
| `fine_type` *             | string  | 罚款类型                                      | **[Enumeradores fine_type](#enumeradores-fine_type)** |
| `fine_percentage` *       | integer | 罚款百分比值，1 到 100                        | -                                                     |
| `days_to_fine` *          | integer | 到期后开始收取罚款的天数                      | -                                                     |

### Enumeradores fine_type

| 枚举值             | 描述             |
|--------------------|------------------|
| absolute           | 绝对值           |
| percentage         | 百分比值         |

### Objeto interest_settings

选项 1：使用绝对值利息（`interest_type=calendar_days_daily_amount` 或 `interest_type=workdays_daily_amount`）

| 字段                      | 类型    | 描述                                                          | 字符数                                                                                   |
|---------------------------|---------|---------------------------------------------------------------|------------------------------------------------------------------------------------------|
| `interest_type` *         | string  | 利息类型 | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `interest_amount` *       | float   | 按指定时间单位（工作日或日历日）收取的金额                    | -                                                                                        |
| `days_to_interest` *      | integer | 到期后开始收取利息的天数                                      | -                                                                                        |

选项 2：使用百分比利息（`interest_type=calendar_days_monthly_percentage`）

| 字段                     | 类型    | 描述                                                          | 字符数                                                                                       |
|--------------------------|---------|---------------------------------------------------------------|----------------------------------------------------------------------------------------------|
| `interest_type` *        | string  | 利息类型 | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `interest_percentage` *  | integer | 按指定时间单位（工作日或日历日）收取的百分比                  | -                                                                                            |
| `days_to_interest` *     | integer | 到期后开始收取利息的天数                                      | -                                                                                            |

### Enumeradores interest_type

| 枚举值                             | 描述                                          |
|------------------------------------|-----------------------------------------------|
| calendar_days_daily_amount         | 基于日历日的每日金额                          |
| workdays_daily_amount              | 基于工作日的每日金额                          |
| calendar_days_monthly_percentage   | 基于日历日按月收取的利息百分比               |

### Objeto qr_code_settings

| 字段                              | 类型    | 描述                                              | 字符数 |
|-----------------------------------|---------|---------------------------------------------------|--------|
| `pix_key` *                       | uuidv4  | 随机类型的 PIX 密钥                               | 36     |
| `qr_code_on_discharge_enabled` *  | boolean | 确定 QR Code 信息是否包含在退款文件（CNAB）中     | -      |

:::info 信息
PIX 复制粘贴将在 CNAB 文件的第 029 至 105 位置返回。
:::

:::caution 注意！
若在请求中发送 `qr_code_settings` 对象，该钱包将以生成 bolePix 作为 默认配置 。bolePix 是一种支付与 PIX QR Code 绑定的票据。因此，付款人可以通过票据的可输入行或扫描绑定的 PIX QR Code 进行支付。若通过 QR Code 支付，财务清算将即时完成。关于通知，将发送两个 webhook：一个在 PIX 转账时（支付通知，票据转为 `payment_notice` 状态）；另一个在 CIP/Núclea 确认核销后几秒或几分钟后（已支付，票据转为 `paid` 状态）。
:::

### Objeto cnab_settings

| 字段                              | 类型    | 描述                                              | 字符数 |
|-----------------------------------|---------|---------------------------------------------------|--------|
| `default_bank`                    | string  | 处理 CNAB 文件的默认银行布局                      | **[Enumeradores default_bank](#enumeradores-default_bank)** |
| `preferred_layout`                | string  | CNAB 文件首选布局                                 | **[Enumeradores preferred_layout](#enumeradores-preferred_layout)** |

### Enumeradores default_bank

| 枚举值             | 描述             |
|--------------------|------------------|
| santander          | Banco Santander  |
| itau               | Banco Itaú       |
| bradesco           | Banco Bradesco   |
| qi_scd             | QI SCD           |

### Enumeradores preferred_layout

| 枚举值             | 描述             |
|--------------------|------------------|
| 400                | CNAB 400 布局    |
| 240                | 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

| 字段                       | 类型    | 描述                                                    | 字符数 |
|----------------------------|---------|---------------------------------------------------------|--------------------------------------------------------------|
| `requester_profile_key` *  | uuidv4  | 钱包唯一标识键，uuid v4 格式  | 36      |
| `requester_profile_code` * | string  | 钱包唯一识别码                | 19      |
| `request_control_key` *    | uuidv4  | 客户使用的请求唯一标识键，uuid v4 格式 | 36 |
| `account_key` *            | uuidv4  | 账户唯一标识键，uuid v4 格式 | 36 |
| `requester_profile_status` * | string | 钱包状态 | **[Enumeradores requester_profile_status](#enumeradores-requester_profile_status)** |
| `configuration_data` * | object | 钱包默认配置 | **[Objeto configuration_data](#objeto-configuration_data)** |

### Enumeradores profile_status

| 枚举值                             | 描述                                          |
|------------------------------------|-----------------------------------------------|
| pending                            | 钱包已接受，等待确认                          |
| opened                             | 钱包已开启                                    |

## Error Response

STATUS 4xx

Response Body: Error

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

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                   | 描述（英文）<br/>`description`                                                                                          | 描述（葡文）<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.                                                           |

---

# 列出账户钱包

URL: /zh-Hans/documentation/boletos/carteira/listar_carteiras

钱包列表将返回符合请求中发送的 查询参数 的所有账户票据钱包。

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profiles
MÉTODO GET

### Path parameters

| 字段                    | 类型   | 描述                                                  | 字符数 |
|-------------------------|--------|-------------------------------------------------------|--------|
| `account_key`           | uuidv4 | 账户唯一标识键，uuid v4 格式                          | 36     |

### Query parameters

| 字段                     | 类型   | 描述                                                                | 字符数 |
|--------------------------|--------|---------------------------------------------------------------------|--------|
| `request_control_key`    | uuidv4 | 请求唯一标识键，uuid v4 格式                                         | 36     |
| `requester_profile_key`  | uuidv4 | 票据钱包唯一标识键，uuid v4 格式                                     | 36     |
| `requester_profile_code` | string | 钱包唯一识别码                                                       | 19     |
| `page`                   | integer| 页码                                                                 | -      |
| `page_size`              | integer| 每页大小                                                             | -      |

## 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

| 字段           | 类型         | 描述                     | 字符数                                                     |
|----------------|--------------|--------------------------|-----------------------------------------------------------|
| `data` *       | object array | 票据钱包列表             | **[Objeto requester_profile](#objeto-requester_profile)** |
| `pagination` * | object       | 分页信息                 | **[Objeto pagination](#objeto-pagination)**               |

### Objeto requester_profile

| 字段                       | 类型    | 描述                                                    | 字符数 |
|----------------------------|---------|---------------------------------------------------------|--------------------------------------------------------------|
| `requester_profile_key` *  | uuidv4  | 钱包唯一标识键，uuid v4 格式  | 36      |
| `requester_profile_code` * | string  | 钱包唯一识别码                | 19      |
| `request_control_key` *    | uuidv4  | 客户使用的请求唯一标识键，uuid v4 格式 | 36 |
| `account_key` *            | uuidv4  | 账户唯一标识键，uuid v4 格式 | 36 |
| `requester_profile_status` * | string | 钱包状态 | **[Enumeradores requester_profile_status](#enumeradores-requester_profile_status)** |
| `configuration_data` * | object | 钱包默认配置 | **[Objeto configuration_data](#objeto-configuration_data)** |

### Enumeradores requester_profile_status

| 枚举值                             | 描述                                          |
|------------------------------------|-----------------------------------------------|
| pending                            | 钱包已接受，等待确认                          |
| opened                             | 钱包已开启                                    |

### Objeto pagination

| 字段                       | 类型    | 描述                       | 字符数 |
|----------------------------|---------|----------------------------|--------|
| `current_page` *           | integer | 当前页码                   | -      |
| `rows_per_page` *          | integer | 每页记录数                 | -      |

### Objeto configuration_data

| 字段                         | 类型    | 描述                                                                         | 字符数 |
|------------------------------|---------|------------------------------------------------------------------------------|--------|
| `max_payment_days` *         | integer | 票据到期后可供付款的最大日历天数（最多 365 天）                             | -      |
| `write_off_settings`         | object  | 默认核销配置 | **[Objeto write_off_settings](#objeto-write_off_settings)** |
| `protest_settings`           | object  | 默认抗议配置 | **[Objeto protest_settings](#objeto-protest_settings)** |
| `bankruptcy_protest_settings` | object | 默认破产抗议配置 | **[Objeto bankruptcy_protest_settings](#objeto-bankruptcy_protest_settings)** |
| `fine_settings`              | object  | 默认罚款配置 | **[Objeto fine_setings](#objeto-fine_settings)** |
| `interest_settings`          | object  | 默认利息配置 | **[Objeto interest_settings](#objeto-interest_settings)** |
| `qr_code_settings`           | object  | PIX QR Code 默认配置（用于 bolePix） | **[Objeto qr_code_settings](#objeto-qr_code_settings)** |
| `cnab_settings`              | object  | CNAB 文件默认配置 | **[Objeto cnab_settings](#objeto-cnab_settings)** |

### Objeto write_off_settings

| 字段                      | 类型    | 描述                                        | 字符数 |
|---------------------------|---------|---------------------------------------------|--------|
| `days_to_write_off` *     | integer | 到期后自动核销票据的天数                    | -      |

### Objeto protest_settings
| 字段                      | 类型    | 描述                                        | 字符数 |
|---------------------------|---------|---------------------------------------------|--------|
| `days_to_protest` *       | integer | 到期后自动抗议票据的天数                    | -      |

### Objeto bankruptcy_protest_settings

| 字段                           | 类型    | 描述                                              | 字符数 |
|--------------------------------|---------|---------------------------------------------------|--------|
| `days_to_bankruptcy_protest` * | integer | 到期后自动启动破产抗议流程的天数                  | -      |

### Objeto fine_settings

选项 1：绝对值罚款（`fine_type=absolute`）

| 字段                      | 类型    | 描述                                          | 字符数                                                               |
|---------------------------|---------|-----------------------------------------------|----------------------------------------------------------------------|
| `fine_type` *             | string  | 罚款类型                                      | **[Enumeradores fine_type](#enumeradores-fine_type)**                |
| `fine_amount` *           | float   | 罚款绝对值                                    | -                                                                    |
| `days_to_fine` *          | integer | 到期后开始收取罚款的天数                      | -                                                                    |

选项 2：百分比罚款（`fine_type=percentage`）

| 字段                      | 类型    | 描述                                          | 字符数                                                |
|---------------------------|---------|-----------------------------------------------|-------------------------------------------------------|
| `fine_type` *             | string  | 罚款类型                                      | **[Enumeradores fine_type](#enumeradores-fine_type)** |
| `fine_percentage` *       | integer | 罚款百分比值，1 到 100                        | -                                                     |
| `days_to_fine` *          | integer | 到期后开始收取罚款的天数                      | -                                                     |

### Enumeradores fine_type

| 枚举值             | 描述             |
|--------------------|------------------|
| absolute           | 绝对值           |
| percentage         | 百分比值         |

### Objeto interest_settings

选项 1：使用绝对值利息（`interest_type=calendar_days_daily_amount` 或 `interest_type=workdays_daily_amount`）

| 字段                      | 类型    | 描述                                                          | 字符数                                                                                   |
|---------------------------|---------|---------------------------------------------------------------|------------------------------------------------------------------------------------------|
| `interest_type` *         | string  | 利息类型 | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `interest_amount` *       | float   | 按指定时间单位（工作日或日历日）收取的金额                    | -                                                                                        |
| `days_to_interest` *      | integer | 到期后开始收取利息的天数                                      | -                                                                                        |

选项 2：使用百分比利息（`interest_type=calendar_days_monthly_percentage`）

| 字段                     | 类型    | 描述                                                          | 字符数                                                                                       |
|--------------------------|---------|---------------------------------------------------------------|----------------------------------------------------------------------------------------------|
| `interest_type` *        | string  | 利息类型 | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `interest_percentage` *  | integer | 按指定时间单位（工作日或日历日）收取的百分比                  | -                                                                                            |
| `days_to_interest` *     | integer | 到期后开始收取利息的天数                                      | -                                                                                            |

### Enumeradores interest_type

| 枚举值                             | 描述                                          |
|------------------------------------|-----------------------------------------------|
| calendar_days_daily_amount         | 基于日历日的每日金额                          |
| workdays_daily_amount              | 基于工作日的每日金额                          |
| calendar_days_monthly_percentage   | 基于日历日按月收取的利息百分比               |

### Objeto qr_code_settings

| 字段                              | 类型    | 描述                                              | 字符数 |
|-----------------------------------|---------|---------------------------------------------------|--------|
| `pix_key` *                       | uuidv4  | 随机类型的 PIX 密钥                               | 36     |
| `qr_code_on_discharge_enabled` *  | boolean | 确定 QR Code 信息是否包含在退款文件（CNAB）中     | -      |

### Objeto cnab_settings

| 字段                              | 类型    | 描述                                              | 字符数 |
|-----------------------------------|---------|---------------------------------------------------|--------|
| `default_bank`                    | string  | 处理 CNAB 文件的默认银行布局                      | **[Enumeradores default_bank](#enumeradores-default_bank)** |
| `preferred_layout`                | string  | CNAB 文件首选布局                                 | **[Enumeradores preferred_layout](#enumeradores-preferred_layout)** |

### Enumeradores default_bank

| 枚举值             | 描述             |
|--------------------|------------------|
| santander          | Banco Santander  |
| itau               | Banco Itaú       |
| bradesco           | Banco Bradesco   |
| qi_scd             | QI SCD           |

### Enumeradores preferred_layout

| 枚举值             | 描述             |
|--------------------|------------------|
| 400                | CNAB 400 布局    |
| 240                | 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": {}
}
```

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                   | 描述（英文）<br/>`description`                                                                                          | 描述（葡文）<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.                          |

---

# 查询临时文件

URL: /zh-Hans/documentation/boletos/cnab/consulta_por_chave

通过键查询临时 CNAB 文件，可返回有关该文件的详细信息，例如已处理的记录数量以及文件中发现的可能错误。

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /temporary_cnab_file/ TEMPORARY_CNAB_FILE_KEY
MÉTODO GET

### Path parameters

| 字段                      | 类型   | 描述                                                    | 字符数 |
|---------------------------|--------|--------------------------------------------------------|--------|
| `account_key`             | uuidv4 | 账户唯一标识键，uuid v4 格式                            | 36     |
| `requester_profile_key`   | uuidv4 | 钱包唯一标识键，uuid v4 格式                            | 36     |
| `temporary_cnab_file_key` | uuidv4 | 临时 CNAB 文件唯一标识键，uuid v4 格式                  | 36     |

## Response

STATUS 200

Response Body: 文件已接受（无错误）

```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: 文件已拒绝（有错误）

```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

| 字段                           | 类型         | 描述                                                                       | 字符数 |
|--------------------------------|--------------|----------------------------------------------------------------------------|--------------------------------------------------|
| `temporary_cnab_file_key` *    | uuidv4       | 临时 CNAB 文件唯一标识键，uuid v4 格式                                     | 36                                                |
| `temporary_cnab_file_name` *   | uuidv4       | 文件名                                                                     | 100                                               |
| `temporary_cnab_file_status` * | string       | 临时 CNAB 文件状态 | **[Enumeradores temporary_cnab_file_status](#enumeradores-temporary_cnab_file_status)** |
| `occurrence_quantity` *        | integer      | 文件中的记录数量                                                           | -                                                 |
| `total_processed_occurrences` *| integer      | 已处理的记录数量                                                           | -                                                 |
| `error_data`                   | object array | 文件中发现的错误对象（JSON 格式），与 API 返回格式相同 | **[Objeto error_data](#objeto-error_data)**       |
| `created_at` *                 | string       | 文件在数据库中创建的时间戳，ISO Zulu 格式                                 | 20                                         |

### Enumeradores temporary_cnab_file_status

| 枚举值                       | 描述                                                         |
|------------------------------|--------------------------------------------------------------|
| uploaded                     | 上传成功，但文件尚未开始处理                                 |
| processing                   | 文件正在读取中                                               |
| read                         | 文件已读取并接受                                             |
| rejected                     | 文件已读取并因语法错误被拒绝                                 |

### Objeto error_data

| 字段            | 类型    | 描述                       | 字符数 |
|-----------------|---------|----------------------------|--------------------------------------------------|
| `code` *        | string  | 错误代码                   | 9                                                |
| `title` *       | string  | 错误标题                   | 100                                               |
| `description` * | string  | 错误描述（英文）           | 100 |
| `translation` * | integer | 错误描述翻译               | 100                                               |
| `extra_fields`  | object  | 关于错误的附加信息         | -                                         |

:::danger 重要
`extra_fields` 对象中返回的字段用于提供关于错误的附加信息，可能有所不同。因此，不应以严格限定的方式进行映射。
:::

## Error Response

STATUS 4xx

Response Body: Error

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

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                   | 描述（英文）<br/>`description`                                                                                          | 描述（葡文）<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}`                                                                 |

---

# 汇款文件（CNAB）- 简介

URL: /zh-Hans/documentation/boletos/cnab/introducao

:::info
本次调用传输的文件必须遵循 QI Tech 400 位收款文件布局标准。
手册下载链接：[收款布局 - QI Tech 版本 2.1.](https://storage.googleapis.com/live-doc-api/public_samples/Layout%20de%20Cobran%C3%A7a%20-%20QI%20Tech%20v2.1.pdf)
:::

汇款文件（CNAB）提供了在单个文件中发送多条票据登记指令以及其他类型指令（延期、减免、核销等）的可能性，这些指令可针对不同的票据。发送上述指令（延期、减免等）用于已有票据时，票据通过钱包代码（`requester_profile_code`）和我方号码（`our_number`）进行识别。

上传 CNAB 文件后，若请求成功（响应代码 `202`），将创建一个临时 CNAB 文件（`TemporaryCNABFile`）。可以使用[**临时 CNAB 文件查询**](/documentation/boletos/cnab/consulta_por_chave)和[**其记录**](/documentation/boletos/cnab/listar_ocorrencias_temporarias)端点来查看文件处理状态以及可能的错误（包括文件本身及其记录的错误）。

如果发现任何语法错误，文件将被拒绝。但文件将被完整读取，或读取至发现 100 个错误为止，以便能够以更实用、高效的方式返回并修正所有错误。

文件读取时会创建 临时记录 ，只有在文件被接受时才会处理这些记录。也就是说， 如果文件被拒绝（状态为 `rejected`），其所有记录也将被拒绝 。此外，文件被拒绝后，将不再为其创建临时记录。因此，被拒绝文件的记录条目通常少于文件中发送的记录数量。

另一方面，当文件被完整读取并接受（状态为 `read`）时，将开始创建最终记录，这些记录将是实际生效的指令。如果临时记录显示状态为 `rejected`（已拒绝），则表示其中存在语义错误——即内容错误。此时，将附带一个 `error_data` 对象，提供拒绝原因的详细信息。反之，如果状态为 `processed`，则表示最终记录已创建并发送至 CIP/Núclea。有关这些实体的更多详情，请参阅后续关于查询文件和临时记录的页面。

:::tip 通过 CNAB 进行信用分账
在 CNAB 文件中提供[**信用分账**](/documentation/boletos/instrucoes/rateio_de_credito)（分账支付）信息：

- **QI SCD（CNAB400 - QI Tech v2.1 布局）：** 明细记录中 `identificacao_registro = 3`。完整细节请参阅 **[收款布局 - 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 与 CNAB240）：** 明细记录类型 `3`。
- **Itaú（CNAB400 与 CNAB240）：** 明细记录类型 `4`。
- **Santander：** 不支持通过 CNAB 进行信用分账。请使用 REST 接口[**信用分账更新**](/documentation/boletos/instrucoes/rateio_de_credito)，或在通过 API 发行时携带 `split_payment_data`。

**如何映射 N 个分账账户：** 每条分账记录可包含最多 **3 个附加账户**（账户号 + 校验位 + 百分比）。如需超过 3 个分账账户，可在 Boleto 主记录之后**按顺序添加多条分账记录**——它们将累积到同一笔记录中。例如：7 个账户 = 3 条记录（3 + 3 + 1）。

**限制（所有银行）：**
- 仅支持**百分比**计算方式（`计算代码 = 2`）。
- 各百分比之和（受益人 + 分账）必须正好等于 **100**。
- 分账账户总数遵循 REST API 的相同限制（最多 10 个附加账户）。
- `beneficiary_max_amount`（受益人最高金额、超出部分分配给第一条规则的分账模式）**仅支持 REST API**，不支持通过 CNAB 设置。如需此场景，请使用 REST 接口[**发行**](/documentation/boletos/emissao/emissao_boleto_unico_padrao)或[**信用分账更新**](/documentation/boletos/instrucoes/rateio_de_credito)。
:::

---

# 列出临时汇款文件

URL: /zh-Hans/documentation/boletos/cnab/listar_arquivos_temporarios

临时 CNAB 文件列表将返回符合请求中发送的 查询参数 的所有钱包临时 CNAB 文件。

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /temporary_cnab_file
MÉTODO GET

### Path parameters

| 字段                    | 类型   | 描述                                                  | 字符数 |
|-------------------------|--------|-------------------------------------------------------|--------|
| `account_key`           | uuidv4 | 账户唯一标识键，uuid v4 格式                          | 36     |
| `requester_profile_key` | uuidv4 | 钱包唯一标识键，uuid v4 格式                          | 36     |

### Query parameters

| 字段                        | 类型    | 描述                                  | 字符数                   |
|-----------------------------|---------|---------------------------------------|--------------------------|
| `temporary_cnab_file_status` | string | 临时 CNAB 文件状态 | **[Enumeradores temporary_cnab_file_status](#enumeradores-temporary_cnab_file_status)** |
| `page`                      | integer | 页码                                  | -                        |
| `page_size`                 | integer | 每页大小                              | -                        |

### Enumeradores temporary_cnab_file_status

| 枚举值                       | 描述                                                         |
|------------------------------|--------------------------------------------------------------|
| uploaded                     | 上传成功，但文件尚未开始处理                                 |
| processing                   | 文件正在读取中                                               |
| read                         | 文件已读取并接受                                             |
| rejected                     | 文件已读取并因语法错误被拒绝                                 |

## 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

| 字段             | 类型         | 描述                    | 字符数                                      |
|------------------|--------------|-------------------------|---------------------------------------------|
| `data` *         | object array | 临时 CNAB 文件列表      | **[Objeto temporary_cnab_file](#objeto-temporary_cnab_file)**   |
| `pagination` *   | object       | 分页信息                | **[Objeto pagination](#objeto-pagination)** |

### Objeto temporary_cnab_file

| 字段                           | 类型    | 描述                                                    | 字符数 |
|--------------------------------|---------|--------------------------------------------------------|--------------------------------------------------|
| `temporary_cnab_file_key` *    | uuidv4  | 临时 CNAB 文件唯一标识键，uuid v4 格式                  | 36                                                |
| `temporary_cnab_file_name` *   | uuidv4  | 文件名                                                  | 100                                               |
| `temporary_cnab_file_status` * | string  | 临时 CNAB 文件状态 | **[Enumeradores temporary_cnab_file_status](#enumeradores-temporary_cnab_file_status)** |
| `occurrence_quantity` *        | integer | 文件中的记录数量                                        | -                                                 |
| `created_at` *                 | string  | 文件在数据库中创建的时间戳，ISO Zulu 格式               | 20                                         |

### Objeto pagination

| 字段                       | 类型    | 描述           | 字符数 |
|----------------------------|---------|----------------|--------------------------------------------------------------|
| `current_page` *           | integer | 当前页码       | -      |
| `rows_per_page` *          | integer | 每页记录数     | -      |

## Error Response

STATUS 4xx

Response Body: Error

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

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                   | 描述（英文）<br/>`description`                                                                                          | 描述（葡文）<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                                                                 |

---

# 列出临时记录

URL: /zh-Hans/documentation/boletos/cnab/listar_ocorrencias_temporarias

临时记录列表将返回给定 CNAB 文件的所有临时记录。

:::info
当 CNAB 文件因语法错误被拒绝时，将不再为其创建临时记录，因为所有记录都将因文件被拒绝而遭拒。因此，文件被拒绝时，与该文件相关的临时记录数量可能少于文件中发送的记录数量。
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /temporary_cnab_file / TEMPORARY_CNAB_FILE_KEY /occurrences
MÉTODO GET

### Path parameters

| 字段                    | 类型   | 描述                                                  | 字符数 |
|-------------------------|--------|-------------------------------------------------------|--------|
| `account_key`           | uuidv4 | 账户唯一标识键，uuid v4 格式                          | 36     |
| `requester_profile_key` | uuidv4 | 钱包唯一标识键，uuid v4 格式                          | 36     |

### Query parameters

| 字段                | 类型    | 描述                       | 字符数                   |
|---------------------|---------|----------------------------|--------------------------|
| `occurrence_status` | string  | 临时记录状态               | **[Enumeradores occurrence_status](#enumeradores-temporary_cnab_file_status)** |
| `occurrence_type`   | string  | 临时记录类型               | **[Enumeradores occurrence_type](#enumeradores-temporary_cnab_file_type)** |
| `page`              | integer | 页码                       | -                        |
| `page_size`         | integer | 每页大小                   | -                        |

### Enumeradores occurrence_status

| 枚举值                       | 描述                                     |
|------------------------------|------------------------------------------|
| pending                      | 记录尚未处理                             |
| processed                    | 记录处理成功                             |
| rejected                     | 记录因语义错误被处理并拒绝               |

### Enumeradores occurrence_type

| 枚举值                                   | 描述                                     |
|------------------------------------------|------------------------------------------|
| registration                             | 票据登记                                 |
| write_off                                | 票据核销                                 |
| rebate                                   | 票据价值减免                             |
| cancel_rebate                            | 取消减免                                 |
| extension                                | 付款日期延期                             |
| protest_request                          | 抗议申请                                 |
| bankruptcy_protest_request               | 破产抗议申请                             |
| protest_cancel_and_write_off_request     | 取消抗议申请并核销票据                   |
| protest_cancel_request                   | 取消抗议申请                             |
| bank_slip_edit                           | 编辑票据其他数据                         |

## 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"
                }
            }
        }
    ],
    "pagination": {
        "current_page": 1,
        "rows_per_page": 100
    }
}
```

### Response Body Params

| 字段             | 类型         | 描述                    | 字符数                                      |
|------------------|--------------|-------------------------|---------------------------------------------|
| `data` *         | object array | 临时记录列表            | **[Objeto temporary_occurrence](#objeto-temporary_occurrence)**   |
| `pagination` *   | object       | 分页信息                | **[Objeto pagination](#objeto-pagination)** |

### Objeto temporary_cnab_file

| 字段                       | 类型    | 描述                                                    | 字符数 |
|----------------------------|---------|--------------------------------------------------------|--------------------------------------------------|
| `occurrence_key` *         | uuidv4  | 临时记录唯一标识键，uuid v4 格式                        | 36                                                |
| `occurrence_status` *      | string  | 临时记录状态 | **[Enumeradores temporary_occurrence_status](#enumeradores-temporary_occurrence_status)** |
| `occurrence_type` *        | string  | 临时记录类型 | **[Enumeradores occurrence_type](#enumeradores-occurrence_type)** |
| `occurrence_our_number` *  | integer | 文件中的记录数量                                        | -                                                 |
| `error_data`               | object  | 文件中发现的错误对象（JSON 格式），与 API 返回格式相同 | **[Objeto error_data](#objeto-error_data)**       |

### Objeto pagination

| 字段                       | 类型    | 描述           | 字符数 |
|----------------------------|---------|----------------|--------------------------------------------------------------|
| `current_page` *           | integer | 当前页码       | -      |
| `rows_per_page` *          | integer | 每页记录数     | -      |

### Objeto error_data

| 字段            | 类型    | 描述                       | 字符数 |
|-----------------|---------|----------------------------|--------------------------------------------------|
| `code` *        | string  | 错误代码                   | 9                                                |
| `title` *       | string  | 错误标题                   | 100                                               |
| `description` * | string  | 错误描述（英文）           | 100 |
| `translation` * | integer | 错误描述翻译               | 100                                               |
| `extra_fields`  | object  | 关于错误的附加信息         | -                                         |

:::danger 重要
`extra_fields` 对象中返回的字段用于提供关于错误的附加信息，可能有所不同。因此，不应以严格限定的方式进行映射。
:::

## Error Response

STATUS 4xx

Response Body: Error

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

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                   | 描述（英文）<br/>`description`                                                                                          | 描述（葡文）<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}`                                                                 |

---

# 上传汇款文件（CNAB）

URL: /zh-Hans/documentation/boletos/cnab/upload_de_arquivo_remessa

:::caution 注意！
调用必须按照[**上传文档**](/documentation/upload_de_documentos)部分所述的标准进行认证。
:::

汇款文件（CNAB）提供了在单个文件中发送多条票据登记指令以及其他类型指令（延期、减免、核销等）的可能性，这些指令可针对不同的票据。发送上述指令（延期、减免等）用于已有票据时，票据通过钱包代码（`requester_profile_code`）和我方号码（`our_number`）进行识别。

:::info
上传 CNAB 文件后，若请求成功（响应代码 `202`），将创建一个临时 CNAB 文件（`TemporaryCNABFile`）。可以使用[**临时 CNAB 文件查询**](/documentation/boletos/cnab/consulta_por_chave)和[**其记录**](/documentation/boletos/cnab/listar_ocorrencias_temporarias)端点来查看文件处理状态以及可能的错误。
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /cnab_file
MÉTODO POST

### Path parameters

| 字段                    | 类型   | 描述                                                  | 字符数 |
|-------------------------|--------|-------------------------------------------------------|--------|
| `account_key`           | uuidv4 | 账户唯一标识键，uuid v4 格式                          | 36     |
| `requester_profile_key` | uuidv4 | 钱包唯一标识键，uuid v4 格式                          | 36     |

## Request Body Params

以下数据应作为 form-data 在请求 body 中发送：

| 字段    | 类型 | 描述                                  | 字符数 |
|---------|------|---------------------------------------|--------|
| `file` *| file | 符合 QI Tech 规定标准的 CNAB 文件     | -      |

## Response

STATUS 202

Response Body

```json
{
  "temporary_cnab_file_key": "f14e9bac-94ed-4eb1-87b4-7fd7b7a2d280",
  "temporary_cnab_file_status": "accepted"
}
```

### Response Body Params

| 字段                           | 类型    | 描述                                                    | 字符数                     |
|--------------------------------|---------|---------------------------------------------------------|----------------------------|
| `temporary_cnab_file_key` *    | uuidv4  | CNAB 文件唯一标识键，uuid v4 格式                       | 36                         |
| `temporary_cnab_file_status` * | string  | CNAB 文件状态 | **[Enumeradores temporary_cnab_file_status](#enumeradores-cnab_file_status)** |

### Enumeradores temporary_cnab_file_status

| 枚举值     | 描述                                                       |
|------------|------------------------------------------------------------|
| uploaded   | 上传成功，但文件尚未开始处理                               |
| processing | 文件正在读取中                                             |
| read       | 文件已读取并接受                                           |
| rejected   | 文件已读取并被拒绝（文件的所有记录均被拒绝）               |

## Error Response

STATUS 4xx

Response Body: Error

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

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                   | 描述（英文）<br/>`description`                                                                                          | 描述（葡文）<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>`'                          |

---

# 通过密钥查询 Boleto

URL: /zh-Hans/documentation/boletos/consulta/consulta_por_chave

通过密钥查询 Boleto 可返回该 Boleto 的详细信息，例如与该 Boleto 相关的所有指令。

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY
MÉTODO GET

### 路径参数

| 字段                    | 类型   | 描述                              | 字符数 |
|------------------------|--------|-----------------------------------|--------|
| `account_key`          | uuidv4 | 账户唯一标识密钥，格式为 uuid v4  | 36     |
| `requester_profile_key` | uuidv4 | 钱包唯一标识密钥，格式为 uuid v4 | 36     |
| `bank_slip_key`        | uuidv4 | Boleto 唯一标识密钥，格式为 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": "<base64 encoded QR code image>"
  },
  "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"
    }
  ]
}
```

### 响应体参数

| 字段                        | 类型          | 描述                                                                                 | 字符数                                                                           |
|---------------------------|---------------|-------------------------------------------------------------------------------------|----------------------------------------------------------------------------------|
| `bank_slip_key` *         | uuidv4        | Boleto 唯一标识密钥，格式为 uuid v4                                                  | 36                                                                               |
| `request_control_key` *   | uuidv4        | 客户请求唯一标识密钥，格式为 uuid v4                                                 | 36                                                                               |
| `our_number` *            | integer       | Boleto 在钱包中的唯一识别编号                                                        | 11                                                                               |
| `bank_slip_status` *      | string        | Boleto 状态                                                                         | **[bank_slip_status 枚举值](#enumeradores-bank_slip_status)**                    |
| `protest_status` *        | string        | Boleto 在公证处的抗议状态                                                            | **[protest_status 枚举值](#enumeradores-protest_status)**                        |
| `document_number` *       | string        | Boleto 识别编号                                                                     | 10                                                                               |
| `amount` *                | float         | Boleto 基准金额                                                                     | -                                                                                |
| `expiration` *            | string        | 到期日                                                                              | 10                                                                               |
| `barcode` *               | string        | Boleto 条形码                                                                       | 44                                                                               |
| `digitable_line` *        | string        | Boleto 可打印行                                                                     | 47                                                                               |
| `bank_teller_instructions` | string       | 额外注册说明，将显示在 Boleto PDF 中                                                 | 320                                                                              |
| `rebate_amount`           | float         | Boleto 减免金额，将在基准金额之上应用                                                | -                                                                                |
| `max_payment_days` *      | integer       | Boleto 到期后可供支付的最大自然日数（最多 365 天）                                   | -                                                                                |
| `write_off_data`          | object        | 核销配置                                                                             | **[write_off_data 对象](#objeto-write_off_settings)**                            |
| `protest_data`            | object        | 抗议配置                                                                             | **[protest_data 对象](#objeto-protest_settings)**                                |
| `bankruptcy_protest_data` | object        | 破产抗议配置                                                                         | **[bankruptcy_protest_data 对象](#objeto-bankruptcy_protest_settings)**          |
| `fine_data`               | object        | 罚款配置                                                                             | **[fine_data 对象](#objeto-fine_settings)**                                      |
| `interest_data`           | object        | 利息配置                                                                             | **[interest_data 对象](#objeto-interest_settings)**                              |
| `discounts_data`          | object array  | 折扣配置                                                                             | **[discount 对象](#objeto-discounts_data)**                                      |
| `payer_data` *            | object        | 付款方数据                                                                           | **[payer_data 对象](#objetos-payer_data-e-guarantor_data)**                      |
| `guarantor_data` *        | object        | 担保人数据                                                                           | **[guarantor_data 对象](#objetos-payer_data-e-guarantor_data)**                  |
| `qr_code_data`            | object        | QR Code 数据                                                                        | **[qr_code_data 对象](#objeto-qr_code_data)**                                    |
| `payment_notice_data`     | object 或 array | 付款通知数据                                                                       | **[payment_notice_data 对象或数组](#objeto-ou-array-payment_notice_data)**        |
| `payment_data`            | object 或 array | 付款数据                                                                           | **[payment_data 对象或数组](#objeto-ou-array-payment_data)**                      |
| `occurrences`             | object array  | Boleto 相关指令                                                                      | **[bank_slip_occurrence 对象](#objeto-bank_slip_occurrence)**                    |

:::info 说明
`amount` 字段是 Boleto 的**基准金额**，即**不含**罚款（fine）、利息（interest）、减免（rebate）和折扣（discounts）。
:::

### bank_slip_status 枚举值

| 枚举值                          | 描述                                               |
|-------------------------------|----------------------------------------------------|
| accepted                      | 已接受并发送至 Nuclea/CIP 进行分析                  |
| rejected                      | 被 Nuclea/CIP 拒绝注册                              |
| payment_notice                | 付款通知（Boleto 已付但付款尚未清算）               |
| notary_office_payment_notice  | 公证处付款通知（Boleto 已付但付款尚未清算）         |
| registered                    | Nuclea/CIP 已确认注册                               |
| payment_blocked               | 已锁定支付（处于抗议流程中）                        |
| paid                          | 已支付                                              |
| written_off                   | 已核销                                              |

### protest_status 枚举值

| 枚举值                        | 描述                         |
|-----------------------------|------------------------------|
| not_protested                | Boleto 尚未启动抗议流程       |
| protest_requested            | 已申请公证处抗议              |
| notary_office_entry          | Boleto 在公证处，处于三日期间 |
| protest_cancel_requested     | 已申请撤销抗议                |
| notary_office_exit           | Boleto 已离开公证处           |
| protested                    | Boleto 已被抗议               |
| paid_at_notary_office        | 在公证处支付                  |
| judicially_suspended         | 抗议被司法暂停                |
| protest_remove_requested     | 已申请移除抗议                |

### write_off_data 对象

| 字段                  | 类型    | 描述                                  | 字符数 |
|---------------------|---------|---------------------------------------|--------|
| `days_to_write_off` * | integer | Boleto 到期后自动核销的天数           | -      |

### protest_data 对象

| 字段                  | 类型    | 描述                                  | 字符数 |
|---------------------|---------|---------------------------------------|--------|
| `days_to_protest` * | integer | Boleto 到期后自动抗议的天数           | -      |

### bankruptcy_protest_data 对象

| 字段                          | 类型    | 描述                                  | 字符数 |
|-----------------------------|---------|---------------------------------------|--------|
| `days_to_bankruptcy_protest` * | integer | Boleto 到期后自动破产抗议的天数     | -      |

### fine_data 对象

**选项 1：绝对值罚款（`fine_type=absolute`）**

| 字段               | 类型    | 描述                              | 字符数                                               |
|------------------|---------|-----------------------------------|------------------------------------------------------|
| `fine_type` *    | string  | 罚款类型                          | **[fine_type 枚举值](#enumeradores-fine_type)**      |
| `fine_amount` *  | float   | 罚款绝对值                        | -                                                    |
| `days_to_fine` * | integer | 到期后开始收取罚款的天数          | -                                                    |

**选项 2：百分比罚款（`fine_type=percentage`）**

| 字段                  | 类型    | 描述                              | 字符数                                               |
|---------------------|---------|-----------------------------------|------------------------------------------------------|
| `fine_type` *       | string  | 罚款类型                          | **[fine_type 枚举值](#enumeradores-fine_type)**      |
| `fine_percentage` * | integer | 罚款百分比，1 至 100              | -                                                    |
| `days_to_fine` *    | integer | 到期后开始收取罚款的天数          | -                                                    |

### fine_type 枚举值

| 枚举值     | 描述     |
|----------|----------|
| absolute  | 绝对值   |
| percentage | 百分比  |

### interest_data 对象

**选项 1：绝对值利息（`interest_type=calendar_days_daily_amount` 或 `interest_type=workdays_daily_amount`）**

| 字段                   | 类型    | 描述                                      | 字符数                                                      |
|----------------------|---------|-------------------------------------------|-------------------------------------------------------------|
| `interest_type` *    | string  | 利息类型                                  | **[interest_type 枚举值](#enumeradores-interest_type)**     |
| `interest_amount` *  | float   | 每单位时间（工作日或自然日）收取的利息金额 | -                                                           |
| `days_to_interest` * | integer | 到期后开始收取利息的天数                  | -                                                           |

**选项 2：百分比利息（`interest_type=calendar_days_monthly_percentage`）**

| 字段                      | 类型    | 描述                                          | 字符数                                                      |
|-------------------------|---------|-----------------------------------------------|-------------------------------------------------------------|
| `interest_type` *       | string  | 利息类型                                      | **[interest_type 枚举值](#enumeradores-interest_type)**     |
| `interest_percentage` * | integer | 每单位时间（工作日或自然日）收取的利息百分比   | -                                                           |
| `days_to_interest` *    | integer | 到期后开始收取利息的天数                      | -                                                           |

### interest_type 枚举值

| 枚举值                              | 描述                                     |
|-----------------------------------|------------------------------------------|
| calendar_days_daily_amount        | 按自然日计算的每日金额                    |
| workdays_daily_amount             | 按工作日计算的每日金额                    |
| calendar_days_monthly_percentage  | 按自然日计算的月利率百分比                |

### discount 对象

**选项 1：绝对值折扣（`discount_type in ["absolute", "anticipation_calendar_days_daily_amount", "anticipation_workdays_daily_amount"]`）**

| 字段                   | 类型    | 描述                        | 字符数                                                          |
|----------------------|---------|-----------------------------|-----------------------------------------------------------------|
| `discount_amount` *  | float   | 每单位时间的绝对折扣金额    | -                                                               |
| `discount_number` *  | integer | 折扣编号                    | -                                                               |
| `discount_type` *    | string  | 折扣类型（绝对值）          | **[discount_type 枚举值](#enumeradores-discount_type)**         |
| `discount_limit_date` * | string | 折扣截止日期              | 10                                                              |

**选项 2：百分比折扣（`discount_type in ["percentage", "anticipation_calendar_days_daily_percentage", "anticipation_workdays_daily_percentage"]`）**

| 字段                      | 类型    | 描述                        | 字符数                                                          |
|-------------------------|---------|-----------------------------|-----------------------------------------------------------------|
| `discount_percentage` * | float   | 每单位时间的折扣百分比      | -                                                               |
| `discount_number` *     | integer | 折扣编号                    | -                                                               |
| `discount_type` *       | string  | 折扣类型（百分比）          | **[discount_type 枚举值](#enumeradores-discount_type)**         |
| `discount_limit_date` * | string  | 折扣截止日期                | 10                                                              |

:::caution 注意！
一张 Boleto 最多可有三个折扣，且**所有折扣必须为同一类型**，即具有相同的 `discount_type`。折扣编号必须从 1 开始，按递增顺序编号，**最大到 3**。即，若请求中发送两个折扣，必须分别编号为 1 和 2。
:::

### discount_type 枚举值

| 枚举值                                       | 描述                                    |
|--------------------------------------------|----------------------------------------|
| absolute                                    | 固定金额                               |
| anticipation_calendar_days_daily_amount     | 按自然日计算的提前还款每日折扣金额      |
| anticipation_workdays_daily_amount          | 按工作日计算的提前还款每日折扣金额      |
| percentage                                  | 固定百分比                              |
| anticipation_calendar_days_daily_percentage | 按自然日计算的提前还款月折扣百分比      |
| anticipation_workdays_daily_percentage      | 按工作日计算的提前还款年折扣百分比      |

### payer_data 和 guarantor_data 对象

| 字段                  | 类型   | 描述                   | 字符数                                                          |
|---------------------|--------|------------------------|----------------------------------------------------------------|
| `name` *            | string | 全名                   | 100                                                            |
| `document_number` * | string | 证件号码（CPF/CNPJ）   | 11 或 14                                                       |
| `person_type` *     | string | 人员类型（自然人或法人）| **[person_type 枚举值](#enumeradores-person_type)**           |
| `contact`           | object | 联系信息               | **[contact 对象](#objeto-contact)**                            |
| `address`           | object | 地址                   | **[address 对象](#objeto-address)**                            |

### person_type 枚举值

| 枚举值    | 描述   |
|---------|--------|
| natural  | 自然人 |
| legal    | 法人   |

### contact 对象

| 字段    | 类型   | 描述     | 字符数                                |
|-------|--------|----------|---------------------------------------|
| `email` | string | 联系邮箱 | 320                                   |
| `phone` | object | 联系电话 | **[phone 对象](#objeto-phone)**       |

### phone 对象

| 字段                         | 类型   | 描述           | 字符数 |
|----------------------------|--------|----------------|--------|
| `international_dial_code` * | string | 国际区号（DDI） | 3      |
| `area_code` *               | string | 地区区号（DDD） | 2      |
| `number` *                  | string | 电话号码        | 9      |

### address 对象

| 字段              | 类型   | 描述   | 字符数                                             |
|-----------------|--------|--------|----------------------------------------------------|
| `street` *      | string | 街道   | 500                                                |
| `number` *      | string | 门牌号 | 6                                                  |
| `complement`    | string | 补充   | 500                                                |
| `neighborhood` * | string | 社区  | 100                                                |
| `postal_code` * | string | 邮编   | 8                                                  |
| `city` *        | string | 城市   | 100                                                |
| `state` *       | string | 州（UF） | **[state 枚举值](#enumeradores-state)**           |

### state 枚举值

| 枚举值 | 描述                  |
|------|----------------------|
| 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   | 其他                 |

### qr_code_data 对象

| 字段                       | 类型   | 描述                             | 字符数 |
|--------------------------|--------|----------------------------------|--------|
| `qr_code_key`            | uuidv4 | QR Code 唯一标识密钥             | 36     |
| `pix_key`                | uuidv4 | 与 QR Code 关联的 PIX 密钥       | 36     |
| `receiver_conciliation_id` | uuidv4 | QR Code 对账标识符             | 36     |
| `url`                    | string | QR Code 的 URL（Pix 复制粘贴）   | -      |
| `image`                  | string | QR Code URL 的 base64 编码图片   | -      |

### payment_notice_data 对象或数组

:::caution 注意！
对于未配置部分支付的 Boleto，`payment_notice_data` 字段将以**对象**形式返回。对于配置了部分支付的 Boleto，将以**对象数组**形式返回，因为可能存在多笔付款。
此外，如果 Boleto 通过 **QR Code** 支付，该字段不会返回，因为清算在付款当日完成。
:::

| 字段                    | 类型   | 描述       | 字符数                                                                  |
|-----------------------|--------|------------|-------------------------------------------------------------------------|
| `payment_method`      | string | 支付方式   | **[payment_method 枚举值](#enumeradores-payment_method)**              |
| `payment_origin`      | string | 支付来源   | **[payment_origin 枚举值](#enumeradores-payment_origin)**              |
| `payment_notice_date` | string | 付款通知日期 | 10                                                                    |

### payment_data 对象或数组

:::caution 注意！
对于未配置部分支付的 Boleto，`payment_data` 字段将以**对象**形式返回。对于配置了部分支付的 Boleto，将以**对象数组**形式返回，因为可能存在多笔付款。
:::

| 字段                      | 类型   | 描述       | 字符数                                                                  |
|-------------------------|--------|------------|-------------------------------------------------------------------------|
| `paid_amount`           | float  | 付款金额   | -                                                                       |
| `paid_rebate_amount`    | float  | 已付减免金额 | -                                                                     |
| `paid_discount_amount`  | float  | 已付折扣金额 | -                                                                     |
| `paid_fine_amount`      | float  | 已付罚款金额 | -                                                                     |
| `paid_interest_amount`  | float  | 已付利息金额 | -                                                                     |
| `payment_method`        | string | 支付方式   | **[payment_method 枚举值](#enumeradores-payment_method)**              |
| `payment_origin`        | string | 支付来源   | **[payment_origin 枚举值](#enumeradores-payment_origin)**              |
| `payment_credit_date`   | string | 付款入账日期 | 10                                                                    |
| `payment_bank`          | object | Boleto 付款所在的银行。仅在 Boleto 付款后返回 | **[payment_bank 对象](#objeto-payment_bank)** |
| `payment_branch`        | string | Boleto 付款所在的分行（agência）。仅在 Boleto 付款后返回 | -                                          |

:::info 信息
字段 `payment_bank` 和 `payment_branch` 仅在 Boleto 已付款（即存在已确认的付款记录）时返回。在 Boleto 付款之前，响应中不会包含这些字段。
:::

### payment_bank 对象

| 字段   | 类型    | 描述                | 字符数 |
|--------|---------|---------------------|--------|
| `code` | string  | 银行清算代码（3 位数） | 3      |
| `ispb` | integer | 银行 ISPB           | 8      |
| `name` | string  | 银行名称            | -      |

### payment_method 枚举值

| 枚举值         | 描述       |
|--------------|------------|
| cash          | 现金       |
| account_debit | 账户扣款   |
| credit_card   | 信用卡     |
| check         | 支票       |

### payment_origin 枚举值

| 枚举值                  | 描述                       |
|-----------------------|----------------------------|
| phisical_cashier       | 银行网点 - 传统柜台         |
| taa                   | 自动取款机                  |
| internet              | 互联网（网上/办公室银行）    |
| corban                | 银行代理                    |
| call_center           | 电话客服中心                |
| eletronic_file        | 电子文件                    |
| dda                   | DDA                         |
| digital_correspondent | 数字银行代理                |
| qr_code               | Pix QR Code 支付            |

### bank_slip_occurrence 对象

| 字段                    | 类型   | 描述                                               | 字符数                                                              |
|-----------------------|--------|-----------------------------------------------------|---------------------------------------------------------------------|
| `request_control_key` * | uuidv4 | 客户请求唯一标识密钥，格式为 uuid v4               | 36                                                                  |
| `occurrence_key` *    | uuidv4 | Boleto 唯一标识密钥，格式为 uuid v4                | 36                                                                  |
| `occurrence_type` *   | string | 事件类型                                           | **[occurrence_type 枚举值](#enumeradores-occurrence_type)**         |
| `occurrence_status` * | string | 事件状态                                           | **[occurrence_status 枚举值](#enumeradores-occurrence_status)**     |
| `created_at` *        | string | 事件创建日期，ISO 格式（UTC - "YYYY-MM-DDTHH:MM:SSZ"） | 20                                                             |

### occurrence_type 枚举值

| 枚举值              | 描述              |
|-------------------|-------------------|
| registration       | 注册事件          |
| write_off          | 核销申请事件      |
| rebate             | 添加减免事件      |
| cancel_rebate      | 取消减免事件      |
| discount           | 修改折扣事件      |
| fine               | 修改罚款事件      |
| interest           | 修改利息事件      |
| extension          | 延期事件          |
| bank_slip_edit     | 修改 Boleto 其他数据事件 |
| payment_notice     | 付款通知事件      |
| payment            | 付款清算事件      |
| protest_request    | 抗议申请事件      |

### occurrence_status 枚举值

| 枚举值     | 描述                       |
|----------|----------------------------|
| pending   | 已发送至 Nuclea/CIP 待分析  |
| rejected  | 已拒绝                     |
| confirmed | 已确认                     |

## 错误响应

STATUS 4xx

Response Body: 错误

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

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                   | 英文描述<br/>`description`                                                                                              | 葡语描述<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}`).                                                      |

---

# Boleto 列表查询

URL: /zh-Hans/documentation/boletos/consulta/listar_boletos

Boleto 列表将返回符合请求中发送的查询参数的所有钱包 Boleto。

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slips
MÉTODO GET

### 路径参数

| 字段                    | 类型   | 描述                                   | 字符数 |
|------------------------|--------|----------------------------------------|--------|
| `account_key`           | uuidv4 | 账户唯一识别密钥，格式为 uuid v4        | 36     |
| `requester_profile_key` | uuidv4 | 钱包唯一识别密钥，格式为 uuid v4        | 36     |

### 查询参数

| 字段                    | 类型    | 描述                                   | 字符数                                                                    |
|------------------------|---------|----------------------------------------|---------------------------------------------------------------------------|
| `request_control_key`   | uuidv4  | 请求唯一识别密钥，格式为 uuid v4        | 36                                                                        |
| `bank_slip_key`         | uuidv4  | Boleto 唯一识别密钥，格式为 uuid v4     | 36                                                                        |
| `bank_slip_status`      | string  | Boleto 状态                            | **[bank_slip_status 枚举值](#enumeradores-bank_slip_status)**              |
| `page`                  | integer | 页码                                   | -                                                                         |
| `page_size`             | integer | 每页大小                               | -                                                                         |
| `from_date`             | string  | 起始登记日期（格式"YYYY-MM-DD"）        | 10                                                                        |
| `to_date`               | string  | 终止登记日期（格式"YYYY-MM-DD"）        | 10                                                                        |

### bank_slip_status 枚举值

| 枚举值                        | 描述                                          |
|------------------------------|-----------------------------------------------|
| accepted                     | 已接受并发送至 Nuclea/CIP 待分析               |
| rejected                     | 被 Nuclea/CIP 拒绝登记                        |
| payment_notice               | 支付通知（已付款但尚未清算）                  |
| notary_office_payment_notice | 公证处支付通知（已付款但尚未清算）            |
| registered                   | 已由 Nuclea/CIP 确认登记                      |
| payment_blocked              | 已被锁定支付（在抗议流程中）                  |
| paid                         | 已付款                                        |
| written_off                  | 已注销                                        |

## 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

| 字段          | 类型         | 描述         | 字符数                                            |
|--------------|--------------|--------------|---------------------------------------------------|
| `data` *     | object array | Boleto 列表  | **[bank_slip 对象](#objeto-bank_slip)**           |
| `pagination` * | object     | 分页信息     | **[pagination 对象](#objeto-pagination)**         |

### bank_slip 对象

| 字段                       | 类型    | 描述                                           | 字符数                                                                    |
|---------------------------|---------|------------------------------------------------|---------------------------------------------------------------------------|
| `bank_slip_key` *         | uuidv4  | Boleto 唯一识别密钥，格式为 uuid v4             | 36                                                                        |
| `request_control_key` *   | uuidv4  | 客户使用的请求唯一识别密钥，格式为 uuid v4      | 36                                                                        |
| `our_number` *            | integer | Boleto 在钱包中的唯一识别号                     | 11                                                                        |
| `bank_slip_status` *      | string  | Boleto 状态                                    | **[bank_slip_status 枚举值](#enumeradores-bank_slip_status)**              |
| `protest_status` *        | string  | Boleto 公证处抗议状态                           | **[protest_status 枚举值](#enumeradores-protest_status)**                 |
| `document_number` *       | string  | Boleto 识别号码                                | 10                                                                        |
| `amount` *                | float   | Boleto 基础金额                                | -                                                                         |
| `expiration` *            | string  | 到期日期                                       | 10                                                                        |
| `barcode` *               | string  | Boleto 条形码                                  | 44                                                                        |
| `digitable_line` *        | string  | Boleto 可输入行                                | 47                                                                        |
| `bank_teller_instructions` | string | 额外登记说明，将显示在 Boleto PDF 中            | 320                                                                       |
| `rebate_amount`           | float   | Boleto 折扣金额，将在基础金额上应用             | -                                                                         |
| `max_payment_days` *      | integer | 到期后可供付款的最大自然日数（最多 365 天）      | -                                                                         |
| `write_off_data`          | object  | 注销配置                                       | **[write_off_data 对象](#objeto-write_off_settings)**                     |
| `protest_data`            | object  | 抗议配置                                       | **[protest_data 对象](#objeto-protest_settings)**                         |
| `bankruptcy_protest_data` | object  | 破产抗议配置                                   | **[bankruptcy_protest_data 对象](#objeto-bankruptcy_protest_settings)**   |
| `fine_data`               | object  | 罚款配置                                       | **[fine_data 对象](#objeto-fine_settings)**                               |
| `interest_data`           | object  | 利息配置                                       | **[interest_data 对象](#objeto-interest_settings)**                       |
| `discounts_data`          | object array | 折扣                                      | **[discount 对象](#objeto-discounts_data)**                               |
| `payer_data` *            | object  | 付款人数据                                     | **[payer_data 对象](#objetos-payer_data-e-guarantor_data)**               |
| `guarantor_data` *        | object  | 保证人数据                                     | **[guarantor_data 对象](#objetos-payer_data-e-guarantor_data)**           |

### pagination 对象

| 字段             | 类型    | 描述     | 字符数 |
|-----------------|---------|----------|--------|
| `current_page` * | integer | 当前页码 | -      |
| `rows_per_page` * | integer | 每页条数 | -      |

### protest_status 枚举值

| 枚举值                     | 描述                         |
|---------------------------|------------------------------|
| not_protested             | 未启动抗议流程的 Boleto        |
| protest_requested         | 已申请公证处抗议               |
| notary_office_entry       | Boleto 在公证处三日期内        |
| protest_cancel_requested  | 已申请撤销抗议                 |
| notary_office_exit        | Boleto 已离开公证处            |
| protested                 | 已被抗议的 Boleto              |
| paid_at_notary_office     | 已在公证处付款                 |
| judicially_suspended      | 抗议被司法中止                 |
| protest_remove_requested  | 已申请移除抗议                 |

### write_off_data 对象

| 字段                  | 类型    | 描述                                | 字符数 |
|----------------------|---------|-------------------------------------|--------|
| `days_to_write_off` * | integer | 到期后自动注销 Boleto 所需天数       | -      |

### protest_data 对象

| 字段                 | 类型    | 描述                                 | 字符数 |
|---------------------|---------|--------------------------------------|--------|
| `days_to_protest` * | integer | 到期后自动抗议 Boleto 所需天数        | -      |

### bankruptcy_protest_data 对象

| 字段                           | 类型    | 描述                                 | 字符数 |
|-------------------------------|---------|--------------------------------------|--------|
| `days_to_bankruptcy_protest` * | integer | 到期后自动破产抗议 Boleto 所需天数    | -      |

### fine_data 对象

选项 1：绝对值罚款（`fine_type=absolute`）

| 字段              | 类型    | 描述                                        | 字符数                                                          |
|------------------|---------|---------------------------------------------|----------------------------------------------------------------|
| `fine_type` *    | string  | 罚款类型                                    | **[fine_type 枚举值](#enumeradores-fine_type)**                |
| `fine_amount` *  | float   | 罚款绝对值                                  | -                                                              |
| `days_to_fine` * | integer | 到期后开始收取罚款所需天数                   | -                                                              |

选项 2：百分比罚款（`fine_type=percentage`）

| 字段                | 类型    | 描述                                   | 字符数                                                          |
|--------------------|---------|----------------------------------------|----------------------------------------------------------------|
| `fine_type` *      | string  | 罚款类型                               | **[fine_type 枚举值](#enumeradores-fine_type)**                |
| `fine_percentage` * | integer | 罚款百分比，1 到 100                   | -                                                              |
| `days_to_fine` *   | integer | 到期后开始收取罚款所需天数              | -                                                              |

### fine_type 枚举值

| 枚举值     | 描述       |
|-----------|------------|
| absolute  | 绝对值     |
| percentage | 百分比    |

### interest_data 对象

选项 1：绝对值利息（`interest_type=calendar_days_daily_amount` 或 `interest_type=workdays_daily_amount`）

| 字段                  | 类型    | 描述                                               | 字符数                                                          |
|----------------------|---------|----------------------------------------------------|----------------------------------------------------------------|
| `interest_type` *    | string  | 利息类型                                           | **[interest_type 枚举值](#enumeradores-interest_type)**        |
| `interest_amount` *  | float   | 按时间单位（工作日或自然日）收取的利息值            | -                                                              |
| `days_to_interest` * | integer | 到期后开始收取利息所需天数                          | -                                                              |

选项 2：百分比利息（`interest_type=calendar_days_monthly_percentage`）

| 字段                    | 类型    | 描述                                           | 字符数                                                          |
|------------------------|---------|------------------------------------------------|----------------------------------------------------------------|
| `interest_type` *      | string  | 利息类型                                       | **[interest_type 枚举值](#enumeradores-interest_type)**        |
| `interest_percentage` * | integer | 按时间单位（工作日或自然日）收取的利息百分比   | -                                                              |
| `days_to_interest` *   | integer | 到期后开始收取利息所需天数                      | -                                                              |

### interest_type 枚举值

| 枚举值                           | 描述                           |
|---------------------------------|--------------------------------|
| calendar_days_daily_amount       | 按自然日计的每日金额           |
| workdays_daily_amount            | 按工作日计的每日金额           |
| calendar_days_monthly_percentage | 按自然日计的月利率             |

### discount 对象

选项 1：绝对值折扣（`discount_type in ["absolute", "anticipation_calendar_days_daily_amount", "anticipation_workdays_daily_amount"]`）

| 字段                   | 类型    | 描述                                   | 字符数                                                              |
|-----------------------|---------|----------------------------------------|--------------------------------------------------------------------|
| `discount_amount` *   | float   | 按时间单位计的绝对折扣值                | -                                                                  |
| `discount_number` *   | integer | 折扣编号                               | -                                                                  |
| `discount_type` *     | string  | 绝对值折扣配置                         | **[discount_type 枚举值](#enumeradores-discount_type)**            |
| `discount_limit_date` * | string | 折扣应用截止日期                      | 10                                                                 |

选项 2：百分比折扣（`discount_type in ["percentage", "anticipation_calendar_days_daily_percentage", "anticipation_workdays_daily_percentage"]`）

| 字段                     | 类型    | 描述                                   | 字符数                                                              |
|-------------------------|---------|----------------------------------------|--------------------------------------------------------------------|
| `discount_percentage` * | float   | 按时间单位计的百分比折扣值              | -                                                                  |
| `discount_number` *     | integer | 折扣编号                               | -                                                                  |
| `discount_type` *       | string  | 百分比折扣配置                         | **[discount_type 枚举值](#enumeradores-discount_type)**            |
| `discount_limit_date` * | string  | 折扣应用截止日期                       | 10                                                                 |

:::caution 注意！
一张 Boleto 最多可有三个折扣，且**折扣必须为同一类型**，即必须具有相同的 `discount_type`。折扣必须按升序编号，从 **1 开始**。即，若请求中发送两个折扣，则必须编号为 1 和 2。
:::

### discount_type 枚举值

| 枚举值                                       | 描述                                   |
|--------------------------------------------|----------------------------------------|
| absolute                                    | 固定值                                 |
| anticipation_calendar_days_daily_amount     | 按自然日计的每日提前折扣值             |
| anticipation_workdays_daily_amount          | 按工作日计的每日提前折扣值             |
| percentage                                  | 固定百分比                             |
| anticipation_calendar_days_daily_percentage | 按自然日计的月提前折扣百分比           |
| anticipation_workdays_daily_percentage      | 按工作日计的年提前折扣百分比           |

### payer_data 和 guarantor_data 对象

| 字段                  | 类型   | 描述                        | 字符数                                                          |
|----------------------|--------|-----------------------------|----------------------------------------------------------------|
| `name` *             | string | 全名                        | 100                                                            |
| `document_number` *  | string | 证件号码（CPF/CNPJ）        | 11 或 14                                                       |
| `person_type` *      | string | 人员类型（个人或法人）      | **[person_type 枚举值](#enumeradores-person_type)**            |
| `contact`            | object | 联系信息                    | **[contact 对象](#objeto-contact)**                            |
| `address`            | object | 地址                        | **[address 对象](#objeto-address)**                            |

### person_type 枚举值

| 枚举值   | 描述   |
|---------|--------|
| natural | 自然人 |
| legal   | 法人   |

### contact 对象

| 字段    | 类型   | 描述         | 字符数                                      |
|--------|--------|--------------|---------------------------------------------|
| `email` | string | 联系邮箱    | 320                                         |
| `phone` | object | 联系电话    | **[phone 对象](#objeto-phone)**             |

### phone 对象

| 字段                          | 类型   | 描述               | 字符数 |
|------------------------------|--------|--------------------|--------|
| `international_dial_code` *  | string | 国际区号（DDI）    | 3      |
| `area_code` *                | string | 区号（DDD）        | 2      |
| `number` *                   | string | 电话号码           | 9      |

### address 对象

| 字段              | 类型   | 描述       | 字符数                                              |
|-----------------|--------|------------|-----------------------------------------------------|
| `street` *      | string | 街道       | 500                                                 |
| `number` *      | string | 门牌号     | 6                                                   |
| `complement`    | string | 补充信息   | 500                                                 |
| `neighborhood` * | string | 社区       | 100                                                 |
| `postal_code` * | string | 邮政编码   | 8                                                   |
| `city` *        | string | 城市       | 100                                                 |
| `state` *       | string | 州（UF）   | **[state 枚举值](#enumeradores-state)**             |

### state 枚举值

| 枚举值 | 描述            |
|-------|-----------------|
| AC    | Acre            |
| AL    | Alagoas         |
| AM    | Amazonas        |
| AP    | Amapá           |
| BA    | Bahia           |
| CE    | Ceará           |
| DF    | 联邦区          |
| 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    | 例外            |

## 错误响应

STATUS 4xx

Response Body: 错误

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title` | 英文描述<br/>`description` | 葡语描述<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 |

---

# 查询催收钱包

URL: /zh-Hans/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"
    ]
}
```

---

# 查询回执文件

URL: /zh-Hans/documentation/boletos/consultar_v1/consultar_arquivo_retorno

:::info 提示
为确保当天的回执文件包含最新信息，请通过 [回执文件对账例程](/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

| 字段                       | 类型   | 描述             | 字符数 |
|----------------------------|--------|------------------|--------|
| `requester_profile_code` * | string | 催收钱包代码     | 10     |

### Query params

| 字段          | 类型   | 描述               | 字符数                                      |
|---------------|--------|--------------------|---------------------------------------------|
| `cnab_type` * | enum   | 文件类型           | **[枚举值](#enumeradores-cnab_type)** |
| `from` *      | string | 分析周期的开始日期 | 10                                          |
| `to` *        | string | 分析周期的结束日期 | 10                                          |

### Enumeradores cnab_type

| 字段                | 描述       | 
|---------------------|------------|
| requester_discharge | 回执文件   | 

## 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: /zh-Hans/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"}
    
}
```

---

# 生成 PDF

URL: /zh-Hans/documentation/boletos/consultar_v1/emitir_pdf

## Request

ENDPOINT /bank_slip/2-way/ BANK_SLIP_KEY
MÉTODO GET

### Path params

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `BANK_SLIP_KEY` *|  string | 票据标识键 | 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: /zh-Hans/documentation/boletos/consultar_v1/francesinha

## Request

- ENDPOINT /bank_slip/little_french
- MÉTODO GET

### Body params

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `requester_profile_code` *| string | 钱包代码 | 10 | 
| `date` | date | 生成报告的日期，若为空则报告日期为今天（格式 YYYY-MM-DD） | 10 | 

## Response

status: 200

Body.json

    响应体将是一个以 base64 编码的 Excel 文件。

status: 400

Body.json

```json

    { }
    

```

---

# 列出票据

URL: /zh-Hans/documentation/boletos/consultar_v1/listar_boletos

## Request

ENDPOINT /bank_slip/person/ BENEFICIARY_KEY
MÉTODO GET

:::caution **注意**

请注意，在两个示例中，`bank_slip_file` 列表均为空。这意味着该票据不存在 PDF 文件。如果客户希望获取票据的 PDF 版本，我们将在后续步骤中说明如何操作。
:::

### Path params

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `beneficiary_key` *| string | 受益人标识键 | uuid 键 |

### Query params

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `payer_document` | string | 付款人文件编号 | - |
| `bank_slip_status` | enum | 票据状态 | **[枚举值](#enumeradores-bank_slip_status)** | 
| `requester_profile` | string | 票据钱包编号 | - |
| `protest_status` | enum | 抗议状态 | **[枚举值](#enumeradores-protest_status)** |
| `from` | date | 票据创建开始日期 | 10 |
| `to` |  date | 票据创建结束日期 | 10 |
| `number_search` | string | 银行编号（our_number）或文件编号（document_number） | - |
| `page` | integer | 待查询页面 >= 1 | - |
| `page_size` | integer | 最大返回记录数 \<\= 100 | - |

### Enumeradores bank_slip_status
| 字段 | 描述 | 
|---|---|
| accepted | 票据在等待登记队列中 | 
| rejected | 票据被拒绝 | 
| registered | 票据已登记（可供付款） | 
| payment_notice | 票据已付款——但无财务清算 | 
| notary_office_payment_notice | rejected | 
| paid | 票据已付款——已核销并完成财务清算 | 
| written_off | 票据已核销，无财务清算 | 

### Enumeradores protest_status
| 字段 | 描述 | 
|---|---|
| accepted | 票据在等待登记队列中 | 

## 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 一般注意事项：
- 最大页面大小（page_size）为 100。
- 如果当前页面返回的记录数少于 page_size，则 next_page 属性将为空。
:::

---

# Excel 格式日常仓位报告

URL: /zh-Hans/documentation/boletos/consultar_v1/posicao_diaria_excel

## Request

ENDPOINT /bank_slip/duplicates_balance_excel
MÉTODO GET

:::caution 注意
此请求的响应体将是一个以 base64 编码的 Excel 文件。
:::

### Query params

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `beneficiary_key` | string | 受益人标识键（若无 requester_profile_code 则必填） | uuid 键 | 
| `requester_profile_code` | string | 钱包代码（若无 beneficiary_key 则必填） | 10 | 
| `expiration_date` | date | 最大到期日（格式 YYYY-MM-DD） | 10 | 

## Response

STATUS 200

Response Body

```json

此请求的响应体将是一个以 base64 编码的 Excel 文件。

```

STATUS 400

Response Body

```json

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

---

# JSON 格式日常仓位报告

URL: /zh-Hans/documentation/boletos/consultar_v1/posicao_diaria_json

## Request

ENDPOINT /bank_slip/duplicates_balance
MÉTODO GET

### Query params

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `beneficiary_key` | string | 受益人标识键（若无 requester_profile_code 则必填） | 10 | 
| `requester_profile_code` | string | 钱包代码（若无 beneficiary_key 则必填） | 10 | 
| `expiration_date` | date | 最大到期日（格式 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\"}"
}
    

```

---

# 回执文件对账例程

URL: /zh-Hans/documentation/boletos/consultar_v1/rotina_de_conciliacao_de_arquivo_retorno

每天会对票据的回执信息进行对账。为确保当天数据已更新，请使用本页指定的端点验证回执文件是否可供查询。我们建议轮询频率不超过每 2 分钟一次请求。

## Request

ENDPOINT /bank_slip/cnab_discharge_status
MÉTODO GET

## Response

STATUS 200

Response Body: 例程已完成

```json
{
  "discharge_ready": true
}
```

Response Body: 例程待处理

```json
{
  "discharge_ready": false
}
```

---

# 申请票据补发

URL: /zh-Hans/documentation/boletos/consultar_v1/segunda_via_de_boleto

## Request

ENDPOINT /bank_slip/2-way/ BANK_SLIP_KEY
MÉTODO POST

### Path parameters

| 字段                    | 类型   | 描述                                                | 字符数 |
|-------------------------|--------|-----------------------------------------------------|--------|
| `bank_slip_key`         | uuidv4 | 票据唯一标识键，格式为 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": [...],
  "our_number": 2,
  "paid_amount": null,
  "paid_fine_amount": null,
  "paid_interest_amount": null,
  "participant_control_number": null,
  "payer_address": "Rua Carlos tampaio, 204",
  "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"}
    
}
```

---

# 单张 Boleto 发行（即时）

URL: /zh-Hans/documentation/boletos/emissao/emissao_boleto_unico_instantanea

:::danger 重要
要注册 bolePix，必须在将要注册 Boleto 的账户中存在有效的随机 Pix 密钥。
:::

对于即时注册单张 Boleto，创建请求的响应（同步响应）将直接返回已注册（或被拒绝）的 Boleto。Nuclea/CIP 对 Boleto 注册的确认/拒绝时间已包含在此端点的响应时间内。

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/instant
MÉTODO POST

### 路径参数

| 字段                    | 类型   | 描述                              | 字符数 |
|------------------------|--------|-----------------------------------|--------|
| `account_key`          | uuidv4 | 账户唯一标识密钥，格式为 uuid v4  | 36     |
| `requester_profile_key` | uuidv4 | 钱包唯一标识密钥，格式为 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_control_key` *     | uuidv4       | 客户请求唯一标识密钥，格式为 uuid v4                                                                                                                                                    | 36                                                                                        |
| `our_number`                | integer      | Boleto 在钱包中的唯一识别编号，可由客户提供，若未提供则由 QI Tech 自动生成                                                                                                             | 11                                                                                        |
| `document_number`           | string       | Boleto 识别编号，可为电子发票编号                                                                                                                                                      | 10                                                                                        |
| `participant_control_number` | string      | 参与方控制号码                                                                                                                                                                         | 25                                                                                        |
| `amount` *                  | float        | Boleto 基准金额                                                                                                                                                                        | -                                                                                         |
| `expiration` *              | string       | 到期日                                                                                                                                                                                 | 10                                                                                        |
| `bank_teller_instructions`  | string       | 给付款方的备注。最多接受 320 个字符，分布在最多 7 行中。每行最多 90 个字符，若超过则自动换行                                                                                           | 320                                                                                       |
| `rebate_amount`             | float        | Boleto 减免金额，将在基准金额之上应用                                                                                                                                                  | -                                                                                         |
| `max_payment_days`          | integer      | Boleto 到期后可供支付的最大自然日数（最多 365 天）                                                                                                                                     | -                                                                                         |
| `financial_instrument_type` | string       | Boleto 类型                                                                                                                                                                            | **[financial_instrument_type 枚举值](#enumeradores-financial_instrument_type)**            |
| `partial_payment_data`      | object       | 部分支付配置                                                                                                                                                                           | **[partial_payment_data 对象](#objeto-partial_payment_data)**                              |
| `write_off_data`            | object       | 核销配置                                                                                                                                                                               | **[write_off_data 对象](#objeto-write_off_settings)**                                     |
| `protest_data`              | object       | 抗议配置                                                                                                                                                                               | **[protest_data 对象](#objeto-protest_settings)**                                         |
| `bankruptcy_protest_data`   | object       | 破产抗议配置                                                                                                                                                                           | **[bankruptcy_protest_data 对象](#objeto-bankruptcy_protest_settings)**                   |
| `fine_data`                 | object       | 罚款配置                                                                                                                                                                               | **[fine_data 对象](#objeto-fine_settings)**                                               |
| `interest_data`             | object       | 利息配置                                                                                                                                                                               | **[interest_data 对象](#objeto-interest_settings)**                                       |
| `discounts_data`            | object array | 折扣配置                                                                                                                                                                               | **[discount 对象](#objeto-discounts_data)**                                               |
| `payer_data` *              | object       | 付款方数据                                                                                                                                                                             | **[payer_data 对象](#objetos-payer_data-e-guarantor_data)**                               |
| `guarantor_data`            | object       | 担保人数据                                                                                                                                                                             | **[guarantor_data 对象](#objetos-payer_data-e-guarantor_data)**                           |
| `pix_key`                   | uuidv4       | 随机类型 Pix 密钥                                                                                                                                                                      | 36                                                                                        |

:::info BolePix
若在请求中发送可选参数 `pix_key`，将生成 bolePix。bolePix 是一种付款与 Pix QR Code 绑定的 Boleto。付款方既可通过 Boleto 的可打印行付款，也可扫描关联的 Pix QR Code 付款。若通过 QR Code 付款，资金即时到账，而相关的银行回执和 Webhook 将与普通 Boleto 一样生成。

**重要提示：** 要注册 bolePix，必须在将要注册 Boleto 的账户中存在有效的随机 Pix 密钥。
:::

:::tip 钱包默认配置
若请求中未发送 `max_payment_days`、`write_off_data`、`protest_data`、`bankruptcy_protest_data`、`fine_data`、`interest_data` 和 `pix_key` 字段，且钱包中存在默认配置（即 `requester_profile` 的 `configuration_data` 中分别有 `max_payment_days`、`write_off_settings`、`protest_settings`、`bankruptcy_protest_settings`、`fine_settings`、`interest_settings` 和 `qr_code_settings`），则发行时将使用这些默认配置。
:::

:::caution 限制和约束
- **部分支付 Boleto：** 不允许通过 Pix QR Code 付款。因此，不允许在注册时发送 `pix_key`，也不允许为钱包设置 bolePix 生成的**默认配置**。

- **信用卡 Boleto：** 不需要也不允许发送减免、折扣、罚款和利息信息。这是因为市场惯例中，许多金融机构不接受包含这些信息的信用卡 Boleto 付款。钱包也不能将这些配置设为默认值。因此，此类 Boleto 即使在到期后也可部分支付，当前账单不产生利息、罚款、折扣或减免。若要应用这些值，需要在下一账单中包含，可通过 Boleto 的[金额编辑事件](/documentation/boletos/instrucoes/valor)或发行包含这些值的新 Boleto 来实现。此类 Boleto 可发送 `amount = 0`。

**重要提示：** `credit_card` 类型的 Boleto 必须支持部分支付，因此需要提供 `partial_payment_data` 信息或在钱包中设置此默认配置。若未发送 `financial_instrument_type` 字段，默认值为 `digital_commercial_invoice`。
:::

:::tip 钱包建议
- **标准 Boleto 钱包：** 保持罚款、利息和抗议的默认配置
- **部分支付 Boleto 钱包：** 无 Pix 配置，并设置部分支付规则
- **信用卡 Boleto 钱包：** 无罚款、利息、折扣或减免配置

创建专用钱包可确保每种类型 Boleto 的默认配置适当，并避免业务规则冲突。
:::

:::info 状态机
部分支付 Boleto 的状态机有所不同。详情请参阅**[简介](/documentation/boletos/introducao)**，其中包含如何按照市场最佳实践对 Boleto 应用利息和罚款的说明。
:::

### financial_instrument_type 枚举值

| 枚举值                               | 描述                              |
|------------------------------------|----------------------------------|
| digital_commercial_invoice          | DMI 商业发票指定复本              |
| credit_card                         | 信用卡                           |
| check                               | 支票                             |
| digital_commercial                  | DM 商业复本                       |
| digital_service_invoice             | 服务复本                         |
| digital_service_invoice_indication  | DSI 服务复本指定                  |
| digital_rural_invoice               | DR 农村复本                       |
| bill_of_exchange                    | LC 汇票                          |
| commercial_credit_note              | NCC 商业信贷票据                  |
| export_credit_note                  | NCE 出口信贷票据                  |
| industrial_credit_note              | NCI 工业信贷票据                  |
| rural_credit_note                   | NCR 农村信贷票据                  |
| promissory_note                     | NP 本票                          |
| rural_promissory_note               | NPR 农村本票                      |
| mercantile_triplicate               | TM 商业三联单                     |
| service_triplicate                  | TS 服务三联单                     |
| insurance_note                      | NS 保险票据                      |
| receipt                             | RC 收据                          |
| printed_bank_slip                   | FAT 票据                         |
| debit_note                          | ND 借记票据                      |
| insurance_policy                    | AP 保险单                        |
| school_monthly_fee                  | ME 学费月付款                     |
| consortium_installment              | PC 联合体分期付款                 |
| invoice                             | NF 发票                          |
| debt_document                       | DD 债务文件                      |
| rural_product_certificate           | 农村产品证书                      |
| warrant                             | 权证                             |
| state_active_debt                   | 州活跃债务                        |
| municipal_active_debt               | 市活跃债务                        |
| federal_active_debt                 | 联邦活跃债务                      |
| condominium_charges                 | 公寓费用                         |
| proposal_bank_slip                  | 提案 Boleto                      |
| deposit_and_contribution_bank_slip  | 存款和认购 Boleto                 |
| others                              | 其他                             |

### partial_payment_data 对象

| 字段                                  | 类型    | 描述                       | 字符数                                                                         |
|-------------------------------------|---------|---------------------------|--------------------------------------------------------------------------------|
| `partial_payment_minimum_type` *    | string  | 部分支付最小金额类型       | **[partial_payment_type 枚举值](#enumeradores-partial_payment_type)**          |
| `partial_payment_minimum_percentage` | float  | 允许的最小部分支付百分比   | -                                                                              |
| `partial_payment_minimum_amount`    | float   | 允许的最小部分支付金额     | -                                                                              |
| `partial_payment_maximum_type`      | string  | 部分支付最大金额类型       | **[partial_payment_type 枚举值](#enumeradores-partial_payment_type)**          |
| `partial_payment_maximum_percentage` | float  | 允许的最大部分支付百分比   | -                                                                              |
| `partial_payment_maximum_amount`    | float   | 允许的最大部分支付金额     | -                                                                              |
| `partial_payment_quantity` *        | integer | 允许的部分支付次数         | -                                                                              |

:::caution 注意！
根据 `partial_payment_minimum_type` 和 `partial_payment_maximum_type` 字段发送的值，需要相应发送 `partial_payment_minimum_amount` 或 `partial_payment_minimum_percentage`，以及 `partial_payment_maximum_amount` 或 `partial_payment_maximum_percentage`。
:::

### partial_payment_type 枚举值

| 枚举值     | 描述     |
|----------|----------|
| absolute  | 绝对金额 |
| percentage | 百分比  |

### write_off_data 对象

| 字段                  | 类型    | 描述                             | 字符数 |
|---------------------|---------|----------------------------------|--------|
| `days_to_write_off` * | integer | Boleto 到期后自动核销的天数      | -      |

### protest_data 对象

| 字段                  | 类型    | 描述                             | 字符数 |
|---------------------|---------|----------------------------------|--------|
| `days_to_protest` * | integer | Boleto 到期后自动抗议的天数      | -      |

### bankruptcy_protest_data 对象

| 字段                          | 类型    | 描述                              | 字符数 |
|-----------------------------|---------|-----------------------------------|--------|
| `days_to_bankruptcy_protest` * | integer | Boleto 到期后自动破产抗议的天数 | -      |

### fine_data 对象

**选项 1：绝对值罚款（`fine_type=absolute`）**

| 字段               | 类型    | 描述                     | 字符数                                               |
|------------------|---------|--------------------------|------------------------------------------------------|
| `fine_type` *    | string  | 罚款类型                 | **[fine_type 枚举值](#enumeradores-fine_type)**      |
| `fine_amount` *  | float   | 罚款绝对值               | -                                                    |
| `days_to_fine` * | integer | 到期后开始收取罚款的天数  | -                                                    |

**选项 2：百分比罚款（`fine_type=percentage`）**

| 字段                  | 类型    | 描述                     | 字符数                                               |
|---------------------|---------|--------------------------|------------------------------------------------------|
| `fine_type` *       | string  | 罚款类型                 | **[fine_type 枚举值](#enumeradores-fine_type)**      |
| `fine_percentage` * | integer | 罚款百分比，1 至 100     | -                                                    |
| `days_to_fine` *    | integer | 到期后开始收取罚款的天数  | -                                                    |

### fine_type 枚举值

| 枚举值     | 描述     |
|----------|----------|
| absolute  | 绝对值   |
| percentage | 百分比  |

### interest_data 对象

**选项 1：绝对值利息（`interest_type=calendar_days_daily_amount` 或 `interest_type=workdays_daily_amount`）**

| 字段                   | 类型    | 描述                                       | 字符数                                                      |
|----------------------|---------|---------------------------------------------|-------------------------------------------------------------|
| `interest_type` *    | string  | 利息类型                                   | **[interest_type 枚举值](#enumeradores-interest_type)**     |
| `interest_amount` *  | float   | 每单位时间（工作日或自然日）收取的利息金额  | -                                                           |
| `days_to_interest` * | integer | 到期后开始收取利息的天数                   | -                                                           |

**选项 2：百分比利息（`interest_type=calendar_days_monthly_percentage`）**

| 字段                      | 类型    | 描述                                           | 字符数                                                      |
|-------------------------|---------|------------------------------------------------|-------------------------------------------------------------|
| `interest_type` *       | string  | 利息类型                                       | **[interest_type 枚举值](#enumeradores-interest_type)**     |
| `interest_percentage` * | integer | 每单位时间（工作日或自然日）收取的利息百分比    | -                                                           |
| `days_to_interest` *    | integer | 到期后开始收取利息的天数                       | -                                                           |

### interest_type 枚举值

| 枚举值                              | 描述                                     |
|-----------------------------------|------------------------------------------|
| calendar_days_daily_amount        | 按自然日计算的每日金额                    |
| workdays_daily_amount             | 按工作日计算的每日金额                    |
| calendar_days_monthly_percentage  | 按自然日计算的月利率百分比                |

### discount 对象

**选项 1：绝对值折扣**

| 字段                   | 类型    | 描述                    | 字符数                                                          |
|----------------------|---------|-------------------------|----------------------------------------------------------------|
| `discount_amount` *  | float   | 每单位时间的绝对折扣金额 | -                                                              |
| `discount_number` *  | integer | 折扣编号                | -                                                              |
| `discount_type` *    | string  | 折扣类型（绝对值）      | **[discount_type 枚举值](#enumeradores-discount_type)**        |
| `discount_limit_date` * | string | 折扣截止日期          | 10                                                             |

**选项 2：百分比折扣**

| 字段                      | 类型    | 描述                    | 字符数                                                          |
|-------------------------|---------|-------------------------|----------------------------------------------------------------|
| `discount_percentage` * | float   | 每单位时间的折扣百分比   | -                                                              |
| `discount_number` *     | integer | 折扣编号                | -                                                              |
| `discount_type` *       | string  | 折扣类型（百分比）      | **[discount_type 枚举值](#enumeradores-discount_type)**        |
| `discount_limit_date` * | string  | 折扣截止日期            | 10                                                             |

:::caution 注意！
一张 Boleto 最多可有三个折扣，且**所有折扣必须为同一类型**，即具有相同的 `discount_type`。折扣编号必须从 1 开始，按递增顺序编号，**最大到 3**。
:::

### discount_type 枚举值

| 枚举值                                       | 描述                                    |
|--------------------------------------------|----------------------------------------|
| absolute                                    | 固定金额                               |
| anticipation_calendar_days_daily_amount     | 按自然日计算的提前还款每日折扣金额      |
| anticipation_workdays_daily_amount          | 按工作日计算的提前还款每日折扣金额      |
| percentage                                  | 固定百分比                              |
| anticipation_calendar_days_daily_percentage | 按自然日计算的提前还款月折扣百分比      |
| anticipation_workdays_daily_percentage      | 按工作日计算的提前还款年折扣百分比      |

### payer_data 和 guarantor_data 对象

| 字段                  | 类型   | 描述                   | 字符数                                                          |
|---------------------|--------|------------------------|----------------------------------------------------------------|
| `name` *            | string | 全名                   | 100                                                            |
| `document_number` * | string | 证件号码（CPF/CNPJ）   | 11 或 14                                                       |
| `person_type` *     | string | 人员类型               | **[person_type 枚举值](#enumeradores-person_type)**            |
| `contact`           | object | 联系信息               | **[contact 对象](#objeto-contact)**                            |
| `address`           | object | 地址                   | **[address 对象](#objeto-address)**                            |

### person_type 枚举值

| 枚举值    | 描述   |
|---------|--------|
| natural  | 自然人 |
| legal    | 法人   |

### contact 对象

| 字段    | 类型   | 描述     | 字符数                                |
|-------|--------|----------|---------------------------------------|
| `email` | string | 联系邮箱 | 320                                   |
| `phone` | object | 联系电话 | **[phone 对象](#objeto-phone)**       |

### phone 对象

| 字段               | 类型   | 描述           | 字符数 |
|------------------|--------|----------------|--------|
| `country_code` * | string | 国际区号（DDI） | 3      |
| `area_code` *    | string | 地区区号（DDD） | 2      |
| `number` *       | string | 电话号码        | 9      |

### address 对象

| 字段              | 类型   | 描述   | 字符数                                             |
|-----------------|--------|--------|----------------------------------------------------|
| `street` *      | string | 街道   | 500                                                |
| `number` *      | string | 门牌号 | 6                                                  |
| `complement`    | string | 补充   | 500                                                |
| `neighborhood` * | string | 社区  | 100                                                |
| `postal_code` * | string | 邮编   | 8                                                  |
| `city` *        | string | 城市   | 100                                                |
| `state` *       | string | 州（UF） | **[state 枚举值](#enumeradores-state)**           |

### state 枚举值

| 枚举值 | 描述                  |
|------|----------------------|
| 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   | 其他                 |

### notification 对象

| 字段                    | 类型    | 描述                                       | 字符数    |
|-----------------------|---------|--------------------------------------------|-----------|
| `document_number` *   | string  | 接收通知者的证件号码（CPF/CNPJ）            | 11 或 14  |
| `name` *              | string  | 接收通知者姓名                              | 100       |
| `email`               | string  | 通知发送邮箱                               | 320       |
| `phone`               | object  | 通知发送联系电话                            | **[phone 对象](#objeto-phone)** |
| `send_2_way` *        | boolean | 发送副本                                   | -         |
| `send_before_due_date` * | boolean | 在到期日前向付款方发送通知              | -         |
| `send_after_due_date` *  | boolean | Boleto 到期时向付款方发送通知           | -         |
| `send_on_protest` *   | boolean | 进入抗议流程时发送通知                      | -         |

## Response

STATUS 201

Response Body: 已注册 Boleto

```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": "<base64 encoded QR code image>"
  }
}
```

STATUS 202

Response Body: 待注册 Boleto

```json
{
  "request_control_key": "f14e9bac-94ed-4eb1-87b4-7fd7b7a2d280",
  "bank_slip_key": "e8599844-5cad-40b4-8716-cb4770d415b4",
  "bank_slip_status": "accepted"
}
```

:::info 说明
若返回 **HTTP Status 202** 且 `bank_slip_status` 值为 `accepted`，则不应重试发行。

此发行将异步处理。需要通过查询 Boleto 来验证状态，或等待接收[Webhook 页面](/documentation/boletos/v2/webhooks/boleto)中描述的确认 Webhook。
:::

### 响应体参数

| 字段                    | 类型    | 描述                                               | 字符数                                                               |
|-----------------------|---------|----------------------------------------------------|----------------------------------------------------------------------|
| `request_control_key` * | uuidv4 | 客户请求唯一标识密钥，格式为 uuid v4               | 36                                                                   |
| `bank_slip_key` *     | uuidv4  | Boleto 唯一标识密钥，格式为 uuid v4                | 36                                                                   |
| `bank_slip_status` *  | string  | Boleto 状态                                        | **[bank_slip_status 枚举值](#enumeradores-bank_slip_status)**        |
| `our_number` *        | integer | Boleto 在钱包中的唯一识别编号                      | 11                                                                   |
| `barcode` *           | string  | Boleto 条形码                                      | 44                                                                   |
| `digitable_line` *    | string  | Boleto 可打印行                                    | 47                                                                   |
| `qr_code_data`        | object  | QR Code 数据                                       | **[qr_code_data 对象](#objeto-qr_code_data)**                        |
| `created_at` *        | string  | 事件创建日期，ISO 格式（UTC - "YYYY-MM-DDTHH:MM:SSZ"） | 20                                                               |

### bank_slip_status 枚举值

| 枚举值     | 描述                      |
|----------|---------------------------|
| accepted  | Boleto 已接受但尚未注册    |
| registered | Boleto 已注册             |

### qr_code_data 对象

| 字段                       | 类型   | 描述                             | 字符数 |
|--------------------------|--------|----------------------------------|--------|
| `qr_code_key`            | uuidv4 | QR Code 唯一标识密钥             | 36     |
| `pix_key`                | uuidv4 | 与 QR Code 关联的 PIX 密钥       | 36     |
| `receiver_conciliation_id` | uuidv4 | QR Code 对账标识符             | 36     |
| `url`                    | string | QR Code 的 URL（Pix 复制粘贴）   | -      |
| `image`                  | string | QR Code URL 的 base64 编码图片   | -      |

## 错误响应

STATUS 4xx

Response Body: 错误

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

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`  | 英文描述<br/>`description`                                                                                              | 葡语描述<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                    | 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.                                          |

---

# 单张 Boleto 发行（标准）

URL: /zh-Hans/documentation/boletos/emissao/emissao_boleto_unico_padrao

:::danger 重要
要注册 bolePix，必须在将要注册 Boleto 的账户中存在有效的随机 Pix 密钥。
:::

在标准 Boleto 注册流程中，若请求成功，响应将返回状态为 `accepted` 的 Boleto（Boleto 已被 QI Tech 接受）。Nuclea/CIP 确认或拒绝后，Boleto 将转为 `registered` 或 `rejected` 状态。

:::caution 注意！
由于这是异步注册，当 Boleto 状态从 `accepted` 变更为 `registered` 或 `rejected` 时，申请方将通过 [**Webhook**](/documentation/boletos/v2/webhooks/boleto) 收到通知。
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip
MÉTODO POST

### 路径参数

| 字段                    | 类型   | 描述                              | 字符数 |
|------------------------|--------|-----------------------------------|--------|
| `account_key`          | uuidv4 | 账户唯一标识密钥，格式为 uuid v4  | 36     |
| `requester_profile_key` | uuidv4 | 钱包唯一标识密钥，格式为 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": "John Smith",
        "account_number": "1234567",
        "account_digit": "8"
      },
      {
        "percentage": 10,
        "document_number": "10987654321",
        "account_owner_name": "Mary Johnson",
        "account_number": "7654321",
        "account_digit": "0"
      }
    ]
  }
}
```

### 请求体

| 字段                          | 类型         | 描述                                                                                                                                                                                    | 字符数                                                                                     |
|-----------------------------|--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| `request_control_key` *     | uuidv4       | 客户请求唯一标识密钥，格式为 uuid v4                                                                                                                                                    | 36                                                                                        |
| `our_number`                | integer      | Boleto 在钱包中的唯一识别编号，可由客户提供，若未提供则由 QI Tech 自动生成                                                                                                             | 11                                                                                        |
| `document_number`           | string       | Boleto 识别编号，可为电子发票编号                                                                                                                                                      | 10                                                                                        |
| `participant_control_number` | string      | 参与方控制号码                                                                                                                                                                         | 25                                                                                        |
| `amount` *                  | float        | Boleto 基准金额                                                                                                                                                                        | -                                                                                         |
| `expiration` *              | string       | 到期日                                                                                                                                                                                 | 10                                                                                        |
| `bank_teller_instructions`  | string       | 给付款方的备注。最多接受 320 个字符，分布在最多 7 行中。每行最多 90 个字符，若超过则自动换行                                                                                           | 320                                                                                       |
| `rebate_amount`             | float        | Boleto 减免金额，将在基准金额之上应用                                                                                                                                                  | -                                                                                         |
| `max_payment_days`          | integer      | Boleto 到期后可供支付的最大自然日数（最多 365 天）                                                                                                                                     | -                                                                                         |
| `financial_instrument_type` | string       | Boleto 类型                                                                                                                                                                            | **[financial_instrument_type 枚举值](#enumeradores-financial_instrument_type)**            |
| `partial_payment_data`      | object       | 部分支付配置                                                                                                                                                                           | **[partial_payment_data 对象](#objeto-partial_payment_data)**                              |
| `write_off_data`            | object       | 核销配置                                                                                                                                                                               | **[write_off_data 对象](#objeto-write_off_settings)**                                     |
| `protest_data`              | object       | 抗议配置                                                                                                                                                                               | **[protest_data 对象](#objeto-protest_settings)**                                         |
| `bankruptcy_protest_data`   | object       | 破产抗议配置                                                                                                                                                                           | **[bankruptcy_protest_data 对象](#objeto-bankruptcy_protest_settings)**                   |
| `fine_data`                 | object       | 罚款配置                                                                                                                                                                               | **[fine_data 对象](#objeto-fine_settings)**                                               |
| `interest_data`             | object       | 利息配置                                                                                                                                                                               | **[interest_data 对象](#objeto-interest_settings)**                                       |
| `discounts_data`            | object array | 折扣配置                                                                                                                                                                               | **[discount 对象](#objeto-discounts_data)**                                               |
| `payer_data` *              | object       | 付款方数据                                                                                                                                                                             | **[payer_data 对象](#objetos-payer_data-e-guarantor_data)**                               |
| `guarantor_data`            | object       | 担保人数据                                                                                                                                                                             | **[guarantor_data 对象](#objetos-payer_data-e-guarantor_data)**                           |
| `pix_key`                   | uuidv4       | 随机类型 Pix 密钥                                                                                                                                                                      | 36                                                                                        |
| `notification`              | object       | 付款方通知配置                                                                                                                                                                         | **[notification 对象](#objeto-notification)**                                             |
| `split_payment_data`        | object       | Boleto 的信用分账（分账支付）配置                                                                                                                                                      | **[split_payment_data 对象](#objeto-split_payment_data)**                                 |

:::info BolePix
若在请求中发送可选参数 `pix_key`，将生成 bolePix。bolePix 是一种付款与 Pix QR Code 绑定的 Boleto。付款方既可通过 Boleto 的可打印行付款，也可扫描关联的 Pix QR Code 付款。若通过 QR Code 付款，资金即时到账，而相关的银行回执和 Webhook 将与普通 Boleto 一样生成。

**重要提示：** 要注册 bolePix，必须在将要注册 Boleto 的账户中存在有效的随机 Pix 密钥。
:::

:::tip 钱包默认配置
若请求中未发送 `max_payment_days`、`write_off_data`、`protest_data`、`bankruptcy_protest_data`、`fine_data`、`interest_data` 和 `pix_key` 字段，且钱包中存在默认配置，则发行时将使用这些默认配置。
:::

:::caution 限制和约束
- **部分支付 Boleto：** 不允许通过 Pix QR Code 付款。因此，不允许在注册时发送 `pix_key`，也不允许为钱包设置 bolePix 生成的**默认配置**。

- **信用卡 Boleto：** 不需要也不允许发送减免、折扣、罚款和利息信息。此类 Boleto 即使在到期后也可部分支付，当前账单不产生利息、罚款、折扣或减免。可发送 `amount = 0`。

**重要提示：** `credit_card` 类型的 Boleto 必须支持部分支付，若未发送 `financial_instrument_type` 字段，默认值为 `digital_commercial_invoice`。
:::

:::tip 钱包建议
- **标准 Boleto 钱包：** 保持罚款、利息和抗议的默认配置
- **部分支付 Boleto 钱包：** 无 Pix 配置，并设置部分支付规则
- **信用卡 Boleto 钱包：** 无罚款、利息、折扣或减免配置

创建专用钱包可确保每种类型 Boleto 的默认配置适当，并避免业务规则冲突。
:::

:::info 状态机
部分支付 Boleto 的状态机有所不同。详情请参阅**[简介](/documentation/boletos/introducao)**。
:::

### financial_instrument_type 枚举值

| 枚举值                               | 描述                              |
|------------------------------------|----------------------------------|
| digital_commercial_invoice          | DMI 商业发票指定复本              |
| credit_card                         | 信用卡                           |
| check                               | 支票                             |
| digital_commercial                  | DM 商业复本                       |
| digital_service_invoice             | 服务复本                         |
| digital_service_invoice_indication  | DSI 服务复本指定                  |
| digital_rural_invoice               | DR 农村复本                       |
| bill_of_exchange                    | LC 汇票                          |
| commercial_credit_note              | NCC 商业信贷票据                  |
| export_credit_note                  | NCE 出口信贷票据                  |
| industrial_credit_note              | NCI 工业信贷票据                  |
| rural_credit_note                   | NCR 农村信贷票据                  |
| promissory_note                     | NP 本票                          |
| rural_promissory_note               | NPR 农村本票                      |
| mercantile_triplicate               | TM 商业三联单                     |
| service_triplicate                  | TS 服务三联单                     |
| insurance_note                      | NS 保险票据                      |
| receipt                             | RC 收据                          |
| printed_bank_slip                   | FAT 票据                         |
| debit_note                          | ND 借记票据                      |
| insurance_policy                    | AP 保险单                        |
| school_monthly_fee                  | ME 学费月付款                     |
| consortium_installment              | PC 联合体分期付款                 |
| invoice                             | NF 发票                          |
| debt_document                       | DD 债务文件                      |
| rural_product_certificate           | 农村产品证书                      |
| warrant                             | 权证                             |
| state_active_debt                   | 州活跃债务                        |
| municipal_active_debt               | 市活跃债务                        |
| federal_active_debt                 | 联邦活跃债务                      |
| condominium_charges                 | 公寓费用                         |
| proposal_bank_slip                  | 提案 Boleto                      |
| deposit_and_contribution_bank_slip  | 存款和认购 Boleto                 |
| others                              | 其他                             |

### split_payment_data 对象

用于配置 Boleto 的**信用分账**（分账支付），将结算金额在 Boleto 受益人和最多 10 个额外账户之间分配。目标账户必须为开通状态并已在 QI Tech 注册，且各项百分比之和（受益人 + 规则）必须正好等于 100。

| 字段                                    | 类型         | 描述                                                                                            | 字符数     |
|----------------------------------------|--------------|------------------------------------------------------------------------------------------------|------------|
| `beneficiary_settlement_percentage` *  | float        | 分配给 Boleto 受益人的结算金额百分比，取值范围 0 至 100                                         | -          |
| `beneficiary_max_amount`               | float        | 受益人在结算时可获得的最大金额。当付款金额超过此限额时，超出部分将全部分配给 `split_payment_rules` 数组中的第一条规则。取值大于 0 且不大于 Boleto 金额 | - |
| `split_payment_rules` *                | object array | 分账规则列表。最少 1 条，最多 10 条                                                              | **[split_payment_rule 对象](#objeto-split_payment_rule)** |

#### split_payment_rule 对象

| 字段                    | 类型     | 描述                                                                                | 字符数     |
|-------------------------|----------|-------------------------------------------------------------------------------------|------------|
| `percentage` *          | float    | 分配给该账户的结算金额百分比，取值范围 0 至 100。当此规则专门用于接收 `beneficiary_max_amount` 之上的超出部分时，请使用 `0` | - |
| `document_number` *     | string   | 目标账户持有人的 CPF/CNPJ                                                           | 11 或 14   |
| `account_owner_name` *  | string   | 目标账户持有人姓名                                                                  | 100        |
| `account_number` *      | string   | 目标账户号                                                                          | 20         |
| `account_digit` *       | string   | 目标账户校验位                                                                      | 2          |

:::caution 注意！
- `beneficiary_settlement_percentage` 与 `split_payment_rules` 中各项百分比之和必须正好等于 **100**。
- `document_number` 在各规则之间必须唯一，且不得与受益人相同。
- 分账适用于 Boleto 的所有结算流程（SILOC、STR、公证处和 Pix QR Code）。
- 提供 `beneficiary_max_amount` 时，必须大于 0 且不大于 Boleto 金额。当任一规则的 `percentage = 0` 时，此字段必填。
- 每张 Boleto 仅允许**一条**规则的 `percentage = 0`（即超出部分的接收方）。
- 发行后，只要 Boleto 处于 `registered` 状态且尚未支付，可通过[**信用分账更新接口**](/documentation/boletos/instrucoes/rateio_de_credito)更新规则。
:::

:::tip 用例：将利息/滞纳金导向单独账户
若希望受益人始终收到 Boleto 面值，并由不同账户接收逾期付款产生的利息/滞纳金，请配置 `beneficiary_settlement_percentage = 100` + `beneficiary_max_amount = ` + 一条 `percentage = 0` 的规则，指向超出部分的接收账户。完整说明请参见 [**信用分账更新**](/documentation/boletos/instrucoes/rateio_de_credito#用例将逾期利息和滞纳金导向单独账户)。
:::

### partial_payment_data 对象

| 字段                                  | 类型    | 描述                       | 字符数                                                                         |
|-------------------------------------|---------|---------------------------|--------------------------------------------------------------------------------|
| `partial_payment_minimum_type` *    | string  | 部分支付最小金额类型       | **[partial_payment_type 枚举值](#enumeradores-partial_payment_type)**          |
| `partial_payment_minimum_percentage` | float  | 允许的最小部分支付百分比   | -                                                                              |
| `partial_payment_minimum_amount`    | float   | 允许的最小部分支付金额     | -                                                                              |
| `partial_payment_maximum_type`      | string  | 部分支付最大金额类型       | **[partial_payment_type 枚举值](#enumeradores-partial_payment_type)**          |
| `partial_payment_maximum_percentage` | float  | 允许的最大部分支付百分比   | -                                                                              |
| `partial_payment_maximum_amount`    | float   | 允许的最大部分支付金额     | -                                                                              |
| `partial_payment_quantity` *        | integer | 允许的部分支付次数         | -                                                                              |

:::caution 注意！
根据 `partial_payment_minimum_type` 和 `partial_payment_maximum_type` 字段发送的值，需要相应发送对应的金额或百分比字段。
:::

### partial_payment_type 枚举值

| 枚举值     | 描述     |
|----------|----------|
| absolute  | 绝对金额 |
| percentage | 百分比  |

### write_off_data 对象

| 字段                  | 类型    | 描述                             | 字符数 |
|---------------------|---------|----------------------------------|--------|
| `days_to_write_off` * | integer | Boleto 到期后自动核销的天数      | -      |

### protest_data 对象

| 字段                  | 类型    | 描述                             | 字符数 |
|---------------------|---------|----------------------------------|--------|
| `days_to_protest` * | integer | Boleto 到期后自动抗议的天数      | -      |

### bankruptcy_protest_data 对象

| 字段                          | 类型    | 描述                              | 字符数 |
|-----------------------------|---------|-----------------------------------|--------|
| `days_to_bankruptcy_protest` * | integer | Boleto 到期后自动破产抗议的天数 | -      |

### fine_data 对象

**选项 1：绝对值罚款（`fine_type=absolute`）**

| 字段               | 类型    | 描述                     | 字符数                                               |
|------------------|---------|--------------------------|------------------------------------------------------|
| `fine_type` *    | string  | 罚款类型                 | **[fine_type 枚举值](#enumeradores-fine_type)**      |
| `fine_amount` *  | float   | 罚款绝对值               | -                                                    |
| `days_to_fine` * | integer | 到期后开始收取罚款的天数  | -                                                    |

**选项 2：百分比罚款（`fine_type=percentage`）**

| 字段                  | 类型    | 描述                     | 字符数                                               |
|---------------------|---------|--------------------------|------------------------------------------------------|
| `fine_type` *       | string  | 罚款类型                 | **[fine_type 枚举值](#enumeradores-fine_type)**      |
| `fine_percentage` * | integer | 罚款百分比，1 至 100     | -                                                    |
| `days_to_fine` *    | integer | 到期后开始收取罚款的天数  | -                                                    |

### fine_type 枚举值

| 枚举值     | 描述     |
|----------|----------|
| absolute  | 绝对值   |
| percentage | 百分比  |

### interest_data 对象

**选项 1：绝对值利息**

| 字段                   | 类型    | 描述                                       | 字符数                                                      |
|----------------------|---------|---------------------------------------------|-------------------------------------------------------------|
| `interest_type` *    | string  | 利息类型                                   | **[interest_type 枚举值](#enumeradores-interest_type)**     |
| `interest_amount` *  | float   | 每单位时间（工作日或自然日）收取的利息金额  | -                                                           |
| `days_to_interest` * | integer | 到期后开始收取利息的天数                   | -                                                           |

**选项 2：百分比利息**

| 字段                      | 类型    | 描述                                           | 字符数                                                      |
|-------------------------|---------|------------------------------------------------|-------------------------------------------------------------|
| `interest_type` *       | string  | 利息类型                                       | **[interest_type 枚举值](#enumeradores-interest_type)**     |
| `interest_percentage` * | integer | 每单位时间（工作日或自然日）收取的利息百分比    | -                                                           |
| `days_to_interest` *    | integer | 到期后开始收取利息的天数                       | -                                                           |

### interest_type 枚举值

| 枚举值                              | 描述                                     |
|-----------------------------------|------------------------------------------|
| calendar_days_daily_amount        | 按自然日计算的每日金额                    |
| workdays_daily_amount             | 按工作日计算的每日金额                    |
| calendar_days_monthly_percentage  | 按自然日计算的月利率百分比                |

### discount 对象

**选项 1：绝对值折扣**

| 字段                   | 类型    | 描述                    | 字符数                                                          |
|----------------------|---------|-------------------------|----------------------------------------------------------------|
| `discount_amount` *  | float   | 每单位时间的绝对折扣金额 | -                                                              |
| `discount_number` *  | integer | 折扣编号                | -                                                              |
| `discount_type` *    | string  | 折扣类型（绝对值）      | **[discount_type 枚举值](#enumeradores-discount_type)**        |
| `discount_limit_date` * | string | 折扣截止日期          | 10                                                             |

**选项 2：百分比折扣**

| 字段                      | 类型    | 描述                    | 字符数                                                          |
|-------------------------|---------|-------------------------|----------------------------------------------------------------|
| `discount_percentage` * | float   | 每单位时间的折扣百分比   | -                                                              |
| `discount_number` *     | integer | 折扣编号                | -                                                              |
| `discount_type` *       | string  | 折扣类型（百分比）      | **[discount_type 枚举值](#enumeradores-discount_type)**        |
| `discount_limit_date` * | string  | 折扣截止日期            | 10                                                             |

:::caution 注意！
一张 Boleto 最多可有三个折扣，且**所有折扣必须为同一类型**，折扣编号必须从 1 开始按递增顺序编号。
:::

### discount_type 枚举值

| 枚举值                                       | 描述                                    |
|--------------------------------------------|----------------------------------------|
| absolute                                    | 固定金额                               |
| anticipation_calendar_days_daily_amount     | 按自然日计算的提前还款每日折扣金额      |
| anticipation_workdays_daily_amount          | 按工作日计算的提前还款每日折扣金额      |
| percentage                                  | 固定百分比                              |
| anticipation_calendar_days_daily_percentage | 按自然日计算的提前还款月折扣百分比      |
| anticipation_workdays_daily_percentage      | 按工作日计算的提前还款年折扣百分比      |

### payer_data 和 guarantor_data 对象

| 字段                  | 类型   | 描述                   | 字符数                                                          |
|---------------------|--------|------------------------|----------------------------------------------------------------|
| `name` *            | string | 全名                   | 100                                                            |
| `document_number` * | string | 证件号码（CPF/CNPJ）   | 11 或 14                                                       |
| `person_type` *     | string | 人员类型               | **[person_type 枚举值](#enumeradores-person_type)**            |
| `contact`           | object | 联系信息               | **[contact 对象](#objeto-contact)**                            |
| `address`           | object | 地址                   | **[address 对象](#objeto-address)**                            |

### person_type 枚举值

| 枚举值    | 描述   |
|---------|--------|
| natural  | 自然人 |
| legal    | 法人   |

### contact 对象

| 字段    | 类型   | 描述     | 字符数                                |
|-------|--------|----------|---------------------------------------|
| `email` | string | 联系邮箱 | 320                                   |
| `phone` | object | 联系电话 | **[phone 对象](#objeto-phone)**       |

### phone 对象

| 字段               | 类型   | 描述           | 字符数 |
|------------------|--------|----------------|--------|
| `country_code` * | string | 国际区号（DDI） | 3      |
| `area_code` *    | string | 地区区号（DDD） | 2      |
| `number` *       | string | 电话号码        | 9      |

### address 对象

| 字段              | 类型   | 描述   | 字符数                                             |
|-----------------|--------|--------|----------------------------------------------------|
| `street` *      | string | 街道   | 500                                                |
| `number` *      | string | 门牌号 | 6                                                  |
| `complement`    | string | 补充   | 500                                                |
| `neighborhood` * | string | 社区  | 100                                                |
| `postal_code` * | string | 邮编   | 8                                                  |
| `city` *        | string | 城市   | 100                                                |
| `state` *       | string | 州（UF） | **[state 枚举值](#enumeradores-state)**           |

### state 枚举值

| 枚举值 | 描述                  |
|------|----------------------|
| 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   | 其他                 |

### notification 对象

| 字段                    | 类型    | 描述                                       | 字符数    |
|-----------------------|---------|--------------------------------------------|-----------|
| `document_number` *   | string  | 接收通知者的证件号码（CPF/CNPJ）            | 11 或 14  |
| `name` *              | string  | 接收通知者姓名                              | 100       |
| `email`               | string  | 通知发送邮箱                               | 320       |
| `phone`               | object  | 通知发送联系电话                            | **[phone 对象](#objeto-phone)** |
| `send_2_way` *        | boolean | 发送副本                                   | -         |
| `send_before_due_date` * | boolean | 在到期日前向付款方发送通知              | -         |
| `send_after_due_date` *  | boolean | Boleto 到期时向付款方发送通知           | -         |
| `send_on_protest` *   | boolean | 进入抗议流程时发送通知                      | -         |

## 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": "<base64 encoded QR code image>"
  }
}
```

### 响应体参数

| 字段                    | 类型    | 描述                                               | 字符数                                                               |
|-----------------------|---------|----------------------------------------------------|----------------------------------------------------------------------|
| `request_control_key` * | uuidv4 | 客户请求唯一标识密钥，格式为 uuid v4               | 36                                                                   |
| `bank_slip_key` *     | uuidv4  | Boleto 唯一标识密钥，格式为 uuid v4                | 36                                                                   |
| `bank_slip_status` *  | string  | Boleto 状态                                        | **[bank_slip_status 枚举值](#enumeradores-bank_slip_status)**        |
| `our_number` *        | integer | Boleto 在钱包中的唯一识别编号                      | 11                                                                   |
| `barcode` *           | string  | Boleto 条形码                                      | 44                                                                   |
| `digitable_line` *    | string  | Boleto 可打印行                                    | 47                                                                   |
| `qr_code_data`        | object  | QR Code 数据                                       | **[qr_code_data 对象](#objeto-qr_code_data)**                        |
| `created_at` *        | string  | 事件创建日期，ISO 格式（UTC - "YYYY-MM-DDTHH:MM:SSZ"） | 20                                                               |

### bank_slip_status 枚举值

| 枚举值     | 描述                      |
|----------|---------------------------|
| accepted  | Boleto 已接受但尚未注册    |

### qr_code_data 对象

| 字段                       | 类型   | 描述                             | 字符数 |
|--------------------------|--------|----------------------------------|--------|
| `qr_code_key`            | uuidv4 | QR Code 唯一标识密钥             | 36     |
| `pix_key`                | uuidv4 | 与 QR Code 关联的 PIX 密钥       | 36     |
| `receiver_conciliation_id` | uuidv4 | QR Code 对账标识符             | 36     |
| `url`                    | string | QR Code 的 URL（Pix 复制粘贴）   | -      |
| `image`                  | string | QR Code URL 的 base64 编码图片   | -      |

## 错误响应

STATUS 4xx

Response Body: 错误

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

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`  | 英文描述<br/>`description`                                                                                              | 葡语描述<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                    | 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.                                          |

---

# 批量 Boleto 发行

URL: /zh-Hans/documentation/boletos/emissao/emissao_em_lote

:::danger 重要
要注册 bolePix，必须在将要注册 Boleto 的账户中存在有效的随机 Pix 密钥。
:::

批量 Boleto 发行仅以异步方式进行。若某张 Boleto 在验证所提供信息时失败，则同一请求中的所有 Boleto 均不会被注册。

:::caution 注意！
由于这是异步注册，当每张 Boleto 状态从 `accepted` 变更为 `registered` 或 `rejected` 时，申请方将通过 [**Webhook**](/documentation/boletos/v2/webhooks/boleto) 收到通知。
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/batch
MÉTODO POST

### 路径参数

| 字段                    | 类型   | 描述                              | 字符数 |
|------------------------|--------|-----------------------------------|--------|
| `account_key`          | uuidv4 | 账户唯一标识密钥，格式为 uuid v4  | 36     |
| `requester_profile_key` | uuidv4 | 钱包唯一标识密钥，格式为 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"
      }
    }
  ]
}
```

### 请求体参数

| 字段           | 类型                                                         | 描述                   | 字符数 |
|--------------|--------------------------------------------------------------|------------------------|--------|
| `bank_slips` * | **[bank_slip 对象](#objeto-bank_slip)** 数组                | 待注册的 Boleto 列表    | -      |

### bank_slip 对象

| 字段                          | 类型         | 描述                                                                                                   | 字符数                                                                                     |
|-----------------------------|--------------|--------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| `request_control_key` *     | uuidv4       | 客户请求唯一标识密钥，格式为 uuid v4                                                                    | 36                                                                                        |
| `our_number`                | integer      | Boleto 在钱包中的唯一识别编号，可由客户提供，若未提供则由 QI Tech 自动生成                              | 11                                                                                        |
| `document_number`           | string       | Boleto 识别编号                                                                                        | 10                                                                                        |
| `participant_control_number` | string      | 参与方控制号码                                                                                         | 25                                                                                        |
| `amount` *                  | float        | Boleto 基准金额                                                                                        | -                                                                                         |
| `expiration` *              | string       | 到期日                                                                                                 | 10                                                                                        |
| `bank_teller_instructions`  | string       | 注册附加说明，将显示在 Boleto PDF 中。最多接受 320 个字符，分布在最多 7 行中                           | 320                                                                                       |
| `rebate_amount`             | float        | Boleto 减免金额，将在基准金额之上应用                                                                  | -                                                                                         |
| `max_payment_days`          | integer      | Boleto 到期后可供支付的最大自然日数（最多 365 天）                                                     | -                                                                                         |
| `financial_instrument_type` | string       | Boleto 类型                                                                                            | **[financial_instrument_type 枚举值](#enumeradores-financial_instrument_type)**            |
| `partial_payment_data`      | object       | 部分支付配置                                                                                           | **[partial_payment_data 对象](#objeto-partial_payment_data)**                              |
| `write_off_data`            | object       | 核销配置                                                                                               | **[write_off_data 对象](#objeto-write_off_settings)**                                     |
| `protest_data`              | object       | 抗议配置                                                                                               | **[protest_data 对象](#objeto-protest_settings)**                                         |
| `bankruptcy_protest_data`   | object       | 破产抗议配置                                                                                           | **[bankruptcy_protest_data 对象](#objeto-bankruptcy_protest_settings)**                   |
| `fine_data`                 | object       | 罚款配置                                                                                               | **[fine_data 对象](#objeto-fine_settings)**                                               |
| `interest_data`             | object       | 利息配置                                                                                               | **[interest_data 对象](#objeto-interest_settings)**                                       |
| `discounts_data`            | object array | 折扣配置                                                                                               | **[discount 对象](#objeto-discounts_data)**                                               |
| `payer_data` *              | object       | 付款方数据                                                                                             | **[payer_data 对象](#objetos-payer_data-e-guarantor_data)**                               |
| `guarantor_data`            | object       | 担保人数据                                                                                             | **[guarantor_data 对象](#objetos-payer_data-e-guarantor_data)**                           |
| `pix_key`                   | uuidv4       | 随机类型 Pix 密钥                                                                                      | 36                                                                                        |

:::info BolePix
若在请求中发送可选参数 `pix_key`，将生成 bolePix。**重要提示：** 要注册 bolePix，必须在将要注册 Boleto 的账户中存在有效的随机 Pix 密钥。
:::

:::tip 钱包默认配置
若请求中未发送 `max_payment_days`、`write_off_data`、`protest_data`、`bankruptcy_protest_data`、`fine_data`、`interest_data` 和 `pix_key` 字段，且钱包中存在默认配置，则发行时将使用这些默认配置。
:::

:::caution 限制和约束
- **部分支付 Boleto：** 不允许通过 Pix QR Code 付款。
- **信用卡 Boleto：** 不需要也不允许发送减免、折扣、罚款和利息信息。此类 Boleto 必须支持部分支付。若未发送 `financial_instrument_type` 字段，默认值为 `digital_commercial_invoice`。
:::

:::tip 钱包建议
- **标准 Boleto 钱包：** 保持罚款、利息和抗议的默认配置
- **部分支付 Boleto 钱包：** 无 Pix 配置，并设置部分支付规则
- **信用卡 Boleto 钱包：** 无罚款、利息、折扣或减免配置
:::

:::info 状态机
部分支付 Boleto 的状态机有所不同。详情请参阅**[简介](/documentation/boletos/introducao)**。
:::

### financial_instrument_type 枚举值

| 枚举值                               | 描述                              |
|------------------------------------|----------------------------------|
| digital_commercial_invoice          | DMI 商业发票指定复本              |
| credit_card                         | 信用卡                           |
| check                               | 支票                             |
| digital_commercial                  | DM 商业复本                       |
| digital_service_invoice             | 服务复本                         |
| digital_service_invoice_indication  | DSI 服务复本指定                  |
| digital_rural_invoice               | DR 农村复本                       |
| bill_of_exchange                    | LC 汇票                          |
| commercial_credit_note              | NCC 商业信贷票据                  |
| export_credit_note                  | NCE 出口信贷票据                  |
| industrial_credit_note              | NCI 工业信贷票据                  |
| rural_credit_note                   | NCR 农村信贷票据                  |
| promissory_note                     | NP 本票                          |
| rural_promissory_note               | NPR 农村本票                      |
| mercantile_triplicate               | TM 商业三联单                     |
| service_triplicate                  | TS 服务三联单                     |
| insurance_note                      | NS 保险票据                      |
| receipt                             | RC 收据                          |
| printed_bank_slip                   | FAT 票据                         |
| debit_note                          | ND 借记票据                      |
| insurance_policy                    | AP 保险单                        |
| school_monthly_fee                  | ME 学费月付款                     |
| consortium_installment              | PC 联合体分期付款                 |
| invoice                             | NF 发票                          |
| debt_document                       | DD 债务文件                      |
| rural_product_certificate           | 农村产品证书                      |
| warrant                             | 权证                             |
| state_active_debt                   | 州活跃债务                        |
| municipal_active_debt               | 市活跃债务                        |
| federal_active_debt                 | 联邦活跃债务                      |
| condominium_charges                 | 公寓费用                         |
| proposal_bank_slip                  | 提案 Boleto                      |
| deposit_and_contribution_bank_slip  | 存款和认购 Boleto                 |
| others                              | 其他                             |

### partial_payment_data 对象

| 字段                                  | 类型    | 描述                       | 字符数                                                                         |
|-------------------------------------|---------|---------------------------|--------------------------------------------------------------------------------|
| `partial_payment_minimum_type` *    | string  | 部分支付最小金额类型       | **[partial_payment_type 枚举值](#enumeradores-partial_payment_type)**          |
| `partial_payment_minimum_percentage` | float  | 允许的最小部分支付百分比   | -                                                                              |
| `partial_payment_minimum_amount`    | float   | 允许的最小部分支付金额     | -                                                                              |
| `partial_payment_maximum_type`      | string  | 部分支付最大金额类型       | **[partial_payment_type 枚举值](#enumeradores-partial_payment_type)**          |
| `partial_payment_maximum_percentage` | float  | 允许的最大部分支付百分比   | -                                                                              |
| `partial_payment_maximum_amount`    | float   | 允许的最大部分支付金额     | -                                                                              |
| `partial_payment_quantity` *        | integer | 允许的部分支付次数         | -                                                                              |

### partial_payment_type 枚举值

| 枚举值     | 描述     |
|----------|----------|
| absolute  | 绝对金额 |
| percentage | 百分比  |

### write_off_data 对象

| 字段                  | 类型    | 描述                             | 字符数 |
|---------------------|---------|----------------------------------|--------|
| `days_to_write_off` * | integer | Boleto 到期后自动核销的天数      | -      |

### protest_data 对象

| 字段                  | 类型    | 描述                             | 字符数 |
|---------------------|---------|----------------------------------|--------|
| `days_to_protest` * | integer | Boleto 到期后自动抗议的天数      | -      |

### bankruptcy_protest_data 对象

| 字段                          | 类型    | 描述                              | 字符数 |
|-----------------------------|---------|-----------------------------------|--------|
| `days_to_bankruptcy_protest` * | integer | Boleto 到期后自动破产抗议的天数 | -      |

### fine_data 对象

**选项 1：绝对值罚款（`fine_type=absolute`）**

| 字段               | 类型    | 描述                     | 字符数                                               |
|------------------|---------|--------------------------|------------------------------------------------------|
| `fine_type` *    | string  | 罚款类型                 | **[fine_type 枚举值](#enumeradores-fine_type)**      |
| `fine_amount` *  | float   | 罚款绝对值               | -                                                    |
| `days_to_fine` * | integer | 到期后开始收取罚款的天数  | -                                                    |

**选项 2：百分比罚款（`fine_type=percentage`）**

| 字段                  | 类型    | 描述                     | 字符数                                               |
|---------------------|---------|--------------------------|------------------------------------------------------|
| `fine_type` *       | string  | 罚款类型                 | **[fine_type 枚举值](#enumeradores-fine_type)**      |
| `fine_percentage` * | integer | 罚款百分比，1 至 100     | -                                                    |
| `days_to_fine` *    | integer | 到期后开始收取罚款的天数  | -                                                    |

### fine_type 枚举值

| 枚举值     | 描述     |
|----------|----------|
| absolute  | 绝对值   |
| percentage | 百分比  |

### interest_data 对象

**选项 1：绝对值利息**

| 字段                   | 类型    | 描述                                       | 字符数                                                      |
|----------------------|---------|---------------------------------------------|-------------------------------------------------------------|
| `interest_type` *    | string  | 利息类型                                   | **[interest_type 枚举值](#enumeradores-interest_type)**     |
| `interest_amount` *  | float   | 每单位时间（工作日或自然日）收取的利息金额  | -                                                           |
| `days_to_interest` * | integer | 到期后开始收取利息的天数                   | -                                                           |

**选项 2：百分比利息**

| 字段                      | 类型    | 描述                                           | 字符数                                                      |
|-------------------------|---------|------------------------------------------------|-------------------------------------------------------------|
| `interest_type` *       | string  | 利息类型                                       | **[interest_type 枚举值](#enumeradores-interest_type)**     |
| `interest_percentage` * | integer | 每单位时间（工作日或自然日）收取的利息百分比    | -                                                           |
| `days_to_interest` *    | integer | 到期后开始收取利息的天数                       | -                                                           |

### interest_type 枚举值

| 枚举值                              | 描述                                     |
|-----------------------------------|------------------------------------------|
| calendar_days_daily_amount        | 按自然日计算的每日金额                    |
| workdays_daily_amount             | 按工作日计算的每日金额                    |
| calendar_days_monthly_percentage  | 按自然日计算的月利率百分比                |

### discount 对象

**选项 1：绝对值折扣**

| 字段                   | 类型    | 描述                    | 字符数                                                          |
|----------------------|---------|-------------------------|----------------------------------------------------------------|
| `discount_amount` *  | float   | 每单位时间的绝对折扣金额 | -                                                              |
| `discount_number` *  | integer | 折扣编号                | -                                                              |
| `discount_type` *    | string  | 折扣类型（绝对值）      | **[discount_type 枚举值](#enumeradores-discount_type)**        |
| `discount_limit_date` * | string | 折扣截止日期          | 10                                                             |

**选项 2：百分比折扣**

| 字段                      | 类型    | 描述                    | 字符数                                                          |
|-------------------------|---------|-------------------------|----------------------------------------------------------------|
| `discount_percentage` * | float   | 每单位时间的折扣百分比   | -                                                              |
| `discount_number` *     | integer | 折扣编号                | -                                                              |
| `discount_type` *       | string  | 折扣类型（百分比）      | **[discount_type 枚举值](#enumeradores-discount_type)**        |
| `discount_limit_date` * | string  | 折扣截止日期            | 10                                                             |

:::caution 注意！
一张 Boleto 最多可有三个折扣，且**所有折扣必须为同一类型**，折扣编号必须从 1 开始按递增顺序编号。
:::

### discount_type 枚举值

| 枚举值                                       | 描述                                    |
|--------------------------------------------|----------------------------------------|
| absolute                                    | 固定金额                               |
| anticipation_calendar_days_daily_amount     | 按自然日计算的提前还款每日折扣金额      |
| anticipation_workdays_daily_amount          | 按工作日计算的提前还款每日折扣金额      |
| percentage                                  | 固定百分比                              |
| anticipation_calendar_days_daily_percentage | 按自然日计算的提前还款月折扣百分比      |
| anticipation_workdays_daily_percentage      | 按工作日计算的提前还款年折扣百分比      |

### payer_data 和 guarantor_data 对象

| 字段                  | 类型   | 描述                   | 字符数                                                          |
|---------------------|--------|------------------------|----------------------------------------------------------------|
| `name` *            | string | 全名                   | 100                                                            |
| `document_number` * | string | 证件号码（CPF/CNPJ）   | 11 或 14                                                       |
| `person_type` *     | string | 人员类型               | **[person_type 枚举值](#enumeradores-person_type)**            |
| `contact`           | object | 联系信息               | **[contact 对象](#objeto-contact)**                            |
| `address`           | object | 地址                   | **[address 对象](#objeto-address)**                            |

### person_type 枚举值

| 枚举值    | 描述   |
|---------|--------|
| natural  | 自然人 |
| legal    | 法人   |

### contact 对象

| 字段    | 类型   | 描述     | 字符数                                |
|-------|--------|----------|---------------------------------------|
| `email` | string | 联系邮箱 | 320                                   |
| `phone` | object | 联系电话 | **[phone 对象](#objeto-phone)**       |

### phone 对象

| 字段               | 类型   | 描述           | 字符数 |
|------------------|--------|----------------|--------|
| `country_code` * | string | 国际区号（DDI） | 3      |
| `area_code` *    | string | 地区区号（DDD） | 2      |
| `number` *       | string | 电话号码        | 9      |

### address 对象

| 字段              | 类型   | 描述   | 字符数                                             |
|-----------------|--------|--------|----------------------------------------------------|
| `street` *      | string | 街道   | 500                                                |
| `number` *      | string | 门牌号 | 6                                                  |
| `complement`    | string | 补充   | 500                                                |
| `neighborhood` * | string | 社区  | 100                                                |
| `postal_code` * | string | 邮编   | 8                                                  |
| `city` *        | string | 城市   | 100                                                |
| `state` *       | string | 州（UF） | **[state 枚举值](#enumeradores-state)**           |

### state 枚举值

| 枚举值 | 描述                  |
|------|----------------------|
| 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   | 其他                 |

### notification 对象

| 字段                    | 类型    | 描述                                       | 字符数    |
|-----------------------|---------|--------------------------------------------|-----------|
| `document_number` *   | string  | 接收通知者的证件号码（CPF/CNPJ）            | 11 或 14  |
| `name` *              | string  | 接收通知者姓名                              | 100       |
| `email`               | string  | 通知发送邮箱                               | 320       |
| `phone`               | object  | 通知发送联系电话                            | **[phone 对象](#objeto-phone)** |
| `send_2_way` *        | boolean | 发送副本                                   | -         |
| `send_before_due_date` * | boolean | 在到期日前向付款方发送通知              | -         |
| `send_after_due_date` *  | boolean | Boleto 到期时向付款方发送通知           | -         |
| `send_on_protest` *   | boolean | 进入抗议流程时发送通知                      | -         |

## Response

STATUS 202

Response Body

```json
{
  "bank_slips": [
    {
      "request_control_key": "c86d8902-a5ae-4d1f-8872-e6fea1268aab",
      "bank_slip_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "bank_slip_status": "accepted",
      "our_number": 123456789,
      "barcode": "32998995900000892812147469258072220406456140",
      "digitable_line": "32992147466925807222704064561402899590000089281"
    },
    {
      "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

### 响应体参数

| 字段           | 类型                                                                | 描述                    | 字符数 |
|--------------|---------------------------------------------------------------------|-------------------------|--------|
| `bank_slips` | **[bank_slip_response 对象](#objeto-bank_slip_response)** 数组      | Boleto 列表             | -      |

### bank_slip_response 对象

| 字段                    | 类型    | 描述                                               | 字符数                                                               |
|-----------------------|---------|----------------------------------------------------|----------------------------------------------------------------------|
| `request_control_key` * | uuidv4 | 客户请求唯一标识密钥，格式为 uuid v4               | 36                                                                   |
| `bank_slip_key` *     | uuidv4  | Boleto 唯一标识密钥，格式为 uuid v4                | 36                                                                   |
| `bank_slip_status` *  | string  | Boleto 状态                                        | **[bank_slip_status 枚举值](#enumeradores-bank_slip_status)**        |
| `our_number` *        | integer | Boleto 在钱包中的唯一识别编号                      | 11                                                                   |
| `barcode` *           | string  | Boleto 条形码                                      | 44                                                                   |
| `digitable_line` *    | string  | Boleto 可打印行                                    | 47                                                                   |
| `qr_code_data`        | object  | QR Code 数据                                       | **[qr_code_data 对象](#objeto-qr_code_data)**                        |
| `created_at` *        | string  | 事件创建日期，ISO 格式（UTC - "YYYY-MM-DDTHH:MM:SSZ"） | 20                                                               |

### bank_slip_status 枚举值

| 枚举值     | 描述                      |
|----------|---------------------------|
| accepted  | Boleto 已接受但尚未注册    |

### qr_code_data 对象

| 字段                       | 类型   | 描述                             | 字符数 |
|--------------------------|--------|----------------------------------|--------|
| `qr_code_key`            | uuidv4 | QR Code 唯一标识密钥             | 36     |
| `pix_key`                | uuidv4 | 与 QR Code 关联的 PIX 密钥       | 36     |
| `receiver_conciliation_id` | uuidv4 | QR Code 对账标识符             | 36     |
| `url`                    | string | QR Code 的 URL（Pix 复制粘贴）   | -      |
| `image`                  | string | QR Code URL 的 base64 编码图片   | -      |

## 错误响应

Response Body: 错误

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

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`  | 英文描述<br/>`description`                                                                                              | 葡语描述<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                    | 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.                                          |

---

# 取消折让

URL: /zh-Hans/documentation/boletos/instrucoes/abatimento/cancelar_abatimento

取消折让意味着取消 Boleto 的现有折让。若有意移除折让或创建新折让，则需进行取消操作。

:::caution 注意！
若存在待确认的折让取消申请，或不存在活跃的折让，则无法申请取消折让。

**注意：** 在 Boleto 登记时发送的折让金额（`rebate_amount`）（若大于 R$0,00）视为活跃折让。
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /cancel_rebate
MÉTODO POST

### 路径参数

| 字段                    | 类型   | 描述                                   | 字符数 |
|------------------------|--------|----------------------------------------|--------|
| `account_key`           | uuidv4 | 账户唯一识别密钥，格式为 uuid v4        | 36     |
| `requester_profile_key` | uuidv4 | 钱包唯一识别密钥，格式为 uuid v4        | 36     |
| `bank_slip_key`         | uuidv4 | Boleto 唯一识别密钥，格式为 uuid v4     | 36     |

Request Body

```json
{
  "request_control_key": "86864aec-a6c8-462e-8460-b05ef5a1eb62"
}
```

### Request Body Params

| 字段                      | 类型   | 描述                                           | 字符数 |
|--------------------------|--------|------------------------------------------------|--------|
| `request_control_key` *  | uuidv4 | 客户使用的请求唯一识别密钥，格式为 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

| 字段               | 类型   | 描述                                           | 字符数 |
|-----------------|--------|------------------------------------------------|--------|
| `occurrence_key` * | uuidv4 | 事件（指令）唯一识别密钥，格式为 uuid v4        | 36     |
| `bank_slip_key` *  | uuidv4 | Boleto 唯一识别密钥，格式为 uuid v4             | 36     |

### 错误响应

STATUS 4xx

Response Body: 错误

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title` | 英文描述<br/>`description` | 葡语描述<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. |

---

# 创建折让

URL: /zh-Hans/documentation/boletos/instrucoes/abatimento/criar_abatimento

为 Boleto 创建折让意味着从票据基础金额中扣除部分金额，以减少最终付款金额。

:::caution 注意！
若存在待确认的折让申请或已有活跃的折让，则不允许创建新的折让。若有活跃折让且需要修改，必须先发送取消折让的请求。待确认后，方可创建另一个折让。

**注意：** 在 Boleto 登记时发送的折让金额（`rebate_amount`）不算作**待处理**的折让申请，但算作活跃的折让申请。
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /rebate
MÉTODO POST

### 路径参数

| 字段                    | 类型   | 描述                                   | 字符数 |
|------------------------|--------|----------------------------------------|--------|
| `account_key`           | uuidv4 | 账户唯一识别密钥，格式为 uuid v4        | 36     |
| `requester_profile_key` | uuidv4 | 钱包唯一识别密钥，格式为 uuid v4        | 36     |
| `bank_slip_key`         | uuidv4 | Boleto 唯一识别密钥，格式为 uuid v4     | 36     |

Request Body

```json
{
  "request_control_key": "d66b807a-25fa-4e21-b198-9beb221a29ce",
  "rebate_amount": 150.00
}
```

### Request Body Params

| 字段                      | 类型   | 描述                                           | 字符数 |
|--------------------------|--------|------------------------------------------------|--------|
| `request_control_key` *  | uuidv4 | 客户使用的请求唯一识别密钥，格式为 uuid v4      | 36     |
| `rebate_amount` *        | float  | 折让绝对金额                                   | -      |

## Response

STATUS 202

Response Body

```json
{
  "occurrence_key": "7f01165b-fdd0-4f59-b231-42170ea90131",
  "bank_slip_key": "dad779c1-5e1c-422e-9f36-c704916a87cf"
}
```

### Response Body Params

| 字段               | 类型   | 描述                                           | 字符数 |
|-----------------|--------|------------------------------------------------|--------|
| `occurrence_key` * | uuidv4 | 事件（指令）唯一识别密钥，格式为 uuid v4        | 36     |
| `bank_slip_key` *  | uuidv4 | Boleto 唯一识别密钥，格式为 uuid v4             | 36     |

### 错误响应

STATUS 4xx

Response Body: 错误

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title` | 英文描述<br/>`description` | 葡语描述<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. | 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. |

---

# 注销

URL: /zh-Hans/documentation/boletos/instrucoes/baixa

当 Boleto 被注销时，将无法再用于付款，即 Boleto "已取消"。

:::caution 注意！
若存在待确认的注销申请，则不允许创建新的申请。 
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /write_off
MÉTODO POST

### 路径参数

| 字段                    | 类型   | 描述                                   | 字符数 |
|------------------------|--------|----------------------------------------|--------|
| `account_key`           | uuidv4 | 账户唯一识别密钥，格式为 uuid v4        | 36     |
| `requester_profile_key` | uuidv4 | 钱包唯一识别密钥，格式为 uuid v4        | 36     |
| `bank_slip_key`         | uuidv4 | Boleto 唯一识别密钥，格式为 uuid v4     | 36     |

Request Body

```json
{
  "request_control_key": "614a451d-3b82-460e-bcc0-2caf3dde711f"
}
```

### Request Body Params

| 字段                      | 类型   | 描述                                           | 字符数 |
|--------------------------|--------|------------------------------------------------|--------|
| `request_control_key` *  | uuidv4 | 客户使用的请求唯一识别密钥，格式为 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

| 字段               | 类型   | 描述                                           | 字符数 |
|-----------------|--------|------------------------------------------------|--------|
| `occurrence_key` * | uuidv4 | 事件（指令）唯一识别密钥，格式为 uuid v4        | 36     |
| `bank_slip_key` *  | uuidv4 | Boleto 唯一识别密钥，格式为 uuid v4             | 36     |

### 错误响应

STATUS 4xx

Response Body: 错误

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title` | 英文描述<br/>`description` | 葡语描述<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. | Já existe uma ocorrência de baixa pendente para este boleto. Por favor, aguarde a confirmação dessa ocorrência antes de enviar outra. |

---

# 折扣

URL: /zh-Hans/documentation/boletos/instrucoes/desconto

折扣指令用于应用具有多种计算规则的折扣。若相关 Boleto 已存在折扣，且折扣指令被接受，则原有折扣将被覆盖。

:::caution 注意！
若存在待确认的折扣添加申请，则不允许创建新的申请。 
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /discount
MÉTODO POST

### 路径参数

| 字段                    | 类型   | 描述                                   | 字符数 |
|------------------------|--------|----------------------------------------|--------|
| `account_key`           | uuidv4 | 账户唯一识别密钥，格式为 uuid v4        | 36     |
| `requester_profile_key` | uuidv4 | 钱包唯一识别密钥，格式为 uuid v4        | 36     |
| `bank_slip_key`         | uuidv4 | Boleto 唯一识别密钥，格式为 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

| 字段                      | 类型         | 描述                                           | 字符数                                                          |
|--------------------------|--------------|------------------------------------------------|----------------------------------------------------------------|
| `request_control_key` *  | uuidv4       | 客户使用的请求唯一识别密钥，格式为 uuid v4      | 36                                                             |
| `discounts_data`         | object array | 折扣                                           | **[discount 对象](#objeto-discounts_data)**                    |

### discount 对象

选项 1：绝对值折扣（`discount_type in ["absolute", "anticipation_calendar_days_daily_amount", "anticipation_workdays_daily_amount"]`）

| 字段                   | 类型    | 描述                                   | 字符数                                                              |
|-----------------------|---------|----------------------------------------|--------------------------------------------------------------------|
| `discount_amount` *   | float   | 按时间单位计的绝对折扣值                | -                                                                  |
| `discount_number` *   | integer | 折扣编号                               | -                                                                  |
| `discount_type` *     | string  | 绝对值折扣配置                         | **[discount_type 枚举值](#enumeradores-discount_type)**            |
| `discount_limit_date` * | string | 折扣应用截止日期                      | 10                                                                 |

选项 2：百分比折扣（`discount_type in ["percentage", "anticipation_calendar_days_daily_percentage", "anticipation_workdays_daily_percentage"]`）

| 字段                     | 类型    | 描述                                   | 字符数                                                              |
|-------------------------|---------|----------------------------------------|--------------------------------------------------------------------|
| `discount_percentage` * | float   | 按时间单位计的百分比折扣值              | -                                                                  |
| `discount_number` *     | integer | 折扣编号                               | -                                                                  |
| `discount_type` *       | string  | 百分比折扣配置                         | **[discount_type 枚举值](#enumeradores-discount_type)**            |
| `discount_limit_date` * | string  | 折扣应用截止日期                       | 10                                                                 |

:::caution 注意！
一张 Boleto 最多可有三个折扣，且**折扣必须为同一类型**，即必须具有相同的 `discount_type`。折扣必须按升序编号，从 **1 开始**。即，若请求中发送两个折扣，则必须编号为 1 和 2。
:::

### discount_type 枚举值

| 枚举值                                       | 描述                                   |
|--------------------------------------------|----------------------------------------|
| absolute                                    | 固定值                                 |
| anticipation_calendar_days_daily_amount     | 按自然日计的每日提前折扣值             |
| anticipation_workdays_daily_amount          | 按工作日计的每日提前折扣值             |
| percentage                                  | 固定百分比                             |
| anticipation_calendar_days_daily_percentage | 按自然日计的月提前折扣百分比           |
| anticipation_workdays_daily_percentage      | 按工作日计的年提前折扣百分比           |

## Response

STATUS 202

Response Body

```json
{
  "occurrence_key": "aaf64135-6bd8-4d49-be6f-e8f884b20ee7",
  "bank_slip_key": "470cfcae-159b-4de4-ad22-2d3b2dd717f7"
}
```

### Response Body Params

| 字段               | 类型   | 描述                                           | 字符数 |
|-----------------|--------|------------------------------------------------|--------|
| `occurrence_key` * | uuidv4 | 事件（指令）唯一识别密钥，格式为 uuid v4        | 36     |
| `bank_slip_key` *  | uuidv4 | Boleto 唯一识别密钥，格式为 uuid v4             | 36     |

### 错误响应

STATUS 4xx

Response Body: 错误

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title` | 英文描述<br/>`description` | 葡语描述<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. |

---

# 编辑

URL: /zh-Hans/documentation/boletos/instrucoes/edicao

编辑指令用于在票据发行后修改其可配置的数据，例如自动核销设置、抗议设置、破产抗议设置和付款人数据。该指令允许在单次请求中更新票据的多个方面。

:::caution 注意！
票据必须处于 `registered` 状态才能进行编辑。请求中除 `request_control_key` 外，至少必须提供一个数据字段（`write_off_data`、`protest_data`、`bankruptcy_protest_data` 或 `payer_data`）。
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /bank_slip_edit
MÉTODO POST

### Path parameters

| 字段                    | 类型   | 描述                                                  | 字符数 |
|-------------------------|--------|-------------------------------------------------------|--------|
| `account_key`           | uuidv4 | 账户唯一标识键，uuid v4 格式                          | 36     |
| `requester_profile_key` | uuidv4 | 钱包唯一标识键，uuid v4 格式                          | 36     |
| `bank_slip_key`         | uuidv4 | 票据唯一标识键，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

| 字段                       | 类型    | 描述                                                                         | 字符数 |
|----------------------------|---------|------------------------------------------------------------------------------|--------|
| `request_control_key` *    | uuidv4  | 客户使用的请求唯一标识键，uuid v4 格式                                       | 36     |
| `write_off_data`           | object  | 自动核销设置（null 表示移除）                                               | **[Objeto write_off_data](#objeto-write_off_data)** |
| `protest_data`             | object  | 抗议设置（null 表示移除）                                                   | **[Objeto protest_data](#objeto-protest_data)** |
| `bankruptcy_protest_data`  | object  | 破产抗议设置（null 表示移除）                                               | **[Objeto bankruptcy_protest_data](#objeto-bankruptcy_protest_data)** |
| `payer_data`               | object  | 付款人数据（`address` 为 null 或 `contact` 为 null 表示移除对应字段）       | **[Objeto payer_data](#objeto-payer_data)** |

:::info 说明
请求中至少必须提供一个数据字段（`write_off_data`、`protest_data`、`bankruptcy_protest_data` 或 `payer_data`）。
:::

### Objeto write_off_data

| 字段                      | 类型    | 描述                                        | 字符数 |
|---------------------------|---------|---------------------------------------------|--------|
| `days_to_write_off` *     | integer | 到期后自动核销票据的天数                    | -      |

### Objeto protest_data

| 字段                      | 类型    | 描述                                        | 字符数 |
|---------------------------|---------|---------------------------------------------|--------|
| `days_to_protest` *       | integer | 到期后自动抗议票据的天数                    | -      |

### Objeto bankruptcy_protest_data

| 字段                           | 类型    | 描述                                              | 字符数 |
|--------------------------------|---------|---------------------------------------------------|--------|
| `days_to_bankruptcy_protest` * | integer | 到期后自动启动破产抗议流程的天数                  | -      |

### Objeto payer_data

| 字段      | 类型   | 描述         | 字符数                                                |
|-----------|--------|--------------|-------------------------------------------------------|
| `contact` | object | 联系信息     | **[Objeto contact](#objeto-contact)**                 |
| `address` | object | 地址         | **[Objeto address](#objeto-address)**                 |

### Objeto contact

| 字段    | 类型   | 描述         | 字符数                                  |
|---------|--------|--------------|----------------------------------------|
| `email` | string | 联系电子邮件 | 320                                    |
| `phone` | object | 联系电话     | **[Objeto phone](#objeto-phone)**      |

### Objeto phone

| 字段                          | 类型   | 描述                    | 字符数 |
|-------------------------------|--------|-------------------------|--------|
| `international_dial_code` *   | string | 国际区号（DDI）         | 3      |
| `area_code` *                 | string | 地区区号（DDD）         | 2      |
| `number` *                    | string | 补充号码                | 9      |

### Objeto address

| 字段                      | 类型   | 描述       | 字符数 |
|---------------------------|--------|------------|--------|
| `street` *                | string | 街道       | 500    |
| `number` *                | string | 门牌号     | 6      |
| `complement`              | string | 补充信息   | 500    |
| `neighborhood` *          | string | 社区/街区  | 100    |
| `postal_code` *           | string | 邮政编码   | 8      |
| `city` *                  | string | 城市       | 100    |
| `state` *                 | string | 州（UF） | **[Enumerador state](#enumeradores-state)** |

### Enumeradores state

| 枚举值 | 描述                  |
|--------|-----------------------|
| 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

| 字段               | 类型   | 描述                                                | 字符数 |
|--------------------|--------|-----------------------------------------------------|--------|
| `occurrence_key` * | uuidv4 | 记录（指令）唯一标识键，uuid v4 格式                | 36     |
| `bank_slip_key` *  | uuidv4 | 票据唯一标识键，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": {}
}
```

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                   | 描述（英文）<br/>`description`                                                                                          | 描述（葡文）<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'.                                                                           |

---

# 延期

URL: /zh-Hans/documentation/boletos/instrucoes/extensao

延期申请用于延长票据的到期日期。

:::caution 注意！
若存在待确认的延期申请，则不允许创建新的申请。 
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /extension
MÉTODO POST

### 路径参数

| 字段                    | 类型   | 描述                                   | 字符数 |
|------------------------|--------|----------------------------------------|--------|
| `account_key`           | uuidv4 | 账户唯一识别密钥，格式为 uuid v4        | 36     |
| `requester_profile_key` | uuidv4 | 钱包唯一识别密钥，格式为 uuid v4        | 36     |
| `bank_slip_key`         | uuidv4 | Boleto 唯一识别密钥，格式为 uuid v4     | 36     |

Request Body

```json
{
  "request_control_key": "2e2f0053-a988-40c7-ad17-41c4c4da861e",
  "new_expiration_date": "2025-01-01"
}
```

### Request Body Params

| 字段                      | 类型   | 描述                                           | 字符数 |
|--------------------------|--------|------------------------------------------------|--------|
| `request_control_key` *  | uuidv4 | 客户使用的请求唯一识别密钥，格式为 uuid v4      | 36     |
| `new_expiration_date` *  | string | 新到期日期，格式为 "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

| 字段               | 类型   | 描述                                           | 字符数 |
|-----------------|--------|------------------------------------------------|--------|
| `occurrence_key` * | uuidv4 | 事件（指令）唯一识别密钥，格式为 uuid v4        | 36     |
| `bank_slip_key` *  | uuidv4 | Boleto 唯一识别密钥，格式为 uuid v4             | 36     |

### 错误响应

STATUS 4xx

Response Body: 错误

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title` | 英文描述<br/>`description` | 葡语描述<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. |

---

# 利息

URL: /zh-Hans/documentation/boletos/instrucoes/juros

利息指令用于配置在截止日期后付款时应收取的利息。若相关 Boleto 已存在利息配置，且利息指令被接受，则原有配置将被覆盖。

:::caution 注意！
若存在待确认的利息指令，则不允许发送新的指令。 
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /interest
MÉTODO POST

### 路径参数

| 字段                    | 类型   | 描述                                   | 字符数 |
|------------------------|--------|----------------------------------------|--------|
| `account_key`           | uuidv4 | 账户唯一识别密钥，格式为 uuid v4        | 36     |
| `requester_profile_key` | uuidv4 | 钱包唯一识别密钥，格式为 uuid v4        | 36     |
| `bank_slip_key`         | uuidv4 | Boleto 唯一识别密钥，格式为 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

| 字段                      | 类型   | 描述                                           | 字符数                                                          |
|--------------------------|--------|------------------------------------------------|----------------------------------------------------------------|
| `request_control_key` *  | uuidv4 | 客户使用的请求唯一识别密钥，格式为 uuid v4      | 36                                                             |
| `interest_data`          | object | 利息配置                                       | **[interest_data 对象](#objeto-interest_data)**                |

### interest_data 对象

选项 1：绝对值利息（`interest_type=calendar_days_daily_amount` 或 `interest_type=workdays_daily_amount`）

| 字段                  | 类型    | 描述                                               | 字符数                                                          |
|----------------------|---------|----------------------------------------------------|----------------------------------------------------------------|
| `interest_type` *    | string  | 利息类型                                           | **[interest_type 枚举值](#enumeradores-interest_type)**        |
| `interest_amount` *  | float   | 按时间单位（工作日或自然日）收取的利息值            | -                                                              |
| `days_to_interest` * | integer | 到期后开始收取利息所需天数                          | -                                                              |

选项 2：百分比利息（`interest_type=calendar_days_monthly_percentage`）

| 字段                    | 类型    | 描述                                           | 字符数                                                          |
|------------------------|---------|------------------------------------------------|----------------------------------------------------------------|
| `interest_type` *      | string  | 利息类型                                       | **[interest_type 枚举值](#enumeradores-interest_type)**        |
| `interest_percentage` * | integer | 按时间单位（工作日或自然日）收取的利息百分比   | -                                                              |
| `days_to_interest` *   | integer | 到期后开始收取利息所需天数                      | -                                                              |

### interest_type 枚举值

| 枚举值                           | 描述                           |
|---------------------------------|--------------------------------|
| calendar_days_daily_amount       | 按自然日计的每日金额           |
| workdays_daily_amount            | 按工作日计的每日金额           |
| calendar_days_monthly_percentage | 按自然日计的月利率             |

## Response

STATUS 202

Response Body

```json
{
  "occurrence_key": "5a745b65-9a2c-44eb-b43e-c80ef5429d94",
  "bank_slip_key": "fdafdffa-cbd4-4f3c-8e3d-990428305161"
}
```

### Response Body Params

| 字段               | 类型   | 描述                                           | 字符数 |
|-----------------|--------|------------------------------------------------|--------|
| `occurrence_key` * | uuidv4 | 事件（指令）唯一识别密钥，格式为 uuid v4        | 36     |
| `bank_slip_key` *  | uuidv4 | Boleto 唯一识别密钥，格式为 uuid v4             | 36     |

### 错误响应

STATUS 4xx

Response Body: 错误

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title` | 英文描述<br/>`description` | 葡语描述<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 | 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. |

---

# 查询指令批次

URL: /zh-Hans/documentation/boletos/instrucoes/lote/consultar_lote_de_instrucoes

返回先前创建批次的详情，包括所生成事件的列表、每个事件的状态以及对应 Boleto 的基本信息。

## Request

ENDPOINT /v2/bank_slip/account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /occurrence_batches/ BATCH_KEY /results
MÉTODO GET

### 路径参数

| 字段                    | 类型   | 描述                                   | 字符数 |
|------------------------|--------|----------------------------------------|--------|
| `account_key`           | uuidv4 | 账户唯一识别密钥，格式为 uuid v4        | 36     |
| `requester_profile_key` | uuidv4 | 钱包唯一识别密钥，格式为 uuid v4        | 36     |
| `batch_key`             | uuidv4 | 批次密钥（由创建 POST 返回）            | 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

| 字段                       | 类型    | 描述                                                                          |
|----------------------------|---------|-------------------------------------------------------------------------------|
| `batch_key` *              | uuidv4  | 批次密钥                                                                       |
| `requester_profile_key` *  | uuidv4  | 持有该批次的钱包密钥                                                           |
| `occurrence_type` *        | string  | 批次的指令类型                                                                 |
| `occurrence_quantity` *    | integer | 批次中发送的总项目数                                                           |
| `accepted_quantity` *      | integer | 批次中被接受的项目数                                                           |
| `created_at` *             | string  | 批次的 UTC 创建时间（ISO 8601，含 `Z` 后缀）                                   |
| `items` *                  | array   | 批次生成的事件列表。详见 **[item 对象](#item-对象)**                            |

### item 对象

| 字段                                           | 类型    | 描述                                                                       |
|------------------------------------------------|---------|----------------------------------------------------------------------------|
| `bank_slip_key` *                              | uuidv4  | 事件对应的 Boleto 密钥                                                      |
| `occurrence_key` *                             | uuidv4  | 创建事件的唯一密钥                                                          |
| `request_control_key` *                        | string  | 客户为该项目提供的控制密钥                                                  |
| `occurrence_type` *                            | string  | 指令类型                                                                    |
| `payer_name`                                   | string  | Boleto 付款人名称                                                           |
| `payer_document`                               | string  | 付款人证件号                                                                |
| `amount`                                       | float   | Boleto 基础金额                                                             |
| `our_number`                                   | string  | Boleto 的 "our number"                                                      |
| `requester_occurrence_status`                  | string  | 请求方视角的事件状态（例如 `accepted`、`rejected`）                          |
| `registration_institution_occurrence_status`   | string  | 注册机构侧的事件处理状态（例如 `submitted`、`confirmed`）                    |
| `created_at` *                                 | string  | 事件的 UTC 创建时间（ISO 8601，含 `Z` 后缀）                                |

### Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "标题",
  "description": "description in English",
  "translation": "descrição em português",
  "code": "代码",
  "extra_fields": {}
}
```

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title` | 描述（英）<br/>`description`           | 描述（葡）<br/>`translation`            |
|------------------------|--------------------|--------------------|----------------------------------------|------------------------------------------|
| 404                    | BKS000013          | Not Found          | Requester profile not found            | Carteira não encontrada                  |

:::caution 注意！
当 `batch_key` 不存在或不属于所提供的 `requester_profile_key` 时，API 同样返回 `BKS000013`（"Carteira não encontrada"）。请确认 `batch_key` 是否在所查询的钱包下创建。
:::

---

# 创建指令批次

URL: /zh-Hans/documentation/boletos/instrucoes/lote/criar_lote_de_instrucoes

通过单次请求，对多个不同的 Boleto 提交同一类型的指令（注销、折扣、展期、抗议等）。QI Tech 会对整个批次进行校验，要么所有项均被接受，要么全部不予处理。

- 若**任一**项未通过语义校验，则该批次**所有**项均不会被处理。错误响应会逐项说明拒绝原因。
- 若所有项均通过校验，相应的事件将异步创建并逐一处理。每当事件状态变更时，系统将通过 [**webhook**](/documentation/boletos/v2/webhooks/boleto) 通知请求方。

:::info 幂等性
批次级的 `request_control_key` 保证幂等性：重复使用同一密钥再次发送，将返回已创建的批次，不会重复创建。

每个项目也拥有自己的 `request_control_key`，并在项目级别保持幂等性。若再次使用已使用过的 `request_control_key` 提交项目，整个批次将被拒绝。
:::

:::caution 注意！
本操作仅适用于注册在 **QI SCD** 注册机构下的钱包。
:::

## Request

ENDPOINT /v2/bank_slip/account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /occurrence_batches
MÉTODO POST

### 路径参数

| 字段                    | 类型   | 描述                                   | 字符数 |
|------------------------|--------|----------------------------------------|--------|
| `account_key`           | uuidv4 | 账户唯一识别密钥，格式为 uuid v4        | 36     |
| `requester_profile_key` | uuidv4 | 钱包唯一识别密钥，格式为 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

| 字段                     | 类型                                  | 描述                                                                  | 字符数 |
|--------------------------|--------------------------------------|-----------------------------------------------------------------------|--------|
| `request_control_key` *  | string                               | 客户定义的批次唯一密钥，用于保证批次的幂等性                          | 1–64   |
| `occurrence_type` *      | string                               | 应用于所有项目的指令类型。详见 **[occurrence_type 枚举](#occurrence_type-枚举)** | -      |
| `items` *                | **[item 对象](#item-对象)** 数组       | 指令列表（最少 1 项，最多 10000 项）                                  | -      |

### occurrence_type 枚举

| 枚举值                    | 描述                                                            |
|---------------------------|-----------------------------------------------------------------|
| `extension`               | 到期日延期 —— 每项需提供 `new_due_date`                          |
| `rebate`                  | 应用折扣 —— 每项需提供 `rebate_amount`                           |
| `cancel_rebate`           | 取消已应用的折扣                                                 |
| `write_off`               | 注销 Boleto                                                      |
| `protest_request`         | 抗议申请                                                         |
| `protest_cancel_request`  | 撤回待处理的抗议申请                                             |
| `protest_remove_request`  | 删除（取消）已登记的抗议                                          |

### item 对象

| 字段                     | 类型   | 描述                                                                       | 字符数 |
|--------------------------|--------|----------------------------------------------------------------------------|--------|
| `bank_slip_key` *        | uuidv4 | 指令将应用的 Boleto 密钥                                                    | 36     |
| `request_control_key` *  | string | 客户定义的项目唯一密钥，用于保证项目级幂等性                                | 1–64   |
| `new_due_date`           | string | 新的到期日（`YYYY-MM-DD`）。当 `occurrence_type=extension` 时必填           | 10     |
| `rebate_amount`          | float  | 折扣金额。当 `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

| 字段                     | 类型    | 描述                                                                         | 字符数 |
|--------------------------|---------|------------------------------------------------------------------------------|--------|
| `batch_key` *            | uuidv4  | 批次唯一密钥，用于查询批次详情                                                | 36     |
| `occurrence_quantity` *  | integer | 批次中发送的总项目数                                                          | -      |
| `accepted_quantity` *    | integer | 批次中被接受的项目数                                                          | -      |
| `semantic_errors` *      | array   | 成功时为空数组。语义校验失败时请参阅 **[Error Response](#error-response)**     | -      |

### Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "标题",
  "description": "description in English",
  "translation": "descrição em português",
  "code": "代码",
  "extra_fields": {}
}
```

语义校验失败时（`BLP000112`），响应中的 `reasons` 字段会列出每个被拒绝的项目：

Response Body: 语义校验失败

```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"
        }
      ]
    }
  ]
}
```

### `reasons[]` 对象字段

| 字段                         | 类型    | 描述                                                                  |
|------------------------------|---------|-----------------------------------------------------------------------|
| `occurrence_sequence` *      | string  | 项目在请求 `items` 数组中的位置（从 `"0"` 开始）                       |
| `bank_slip_key` *            | uuidv4  | 被拒项目对应的 Boleto 密钥                                             |
| `request_control_key` *      | string  | 客户为该项目提供的控制密钥                                             |
| `errors` *                   | array   | 拒绝原因列表（同一项目可能存在多个原因）                                |
| `errors[].reason_code` *     | string  | 拒绝原因代码（Febraban 标准）                                          |
| `errors[].translation_pt_br` | string  | 原因的葡萄牙语描述                                                     |
| `errors[].translation_en_us` | string  | 原因的英语描述                                                         |
| `errors[].created_at`        | string  | 原因在目录中的登记日期                                                 |

### 错误代码

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`     | 描述（英）<br/>`description`                                                                | 描述（葡）<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                                                                            |

---

# 列出指令批次

URL: /zh-Hans/documentation/boletos/instrucoes/lote/listar_lotes_de_instrucoes

按分页方式列出某钱包下创建的指令批次，可按指令类型和日期范围进行筛选。

## Request

ENDPOINT /v2/bank_slip/account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /occurrence_batches
MÉTODO GET

### 路径参数

| 字段                    | 类型   | 描述                                   | 字符数 |
|------------------------|--------|----------------------------------------|--------|
| `account_key`           | uuidv4 | 账户唯一识别密钥，格式为 uuid v4        | 36     |
| `requester_profile_key` | uuidv4 | 钱包唯一识别密钥，格式为 uuid v4        | 36     |

### Query Parameters

| 字段              | 类型    | 描述                                                                                  |
|-------------------|---------|---------------------------------------------------------------------------------------|
| `page`            | integer | 查询页码（默认 `1`）                                                                  |
| `page_size`       | integer | 每页批次数量（默认 `20`，最大 `100`）                                                  |
| `occurrence_type` | string  | 按指令类型筛选。可使用与创建 POST 相同的枚举                                          |
| `from_date`       | string  | 起始日期（含），格式 `YYYY-MM-DD`，对批次的 `created_at` 进行筛选                      |
| `to_date`         | string  | 结束日期（含），格式 `YYYY-MM-DD`，对批次的 `created_at` 进行筛选                      |

## 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

| 字段                              | 类型    | 描述                                                                  |
|-----------------------------------|---------|-----------------------------------------------------------------------|
| `data` *                          | array   | 当前页的批次列表                                                       |
| `data[].batch_key` *              | uuidv4  | 批次密钥                                                               |
| `data[].request_control_key` *    | string  | 创建批次时客户提供的控制密钥                                            |
| `data[].requester_profile_key` *  | uuidv4  | 持有该批次的钱包密钥                                                    |
| `data[].occurrence_type` *        | string  | 批次的指令类型                                                          |
| `data[].occurrence_quantity` *    | integer | 批次中发送的总项目数                                                    |
| `data[].accepted_quantity` *      | integer | 批次中被接受的项目数                                                    |
| `data[].created_at` *             | string  | 批次的 UTC 创建时间（ISO 8601，含 `Z` 后缀）                            |
| `pagination` *                    | object  | 分页元数据                                                              |
| `pagination.page` *               | integer | 当前页                                                                  |
| `pagination.page_size` *          | integer | 每页大小                                                                |
| `pagination.total` *              | integer | 符合筛选条件的批次总数                                                  |

### Error Response

STATUS 4xx

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title` | 描述（英）<br/>`description` | 描述（葡）<br/>`translation` |
|------------------------|--------------------|--------------------|------------------------------|------------------------------|
| 400                    | QIT000001          | Bad Request        | Schema Error                 | Schema Inválido              |
| 404                    | BKS000013          | Not Found          | Requester profile not found  | Carteira não encontrada      |

---

# 罚款

URL: /zh-Hans/documentation/boletos/instrucoes/multa

罚款指令用于配置在截止日期后付款时应收取的罚款。若相关 Boleto 已存在罚款配置，且罚款指令被接受，则原有配置将被覆盖。

:::caution 注意！
若存在待确认的罚款指令，则不允许发送新的指令。 
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /fine
MÉTODO POST

### 路径参数

| 字段                    | 类型   | 描述                                   | 字符数 |
|------------------------|--------|----------------------------------------|--------|
| `account_key`           | uuidv4 | 账户唯一识别密钥，格式为 uuid v4        | 36     |
| `requester_profile_key` | uuidv4 | 钱包唯一识别密钥，格式为 uuid v4        | 36     |
| `bank_slip_key`         | uuidv4 | Boleto 唯一识别密钥，格式为 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

| 字段                      | 类型   | 描述                                           | 字符数                                                          |
|--------------------------|--------|------------------------------------------------|----------------------------------------------------------------|
| `request_control_key` *  | uuidv4 | 客户使用的请求唯一识别密钥，格式为 uuid v4      | 36                                                             |
| `interest_data`          | object | 罚款配置                                       | **[fine_data 对象](#objeto-fine_data)**                        |

### fine_data 对象

选项 1：绝对值罚款（`fine_type=absolute`）

| 字段              | 类型    | 描述                                        | 字符数                                                          |
|------------------|---------|---------------------------------------------|----------------------------------------------------------------|
| `fine_type` *    | string  | 罚款类型                                    | **[fine_type 枚举值](#enumeradores-fine_type)**                |
| `fine_amount` *  | float   | 罚款绝对值                                  | -                                                              |
| `days_to_fine` * | integer | 到期后开始收取罚款所需天数                   | -                                                              |

选项 2：百分比罚款（`fine_type=percentage`）

| 字段                | 类型    | 描述                                   | 字符数                                                          |
|--------------------|---------|----------------------------------------|----------------------------------------------------------------|
| `fine_type` *      | string  | 罚款类型                               | **[fine_type 枚举值](#enumeradores-fine_type)**                |
| `fine_percentage` * | integer | 罚款百分比，1 到 100                   | -                                                              |
| `days_to_fine` *   | integer | 到期后开始收取罚款所需天数              | -                                                              |

### fine_type 枚举值

| 枚举值     | 描述       |
|-----------|------------|
| absolute  | 绝对值     |
| percentage | 百分比    |

## Response

STATUS 202

Response Body

```json
{
  "occurrence_key": "aaf64135-6bd8-4d49-be6f-e8f884b20ee7",
  "bank_slip_key": "470cfcae-159b-4de4-ad22-2d3b2dd717f7"
}
```

### Response Body Params

| 字段               | 类型   | 描述                                           | 字符数 |
|-----------------|--------|------------------------------------------------|--------|
| `occurrence_key` * | uuidv4 | 事件（指令）唯一识别密钥，格式为 uuid v4        | 36     |
| `bank_slip_key` *  | uuidv4 | Boleto 唯一识别密钥，格式为 uuid v4             | 36     |

### 错误响应

STATUS 4xx

Response Body: 错误

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title` | 英文描述<br/>`description` | 葡语描述<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 | 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. |

---

# 部分付款

URL: /zh-Hans/documentation/boletos/instrucoes/pagamento_parcial

部分付款指令允许修改票据的部分付款配置，前提是票据已登记且启用了部分付款功能。若票据已有部分付款配置，接受新指令后，原有配置将被覆盖。

:::caution 注意！
若存在待确认的部分付款指令，则不允许发送新的指令。
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /partial_payment
MÉTODO POST

### Path parameters

| 字段                    | 类型   | 描述                                                  | 字符数 |
|-------------------------|--------|-------------------------------------------------------|--------|
| `account_key`           | uuidv4 | 账户唯一标识键，uuid v4 格式                          | 36     |
| `requester_profile_key` | uuidv4 | 钱包唯一标识键，uuid v4 格式                          | 36     |
| `bank_slip_key`         | uuidv4 | 票据唯一标识键，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

| 字段                      | 类型    | 描述                                                                         | 字符数 |
|---------------------------|---------|------------------------------------------------------------------------------|--------|
| `request_control_key` *   | uuidv4  | 客户使用的请求唯一标识键，uuid v4 格式                                       | 36     |
| `partial_payment_data` *  | object  | 部分付款配置                                                                 | **[Objeto partial_payment_data](#objeto-partial_payment_data)** |

### Objeto partial_payment_data

| 字段                                    | 类型    | 描述                                          | 字符数 |
|-----------------------------------------|---------|-----------------------------------------------|--------|
| `partial_payment_minimum_type` *        | string  | 部分付款最小金额类型                          | **[Enumeradores partial_payment_type](#enumeradores-partial_payment_type)** |
| `partial_payment_minimum_percentage`    | float   | 部分付款允许的最小百分比                      | -      |
| `partial_payment_minimum_amount`        | float   | 部分付款允许的最小金额                        | -      |
| `partial_payment_maximum_type`          | string  | 部分付款最大金额类型                          | **[Enumeradores partial_payment_type](#enumeradores-partial_payment_type)** |
| `partial_payment_maximum_percentage`    | float   | 部分付款允许的最大百分比                      | -      |
| `partial_payment_maximum_amount`        | float   | 部分付款允许的最大金额                        | -      |
| `partial_payment_quantity` *            | integer | 允许的部分付款次数                            | -      |

:::caution 注意！
根据 `partial_payment_minimum_type` 和 `partial_payment_maximum_type` 字段的值，需要相应发送 `partial_payment_minimum_amount` 或 `partial_payment_minimum_percentage`，以及 `partial_payment_maximum_amount` 或 `partial_payment_maximum_percentage`。
:::

### Enumeradores partial_payment_type

| 枚举值      | 描述     |
|-------------|----------|
| absolute    | 绝对值   |
| percentage  | 百分比   |

## Response

STATUS 202

Response Body

```json
{
  "occurrence_key": "5a745b65-9a2c-44eb-b43e-c80ef5429d94",
  "bank_slip_key": "fdafdffa-cbd4-4f3c-8e3d-990428305161"
}
```

### Response Body Params

| 字段               | 类型   | 描述                                                | 字符数 |
|--------------------|--------|-----------------------------------------------------|--------|
| `occurrence_key` * | uuidv4 | 记录（指令）唯一标识键，uuid v4 格式                | 36     |
| `bank_slip_key` *  | uuidv4 | 票据唯一标识键，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": {}
}
```

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                   | 描述（英文）<br/>`description`                                                                                          | 描述（葡文）<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.                          |

---

# 查询抗议工具文件

URL: /zh-Hans/documentation/boletos/instrucoes/protesto/consulta_instrumento_de_protesto

抗议工具文件是公证处在抗议执行过程中发出的官方文件，用于证明催收程序已执行。该文件在抗议完成后发出，前提是债务人在被通知后未支付债务。

:::caution 注意！
只有在票据**被实际抗议**（`protest_status` 值为 `protested`）之后，才能查询抗议工具文件。
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /protest_instrument
MÉTODO GET

### Path parameters

| 字段                    | 类型   | 描述                                                  | 字符数 |
|-------------------------|--------|-------------------------------------------------------|--------|
| `account_key`           | uuidv4 | 账户唯一标识键，uuid v4 格式                          | 36     |
| `requester_profile_key` | uuidv4 | 钱包唯一标识键，uuid v4 格式                          | 36     |
| `bank_slip_key`         | uuidv4 | 票据唯一标识键，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

| 字段               | 类型    | 描述                                                | 字符数 |
|--------------------|---------|-----------------------------------------------------|--------|
| `bank_slip_key` *  | uuidv4  | 票据唯一标识键，uuid v4 格式                        | 36     |
| `file_url` *       | string  | 包含抗议工具文件（PDF）的文件 URL                   | -      |

## Error Response

STATUS 4xx

Response Body: Error

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

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                   | 描述（英文）<br/>`description`                                                                                          | 描述（葡文）<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. |

---

# 通过键查询抗议

URL: /zh-Hans/documentation/boletos/instrucoes/protesto/consulta_por_chave

通过键查询抗议，可返回有关该抗议的详细信息。

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /protest/ BANK_SLIP_KEY
MÉTODO GET

### Path parameters

| 字段                    | 类型   | 描述                                                  | 字符数 |
|-------------------------|--------|-------------------------------------------------------|--------|
| `account_key`           | uuidv4 | 账户唯一标识键，uuid v4 格式                          | 36     |
| `requester_profile_key` | uuidv4 | 钱包唯一标识键，uuid v4 格式                          | 36     |
| `bank_slip_key`         | uuidv4 | 票据唯一标识键，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": {
    "city": "VITORIA",
    "uf": "ES"
  }
}
```

### Response Body Params

| 字段                       | 类型    | 描述                                                                         | 字符数 |
|----------------------------|---------|------------------------------------------------------------------------------|--------------------------------------------------|
| `protest_key` *            | uuidv4  | 抗议唯一标识键，uuid v4 格式                                                 | 36                                                |
| `request_control_key` *    | uuidv4  | 客户使用的请求唯一标识键，uuid v4 格式                                       | 36                                                |
| `protest_status` *         | string  | 抗议状态 | **[Enumeradores protest_status](#enumeradores-protest_status)** |
| `bank_slip_key` *          | uuidv4  | 票据唯一标识键，uuid v4 格式                                                 | 36                                                |
| `requester_profile_code` * | string  | 钱包唯一识别码                                                               | 10                                                |
| `protest_type` *           | string  | 抗议类型 | **[Enumeradores protest_type](#enumeradores-protest_type)** |
| `protocol_number`          | string  | 协议号码                                                                     | 10                                                |
| `protocol_date`            | string  | 协议日期（格式"YYYY-MM-DD"）                                                 | 10                                                |
| `notary_office`            | object  | 公证处数据 | **[Objeto notary_office](#objeto-notary_office)** |

### Enumeradores protest_status

| 枚举值                       | 描述                                                     |
|------------------------------|----------------------------------------------------------|
| accepted                     | 已接受，但尚未发送至公证处                               |
| submitted                    | 已发送至公证处                                           |
| cancellation_requested       | 已申请中止抗议                                           |
| cancelled                    | 发送已取消，或抗议已中止                                 |
| rejected                     | 抗议申请被拒绝                                           |
| at_notary_office             | 在公证处，处于三日期间                                   |
| paid_at_notary_office        | 票据已在公证处支付                                       |
| protested                    | 票据已被抗议并核销                                       |
| removal_requested            | 票据已被抗议，已申请取消                                 |
| removed                      | 抗议已取消                                               |

### Enumeradores protest_type

| 枚举值               | 描述         |
|----------------------|--------------|
| protest              | 普通抗议     |
| bankruptcy_protest   | 破产抗议     |

### Objeto notary_office

| 字段      | 类型   | 描述                 | 字符数 |
|-----------|--------|----------------------|--------|
| `city` *  | string | 公证处所在城市       | -      |
| `uf` *    | string | 公证处所在州（UF）   | 2      |

## Error Response

STATUS 4xx

Response Body: Error

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

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                   | 描述（英文）<br/>`description`                                                                                          | 描述（葡文）<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. |

---

# 撤回（中止）抗议

URL: /zh-Hans/documentation/boletos/instrucoes/protesto/desistencia_de_protesto

可以通过发送 `protest_cancel_request` 指令来撤回抗议申请。

:::caution 注意！
`protest_cancel_request` 记录本身不会核销票据。若公证处的退出由 `protest_cancel_request` 类型的记录触发，则会创建一条 `notary_office_exit` 记录，该记录会发送至 CIP/Nuclea 以解除票据的支付冻结。确认后，票据可再次通过可输入行进行支付。若希望在撤回抗议后同时核销票据，建议发送[**撤回抗议并核销票据**](/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

| 字段                    | 类型   | 描述                                                  | 字符数 |
|-------------------------|--------|-------------------------------------------------------|--------|
| `account_key`           | uuidv4 | 账户唯一标识键，uuid v4 格式                          | 36     |
| `requester_profile_key` | uuidv4 | 钱包唯一标识键，uuid v4 格式                          | 36     |
| `bank_slip_key`         | uuidv4 | 票据唯一标识键，uuid v4 格式                          | 36     |

Request Body

```json
{
  "request_control_key": "614a451d-3b82-460e-bcc0-2caf3dde711f"
}
```

### Request Body Params

| 字段                      | 类型    | 描述                                                                         | 字符数 |
|---------------------------|---------|------------------------------------------------------------------------------|--------|
| `request_control_key` *   | uuidv4  | 客户使用的请求唯一标识键，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

| 字段               | 类型   | 描述                                                | 字符数 |
|--------------------|--------|-----------------------------------------------------|--------|
| `occurrence_key` * | uuidv4 | 记录（指令）唯一标识键，uuid v4 格式                | 36     |
| `bank_slip_key` *  | uuidv4 | 票据唯一标识键，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": {}
}
```

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                   | 描述（英文）<br/>`description`                                                                                          | 描述（葡文）<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. |

---

# 撤回（中止）抗议并核销票据

URL: /zh-Hans/documentation/boletos/instrucoes/protesto/desistencia_de_protesto_e_baixa_do_boleto

撤回抗议申请的另一种方式是发送 `protest_cancel_and_write_off_request` 指令。

:::caution 注意！
`protest_cancel_and_write_off_request` 指令还会在 CIP/Nuclea 中核销票据。确认后，将自动创建 `write_off` 记录并发送至 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

| 字段                    | 类型   | 描述                                                  | 字符数 |
|-------------------------|--------|-------------------------------------------------------|--------|
| `account_key`           | uuidv4 | 账户唯一标识键，uuid v4 格式                          | 36     |
| `requester_profile_key` | uuidv4 | 钱包唯一标识键，uuid v4 格式                          | 36     |
| `bank_slip_key`         | uuidv4 | 票据唯一标识键，uuid v4 格式                          | 36     |

Request Body

```json
{
  "request_control_key": "614a451d-3b82-460e-bcc0-2caf3dde711f"
}
```

### Request Body Params

| 字段                      | 类型    | 描述                                                                         | 字符数 |
|---------------------------|---------|------------------------------------------------------------------------------|--------|
| `request_control_key` *   | uuidv4  | 客户使用的请求唯一标识键，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

| 字段               | 类型   | 描述                                                | 字符数 |
|--------------------|--------|-----------------------------------------------------|--------|
| `occurrence_key` * | uuidv4 | 记录（指令）唯一标识键，uuid v4 格式                | 36     |
| `bank_slip_key` *  | uuidv4 | 票据唯一标识键，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": {}
}
```

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                   | 描述（英文）<br/>`description`                                                                                          | 描述（葡文）<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. |

---

# 简介

URL: /zh-Hans/documentation/boletos/instrucoes/protesto/introducao

## 公证处抗议

公证处抗议申请可在票据到期日之后提出，用于要求付款人在公证处偿还票款。若付款人未履行，将在其名下进行公开的违约登记，并将其姓名列入 Serasa 等信用保护机构。

## 抗议流程

### 抗议申请

票据的抗议流程始于一次**抗议申请**：类型为 `protest_request` 的指令。一旦 CIP/Nuclea 接受了抗议申请（`protest_request` 指令得到确认），票据将被冻结支付，这意味着付款人只能在公证处进行支付。同时，还会创建一条 `notary_office_entry` 记录，用于将抗议申请发送至公证处。抗议申请的汇款每天上午 9 点发送至公证处，因此，若在该时间之后收到抗议申请指令，则将在次日发送至公证处。

在随后的几天内，公证处需确认票据已进入公证处（`notary_office_entry` 记录得到确认），随后进入三日期间。三日期间是付款人在公证处支付票款的 3 个工作日期限，若未能支付，票据将被抗议。若票据在公证处支付，则会为该票据创建 `notary_office_payment_notice` 类型的记录，并在次日完成清算。在后一种情况下，还会自动生成 `payment_write_off` 指令，以便在 CIP/Nuclea 核销票据。

若三日期间结束，票据未被支付且未申请撤回抗议，票据将被抗议。此时，将生成 `protest_write_off` 指令，在 CIP/Nuclea 中核销票据，票据的生命周期随之结束。

### 撤回（中止）抗议申请

若付款人与背书人之间的纠纷在票据被实际抗议之前（即三日期间最后一天之前）直接解决，可以发送 `protest_cancel_request` 指令撤回抗议申请；或发送 `protest_cancel_and_write_off_request` 指令，同时撤回抗议申请并在 CIP/Nuclea 中核销票据。值得注意的是，`protest_cancel_request` 记录本身不会核销票据。若公证处的退出由 `protest_cancel_request` 类型的记录触发，则会创建一条 `notary_office_exit` 记录，该记录会发送至 CIP/Nuclea 以解除票据的支付冻结。确认后，票据可再次通过可输入行进行支付。另一方面，若公证处的退出由 `protest_cancel_and_write_off_request` 类型的记录触发，则会自动创建 `write_off` 记录，在 CIP/Nuclea 中核销票据。

### 撤销（取消）抗议申请

若票据已被抗议后，付款人与背书人之间的纠纷才得以解决，可以发送 `protest_remove_request` 类型的指令，该指令会撤销公开的违约登记以及与该票据相关的一切损害付款人名誉的记录。若记录得到确认（被公证处接受），抗议将被撤销，且由于票据已在 CIP/Nuclea 中核销，不会再为该票据创建任何其他指令。

---

# 列出抗议

URL: /zh-Hans/documentation/boletos/instrucoes/protesto/listar_protestos

抗议列表将返回符合请求中发送的 查询参数 的所有钱包票据公证处抗议记录。

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /protests
MÉTODO GET

### Path parameters

| 字段                    | 类型   | 描述                                                  | 字符数 |
|-------------------------|--------|-------------------------------------------------------|--------|
| `account_key`           | uuidv4 | 账户唯一标识键，uuid v4 格式                          | 36     |
| `requester_profile_key` | uuidv4 | 钱包唯一标识键，uuid v4 格式                          | 36     |

### Query parameters

| 字段                    | 类型    | 描述                                                   | 字符数                   |
|-------------------------|---------|--------------------------------------------------------|--------------------------|
| `protest_key`           | uuidv4  | 抗议唯一标识键，uuid v4 格式                           | 36                       |
| `request_control_key`   | uuidv4  | 请求唯一标识键，uuid v4 格式                           | 36                       |
| `protest_status`        | string  | 抗议状态 | **[Enumeradores protest_status](#enumeradores-protest_status)** |
| `bank_slip_key`         | uuidv4  | 票据唯一标识键，uuid v4 格式                           | 36                       |
| `protocol_number`       | string  | 协议号码                                               | 36                       |
| `protocol_date`         | string  | 协议日期（格式"YYYY-MM-DD"）                           | 10                       |
| `page_size`             | integer | 每页大小                                               | -                        |
| `from_date`             | string  | 起始日期（格式"YYYY-MM-DD"）                           | 10                       |
| `to_date`               | string  | 结束日期（格式"YYYY-MM-DD"）                           | 10                       |

### Enumeradores protest_status

| 枚举值                       | 描述                                                     |
|------------------------------|----------------------------------------------------------|
| accepted                     | 已接受，但尚未发送至公证处                               |
| submitted                    | 已发送至公证处                                           |
| cancellation_requested       | 已申请中止抗议                                           |
| cancelled                    | 发送已取消，或抗议已中止                                 |
| rejected                     | 抗议申请被拒绝                                           |
| at_notary_office             | 在公证处，处于三日期间                                   |
| paid_at_notary_office        | 票据已在公证处支付                                       |
| protested                    | 票据已被抗议并核销                                       |
| removal_requested            | 票据已被抗议，已申请取消                                 |
| removed                      | 抗议已取消                                               |

## 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

| 字段             | 类型         | 描述               | 字符数                                      |
|------------------|--------------|--------------------|--------------------------------------------|
| `data` *         | object array | 抗议列表           | **[Objeto protest](#objeto-protest)**      |
| `pagination` *   | object       | 分页信息           | **[Objeto pagination](#objeto-pagination)**|

### Objeto protest

| 字段                       | 类型    | 描述                                                                         | 字符数 |
|----------------------------|---------|------------------------------------------------------------------------------|--------------------------------------------------|
| `protest_key` *            | uuidv4  | 抗议唯一标识键，uuid v4 格式                                                 | 36                                                |
| `request_control_key` *    | uuidv4  | 客户使用的请求唯一标识键，uuid v4 格式                                       | 36                                                |
| `protest_status` *         | string  | 抗议状态 | **[Enumeradores protest_status](#enumeradores-protest_status)** |
| `bank_slip_key` *          | uuidv4  | 票据唯一标识键，uuid v4 格式                                                 | 36                                                |
| `requester_profile_code` * | string  | 钱包唯一识别码                                                               | 10                                                |
| `protest_type` *           | string  | 抗议类型 | **[Enumeradores protest_type](#enumeradores-protest_type)** |
| `protocol_number`          | string  | 协议号码                                                                     | 10                                                |
| `protocol_date`            | string  | 协议日期（格式"YYYY-MM-DD"）                                                 | 10                                                |
| `notary_office`            | object  | 公证处数据 | **[Objeto notary_office](#objeto-notary_office)** |

### Objeto pagination

| 字段                       | 类型    | 描述       | 字符数 |
|----------------------------|---------|------------|--------------------------------------------------------------|
| `current_page` *           | integer | 当前页码   | -      |
| `rows_per_page` *          | integer | 每页记录数 | -      |

### Enumeradores protest_type

| 枚举值               | 描述         |
|----------------------|--------------|
| protest              | 普通抗议     |
| bankruptcy_protest   | 破产抗议     |

### Enumeradores protest_status

| 枚举值                       | 描述                                                     |
|------------------------------|----------------------------------------------------------|
| accepted                     | 已接受，但尚未发送至公证处                               |
| submitted                    | 已发送至公证处                                           |
| cancellation_requested       | 已申请中止抗议                                           |
| cancelled                    | 发送已取消，或抗议已中止                                 |
| rejected                     | 抗议申请被拒绝                                           |
| at_notary_office             | 在公证处，处于三日期间                                   |
| paid_at_notary_office        | 票据已在公证处支付                                       |
| protested                    | 票据已被抗议并核销                                       |
| removal_requested            | 票据已被抗议，已申请取消                                 |
| removed                      | 抗议已取消                                               |

### Objeto notary_office

| 字段      | 类型   | 描述                 | 字符数 |
|-----------|--------|----------------------|--------|
| `city` *  | string | 公证处所在城市       | -      |
| `uf` *    | string | 公证处所在州（UF）   | 2      |

## Error Response

STATUS 4xx

Response Body: Error

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

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                   | 描述（英文）<br/>`description`                                                                                          | 描述（葡文）<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                                                                 |

---

# 抗议申请

URL: /zh-Hans/documentation/boletos/instrucoes/protesto/pedido_de_protesto

公证处抗议申请可在票据到期日之后提出，用于要求付款人在公证处偿还票款。若付款人未履行，将在其名下进行公开的违约登记，并将其姓名列入 Serasa 等信用保护机构。

:::caution 注意！
发送抗议申请时，票据中必须包含付款人的地址。 若地址不存在，可发送票据编辑指令进行补充。此外，若票据已处于抗议流程中，则不允许发送新的抗议申请。
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /protest_request
MÉTODO POST

### Path parameters

| 字段                    | 类型   | 描述                                                  | 字符数 |
|-------------------------|--------|-------------------------------------------------------|--------|
| `account_key`           | uuidv4 | 账户唯一标识键，uuid v4 格式                          | 36     |
| `requester_profile_key` | uuidv4 | 钱包唯一标识键，uuid v4 格式                          | 36     |
| `bank_slip_key`         | uuidv4 | 票据唯一标识键，uuid v4 格式                          | 36     |

Request Body

```json
{
  "request_control_key": "614a451d-3b82-460e-bcc0-2caf3dde711f",
  "protest_type": "protest"
}
```

### Request Body Params

| 字段                      | 类型    | 描述                                                                         | 字符数 |
|---------------------------|---------|------------------------------------------------------------------------------|--------|
| `request_control_key` *   | uuidv4  | 客户使用的请求唯一标识键，uuid v4 格式                                       | 36     |
| `protest_type` *          | string  | 抗议类型（普通或破产）                                                       | **[Enumeradores protest_type](#enumeradores-protest_type)** |

### Enumeradores protest_type

| 枚举值               | 描述         |
|----------------------|--------------|
| protest              | 普通抗议     |
| bankruptcy_protest   | 破产抗议     |

## Response

STATUS 202

Response Body

```json
{
  "occurrence_key": "2552bd64-950b-437e-a53a-a133ffea03d7",
  "bank_slip_key": "960f78d4-4426-4762-98da-3ce3713ae0a5"
}
```

### Response Body Params

| 字段               | 类型   | 描述                                                | 字符数 |
|--------------------|--------|-----------------------------------------------------|--------|
| `occurrence_key` * | uuidv4 | 记录（指令）唯一标识键，uuid v4 格式                | 36     |
| `bank_slip_key` *  | uuidv4 | 票据唯一标识键，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": {}
}
```

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                   | 描述（英文）<br/>`description`                                                                                          | 描述（葡文）<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.                          |

---

# 撤销抗议

URL: /zh-Hans/documentation/boletos/instrucoes/protesto/sustacao_de_protesto

如果付款人和出票人担保人之间的纠纷在票据已被抗议后得以解决，可以发送 `protest_remove_request` 类型的指令，该指令将删除公开的拖欠记录以及与该票据相关的任何损害付款人信誉的记录。

:::caution 注意！
如果该事件被确认（公证处接受），抗议将被撤销，并且不会为该票据创建更多指令，因为该票据已在 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

| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key` | uuidv4 | 账户的唯一标识键，格式为 uuid v4 | 36 |
| `requester_profile_key` | uuidv4 | 钱包的唯一标识键，格式为 uuid v4 | 36 |
| `bank_slip_key` | uuidv4 | 票据的唯一标识键，格式为 uuid v4 | 36 |

Request Body

```json
{
  "request_control_key": "614a451d-3b82-460e-bcc0-2caf3dde711f"
}
```

### Request Body Params

| 字段 | 类型 | 描述 | 字符数 |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuidv4 | 客户使用的请求唯一标识键，格式为 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

| 字段 | 类型 | 描述 | 字符数 |
|--------------------|--------|-----------------------------------------------------------------------------------|------------|
| `occurrence_key` * | uuidv4 | 事件（指令）的唯一标识键，格式为 uuid v4 | 36 |
| `bank_slip_key` * | uuidv4 | 票据的唯一标识键，格式为 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": {}
}
```

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title` | 描述 (eng)<br/>`description` | 描述 (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. |

---

# 信用分账更新

URL: /zh-Hans/documentation/boletos/instrucoes/rateio_de_credito

此接口用于更新已发行 Boleto 的**信用分账**（分账支付）规则。新规则将完全替换原有规则，并适用于该 Boleto 的下一次结算。

:::caution 注意！
- Boleto 必须处于 `registered` 状态且尚未支付。
- `beneficiary_settlement_percentage` 与 `split_payment_rules` 中各项百分比之和必须正好等于 **100**。
- 请求体将**完全替换**现有的所有分账规则（非增量更新）。
- 分账适用于 Boleto 的所有结算流程（SILOC、STR、公证处和 Pix QR Code），包括已生成 QR Code 的 Boleto——此时 QR Code 中的规则也会自动同步更新。
- 分账规则中的账户必须为开通状态并已在 QI Tech 注册（QI Tech 将根据所提供的 `document_number`、`account_number` 和 `account_digit` 进行查询）。
:::

## Request

ENDPOINT /v2/bank_slip/account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /split_payment
方法 PUT

### 路径参数

| 字段                    | 类型   | 描述                                       | 字符数     |
|-------------------------|--------|--------------------------------------------|------------|
| `account_key`           | uuidv4 | Boleto 所在账户的唯一标识密钥              | 36         |
| `requester_profile_key` | uuidv4 | 钱包的唯一标识密钥                         | 36         |
| `bank_slip_key`         | uuidv4 | Boleto 的唯一标识密钥                      | 36         |

请求体

```json
{
  "beneficiary_settlement_percentage": 70,
  "split_payment_rules": [
    {
      "percentage": 20,
      "document_number": "12345678901",
      "account_owner_name": "John Smith",
      "account_number": "1234567",
      "account_digit": "8"
    },
    {
      "percentage": 10,
      "document_number": "10987654321",
      "account_owner_name": "Mary Johnson",
      "account_number": "7654321",
      "account_digit": "0"
    }
  ]
}
```

### 请求体参数

| 字段                                    | 类型         | 描述                                                                                            | 字符数     |
|----------------------------------------|--------------|------------------------------------------------------------------------------------------------|------------|
| `beneficiary_settlement_percentage` *  | float        | 分配给 Boleto 受益人的结算金额百分比，取值范围 0 至 100                                         | -          |
| `beneficiary_max_amount`               | float        | 受益人在结算时可获得的最大金额。当付款金额超过此限额时，超出部分将全部分配给 `split_payment_rules` 数组中的第一条规则。取值大于 0 且不大于 Boleto 金额 | - |
| `split_payment_rules` *                | object array | 分账规则列表。最少 1 条，最多 10 条                                                              | **[split_payment_rule 对象](#objeto-split_payment_rule)** |

### split_payment_rule 对象

| 字段                    | 类型     | 描述                                                                                | 字符数     |
|-------------------------|----------|-------------------------------------------------------------------------------------|------------|
| `percentage` *          | float    | 分配给该账户的结算金额百分比，取值范围 0 至 100。当此规则专门用于接收 `beneficiary_max_amount` 之上的超出部分时，请使用 `0` | - |
| `document_number` *     | string   | 目标账户持有人的 CPF/CNPJ                                                           | 11 或 14   |
| `account_owner_name` *  | string   | 目标账户持有人姓名                                                                  | 100        |
| `account_number` *      | string   | 目标账户号                                                                          | 20         |
| `account_digit` *       | string   | 目标账户校验位                                                                      | 2          |

## 用例：将逾期利息和滞纳金导向单独账户

> **如何配置分账，使超出 Boleto 面值的利息和滞纳金被导向与受益人不同的账户？**

此场景常见于代第三方（学校、物业、市场平台等）发行 Boleto 的平台：Boleto 持有人始终应收取面值，而平台则在逾期付款时获得额外的利息/滞纳金。

通过 `beneficiary_max_amount` 与一条 `percentage = 0` 的分账规则配合实现：

```json
{
  "beneficiary_settlement_percentage": 100,
  "beneficiary_max_amount": 1000.00,
  "split_payment_rules": [
    {
      "percentage": 0,
      "document_number": "12345678000199",
      "account_owner_name": "收款平台",
      "account_number": "1234567",
      "account_digit": "8"
    }
  ]
}
```

**计算方式**（以 R$ 1.000,00 的 Boleto 为例）：

| 场景 | 已付金额 | 受益人收到 | 平台收到 |
|---|---|---|---|
| 按时付款 | R$ 1.000,00 | R$ 1.000,00 | R$ 0,00（不生成结算） |
| 逾期付款（含 R$ 100,00 利息/滞纳金） | R$ 1.100,00 | R$ 1.000,00 | R$ 100,00 |
| 部分逾期付款 | R$ 950,00 | R$ 950,00 | R$ 0,00 |

规则：受益人**最多**收到 `beneficiary_max_amount`；超过该限额的金额将全部分配给 `split_payment_rules` 中的**第一条**规则。

:::caution 注意！
- `beneficiary_max_amount` 必须大于 0 且不大于 Boleto 金额（`amount`）。
- 当任一规则的 `percentage = 0` 时，必须填写 `beneficiary_max_amount`。
- 每张 Boleto 仅允许 `split_payment_rules` 中**一条**规则的 `percentage = 0`（即超出部分的接收方）。
:::

## Response

状态码 204

响应体

```json
{}
```

## 错误响应

状态码 4xx

响应体：错误

```json
{
  "title": "标题",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "代码",
  "extra_fields": {}
}
```

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`          | 英文描述<br/>`description`                                                                   | 葡语描述<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.                                   |

---

# 金额

URL: /zh-Hans/documentation/boletos/instrucoes/valor

金额指令允许修改已登记票据的金额。若票据存在待确认的金额指令，则不允许发送新的指令。

:::caution 注意！
若存在待确认的金额指令，则不允许发送新的指令。
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /amount
MÉTODO POST

### Path parameters

| 字段                    | 类型   | 描述                                                  | 字符数 |
|-------------------------|--------|-------------------------------------------------------|--------|
| `account_key`           | uuidv4 | 账户唯一标识键，uuid v4 格式                          | 36     |
| `requester_profile_key` | uuidv4 | 钱包唯一标识键，uuid v4 格式                          | 36     |
| `bank_slip_key`         | uuidv4 | 票据唯一标识键，uuid v4 格式                          | 36     |

Request Body

```json
{
    "request_control_key": "01234567-89ab-cdef-0123-456789abcdef",
    "amount": 150.50
}
```

### Request Body Params

| 字段                      | 类型    | 描述                                                                         | 字符数 |
|---------------------------|---------|------------------------------------------------------------------------------|--------|
| `request_control_key` *   | uuidv4  | 客户使用的请求唯一标识键，uuid v4 格式                                       | 36     |
| `amount` *                | number  | 票据新金额（必须与当前金额不同）                                             | -      |

:::caution 注意！
金额必须与票据当前金额不同，且最多保留 2 位小数。
:::

## Response

STATUS 202

Response Body

```json
{
  "occurrence_key": "5a745b65-9a2c-44eb-b43e-c80ef5429d94",
  "bank_slip_key": "fdafdffa-cbd4-4f3c-8e3d-990428305161"
}
```

### Response Body Params

| 字段               | 类型   | 描述                                                | 字符数 |
|--------------------|--------|-----------------------------------------------------|--------|
| `occurrence_key` * | uuidv4 | 记录（指令）唯一标识键，uuid v4 格式                | 36     |
| `bank_slip_key` *  | uuidv4 | 票据唯一标识键，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": {}
}
```

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                   | 描述（英文）<br/>`description`                                                                                          | 描述（葡文）<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.                          |

---

# 简介

URL: /zh-Hans/documentation/boletos/introducao

## 银行票据（Boleto bancário）

银行票据通常与收款业务相关。其特点是可输入的数字行**不**以数字 8 开头。银行票据在银行同业清算所（CIP/Núclea）进行登记，可在巴西中央银行授权的金融机构和支付机构进行支付。

## 收款钱包（Carteira de cobrança）

首先需要说明的是，在本文档中，收款钱包称为 `requester_profile`。收款钱包必然关联到一个账户，并带有特定的默认配置（如利息、罚款、抗议等），用于银行票据的登记。一旦在创建或编辑收款钱包时设置了这些默认配置，每当用户登记票据时，若未发送某项配置，将使用该参数的默认配置。

:::info 示例
创建收款钱包时，用户为钱包设置了罚款配置：若付款人延迟付款 5 天或以上，将收取 R$10.00 的罚款。登记票据时，该配置可被覆盖；例如，可以选择收取 R$15.00 的罚款，甚至不收取任何罚款。但是，如果在登记票据时没有覆盖该配置，则采用钱包的默认配置（付款人延迟超过 5 天时收取 R$10.00 罚款）。
:::

可以为同一账户创建多个收款钱包，账户开设时会自动创建一个初始钱包（无任何默认配置）。创建多个收款钱包的可能性允许用户创建具有不同默认配置的钱包；而默认配置则简化了具有相同配置的多张票据的登记，因为在登记票据时无需每次都发送罚款、利息等配置。

## 票据状态机

票据在其生命周期中可能经历以下状态：

| 枚举值                        | 翻译                   | 描述                                                                     |
|-------------------------------|------------------------|--------------------------------------------------------------------------|
| accepted                      | 已接受                 | 票据已接受，等待 CIP/Núclea 确认                                         |
| rejected                      | 已拒绝                 | 票据登记请求未被接受                                                     |
| registered                    | 已登记                 | 票据已在 CIP/Núclea 登记                                                 |
| payment_blocked               | 已冻结支付             | 票据因进入抗议流程而在 CIP/Núclea 被冻结支付                             |
| written_off                   | 已核销                 | 票据已核销（不再可支付）                                                 |
| payment_notice                | 支付通知               | 票据已支付并核销，但尚未完成财务清算                                     |
| paid                          | 已支付                 | 票据已支付、核销并完成财务清算                                           |

### 状态转换

- `accepted` -> `rejected`：票据登记未被 CIP/Núclea 接受；
- `accepted` -> `registered`：票据登记被 CIP/Núclea 接受；
- `registered` -> `written_off`：票据未经支付被核销；
- `registered` -> `payment_notice`：票据已支付并核销，但尚未完成财务清算；
- `payment_notice` -> `paid`：支付后，票据完成财务清算；
- `registered` -> `payment_blocked`：票据支付被冻结，因抗议流程开始；
- `payment_blocked` -> `notary_office_payment_notice`：票据在公证处支付并核销，但尚未完成财务清算；
- `notary_office_payment_notice` -> `paid`：在公证处支付后，票据完成财务清算；
- `payment_blocked` -> `written_off`：票据已被抗议。

:::caution 注意
对于配置了部分付款的票据，状态转换方式有所不同。收到付款后，若另一家银行发送的是银行间部分核销，配置了部分付款的票据仍保持 `registered` 状态。您会正常收到 [payment notice](/documentation/boletos/webhooks/boleto) 和 [payment](/documentation/boletos/webhooks/boleto) 的 webhook 通知，但票据保持 `registered` 状态。只有当付款银行通过 CIP/Núclea 发送银行间全额核销时，票据才会转为 `payment_notice` 状态，随后转为 `paid` 状态。若希望在任何时候核销票据，或总金额已支付但另一家机构未发送银行间全额核销，您可以发送[核销指令](/documentation/boletos/instrucoes/baixa)。

对于**信用卡**类型（`credit_card`）的票据，请注意这些票据不会收到银行间全额核销。因此，客户始终有责任手动核销票据，否则票据将在最大支付日期（根据 `max_payment_days` 配置）后 D+7 自动核销。
:::

## 票据登记

### 通过 API

标准登记流程

若系统通过[**标准登记流程**](/documentation/boletos/emissao/emissao_boleto_unico_padrao)收到票据登记请求，且该请求被接受（即发送的信息无任何不一致），将返回状态为 `accepted` 的票据，但这并不意味着该票据会被实际登记。在将票据发送至 CIP/Núclea 并收到响应后，票据将转为 `rejected` 或 `accepted` 状态。

批量登记流程

批量发行票据以异步方式进行，若任何票据在验证中失败，则所有票据均不会被登记。当票据状态发生变化时，申请人将通过 [**webhook**](/documentation/boletos/v2/webhooks/boleto) 收到通知。更多详情请查阅[**完整文档**](/documentation/boletos/emissao/emissao_em_lote)。

即时登记流程

票据登记还有另一种选择：[**即时登记流程**](/documentation/boletos/emissao/emissao_boleto_unico_instantanea)。在该流程中，票据登记以同步方式处理，API 响应直接返回票据是否被接受或拒绝；即响应返回的票据已具有 `accepted` 或 `rejected` 状态。Núclea/CIP 关于票据登记的确认/拒绝时间包含在该端点的响应时间内。

### 通过汇款文件

通过文件请求登记票据与通过 API 登记的最终结果完全相同。区别在于，通过文件登记时，需要将文件处理时间计入票据登记的总时间。因此，通常比通过 API 登记耗时更长。

另一方面，通过文件登记时，可以一次性登记大量票据。

---

# 列出清算组

URL: /zh-Hans/documentation/boletos/liquidacao/listar_grupos_de_liquidacao

:::info 信息
在我们的系统中，清算组是协调交易与已清算票据的一种方式。该流程（清算）描述了将已支付票据的金额转移至应收款账户的过程。简而言之，每当 QI 收到票据已被其他银行支付（或对于已抗议的票据，由公证处支付）的信息时，就会为该特定票据创建一条清算记录。随后，会创建**清算组**，这些清算组表示按类型分组的清算批次。

此后，会为该清算组执行向客户账户的付款交易。该交易的 **transaction_key** 随后将保存用于对账，通过此方式您可以查看在某次特定交易中已清算的所有票据。例如，若您有五张各 R$ 5.00 的票据，其中一张通过公证处支付，一张通过 QR Code PIX 支付，另外三张由其他银行通过可输入行或条形码支付，则会为这些票据创建五条清算记录。随后，这些清算记录将被分为三个清算组：一个 R$ 15.00 的清算组包含三张通过可输入行或条形码支付的票据（对其执行一笔交易）；一个 R$ 5.00 的清算组包含通过 QR Code PIX 支付的票据；最后一个 R$ 5.00 的清算组包含通过公证处支付的票据。
:::

清算组列表将返回符合请求中发送的 查询参数 的所有账户清算组。

## Request

ENDPOINT /account/ ACCOUNT_KEY /bank_slip_settlement_groups
MÉTODO GET

### Path parameters

| 字段            | 类型   | 描述                     | 字符数 |
|-----------------|--------|--------------------------|--------|
| `account_key`   | uuidv4 | 账户唯一标识键           | 36     |

### Query parameters

| 字段                               | 类型    | 描述                                      | 字符数                   |
|------------------------------------|---------|-------------------------------------------|--------------------------|
| `bank_slip_settlement_group_key`   | uuidv4  | 清算组唯一标识键，uuid v4 格式            | 36                       |
| `transaction_key`                  | uuidv4  | 清算组交易唯一标识键，uuid v4 格式        | 36                       |
| `bank_slip_settlement_group_status`| string  | 清算组状态 | **[Enumeradores bank_slip_settlement_group_status](#enumeradores-bank_slip_settlement_group_status)** |
| `date_from`                        | string  | 起始日期，格式"YYYY-MM-DD"                |                          |
| `date_to`                          | string  | 结束日期，格式"YYYY-MM-DD"                |                          |
| `page`                             | integer | 页码                                      | -                        |
| `page_size`                        | integer | 每页大小                                  | -                        |

## 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

| 字段             | 类型         | 描述               | 字符数                                                                                             |
|------------------|--------------|--------------------|----------------------------------------------------------------------------------------------------|
| `data`           | object array | 票据               | **[Objeto bank_slip_settlement_group](#objeto-bank_slip_settlement_group)**                        |
| `pagination`     | object       | 分页信息           | **[Objeto pagination](#objeto-pagination)**                                                        |

### Objeto bank_slip_settlement_group

| 字段                                   | 类型    | 描述                        | 字符数 |
|----------------------------------------|---------|-----------------------------|--------------------------------------------------|
| `bank_slip_settlement_group_key`       | uuidv4  | 清算组唯一标识键，uuid v4 格式 | 36                                              |
| `account_key`                          | uuidv4  | 账户唯一标识键              | 36                                              |
| `transaction_key`                      | uuidv4  | 清算组交易唯一标识键，uuid v4 格式 | 36                                         |
| `amount`                               | float   | 已清算总金额                | -                                               |
| `bank_slip_settlement_group_type`      | string  | 清算组类型 | **[Enumeradores bank_slip_settlement_group_type](#enumeradores-bank_slip_settlement_group_type)** |
| `bank_slip_settlement_group_status`    | string  | 清算组状态 | **[Enumeradores bank_slip_settlement_group_status](#enumeradores-bank_slip_settlement_group_status)** |
| `bank_slip_settlement_quantity`        | integer | 清算组中的清算数量          | -                                               |

### Objeto pagination

| 字段                | 类型    | 描述       | 字符数 |
|---------------------|---------|------------|--------|
| `current_page`      | integer | 当前页码   | -      |
| `rows_per_page`     | integer | 每页记录数 | -      |

### Enumeradores bank_slip_settlement_group_type

| 枚举值         | 描述                                                              |
|----------------|-------------------------------------------------------------------|
| siloc          | 用于票据支付（票据金额小于 R$ 250.000）                           |
| qr_code        | 用于通过 QR Code 支付的票据                                       |
| str            | 用于大额票据支付（票据金额大于 R$ 250.000）                       |
| notary_office  | 用于通过公证处支付的票据                                          |
| split_payment  | 来自票据[**信用分账**](/documentation/boletos/instrucoes/rateio_de_credito)的接收方账户清算组 |

:::tip 含信用分账的 Boleto
当 Boleto 配置了[**信用分账**](/documentation/boletos/instrucoes/rateio_de_credito)时，每次支付会按接收方生成一个清算组：
- **Boleto 受益人账户**的清算组保持原始结算流程的类型（`siloc`、`qr_code`、`str` 或 `notary_office`）。
- **分账接收方账户**的清算组以 `split_payment` 类型创建。

每个相关账户（受益人和接收方）都可以使用各自的 `account_key` 调用此接口列出自己的清算组——这样接收方可以精确对账每张 Boleto 收到的金额。
:::

### Enumeradores bank_slip_settlement_group_status

| 枚举值    | 描述                                   |
|-----------|----------------------------------------|
| pending   | 清算组已创建，但交易尚未执行           |
| settled   | 清算组已创建，且交易已执行             |

## Error Response

STATUS 4xx

Response Body: Error

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

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                   | 描述（英文）<br/>`description`                                                                                          | 描述（葡文）<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. |

---

# 列出清算记录

URL: /zh-Hans/documentation/boletos/liquidacao/listar_liquidacoes

:::info 信息
在我们的系统中，**清算记录**描述了将已支付票据的金额转移至应收款账户的过程。简而言之，每当 QI 收到票据已被其他银行支付（或对于已抗议的票据，由公证处支付）的信息时，就会为该特定票据创建一条清算记录。随后，会创建清算组，清算记录始终与清算组关联，清算组代表按类型分组的清算批次。

此后，会为该清算组执行向客户账户的付款交易。该交易的 **transaction_key** 随后将保存用于对账，通过此方式您可以查看在某次特定交易中已清算的所有票据。例如，若您有五张各 R$ 5.00 的票据，其中一张通过公证处支付，一张通过 QR Code PIX 支付，另外三张由其他银行通过可输入行或条形码支付，则会为这些票据创建五条清算记录。随后，这些清算记录将被分为三个清算组：一个 R$ 15.00 的清算组包含三张通过可输入行或条形码支付的票据（对其执行一笔交易）；一个 R$ 5.00 的清算组包含通过 QR Code PIX 支付的票据；最后一个 R$ 5.00 的清算组包含通过公证处支付的票据。
:::

清算记录列表将返回请求中指定清算组的所有清算记录。

## Request

ENDPOINT /account/ ACCOUNT_KEY /bank_slip_settlement_group/ BANK_SLIP_SETTLEMENT_GROUP_KEY /bank_slip_settlements
MÉTODO GET

### Path parameters

| 字段                               | 类型   | 描述                          | 字符数 |
|------------------------------------|--------|-------------------------------|--------|
| `account_key`                      | uuidv4 | 账户唯一标识键                | 36     |
| `bank_slip_settlement_group_key`   | uuidv4 | 清算组唯一标识键              |        |

## 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

| 字段             | 类型         | 描述               | 字符数                                                                                    |
|------------------|--------------|--------------------|---------------------------------------------------------------------------------------------|
| `data`           | object array | 票据               | **[Objeto bank_slip_settlement](#objeto-bank_slip_settlement_group)**                        |
| `pagination`     | object       | 分页信息           | **[Objeto pagination](#objeto-pagination)**                                                  |

### Objeto bank_slip_settlement

| 字段               | 类型    | 描述                               | 字符数 |
|--------------------|---------|------------------------------------|--------|
| `settlement_key`   | uuidv4  | 清算记录唯一标识键                 | 36     |
| `account_key`      | uuidv4  | 账户唯一标识键                     | 36     |
| `amount`           | float   | 已清算金额                         | -      |
| `bank_slip_key`    | uuidv4  | 票据唯一标识键，uuid v4 格式       |        |
| `barcode`          | string  | 票据条形码                         |        |

### Objeto pagination

| 字段                | 类型    | 描述       | 字符数 |
|---------------------|---------|------------|--------|
| `current_page`      | integer | 当前页码   | -      |
| `rows_per_page`     | integer | 每页记录数 | -      |

## Error Response

STATUS 4xx

Response Body: Error

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

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                   | 描述（英文）<br/>`description`                                                                                          | 描述（葡文）<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. |

---

# 清算场景模拟

URL: /zh-Hans/documentation/boletos/liquidacao/simulacao_de_cenarios_de_liquidacao

本页面描述如何模拟外部代理执行的操作，以测试票据清算流程。这些模拟对于集成验证和测试非常有用。

:::info 信息
这些请求没有响应体（response body）。它们模拟外部操作，仅返回 HTTP 状态码。
:::

## 1 - 模拟付款通知

模拟票据的付款通知，将票据状态更改为 `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

| 字段                  | 类型    | 描述                                              | 最大字符数 |
|-----------------------|---------|---------------------------------------------------|------------|
| **bank_slip_key***    | string  | 票据唯一键                                        | 36         |
| **paid_amount**       | float   | 付款金额。若未提供，则使用票据原始金额            | -          |
| **payment_method**    | string  | 使用的付款方式                                    | -          |
| **payment_type**      | string  | 跨行付款类型                                      | -          |

### Enumeradores payment_method

| 枚举值          | 描述     |
|-----------------|----------|
| `cash`          | 现金     |
| `account_debit` | 账户借记 |
| `credit_card`   | 信用卡   |
| `check`         | 支票     |

### Enumeradores payment_type

| 枚举值              | 描述                 |
|---------------------|----------------------|
| `full_interbank`    | 跨行全额支付         |
| `partial_interbank` | 跨行部分支付         |

:::tip 行为说明
- 若未提供 `paid_amount`，将使用票据原始金额
- 若未提供 `payment_type`，则视为全额支付（`full_interbank`）
- 模拟将创建一条付款通知记录
- 模拟后，票据将移至 `payment_notice` 状态
- **重要**：对于 `partial_interbank`，票据状态不会改变。此选项用于模拟部分付款票据的场景，详见[简介](/documentation/boletos/introducao)
:::

## 2 - 模拟票据清算

模拟票据的付款和财务清算，将票据状态更改为 `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

| 字段                  | 类型    | 描述                                                | 最大字符数 |
|-----------------------|---------|-----------------------------------------------------|------------|
| **bank_slip_key***    | string  | 票据唯一键                                          | 36         |
| **paid_amount**       | float   | 清算付款金额。若未提供，则使用票据原始金额          | -          |
| **payment_method**    | string  | 使用的付款方式                                      | -          |

### Enumeradores payment_method

| 枚举值          | 描述     |
|-----------------|----------|
| `cash`          | 现金     |
| `account_debit` | 账户借记 |
| `credit_card`   | 信用卡   |
| `check`         | 支票     |

:::tip 行为说明
- 若未提供 `paid_amount`，将使用票据原始金额
- 模拟默认使用代码 65（支付）创建一条付款记录
- 模拟后，票据将移至 `paid` 状态
:::

---

# 批准票据付款

URL: /zh-Hans/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

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `operation_key` *| string  | 创建付款时返回的键（响应中的 key 参数） | uuid  | 
| `feedback` | string  | 批准或拒绝转账的布尔值："true" 或 "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\"}"
}
```

---

# 查询票据可输入行

URL: /zh-Hans/documentation/boletos/pagamento/consulta_linha_digitavel

## Request

ENDPOINT /bank_slip/payment
MÉTODO GET

### Query params

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `digitable_line` *| string | 票据可输入行 | 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ável fornecida deve conter somente números.",
  "extra_fields": {}
}
```

STATUS 400

Response Body

```json
{
  "code": "BLP000012",
  "title": "Bad Request",
  "http_status": 400,
  "description": "Missing mandatory parameter: digitable_line",
  "translation": "Parâmetro obrigatório 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
| 字段 | 类型 | 描述 | 字符数 |
| --- | -- |--------------------------------------------------------------------| --- |
|`barcode`| string | 票据条形码 | 44 |
|`beneficiary_bank_code`| string | 注册票据的银行代码 | 3 |
|`beneficiary_document_number`| string | 票据受益人（收款人）的 CPF/CNPJ，也是注册票据的账户持有人的 CPF/CNPJ | 14 |
|`beneficiary_legal_name`| string | 票据受益人（收款人）的姓名，也是注册票据的账户持有人姓名 | - |
|`beneficiary_person_type`| enum | 票据受益人（收款人）的法人性质，也是注册票据的账户持有人法人性质 | [Enumerador person_type](#enumeradores-person_type) |
|`calculated_internally`| boolean | 表示计算是否由 QI Tech 内部完成 | - |
|`calculation_date`| string | 票据罚款和利息计算的参考日期 | 10 |
|`calculation_model`| int | 票据罚款和利息计算使用的计算模型，由注册票据的银行提供 | [Códigos calculation_model](#codigos-calculation_model) |
|`digitable_line`| uuid | 票据可输入行 | 47 |
|`discount_amount`| string | 票据准时折扣金额 | - |
|`expiration_date`| string | 票据到期日 | 10 |
|`expired_as_of_payment_date`| boolean | 表示票据在计划付款日期时是否已到期（可忽略此字段） | 10 |
|`expired_as_of_today`| string | 表示票据今天是否已到期 | 10 | 
|`factual_expiration_date`| string | 票据到期的工作日。例如，若票据到期日为 `2023-12-16`，此字段将返回 `2023-12-18` | 10 |
|`fine_amount`| string | 票据计算的罚款金额 | - |
|`guarantor_document`| string | 票据背书人的 CPF/CNPJ | 14 |
|`guarantor_name`| string | 票据背书人的姓名 | - |
|`interest_amount`| string | 票据到期后计算的利息金额 | - |
|`max_payment_date`| string | 票据的最后付款日期 | 10 |
|`nominal_amount`| string | 票据原始金额 | - |
|`payer_document_number`| string | 票据付款人的 CPF/CNPJ | 14 |
|`payer_legal_name`| string | 票据付款人的姓名 | 14 |
|`payer_person_type`| enum | 票据付款人的法人性质 | [Enumerador person_type](#enumeradores-person_type) |
|`payment_date`| string | 票据付款日期 | 10 |
|`rebate_amount`| string | 票据的减免金额 | - |
|`total_amount`| string | 票据总金额（含利息、罚款、减免和折扣） | - |
|`valid_payment_amount`| boolean | 表示付款金额是否有效（始终为 `true`） | - |
|`valid_payment_calculation` | boolean | 表示注册票据的银行计算的金额是否有效（当 `calculation_model` 为 `2` 或 `3` 时） | - |
|`valid_payment_time_frame` | boolean | 表示计划付款日期是否早于票据最后付款日期 | - |

### Enumeradores person_type 
| 枚举值 | 描述 |
| --- | -- |
| `natural` | 自然人 |
| `legal` | 法人 |

### Códigos calculation_model
| 枚举值 | 描述 |
| --- | -- |
| 1 | 付款机构计算票据的罚款和利息值（如果注册票据中有提供，`calculated_internally` 将返回 `true`） |
| 2 | 注册票据的机构计算罚款和利息值，到期后每日在票据集中数据库中更新这些值 |
| 3 | 注册票据的机构计算票据金额，每日在票据集中数据库中更新票据金额 |

## 沙盒环境

### 协议/税务票据

协议/税务票据由政府机构（如市政府、州政府或联邦政府）发行，用于征收税款、费用、社会保险金、罚款及其他应缴政府款项。

在我们的沙盒环境中，我们提供模拟的可输入行用于成功支付模拟和错误场景测试。

### 成功场景

| 可输入行 |
|---|
| 828300000007411100972013905080001546763201900028 |
| 838000000009235700481007241345219112001474229880 |
| 848000000006308600802021201071261517689002201070 |
| 858200000015000000643025703477209504800448091020 |

### 错误场景

| 可输入行 | 错误代码 |
|---|---|
| 858500000037350000643217212883260006147448091022 | IPP000014 |

### 银行票据

银行票据（boleto bancário），也称 boleto 或 bloqueto，是巴西广泛用于支付商品或服务的凭证。通过票据，发行人或企业可以向付款人收取所欠款项。

在我们的沙盒环境中，我们提供模拟的可输入行用于成功支付模拟。

### 成功场景

| 可输入行 |
|---|
| 32990001039000210987502864982109595090000063958 |
| 32990001039000000006836762871105695090000010000 |
| 32990001031000699960099000000200195070000025527 |
| 32990001039000000000103194237800895060001000000 |
| 32990001031000699960095000000208497790000030990 |

---

# 执行票据付款

URL: /zh-Hans/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

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `digitable_line` *| string  | 票据可输入行 | 10 |
| `resource_account_key` *| string | 将要使用的账户键 | 10 |
| `payment_date` | date | 付款执行日期。若未发送，日期默认为今天 | 10 |

:::info 信息

若要查看已接受的付款协议，[请点击此处](https://storage.googleapis.com/live-doc-api/public_samples/active_covenants.xlsx)。

:::

### Response

STATUS 200

Response Body：通过自由账户付款

```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：通过托管账户付款

```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 - 付款超出受理时间

Response Body

```json
{
	"code": "BLP000024",
	"title": "Locked",
	"http_status": 423,
    "description": "Operation window closed. System available from {OPENING_TIME} to {CLOSING_TIME}",
    "translation": "Operação encerrada. Sistema disponível 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": {}
}
```

## 沙盒环境

### 协议/税务票据

协议/税务票据由政府机构（如市政府、州政府或联邦政府）发行，用于征收税款、费用、社会保险金、罚款及其他应缴政府款项。

在我们的沙盒环境中，我们提供模拟的可输入行用于成功支付模拟和错误场景测试。

#### 成功场景

| 可输入行 |
|---|
| 828300000007411100972013905080001546763201900028 |
| 838000000009235700481007241345219112001474229880 |
| 848000000006308600802021201071261517689002201070 |
| 858200000015000000643025703477209504800448091020 |

#### 错误场景

| 可输入行 | 错误代码 |
|---|---|
| 858900000034050002701002700011434710592720230733 | IPP000015 |
| 858400000000750002701007700011434710592720230733 | IPP000013 |
| 858800000040450004322322120716192390688090088931 | IPP000012 |
| 858900000000350004322326120716192390688090083760 | IPP000014 |

### 银行票据

银行票据（boleto bancário），也称 boleto 或 bloqueto，是巴西广泛用于支付商品或服务的凭证。通过票据，发行人或企业可以向付款人收取所欠款项。

在我们的沙盒环境中，我们提供模拟的可输入行用于成功支付模拟。

#### 成功场景

| 可输入行 |
|---|
| 32990001039000210987502864982109595090000063958 |
| 32990001039000000006836762871105695090000010000 |
| 32990001031000699960099000000200195070000025527 |
| 32990001039000000000103194237800895060001000000 |
| 32990001031000699960095000000208497790000030990 |

---

# 票据清算账户重定向

URL: /zh-Hans/documentation/boletos/redirecionamento_de_conta_de_liquidacao

该端点用于更改在 QI Tech 登记的票据的清算账户。

:::caution 注意！
  - 票据仍登记在原账户中，在该账户上有已登记票据时，原账户必须保持开放；
  - Webhooks 将继续发送至原账户的集成合作伙伴；
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /settlement_account
MÉTODO PATCH

### Path parameters

| 字段                    | 类型   | 描述                             | 字符数 |
|-------------------------|--------|----------------------------------|--------|
| `account_key`           | uuidv4 | 发行票据的账户唯一标识键         | 36     |
| `requester_profile_key` | uuidv4 | 钱包唯一标识键                   | 36     |
| `bank_slip_key`         | uuidv4 | 票据唯一标识键                   | 36     |

Request Body

```json
{
  "settlement_account_key": "614a451d-3b82-460e-bcc0-2caf3dde711f"
}
```

### Request Body Params

| 字段                       | 类型    | 描述                             | 字符数 |
|----------------------------|---------|----------------------------------|--------|
| `settlement_account_key` * | uuidv4  | 新清算账户的唯一标识键           | 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": {}
}
```

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`   | 描述（英文）<br/>`description`                                                                                          | 描述（葡文）<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.                                                                                              |

---

# 列出返回文件

URL: /zh-Hans/documentation/boletos/retorno/listar_arquivos_retorno

:::info
响应中提供的 URL 中的文件遵循 QI Tech 400 位返回文件布局标准。
以下是手册下载链接：[催收布局 - QI Tech 版本 2.1](https://storage.googleapis.com/live-doc-api/public_samples/Layout%20de%20Cobran%C3%A7a%20-%20QI%20Tech%20v2.1.pdf)
:::

返回文件用于对账。文件中，每行交易记录（类型 1）对应前一天 CIP/Nuclea 确认或拒绝的一条指令（无论是发行、延期、减免等类型）。

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /discharge_files
MÉTODO GET

### Path parameters

| 字段                    | 类型   | 描述                          | 字符数 |
|-------------------------|--------|-------------------------------|--------|
| `account_key`           | uuidv4 | 账户唯一标识键                | 36     |
| `requester_profile_key` | uuidv4 | 钱包唯一标识键，uuid v4 格式  | 36     |

### Query parameters

| 字段                    | 类型    | 描述                              | 字符数 |
|-------------------------|---------|-----------------------------------|--------|
| `discharge_file_key`    | uuidv4  | 返回文件唯一标识键，uuid v4 格式  | 36     |
| `page`                  | integer | 页码                              | -      |
| `page_size`             | integer | 每页大小                          | -      |
| `from_date`             | string  | 起始日期（格式"YYYY-MM-DD"）      | 10     |
| `to_date`               | string  | 结束日期（格式"YYYY-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

| 字段             | 类型         | 描述               | 字符数                                                                      |
|------------------|--------------|--------------------|---------------------------------------------------------------------------  |
| `data`           | object array | 返回文件           | **[Objeto discharge_file](#objeto-discharge_file)**                         |
| `pagination`     | object       | 分页信息           | **[Objeto pagination](#objeto-pagination)**                                 |

### Objeto discharge_file

| 字段                   | 类型    | 描述                                  | 字符数 |
|------------------------|---------|---------------------------------------|--------|
| `discharge_file_key`   | uuidv4  | 返回文件唯一标识键，uuid v4 格式      | 36     |
| `discharge_file_name`  | string  | 返回文件名称                          | -      |
| `discharge_file_url`   | string  | 返回文件 URL                          | -      |
| `reference_date`       | string  | 返回文件参考日期，格式 YYYY-MM-DD     | 10     |

### Objeto pagination

| 字段                | 类型    | 描述       | 字符数 |
|---------------------|---------|------------|--------|
| `current_page`      | integer | 当前页码   | -      |
| `rows_per_page`     | integer | 每页记录数 | -      |

## Error Response

STATUS 4xx

Response Body: Error

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

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                   | 描述（英文）<br/>`description`                                                                                          | 描述（葡文）<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.                                                                                 |

---

# 发行 bolePix

URL: /zh-Hans/documentation/boletos/v1/emissao/emissao_de_um_bolepix

:::caution 注意
在注册 bolePix 之前，需要在票据将要登记的账户中存在一个有效的随机 Pix 密钥。
:::

在 QI Tech，可以发行与 Pix QR Code 关联的票据。

通过这种方式，付款人可以通过已登记票据的可输入行或通过扫描与该票据关联的 Pix QR Code 来支付票据。

在付款人通过扫描 Pix QR Code 付款的情况下，付款的财务清算是即时的，银行回报以及有关此票据清算的 webhook 将以与普通票据相同的方式生成。

## 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

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `use_multi_process` | boolean | 指示登记指令的处理是发送至队列处理还是按顺序处理。若此参数值为 `true`，则在登记指令的 payload 中必须发送我们的银行编号 `our_number` | - | 

### Body params

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `occurrences` * | array of objects | 待处理的指令列表 | **[Objeto occurrences](#objeto-occurrences)** |

### Objeto occurrences

| 字段                                      | 类型             | 描述                                                                                                                                                    | 字符数                                          |
|-------------------------------------------|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------|
| `amount` *                                | double           | 票据金额                                                                                                                                                | -                                               |
| `automatic_bankruptcy_protest`            | boolean          | 自动抗议配置                                                                                                                                            | -                                               |
| `bank_teller_instructions`                | string           | 出纳指令（票据消息/备注）                                                                                                                               | -                                               |
| `beneficiary_account_key`                 | string           | 受益人账户键                                                                                                                                            | -                                               |
| `beneficiary_key`                         | string           | 受益人键                                                                                                                                                | -                                               |
| `days_to_bankruptcy_protest`              | int              | 自动发送破产抗议的天数                                                                                                                                  | -                                               |
| `document_number`                         | string           | 文件编号                                                                                                                                                | -                                               |
| `expiration` *                            | string           | 到期日                                                                                                                                                  | -                                               |
| `fine_percentage`                         | string           | 罚款百分比                                                                                                                                              | -                                               |
| `interest_daily_value`                    | string           | 每日利息金额（巴西雷亚尔）                                                                                                                              | -                                               |
| `occurrence_type` *                       | string           | 指令类型                                                                                                                                                | -                                               |
| `payer_address`                           | string           | 付款人地址                                                                                                                                              | -                                               |
| `payer_document` *                        | string           | 付款人文件（CPF 或 CNPJ）                                                                                                                               | -                                               |
| `payer_name` *                            | string           | 付款人姓名                                                                                                                                              | -                                               |
| `payer_person_type` *                     | string           | 付款人类型                                                                                                                                              | -                                               |
| `payer_postal_code_root`                  | string           | 邮政编码前五位                                                                                                                                          | -                                               |
| `payer_postal_code_suffix`                | string           | 邮政编码后三位                                                                                                                                          | -                                               |
| `printing_policy`                         | string           | 票据打印策略                                                                                                                                            | -                                               |
| `registration_institution_enumerator` *   | string           | 始终为 `qi_scd`                                                                                                                                         | `qi_scd`                                        |
| `requester_profile` *                     | string           | 钱包编号                                                                                                                                                | 02                                              |
| `requester_profile_code` *                | string           | 钱包代码，格式为："329-钱包-机构-7位账号"。注：QI Tech 默认催收钱包编号为"09" | -                                               |
| `notification`                            | object           | 钱包编号                                                                                                                                                | **[Objeto notification](#objeto-notification)** |  
| `discounts`                               | object           | 包含折扣信息的对象列表                                                                                                                                  | **[Objeto discounts](#objeto-discounts)**       |  
| `guarantor_name`                          | string           | 背书人姓名                                                                                                                                              | -                                               |
| `guarantor_document_root`                 | string           | 背书人 CNPJ 基础部分                                                                                                                                    | -                                               |
| `guarantor_document_subsidiary`           | string           | CNPJ 总部或分支机构信息                                                                                                                                 | -                                               |
| `guarantor_document_digit`                | string           | CNPJ 验证位                                                                                                                                             | -                                               |
| `pix_key` *                               | string           | 关联至 bolePix 的 Pix QR Code 将登记的 Pix 密钥                                                                                                         | 100                                             |

:::info 字段 "***pix_key***"
"***pix_key***" 可以是 **CPF**、**CNPJ**、**电子邮件**、**手机号码** 或 **随机密钥**（UUID），格式如下：

**CPF：** 11 位整数。

**CNPJ：** 14 位整数。

**电子邮件：** 包含至少一个"@"的文本。

**手机号码：** 包含以下值的文本："+55" + "手机 DDD 区号" + "至少 8 位最多 9 位的手机号码整数"。例如："+5511987654321"。

**随机密钥：** UUID。
:::

### Objeto notification
| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `document_number` * | string | 接收通知用户的文件编号 | - |
| `email` * | string | 接收通知用户的电子邮件 | - |
| `name` * | string | 接收通知用户的姓名 | - |
| `phone` * | object | 包含接收通知用户电话信息的对象 | **[Objeto phone](#objeto-phone)** |  
| `send_2_way` * | boolean | 发送补发通知 | true/false |  
| `send_after_due_date` * | boolean | 在票据到期后发送通知 | true/false |
| `send_before_due_date` * | boolean | 在票据到期前发送通知 | true/false |
| `send_on_protest` * | boolean | 发送抗议通知 | true/false|

### Objeto phone 

| 字段 | 类型 | 描述 | 最大字符数 | 
| --- | --- | --- | --- | 
|`country_code` | string | 电话国际区号 | 3 | 
| `area_code` | string | 电话地区区号 | 2 |
| `number` | string | 电话号码（仅数字） | 10 |

### Objeto discounts 
| 字段 | 类型 | 描述 | 字符数 | 
| --- | --- | --- | --- | 
|`discount_value` | float | 折扣金额 | - | 
| `discount_number` | int32 | 折扣应用顺序 | - |
| `discount_limit_date` | date | 折扣适用截止日期 | 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
| 字段 | 类型 | 描述 | 字符数 |
| --- | -- |--------------------------------------------------------------------| --- |
|`bank_slips` | list | 当 `use_multi_process` 参数值为 `false` 时，返回已登记票据的信息列表 | [Objeto Bank Slip](#objeto-bank_slip) | 
| `file_info` | list | 文件信息 | [Objeto File Info](#objeto-file-info) |
| `occurrence_stats` | object | 文件信息 | [Objeto File Info](#objeto-file-info) |
| `semantic_errors` | list | 每张票据处理过程中的错误列表。当处理中存在错误且 `use_multi_process` 参数值为 `false` 时返回 | [Objeto Semantic Error](#objeto-semantic-error) |

### Objeto bank_slip
| 字段 | 类型 | 描述 | 字符数 |
| --- | -- |--------------------------------------------------------------------| --- |
|`amount` | float | 票据金额 | - |
|`bank_slip_key` | uuid | QI Tech 票据唯一标识键 | 36 |
|`bank_slip_status` | enum | 票据状态 | [Enumeradores bank_slip_status](#enumeradores-bank_slip_status) |
|`barcode` | string | 票据条形码 | 44 |
|`beneficiary_account_key` | uuid | 登记票据的账户唯一标识键 | 36 |
|`beneficiary_key` | uuid | 受益人唯一标识键 | 36 |
|`digitable_line` | string | 票据可输入行 | 47 |
|`expiration` | string | 票据到期日 | 10 |
|`nfe_key` | string | 电子发票唯一标识键 | - |
|`nfe_url` | string | 电子发票 URL | - |
|`our_number` | int | 银行编号 | - |
|`participant_control_number` | string | 参与者控制编号 | 10 |
|`payer_postal_code` | string | 付款人邮政编码 | 8 |
|`protest_status` | string | 票据抗议状态 | [Enumeradores protest_status](#enumeradores-protest_status) |
|`qr_code` | object | 与票据关联的 Pix QR Code 信息 | [Objeto qr_code](#objeto-qr_code) |

### Objeto qr_code
| 字段 | 类型 | 描述 | 字符数 |
| --- | -- |--------------------------------------------------------------------| --- |
|`pix_key` | string | 关联至票据的 Pix QR Code 登记的 Pix 密钥 | 100 |
|`qr_code_key` | uuid | 关联至票据的 Pix QR Code 唯一标识键 | 36 |
|`qr_code_url` | string | 关联至票据的 Pix QR Code 的复制粘贴链接 URL | - |

### Enumeradores bank_slip_status
| 枚举值 | 描述 |
| --- | -- |
| `accepted` | 票据已接受处理 |
| `registered` | 票据登记已在票据登记所完成 |
| `paid` | 票据付款金额已贷记至受益人账户 |
| `written_off` | 票据已核销（不可再付款） |
| `rejected` | 票据登记被票据登记所拒绝 |
| `payment_notice` | 票据付款已在付款银行处理的通知（但受益人账户的清算尚未发生） |
| `notary_office_payment_notice` | 已抗议票据的付款已在付款银行处理的通知（但公证处尚未转账，受益人账户的清算尚未发生） |

### Enumeradores protest_status
| 枚举值 | 描述 |
| --- | -- |
| `not_protested` | 票据无抗议申请 |
| `protest_requested` | QI Tech 正在处理抗议申请 |
| `notary_office_entry` | 票据抗议申请已被公证处接受 |
| `protest_cancel_requested` | QI Tech 正在处理取消抗议申请 |
| `notary_office_exit` | 票据抗议已从公证处撤回 |
| `protested` | 公证处已确认抗议，票据处于抗议状态 |
| `paid_at_notary_office` | 公证处已识别票据抗议的付款，正在处理向 QI Tech 的付款转账 |
| `judicially_suspended` | 抗议已被司法暂停 |
| `protest_remove_requested` | 撤销抗议申请已被公证处接受 |

---

# 通过 CNAB 发行票据

URL: /zh-Hans/documentation/boletos/v1/emissao/emissao_via_cnab

通过 CNAB 发行票据，需要将 CNAB 文件发送至 `/multibank_cnab` 端点。

## 认证

需要使用 JWT 令牌进行认证，更多详情请查阅认证文档。

请注意，CNAB 端点的认证方式与其他端点不同：
- 请求的 Content-Type 应为 `multipart/form-data`
- 上传的文件应置于 `file` 字段中

## QI Tech 400 位 CNAB 布局

下方提供了 QI Tech 400 位 CNAB 布局供参考：

CNAB 400 位布局

**文件头部记录（Header de Arquivo）— 类型 0**

| 位置 | 长度 | 格式 | 描述 |
|------|------|------|------|
| 1 | 1 | N | 记录代码 = 0 |
| 2-3 | 2 | N | 记录类型 = 01 |
| 4-9 | 6 | N | 字面量（保留） |
| 10-10 | 1 | A | 服务类型标识符 |
| 11-26 | 16 | A | 字面量 |
| 27-46 | 20 | AN | 企业名称 |
| 47-76 | 30 | AN | 银行名称 |
| 77-79 | 3 | AN | 银行编号 |
| 80-94 | 15 | AN | 企业代码（账户标识） |
| 95-100 | 6 | N | 文件创建日期 (DDMMAA) |
| 101-394 | 294 | A | 保留字段（空格） |
| 395-400 | 6 | N | 顺序编号 |

**批次指令记录（Registro de Detalhe de Instrução）— 类型 1**

| 位置 | 长度 | 格式 | 描述 |
|------|------|------|------|
| 1 | 1 | N | 记录代码 = 1 |
| 2-21 | 20 | AN | 账户标识 |
| 22-22 | 1 | N | 税务标识类型 |
| 23-36 | 14 | N | 税务标识号码（CPF/CNPJ） |
| 37-62 | 26 | AN | 指令类型代码 |
| 63-70 | 8 | N | 到期日 (DDMMAAAA) |
| 71-83 | 13 | N | 金额（分） |
| 84-86 | 3 | N | 银行代码 |
| 87-91 | 5 | N | 机构（AGencia） |
| 92-92 | 1 | A | 机构验证位 |
| 93-102 | 10 | AN | 我们的号码 |
| 103-107 | 5 | N | 钱包号码 |
| 108-108 | 1 | N | 指令标识符 |
| 109-110 | 2 | N | 指令代码 1 |
| 111-122 | 12 | N | 指令日期/值 1 |
| 123-124 | 2 | N | 指令代码 2 |
| 125-136 | 12 | N | 指令日期/值 2 |
| 137-146 | 10 | N | 到期日（DDMMAAAA + 2 位） |
| 147-156 | 10 | AN | 账号 |
| 157-157 | 1 | AN | 账号验证位 |
| 158-162 | 5 | N | 我们的号码（NOSSO_NUMERO） |
| 163-173 | 11 | N | 金额（厘） |
| 174-175 | 2 | N | 指令代码 |
| 176-179 | 4 | N | 减免天数 |
| 180-192 | 13 | N | 减免金额（分） |
| 193-205 | 13 | N | 折扣金额（分） |
| 206-218 | 13 | N | 罚款金额（分） |
| 219-220 | 2 | N | 罚款代码 |
| 221-234 | 14 | N | 付款人 CPF/CNPJ |
| 235-274 | 40 | AN | 付款人姓名 |
| 275-314 | 40 | AN | 付款人地址 |
| 315-326 | 12 | AN | 付款人城市 |
| 327-328 | 2 | A | 付款人州 |
| 329-336 | 8 | N | 付款人邮政编码 |
| 337-394 | 58 | AN | 背书人/保证人姓名 |
| 395-400 | 6 | N | 顺序编号 |

## Request

ENDPOINT /multibank_cnab
MÉTODO POST

请求内容类型为 `multipart/form-data`，将 CNAB 文件放在 `file` 字段中上传。

## Response

STATUS 200

Response Body

```json
{
  "file_info": {
    "beneficiary_code": "329-01-0001-0000001",
    "beneficiary_name": "Greg Brown",
    "file_sequence_id": "00001",
    "file_type_identifier": "1",
    "file_type_literal": "REMESSA",
    "service_code": "01",
    "service_literal": "COBRANÇA",
    "wrote_at": "2020-05-15"
  },
  "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": []
}
```

---

# 通过 JSON 发行票据

URL: /zh-Hans/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 注意！
若未提供票据付款人的地址数据，则无法在未付款时对票据进行公证处抗议。
:::

### Query params

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `use_multi_process` | boolean | 指示登记指令的处理是发送至队列处理还是按顺序处理。若此参数值为 `true`，则在登记指令的 payload 中必须发送我们的银行编号 `our_number` | - | 

### Body params

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `occurrences` * | array of objects | 待处理的指令列表 | **[Objeto occurrences](#objeto-occurrences)** |

### Objeto occurrences

| 字段                                     | 类型             | 描述                                                                                                                                           | 字符数                                          |
|------------------------------------------|------------------|------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------|
| `amount` *                               | double           | 票据金额                                                                                                                                       | -                                               |
| `automatic_bankruptcy_protest`           | boolean          | 自动抗议配置                                                                                                                                   | -                                               |
| `bank_teller_instructions`               | string           | 出纳指令（票据消息/备注）                                                                                                                      | -                                               |
| `beneficiary_account_key`                | string           | 受益人账户键                                                                                                                                   | -                                               |
| `beneficiary_key`                        | string           | 受益人键                                                                                                                                       | -                                               |
| `days_to_bankruptcy_protest`             | int              | 自动发送破产抗议的天数                                                                                                                         | -                                               |
| `document_number`                        | string           | 文件编号                                                                                                                                       | -                                               |
| `expiration` *                           | string           | 到期日                                                                                                                                         | -                                               |
| `fine_percentage`                        | string           | 罚款百分比                                                                                                                                     | -                                               |
| `interest_daily_value`                   | string           | 每日利息金额（巴西雷亚尔）                                                                                                                     | -                                               |
| `occurrence_type` *                      | string           | 指令类型                                                                                                                                       | -                                               |
| `payer_address`                          | string           | 付款人地址                                                                                                                                     | -                                               |
| `payer_document` *                       | string           | 付款人文件（CPF 或 CNPJ）                                                                                                                      | -                                               |
| `payer_name` *                           | string           | 付款人姓名                                                                                                                                     | -                                               |
| `payer_person_type` *                    | string           | 付款人类型                                                                                                                                     | -                                               |
| `payer_postal_code_root`                 | string           | 邮政编码前五位                                                                                                                                 | -                                               |
| `payer_postal_code_suffix`               | string           | 邮政编码后三位                                                                                                                                 | -                                               |
| `printing_policy`                        | string           | 票据打印策略                                                                                                                                   | -                                               |
| `registration_institution_enumerator` *  | string           | 始终为 `qi_scd`                                                                                                                                | `qi_scd`                                        |
| `requester_profile` *                    | string           | 钱包编号                                                                                                                                       | 02                                              |
| `requester_profile_code` *               | string           | 钱包代码，格式为："329-钱包-机构-7位账号"。注：QI Tech 默认催收钱包编号为"09" | -                                               |
| `notification`                           | object           | 钱包编号                                                                                                                                       | **[Objeto notification](#objeto-notification)** |  
| `discounts`                              | object           | 包含折扣信息的对象列表                                                                                                                         | **[Objeto discounts](#objeto-discounts)**       |  
| `guarantor_name`                         | string           | 背书人姓名                                                                                                                                     | -                                               |
| `guarantor_document_root`                | string           | 背书人 CNPJ 基础部分                                                                                                                           | -                                               |
| `guarantor_document_subsidiary`          | string           | CNPJ 总部或分支机构信息                                                                                                                        | -                                               |
| `guarantor_document_digit`               | string           | CNPJ 验证位                                                                                                                                    | -                                               |

### Objeto notification
| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `document_number` * | string | 接收通知用户的文件编号 | - |
| `email` * | string | 接收通知用户的电子邮件 | - |
| `name` * | string | 接收通知用户的姓名 | - |
| `phone` * | object | 包含接收通知用户电话信息的对象 | **[Objeto phone](#objeto-phone)** |  
| `send_2_way` * | boolean | 发送补发通知 | true/false |  
| `send_after_due_date` * | boolean | 在票据到期后发送通知 | true/false |
| `send_before_due_date` * | boolean | 在票据到期前发送通知 | true/false |
| `send_on_protest` * | boolean | 发送抗议通知 | true/false|

### Objeto phone 

| 字段 | 类型 | 描述 | 最大字符数 | 
| --- | --- | --- | --- | 
|`country_code` | string | 电话国际区号 DDI | 3 | 
| `area_code` | string | 电话地区区号 DDD | 2 |
| `number` | string | 电话号码（仅数字） | 10 |

### Objeto discounts 
| 字段 | 类型 | 描述 | 字符数 | 
| --- | --- |---------|--------| 
|`discount_value` | float | 折扣金额 | - | 
| `discount_number` | int | 折扣应用顺序 | - |
| `discount_limit_date` | date | 折扣适用截止日期 | 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
| 字段 | 类型 | 描述 | 字符数 |
| --- | -- |--------------------------------------------------------------------| --- |
|`bank_slips` | list | 当 `use_multi_process` 参数值为 `false` 时，返回已登记票据的信息列表 | [Objeto Bank Slip](#objeto-bank_slip) | 
| `file_info` | list | 文件信息 | [Objeto File Info](#objeto-file-info) |
| `occurrence_stats` | object | 文件信息 | [Objeto File Info](#objeto-file-info) |
| `semantic_errors` | list | 每张票据处理过程中的错误列表。当处理中存在错误且 `use_multi_process` 参数值为 `false` 时返回 | [Objeto Semantic Error](#objeto-semantic-error) |

### Objeto bank_slip
| 字段 | 类型 | 描述 | 字符数 |
| --- | -- |--------------------------------------------------------------------| --- |
|`amount` | float | 票据金额 | - |
|`bank_slip_key` | uuid | QI Tech 票据唯一标识键 | 36 |
|`bank_slip_status` | enum | QI Tech 票据唯一标识键 | [Enumeradores bank_slip_status](#enumeradores-bank_slip_status) |
|`barcode` | string | 票据条形码 | 44 |
|`beneficiary_account_key` | uuid | 登记票据的账户唯一标识键 | 36 |
|`beneficiary_key` | uuid | 登记票据的账户持有人唯一标识键 | 36 |
|`digitable_line` | uuid | 票据可输入行 | 47 |
|`expiration` | string | 票据到期日 | 10 |
|`nfe_key` | string | 电子发票唯一标识键 | - |
|`nfe_url` | string | 电子发票 URL | - |
|`our_number` | int | 银行编号。是票据相对于其登记账户（催收钱包）的顺序标识号。可以在票据登记请求中提供此值。若未提供，QI Tech 将自动生成（递增值，如：账户中登记的第1张票据 `our_number` 为1，第16张票据 `our_number` 为16） | - 
|`participant_control_number` | string | 参与者控制编号 | 10 |
|`payer_postal_code` | string | 票据付款人邮政编码 | 8 |
|`protest_status` | string | 票据抗议状态（如果已申请抗议） | [Enumeradores protest_status](#enumeradores-protest_status) |

### Enumeradores bank_slip_status
| 枚举值 | 描述 |
| --- | -- |
| `accepted` | 票据已接受处理 |
| `registered` | 票据登记已在票据登记所完成 |
| `paid` | 票据付款金额已贷记至受益人账户 |
| `written_off` | 票据已核销（不可再付款） |
| `rejected` | 票据登记被票据登记所拒绝 |
| `payment_notice` | 票据付款已在付款银行处理的通知（但受益人账户的清算尚未发生） |
| `notary_office_payment_notice` | 已抗议票据的付款已在付款银行处理的通知（但公证处尚未转账，受益人账户的清算尚未发生） |

### Enumeradores protest_status
| 枚举值 | 描述 |
| --- | -- |
| `not_protested` | 票据无抗议申请 |
| `protest_requested` | QI Tech 正在处理抗议申请 |
| `notary_office_entry` | 票据抗议申请已被公证处接受 |
| `protest_cancel_requested` | QI Tech 正在处理取消抗议申请 |
| `notary_office_exit` | 票据抗议已从公证处撤回 |
| `protested` | 公证处已确认抗议，票据处于抗议状态 |
| `paid_at_notary_office` | 公证处已识别票据抗议的付款，正在处理向 QI Tech 的付款转账 |
| `judicially_suspended` | 抗议已被司法暂停 |
| `protest_remove_requested` | 撤销抗议申请已被公证处接受 |

---

# 发送票据指令

URL: /zh-Hans/documentation/boletos/v1/enviar_instrucao_de_boleto

## 发送票据指令

要申请票据指令，只需按以下说明发送包含 `occurrence_type` 的发行请求：

| 值 | 描述 |
|---|---|
| `registration` | 登记新票据 |
| `bank_slip_edit` | 编辑现有票据的付款人信息 |
| `extension` | 延期现有票据的到期日 |
| `write_off` | 无财务核销票据 |
| `rebate` | 付款减免 |
| `cancel_rebate` | 取消付款减免 |
| `bank_slip_edit` | 编辑现有票据（折扣、地址、罚款/利息） |
| `protest_request` | 抗议票据 |
| `bankruptcy_protest_request` | 破产抗议 |
| `protest_remove_request` | 取消抗议 |
| `protest_cancel_request` | 中止抗议（不核销） |
| `protest_cancel_and_write_off_request` | 中止抗议并核销 |

**请求示例**

### 延期

要申请此指令，票据必须已登记且可供付款。

Request Body

```json
{
  "occurrences": [
    {
      "occurrence_type": "extension",
      "requester_profile_code": "329-01-0001-0000001",
      "our_number": 1000000,
      "expiration": "2022-06-15"
    }
  ]
}

```

### 核销

要申请此指令，票据必须已登记。

Request Body

```json
{
  "occurrences": [
    {
      "occurrence_type": "write_off",
      "requester_profile_code": "329-01-0001-0000001",
      "our_number": 1000000
    }
  ]
}

```

### 减免

要申请此指令，票据不能已到期。

Request Body

```json
{
  "occurrences": [
    {
      "occurrence_type": "rebate",
      "our_number": 1000000,
      "rebate_amount": 10,
      "requester_profile_code": "329-01-0001-0000001"
    }
  ]
}

```

### 取消减免

要申请此指令，票据必须有有效的减免，且不能已到期。

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"
    }
  ]
}

```

### 折扣

要申请此指令，票据不能已到期/核销。

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
        }
      ]
    }
  ]
}

```

### 添加/编辑地址

要申请此指令，票据必须已登记且可供付款。

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"
    }
  ]
}

```

### 编辑罚款/利息

要申请此指令，票据必须已登记且可供付款。

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
    }
  ]
}

```

### 抗议

要申请此指令，票据必须已到期，且付款人必须有地址数据。

Request Body

```json
{
  "occurrences": [
    {
      "our_number": 1000000002,
      "occurrence_type": "protest_request",
      "requester_profile_code": "329-01-0001-0000001"
    }
  ]
}

```

### 破产抗议

要申请此指令，票据必须已到期，且付款人必须有地址数据。

Request Body

```json
{
  "occurrences": [
    {
      "our_number": 1000000002,
      "occurrence_type": "bankruptcy_protest_request",
      "requester_profile_code": "329-01-0001-0000001"
    }
  ]
}

```

### 取消抗议

要申请此指令，票据必须已被抗议。

Request Body

```json
{
  "occurrences": [
    {
      "our_number": 1000000002,
      "occurrence_type": "protest_remove_request",
      "requester_profile_code": "329-01-0001-0000001"
    }
  ]
}

```

### 取消自动抗议

要申请此指令，票据必须在注册时启用了该选项。

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
    }
  ]
}

```

### 中止抗议（不核销）

要申请此指令，票据必须已被抗议。

Request Body

```json
{
  "occurrences": [
    {
      "our_number": 1000000002,
      "occurrence_type": "protest_cancel_request",
      "requester_profile_code": "329-01-0001-0000001"
    }
  ]
}

```

### 取消自动抗议

要申请此指令，票据必须已被抗议。

Request Body

```json
{
  "occurrences": [
    {
      "our_number": 1000000002,
      "occurrence_type": "protest_cancel_and_write_off_request",
      "requester_profile_code": "329-01-0001-0000001"
    }
  ]
}

```

## 响应示例

响应因每种指令类型而有所不同，通常会导致 occurrence_stats 中每条指令的键值发生变化。

而在 semantic_errors 字段中，将返回一个包含每条记录及其各自错误的对象列表（示例如下）。

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
      }
    }
  ]
}

```

---

# 简介

URL: /zh-Hans/documentation/boletos/v1/introducao

催收钱包是允许发行银行票据的服务。存在多种类型的钱包，每种钱包定义了票据的生成方式、成本、清算费率、应贷记的账户以及各种配置，从而允许银行进行正确的催收。在 QI Tech 开户过程中，客户将自动获得一个 QI 内部钱包和一个 Bradesco 钱包，配备 QI Tech 的全局催收设置。

此外，如果客户希望注册或更改具有不同于全局配置的钱包，可以向我们的团队申请该服务。

## 票据发行如何运作？

QI Tech 的 API 通过状态机对票据生命周期进行抽象，具有以下状态：

## 登记申请
    - accepted：票据发行申请已进入登记队列；
    - rejected：票据发行申请被拒绝，当登记申请包含阻止登记的语义错误时出现。

## 登记完成
    registered：票据已登记，可供付款。

## 付款通知
    - payment_notice：票据付款通知，此通知在票据支付时发送，但财务清算尚未发生。
    - notary_office_payment_notice：票据付款通知，此通知在票据在公证处支付时发送，但财务清算尚未发生。

## 清算
    - paid：票据已支付——已核销并完成财务清算。
    - written_off：票据已核销，无财务清算。

---

# Boleto Webhooks

URL: /zh-Hans/documentation/boletos/webhooks/boleto

:::danger 注意！
QI Tech 的 Webhook 不应进行严格映射。
我们 API 返回的 Webhook 载荷中可能会新增额外字段。
:::

:::info 重新发送 Webhook
您可以按照文档中的详细说明查询和重新发送 Webhook：[重新发送 Webhook](/documentation/notificacoes/reenvio_de_notificacoes)。
:::

## 简介

在系统内 Boleto 的整个生命周期中，将发送包含以下 Boleto 状态（`bank_slip_status`）的 Webhook：

| 枚举值                        | 描述                                                          |
|------------------------------|---------------------------------------------------------------|
| registered                   | Boleto 已登记并可供付款                                        |
| rejected                     | Boleto 发行申请因验证错误被拒绝                               |
| payment_notice               | Boleto 支付通知（已付款但尚未清算）                           |
| notary_office_payment_notice | Boleto 公证处支付通知（已付款但尚未清算）                     |
| paid                         | Boleto 已付款并完成财务清算                                   |
| written_off                  | Boleto 已注销（不可再付款）且无财务清算                       |
| payment_blocked              | 因抗议流程而被锁定支付                                        |

以下类型（`occurrence_type`）的事件被确认时，将发送 Webhook：

| 枚举值                        | 描述                                                          |
|------------------------------|---------------------------------------------------------------|
| registration                 | Boleto 登记                                                   |
| rebate                       | 票据基础金额折让                                              |
| cancel_rebate                | 取消现有折让                                                  |
| extension                    | 延长票据到期日期                                              |
| write_off                    | Boleto 注销                                                   |
| protest_write_off            | 因公证处抗议注销 Boleto                                       |
| payment_write_off            | 因付款注销 Boleto                                             |
| discount                     | 折扣变更                                                      |
| fine                         | 罚款变更                                                      |
| interest                     | 利息变更                                                      |
| protest_request              | 公证处抗议申请                                                |
| bankruptcy_protest_request   | 公证处破产抗议申请                                            |
| notary_office_entry          | 票据进入公证处事件                                            |
| protest_cancel_request       | 撤销当前抗议申请                                              |
| protest_remove_request       | 票据抗议暂停                                                  |
| notary_office_exit           | 票据离开公证处事件                                            |
| payment_notice               | Boleto 支付通知（已付款但尚未清算）                           |
| notary_office_payment_notice | Boleto 公证处支付通知（已付款但尚未清算）                     |
| payment                      | 通知 Boleto 已付款并注销                                      |

:::info 信息
我们 Webhook 的响应超时时间为 10 秒。
:::

## 示例
----

### 登记

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": "9077cc0b-5bbd-4432-888e-6bf6384c250a",
		"occurrence_type": "registration",
		"occurrence_status": "confirmed"
	}
}
```

Webhook Body: 事件被拒绝

```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"
	}
}
```

### 折让/取消折让

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": "rebate",
		"occurrence_status": "confirmed"
	}
}
```

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": "cancel_rebate",
		"occurrence_status": "confirmed"
	}
}
```

### 延期

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"
	}
}
```

### 折扣

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"
	}
}
```

### 利息

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"
	}
}
```

### 罚款

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"
	}
}
```

### 注销

`occurrence_reason` 字段为可选字段，当银行提供注销原因时才会出现。它包含金融机构提供的原因代码和原因名称。

Webhook Body: 无原因

```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: 含原因

```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"
		}
	}
}
```

### 因抗议注销

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"
	}
}
```

### 因付款注销

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"
	}
}
```

### 抗议申请

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"
	}
}
```

### 破产抗议申请

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"
	}
}
```

### 进入公证处

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"
	}
}
```

### 取消抗议

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"
	}
}
```

### 暂停抗议

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"
	}
}
```

### 离开公证处

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"
	}
}
```

### 支付通知

**第一个 Webhook：Boleto 已付款，但尚未清算**

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"
	}
}
```

### 公证处支付通知

**第一个 Webhook：Boleto 已在公证处付款，但尚未清算**

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"
	}
}
```

### 付款

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_bank": {
			"code": "341",
			"ispb": 60701190,
			"name": "ITAU UNIBANCO S.A."
		},
		"payment_branch": "0216"
	}
}
```

:::info 信息
`payment_bank` 和 `payment_branch` 字段表示 Boleto 付款所在的银行和分行。它们仅在付款结算时收到该信息后才会填充；如果未识别出付款银行，`payment_bank` 将返回 `null`。
:::

### payment_origin 枚举值

| 枚举值           | 描述                       |
|----------------|----------------------------|
| cash           | 现金                       |
| account_debit  | 账户扣款                   |
| credit_card    | 信用卡                     |
| check          | 支票                       |

### payment_origin 枚举值

| 枚举值                | 描述                           |
|--------------------|-------------------------------|
| phisical_cashier   | 传统网点                       |
| taa                | 自动取款机终端                  |
| internet           | 网络银行（home/office banking） |
| corban             | 银行代理                       |
| call_center        | 客服中心                       |
| eletronic_file     | 电子文件                       |
| dda                | DDA                            |
| digital_correspondent | 数字代理                   |
| qr_code            | Pix QR Code 支付               |

---

# 票据钱包 Webhooks

URL: /zh-Hans/documentation/boletos/webhooks/carteira

:::danger 注意！
QI Tech 的 webhooks 不应以严格限定的方式进行映射。
我们 API 返回的 webhook payload 中可能会添加新字段。
:::

:::info Webhook 重发
您可以按照文档中的详细说明查询和重发 webhooks：[重发 Webhooks](/documentation/notificacoes/reenvio_de_notificacoes)。
:::

## 简介

在我们系统内创建钱包（`requester_profile`）后，将发送包含以下状态的 webhooks：

| 枚举值     | 描述                               |
|------------|------------------------------------|
| opened     | 票据钱包已开启，可登记票据         |

:::info 信息
我们 webhooks 的响应超时时间为 10 秒。
:::

## 示例
----

### 开启确认

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

URL: /zh-Hans/documentation/boletos/webhooks/liquidacao

:::danger 注意！
QI Tech 的 webhooks 不应以严格限定的方式进行映射。
我们 API 返回的 webhook payload 中可能会添加新字段。
:::

:::info Webhook 重发
您可以按照文档中的详细说明查询和重发 webhooks：[重发 Webhooks](/documentation/notificacoes/reenvio_de_notificacoes)。
:::

## 简介

在我们的系统中，清算组是协调交易与已清算票据的一种方式。该流程（清算）描述了将已支付票据的金额转移至应收款账户的过程。简而言之，每当 QI 收到票据已被其他银行支付（或对于已抗议的票据，由公证处支付）的信息时，就会为该特定票据创建一条清算记录。随后，会创建**清算组**，这些清算组代表按类型分组的清算批次。

此后，会为该清算组执行向客户账户的付款交易。该交易的 **transaction_key** 随后将保存用于对账，通过此方式您可以查看在某次特定交易中已清算的所有票据。例如，若您有五张各 R$ 5.00 的票据，其中一张通过公证处支付，一张通过 QR Code PIX 支付，另外三张由其他银行通过可输入行或条形码支付，则会为这些票据创建五条清算记录。随后，这些清算记录将被分为三个清算组：一个 R$ 15.00 的清算组包含三张通过可输入行或条形码支付的票据（对其执行一笔交易）；一个 R$ 5.00 的清算组包含通过 QR Code PIX 支付的票据；最后一个 R$ 5.00 的清算组包含通过公证处支付的票据。

:::info 信息
我们 webhooks 的响应超时时间为 10 秒。
:::

## 示例
----

### 清算组

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

| 枚举值         | 描述                                                              |
|----------------|-------------------------------------------------------------------|
| siloc          | 用于票据支付（票据金额小于 R$ 250.000）                           |
| qr_code        | 用于通过 QR Code 支付的票据                                       |
| str            | 用于大额票据支付（票据金额大于 R$ 250.000）                       |
| notary_office  | 用于通过公证处支付的票据                                          |

### Enumeradores bank_slip_settlement_group_status

| 枚举值    | 描述                                   |
|-----------|----------------------------------------|
| pending   | 清算组已创建，但交易尚未执行           |
| settled   | 清算组已创建，且交易已执行             |

---

# 返回文件 Webhooks

URL: /zh-Hans/documentation/boletos/webhooks/retorno

返回文件用于对账。文件中，每行交易记录（类型 1）对应前一天 CIP/Nuclea 确认或拒绝的一条指令（无论是发行、延期、减免等类型）。

:::danger 注意！
QI Tech 的 webhooks 不应以严格限定的方式进行映射。
我们 API 返回的 webhook payload 中可能会添加新字段。
:::

:::info Webhook 重发
您可以按照文档中的详细说明查询和重发 webhooks：[重发 Webhooks](/documentation/notificacoes/reenvio_de_notificacoes)。
:::

:::info 信息
我们 webhooks 的响应超时时间为 10 秒。
:::

## 示例
----

### 返回文件

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 支持的银行
目前，返回文件 webhook 支持以下银行：
- Bradesco（bradesco）
- Itaú（itau）
- QI SCD（qi_scd）
- Santander（santander）
:::

:::info 支持的布局
目前，返回文件 webhook 支持以下 CNAB 布局：
- CNAB 400（400）
:::

---

# 认证

URL: /zh-Hans/documentation/caas/account_event/authentication

> 要认证一次调用，请使用以下代码：

```shell
# 在 shell 中，您只需在每个请求中添加适当的 header。
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE-OF-API-KEY"
```

> 请将 API Key 'EXAMPLE-OF-API-KEY' 替换为您的密钥，该密钥应通过我们的支持团队获取。

我们使用 API Key 来允许访问我们的 API。它可能已经通过电子邮件发送给您。如果您尚未收到密钥，请发送电子邮件至 suporte.caas@qitech.com.br 。

我们的 API 期望在所有发送到服务器的请求中，以如下 header 的形式接收 API Key：

`Authorization: EXAMPLE-OF-API-KEY`

:::info **注意**

您必须将 EXAMPLE-OF-API-KEY 替换为您的密钥，该密钥应通过我们的支持团队获取。
:::

---

# Device Validation 对象

URL: /zh-Hans/documentation/caas/account_event/device_validation

通过唯一标识进行设备验证应通过 Event Type Device Validation 端点完成。发送的数据应为设备注册 API 生成的数据，以及一个 Device Scan 会话 ID。也就是说，要执行设备验证，应用程序必须使用 SDK 生成唯一标识符，并完成设备注册，以便后续识别该设备。

### 状态动态 - **analysis_status**

**analysis_status** 状态表示欺诈引擎决策的状态，具有简单的状态机：

* automatically_approved
* automatically_reproved
* in_manual_analysis
* manually_approved
* manually_reproved
* pending

## 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"
}
```

设备验证的所有信息交换均使用以下对象定义。在某些情况下，为了便于实现并减少各方之间的数据流，部分信息可能会被省略。

名称 | 类型 | 描述
:----: | :----: | ---------
id | string | 事件标识符。 **此编号对每个请求必须唯一** *（必填）*
account_id | string | 设备注册系统中已注册账户的标识符。若要对同一注册进行多次分析，只需在不同分析中使用相同的 account_id。*（必填）*
person_id | string | 设备注册系统中与已注册账户关联的用户标识符。若要对同一注册进行多次分析，只需在不同分析中使用相同的 person_id。*（必填）*
session_id | string | Device Scan 分析会话的标识符。*（必填）*
face_recognition_key | string | SDK 生成的用于面部识别的图像标识符。
event_date | datetime | 事件的日期和时间 *（必填）*

## 发送 Device Validation

Request Body

```json
  {
    "id": "12345",
    ...
  }
```

Response Body

```json
  {
    "id": "12345",
    "analysis_status": "automatically_approved",
    "reason": "rule_decision_enum"
  }
```

要执行设备验证，只需将 Device Validation 类型的对象发送到以下端点：

`POST https://api.caas.qitech.app/account_event/event_type/device_validation/event`

---

# HTTP 状态码

URL: /zh-Hans/documentation/caas/account_event/http_status

QI Tech 的所有 API 均遵循以下 HTTP 返回状态码标准，符合 RFC 7231 ：

HTTP 状态码 | 含义 | 描述
---------- | ------- | ---------------------------------
400 | Bad Request | 发送的请求存在格式错误。通常，我们会在消息体中说明错误所在。
401 | Unauthorized | 认证出现问题，请检查 API Key 是否正确且在正确的 header 中，参见 认证 部分。
403 | Forbidden | 访问的端点为内部使用，此 API Key 无法访问。
404 | Not Found | 使用该密钥未找到所请求的数据。当请求无效端点时也会返回此状态。
405 | Method Not Allowed | 所使用的 HTTP 方法不适用于该端点。
406 | Not Acceptable | 请求体中发送的数据无效。通常表示发送的数据不是有效的 JSON。
409 | Conflict | 请求 ID 对应之前已处理过的 ID。当向服务器发送重复请求时返回此状态。
500 | Internal Server Error | 我们在处理此请求时遇到问题，一旦出现此错误，我们的专家将自动收到通知并立即开始分析和解决。
503 | Service Unavailable | 您遇到了计划内或计划外的服务器基础设施不可用情况。

---

# 简介

URL: /zh-Hans/documentation/caas/account_event/introduction

欢迎使用 QI Tech 账户事件 API！此 API 提供对您平台内账户事件监控和规则服务的访问！

此 API 可与 Device Scan 和设备注册 API 配合用于设备验证，也可用于其他验证，例如：

* 登录。
* 页面访问。
* 密码修改。
* 注册数据修改。
* 交易前验证。
* 活体验证。

您可以使用我们的 API 访问端点以评估以下类型的事件：

* **Device Validation** - 用于设备唯一标识的验证。
* **Pre Pix Transaction** - 用于 Pix 交易的预验证。
* **Registration Data Validation** - 用于注册数据的验证。

可以根据您系统的需求实现不同类型的事件。

在右侧，您可以看到使用 curl 的 API 实现。这样，您就有了示例，可以根据自己喜欢的编程语言进行适当调整。

## 遇到问题？

我们不是躲在 API 后面的公司！请联系我们的 支持团队 ，我们将尽快回复。如果您需要快速回复，请随时致电我们！

### 我们热爱反馈

即使您已经解决了问题，或者问题非常简单（甚至是您发现的一个错别字或不当的组织方式），也请给我们发电子邮件，这样我们可以让文档变得越来越实用，下一个人就不必经历您所经历的痛苦！

## 环境

我们为客户提供两个环境。API 的基本 URL 为：

* 生产环境 - `https://api.caas.qitech.app/account_event/`
* 沙盒环境 - `https://api.sandbox.caas.qitech.app/account_event/`

:::danger 重要提示！
不得在 QI Tech 沙盒环境中使用真实的个人和/或法人数据。
:::

在沙盒环境中，提交的分析不计费，并根据为事件配置的规则进行响应。

## 仅限 HTTPS

出于安全原因，与 QI Tech API 的所有通信必须使用 HTTPS 协议。为避免因疏忽或其他原因发出 HTTP 调用，此服务器仅提供使用 TLS 1.2 通信的 443 端口。使用其他协议发出的调用将自动被拒绝。

---

# Pre PIX Transaction

URL: /zh-Hans/documentation/caas/account_event/pre_pix_transaction

当付款人有意发起付款时，交易数据可以事先由我们的服务器进行评估。这样，可以根据该数据集对交易所涉及的风险进行预先分析。

## 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"
}
```

交易必须在转发到处理系统之前发送到 API，以便进行预先欺诈验证。

交易状态表示模型对该交易返回的决策。以下状态用于 **analysis_status** 标志：

* `automatically_approved`
* `automatically_reproved`
* `automatically_challenged`
* `pending`

以下是 analysis_status 标志中返回的每个决策的含义：

状态 | 描述
:----: | ---------
automatically_approved      | 建议批准此交易。
automatically_reproved      | 建议拒绝此交易。
automatically_challenged    | QI Tech 算法建议对此交易发起挑战。
pending                     | 交易正在处理中。

名称 | 类型 | 描述
:----:  | :----:  | ---------
id | string | 客户系统中支付的标识符。 **此编号对每个支付流程必须唯一** *（必填）*
transaction_direction   | 枚举  | 注册交易的类型。定义客户是收款还是付款。*（必填）*
client                  | *client* | 表示客户数据的对象，无论是付款人还是收款人。*（必填）*
amount                  | 整数  | 支付金额，以分为单位——如"标准"部分所述。*（必填）*
pix_modality            | string   | 注册交易的类型。指示是否表示转账、找零或取款。
dict_key                | *dict_key*                | 表示客户在交易中使用的 DICT 绑定密钥数据的对象。
face_recognition_key    | string                    | 面部识别密钥，如果已通过我们的面部识别 API 进行面部识别。
source_account          | *source_account* | 表示被扣款账户数据的对象。*（必填）*
destination_account     | *destination_account* | 表示被入账账户数据的对象。*（必填）*
destination_statistics  | *destination_statistics*  | 表示来自 BACEN DICT API 的被入账账户交易和欺诈历史的对象。
source                  | *source* | Source 类型的对象，描述用于发送支付的应用程序信息
event_date              | datetime | 交易开始的日期和时间，含时区。*（必填）*

*transaction_direction* 的枚举值为：`sent` 和 `received`。

*pix_modality* 的枚举值为：`transacation`、`change` 和 `withdraw`。

## 发送预交易

Request Body

```json
  {
    "id": "12345",
    ...
  }
```

Response Body

```json
  {
    "id": "12345",
    "analysis_status": "automatically_approved",
    "reason": "rule_decision_enum",
    "reason_desciption": "Descrição da regra"
  }
```

要评估预交易，只需将 Transaction 类型的对象发送到以下端点：

`POST https://api.caas.qitech.app/account_event/event_type/pre_pix_transaction`

## 挑战流程

在执行分析后，可能会决定对用户发起挑战，要求其在您的平台上执行新操作。例如，此流程可用于要求用户进行 2FA（例如面部分析）。

## 流程执行步骤

**1.** 事件提交分析后，将返回 *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.** 在第一次分析请求返回挑战 *analysis_status* 后，如果客户流程已完成，可以发送新请求附带结果。此请求必须使用与前一请求相同的 *event_id*，且当前状态必须为 *automatically_challenged*。此更新的可能状态为：

* `approved_by_client`
* `reproved_by_client`

`PATCH https://api.caas.qitech.app/account_event/event_type/pre_pix_transaction/{event_id}`

Request Body：附加信息的发送

```json
{
    "analysis_status": "approved_by_client"
}
````

Response Body

```json
{
  "id": "082373263",
  "analysis_status": "approved_by_client"
  ...
}
```

请注意使用您在第一次分析中使用的相同 event_id。

---

# 查询账户事件

URL: /zh-Hans/documentation/caas/account_event/query_registration

要检索特定账户事件，只需发送 GET 请求。返回的结果是该事件的最新 JSON。如果该标识符与任何对象无关联，则返回 HTTP 状态码 404。

## 可能的事件：
- 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"
```

---

# 标准

URL: /zh-Hans/documentation/caas/account_event/standards

为便于集成并保证信息完整性，整个 API 遵循以下已定义的标准。

## 货币金额
> 示例：

```
10000
12345
98741
1223
1
0
```

API 假设所有发送的货币金额均以巴西雷亚尔计。金额必须以分为单位作为整数发送。

## 带时区的日期和时间
> 一些示例：

```
2019-10-15T22:35:12.232-03:00
2018-05-01T13:32:11.297+00:00
2019-05-01T00:00:00.000+00:00
```

按照 ISO 8601 表示。在这种情况下，时区紧跟在时间之后，必须表示该数据有效的地点的时区。

用于验证的掩码如下：

`YYYY-MM-ddThh:mm:ss.sss±hh:mm`

## 不带时区的日期和时间
> 一些示例：

```
2019-10-15T22:35:12
2018-05-01T13:32:11
2019-05-01T00:00:00
```

按照 ISO 8601 表示。与时区无关的数据应不带时区发送，始终以 UTC 表示，字母 Z 表示该数据为 UTC。因此，将验证以下格式：

`YYYY-MM-ddThh:mm:ss.sssZ`

## 日期
> 一些示例

```
2019-10-15
2019-01-01
2017-03-20
```

对于只接收日期而不包含时间的字段，应使用以下格式发送：

`YYYY-MM-dd`

## 文件编号
由于文件编号差异很大，且许多文件编号包含非数字字符，因此所有文件编号均定义为字符串。将其定义为字符串的另一个好理由是避免前导零消失。本页中预定义的文件编号具有明确的掩码，需经过验证。其他文件编号（如 RG）由于缺乏标准化，将不进行验证。

## CPF

> 针对已定义掩码验证的有效 CPF 示例：

```
123.456.789-12
321.987.543-23
111.283.333-00
```

> 针对已定义掩码验证的无效 CPF 示例：

```
8.577.477-8
08.104.627/0001-23
123.456.789-1
23.456.789-01
```

CPF 始终定义为字符串，并将针对以下掩码进行验证：

`###.###.###-##`

## CNPJ

> 针对已定义掩码验证的有效 CNPJ 示例：

```
08.104.627/0001-02
01.079.210/0114-67
32.402.502/0001-35
```

> 针对已定义掩码验证的无效 CNPJ 示例：

```
8.577.477-8
123.456.789-12
321.987.543-23
32.402.502/0001-3
032.402.502/0001-3
```

CNPJ 始终定义为字符串，并将针对以下掩码进行验证：

`##.###.###/####-##`

## IP

> 针对已定义掩码验证的有效 IP 示例：

```
201.81.161.86
201.081.161.86
201.81.161.086
201.81.0.1
```

> 无效 IP 示例：

```
201.81..86
358.81.161.86
201.81.161
```

IP 必须始终以 IPv4 格式发送，前导零可以发送也可以不发送，遵循以下掩码：

`###.###.###.###`

---

# 状态动态

URL: /zh-Hans/documentation/caas/account_event/status_dynamics

分析过程包括将事件（例如 Device Validation）发送到相应端点并等待响应。

QI Tech 完成事件分析后，将返回包含分析状态的响应。**analysis_status** 字段表示 QI Tech 执行的事件分析结果。

### **analysis_status**

如前所述，QI Tech 有八种 **analysis_status**，指示账户事件引擎的决策状态，具有简单的状态机：

analysis_status | 描述
:---------: | ---------
automatically_approved | QI Tech 算法建议批准此事件。
automatically_reproved | QI Tech 算法建议拒绝此事件。
automatically_challenge | QI Tech 算法建议用户采取行动以获取更多分析信息。
in_manual_analysis | QI Tech 算法已将此事件发送进行人工分析。
manually_approved | 经人工分析后，分析师决定批准该事件。
manually_reproved | 经人工分析后，分析师决定拒绝该事件。
in_queue | 事件正在异步执行。事件结果将通过 Webhook 响应。
pending | 查询耗时超过预期，此事件已进入自动分析队列，将通过 Webhook 响应。
not_analysed | 事件以分析标志为假发送，这意味着我们的系统不会返回建议。

---

# 账户创建

URL: /zh-Hans/documentation/caas/account_monitoring/account_registration

账户监控产品分为个人账户和企业账户，其中个人账户只能包含自然人，而企业账户可以包含法人和自然人。要创建账户，只需将 _Account_ 类型的对象发送到以下端点之一：

- 个人账户

`POST https://api.caas.qitech.app/account_monitoring/natural_person_account`

> 示例

```json
{
    "account_id": "5ce7fab5-8165-44a5-9b89-bb2d6d61e4f4",
    "registration_date": "2019-12-20T15:23:12"
}
```
- 企业账户

`POST https://api.caas.qitech.app/account_monitoring/legal_person_account`

> 示例

```json
{
    "account_id": "5ce7fab5-8165-44a5-9b89-bb2d6d61e4f4",
    "registration_date": "2019-12-20T15:23:12"
}
```

注册的所有信息交换均使用以下对象定义。在某些情况下，为了便于实现并减少各方之间的数据流，部分信息可能会被省略。

名称 | 类型 | 描述
:----: | :----: | ---------
account_id | string | 账户的唯一标识符。 **此编号对每个请求必须唯一**
registration_date |	string (ISO 8601) | 注册的日期和时间。

## 账户停用和重新激活

要在账户监控产品中停用账户，需要在以下端点发送请求，并传入 new_account_status 字段值为 'deactivated'：

- 个人账户

`PATCH https://api.caas.qitech.app/account_monitoring/natural_person_account/{account_id}`

> 示例

```json
{
    "new_account_status" : "deactivated"
}
```
- 企业账户

`PATCH https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}`

> 示例

```json
{
    "new_account_status" : "deactivated"
}
```

这将停用账户并中止其监控。要重新激活账户并恢复其监控，只需在以下端点发送请求，此时传入 new_account_status 为 'active'：

- 个人账户

`PATCH https://api.caas.qitech.app/account_monitoring/natural_person_account/{account_id}`

> 示例

```json
{
    "new_account_status" : "active"
}
```
- 企业账户

`PATCH https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}`

> 示例

```json
{
    "new_account_status" : "active"
}
```

重新激活账户后，账户主题的监控间隔将重新开始。例如，如果所有主题均每 24 小时监控一次，则在账户重新激活时，更新将在重新激活后 24 小时执行。

---

# authentication

URL: /zh-Hans/documentation/caas/account_monitoring/authentication

## 认证

> 要认证一次调用，请使用以下代码：

```shell
# 在 shell 中，您只需在每个请求中添加适当的 header
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE_API_KEY"
```

> 请将 API Key 'EXAMPLE_API_KEY' 替换为您从我们支持团队获取的密钥。

我们使用 API Key 来允许访问我们的 API。它可能已经通过电子邮件发送给您。如果您尚未收到密钥，请发送电子邮件至 suporte.caas@qitech.com.br 。

我们的 API 期望在所有发送到服务器的请求中，以如下 header 的形式接收 API Key：

`Authorization: EXAMPLE_API_KEY`

:::info **注意**

您必须将 EXAMPLE_API_KEY 替换为从支持团队收到的 API Key。
:::

---

# HTTP 状态码

URL: /zh-Hans/documentation/caas/account_monitoring/http_status

QI Tech 的所有 API 均遵循以下 HTTP 返回状态码标准，符合 RFC 7231 ：

HTTP 状态码 | 含义 | 描述
---------- | ------- | ---------------------------------
400 | Bad Request | 发送的请求存在格式错误。在大多数情况下，我们会在消息体中说明错误所在。
401 | Unauthorized | 认证出现问题，请检查 API Key 是否正确且在正确的 header 中，参见 认证 部分。
403 | Forbidden | 访问的端点为内部使用，此 API Key 无法访问。
404 | Not Found | 使用该密钥未找到所请求的数据。当请求无效端点时也会返回此状态。
405 | Method Not Allowed | 所使用的 HTTP 方法不适用于该端点。
406 | Not Acceptable | 请求体中发送的数据无效。通常表示发送的数据不是有效的 JSON。
409 | Conflict | 请求 ID 对应之前已处理过的 ID。当向服务器发送重复请求时返回此状态。
500 | Internal Server Error | 我们在处理此请求时遇到问题，一旦出现此错误，我们的专家将自动收到通知并立即开始分析和解决。
503 | Service Unavailable | 您遇到了计划内或计划外的服务器基础设施不可用情况。

---

# 简介

URL: /zh-Hans/documentation/caas/account_monitoring/introduction

欢迎使用 QI Tech 账户监控 API！您可以使用我们的 API 在各种监控主题上对账户和人员进行监控，监控间隔完全可根据客户的需求自定义。目前该产品具有以下监控主题：

- 对于自然人；
  - OFAC 列表 - 美国外国资产控制办公室制裁名单（Office of Foreign Assets Control）
  - UNSC 列表 - 联合国安全理事会制裁名单（United Nations Security Council）
  - IBAMA 列表 - 巴西环境和可再生自然资源研究院环境处罚名单
  - PEP 列表 - 政治公众人物名单
  - 联邦税务局状态 - 巴西联邦税务局注册状况

- 对于法人；
  - OFAC 列表 - 美国外国资产控制办公室制裁名单（Office of Foreign Assets Control）
  - UNSC 列表 - 联合国安全理事会制裁名单（United Nations Security Council）
  - IBAMA 列表 - 巴西环境和可再生自然资源研究院环境处罚名单
  - CEIS 列表 - 不诚信和被暂停企业注册
  - CNEP 列表 - 国家受处罚企业注册
  - 联邦税务局状态 - 巴西联邦税务局注册状况

请注意，间隔按监控主题和被监控人员类型定义，例如，OFAC 列表对自然人可每 10 天监控一次，对法人可每 30 天监控一次。

每个主题的监控间隔遵循 ISO 8601 标准，可以是以下任意间隔，或其组合：

### 天、周、月和年

| 表示法  | 含义 |
|----------|------------|
| `"P1D"`  | 1 天      |
| `"P7D"`  | 7 天     |
| `"P1W"`  | 1 周   |
| `"P1M"`  | 1 个月      |
| `"P1Y"`  | 1 年      |

---

### 小时、分钟和秒

| 表示法      | 含义                      |
|-------------|----------------------------------|
| `"PT1H"`    | 1 小时                           |
| `"PT30M"`   | 30 分钟                       |
| `"PT45S"`   | 45 秒                      |
| `"PT2H30M"` | 2 小时 30 分钟             |
| `"PT1H15M10S"` | 1 小时、15 分钟和 10 秒 |

---

### 自定义示例

| 表示法         | 含义                              |
|----------------|----------------------------------------|
| `"P1DT12H"`    | 1 天 12 小时                      |
| `"P2W3DT4H30M"` | 2 周、3 天、4 小时和 30 分钟 |

以下，您可以看到使用 curl 的 API 实现。这样，您就有了示例，可以根据自己喜欢的编程语言进行适当调整。

## 遇到问题？

我们不是躲在 API 后面的公司！请联系我们的 支持团队 ，我们将尽快回复。如果您需要快速回复，请随时致电我们！

### 我们热爱反馈

即使您已经解决了问题，或者问题非常简单（甚至是您发现的一个错别字或不当的组织方式），也请给我们发电子邮件，这样我们可以让文档变得越来越实用，下一个人就不必经历您所经历的痛苦！

## 环境

我们为客户提供两个环境。API 的基本 URL 为：

* 生产环境 - `https://api.caas.qitech.app/account_monitoring/`
* 沙盒环境 - `https://api.sandbox.caas.qitech.app/account_monitoring/`

在沙盒环境中，提交的分析不计费，并根据预先建立的规则进行响应。

## 仅限 HTTPS

出于安全原因，与 QI Tech API 的所有通信必须使用 HTTPS 协议。为避免因疏忽或其他原因发出 HTTP 调用，此服务器仅提供使用 TLS 1.2 通信的 443 端口。使用其他协议发出的调用将自动被拒绝。

## 认证

> 要认证一次调用，请使用以下代码：

```shell
# 在 shell 中，您只需在每个请求中添加适当的 header
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE_API_KEY"
```

> 请将 API Key 'EXAMPLE_API_KEY' 替换为您从我们支持团队获取的密钥。

我们使用 API Key 来允许访问我们的 API。它可能已经通过电子邮件发送给您。如果您尚未收到密钥，请发送电子邮件至 suporte.caas@qitech.com.br 。

我们的 API 期望在所有发送到服务器的请求中，以如下 header 的形式接收 API Key：

`Authorization: EXAMPLE_API_KEY`

:::info **注意**

您必须将 EXAMPLE_API_KEY 替换为从支持团队收到的 API Key。
:::

---

# 人员创建

URL: /zh-Hans/documentation/caas/account_monitoring/person_registration

要为各自账户创建人员，必须保持 natural_person_account 和 legal_person_account 端点之间的隔离。

要为账户请求创建人员，只需将 Person 类型的对象发送到以下端点之一，遵循账户创建时的隔离：

### 个人账户

- 创建自然人

`POST https://api.caas.qitech.app/account_monitoring/natural_person_account/{account_id}/natural_person`

> 示例

```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"
    }
}
```
### 企业账户

- 创建自然人

`POST https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}/natural_person`

> 示例

```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"
    }
}
```
birthdate 字段仅对拥有联邦税务局状态监控的账户为必填项，查询未满 18 岁的人员时需要此字段。

- 创建法人

`POST https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}/legal_person`

> 示例

```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"
    }
}
```

## 人员停用和重新激活

要停用人员，操作与账户的操作类似，使用以下端点：

### 个人账户

- 创建自然人

`PATCH https://api.caas.qitech.app/account_monitoring/natural_person_account/{account_id}/natural_person`

> 示例

```json
{
    "new_person_status" : "deactivated"
}
```
### 企业账户

- 创建自然人

`PATCH https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}/natural_person`

> 示例

```json
{
    "new_person_status" : "deactivated"
}
```

- 创建法人

`PATCH https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}/legal_person`

> 示例

```json
{
    "new_person_status" : "deactivated"
}
```

要重新激活之前停用的人员，操作与停用人员相同，但 new_person_status 传入 'active'，使用以下端点：

### 个人账户

- 创建自然人

`PATCH https://api.caas.qitech.app/account_monitoring/natural_person_account/{account_id}/natural_person`

> 示例

```json
{
    "new_person_status" : "active"
}
```
### 企业账户

- 创建自然人

`PATCH https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}/natural_person`

> 示例

```json
{
    "new_person_status" : "active"
}
```

- 创建法人

`PATCH https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}/legal_person`

> 示例

```json
{
    "new_person_status" : "active"
}
```

---

# 标准

URL: /zh-Hans/documentation/caas/account_monitoring/standards

为便于集成并保证信息完整性，整个 API 遵循以下已定义的标准。

## 带时区的日期和时间
> 一些示例：

```
2019-10-15T22:35:12-03:00
2018-05-01T13:32:11+00:00
2019-05-01T00:00:00+00:00
```

按照 ISO 8601 表示。在这种情况下，时区紧跟在时间之后，必须表示该数据有效的地点的时区。例如，如果租约计划在巴西利亚机场于 09:30 开始，发送的时间应表示为 09:30-03:00；如果租约计划在马瑙斯于 09:30 开始，则应表示为 09:30-04:00。

用于验证的掩码如下：

`YYYY-MM-ddThh:mm:ss±hh:mm`

## 不带时区的日期和时间
> 一些示例：

```
2019-10-15T22:35:12Z
2018-05-01T13:32:11Z
2019-05-01T00:00:00Z
```

按照 ISO 8601 表示。与时区无关的数据应不带时区发送，始终以 UTC 表示，字母 Z 表示该数据为 UTC。因此，将验证以下格式：

`YYYY-MM-ddThh:mm:ssZ`

## 日期
> 一些示例

``` 
2019-10-15
2019-01-01
2017-03-20
```

对于只接收日期的字段（例如出生日期），应不包含任何时间，使用以下格式发送：

`YYYY-MM-dd`
 

## 文件编号
由于文件编号差异很大，且许多文件编号包含非数字字符，因此所有文件编号均定义为字符串。将其定义为字符串的另一个好理由是避免前导零消失。本页中预定义的文件编号具有明确的掩码，需经过验证。其他文件编号（如 RG）由于缺乏标准化，将不进行验证。

## CPF

> 针对已定义掩码验证的有效 CPF 示例：

```
123.456.789-12
321.987.543-23
111.283.333-00
```

> 针对已定义掩码验证的无效 CPF 示例：

```
8.577.477-8
08.104.627/0001-23
123.456.789-1
23.456.789-01
```

CPF 始终定义为字符串，并将针对以下掩码进行验证：

`###.###.###-##`

## CNPJ

> 针对已定义掩码验证的有效 CNPJ 示例：

```
08.104.627/0001-02
01.079.210/0114-67
32.402.502/0001-35
```

> 针对已定义掩码验证的无效 CNPJ 示例：

```
8.577.477-8
123.456.789-12
321.987.543-23
32.402.502/0001-3
032.402.502/0001-3
```

CNPJ 始终定义为字符串，并将针对以下掩码进行验证：

`##.###.###/####-##`

---

# Webhook

URL: /zh-Hans/documentation/caas/account_monitoring/webhook

监控主题的更新将通过发送 Webhook 进行通知。为此，需要通过[支持](mailto:suporte.caas@qitech.com.br)团队配置一个端点地址，我们将通过该地址通知更新，以及一个用于签名请求的 *signature_key*。请注意，所有 Webhook 发送均将发送到单个端点。

:::info **注意**

出于安全原因，所有 Webhook 请求将仅发送到通过 HTTPS 提供服务的端点。
:::

## 签名

> Python 签名计算示例

```python
    hmac_obj = hmac.new(signature_key.encode('utf-8'), (url + method + payload).encode('utf-8'), hashlib.sha1)
    return hmac_obj.hexdigest()
```

为确保在 Webhook 端点收到的请求来自我们的服务器，HMAC 签名将在 *Signature* Header 中发送，方式与认证过程类似。

在服务器端计算签名的预期值后，需要将计算的签名与发送的签名进行比较。如果签名匹配，则表示请求来自我们的服务器且可信。

## 事件更新 Webhook

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"
}
```

以下是每个字段的含义：

| 名称             | 类型              | 描述                                                          
|:----------------:|:-----------------:|-------------------------------------------------------------------------
| person_type      | string            | 人员类型（natural_person 或 legal_person）。                        
| account_type     | string            | 账户类型（natural_person_account 或 legal_person_account）。         
| person_id        | string             | 人员的唯一标识符，在创建请求中传入。       
| account_id       | string            | 账户的唯一标识符，在创建请求中传入。        
| monitoring_topic | string            | 发生变化的监控主题。                            
| event            | string            | 发生的事件类型，如限制名单主题的 "entered"（进入）或 "exited"（退出）。 

监控主题更新请求采用上述格式，并通知账户内某个监控主题状态的变化。使用的方法为 PUT，端点地址根据客户需求也可包含事件 ID。需要注意的是，请求体以 UTF-8 编码的文本形式发送。

## 重试

当收到 HTTP 状态码 200 作为响应时，通知视为已完成。如果通知失败，将进行 7 次重试，重试间隔如下，直到返回 200 或重试结束：

* 10 秒
* 40 秒
* 160 秒
* 640 秒
* 2560 秒
* 10240 秒
* 40960 秒

---

# 创建会话

URL: /zh-Hans/documentation/caas/auth_session_manager/auth_session

认证会话对象是一个表示用户认证流程的实体。通过此元素，您可以管理注册信息收集过程。

## 认证会话对象定义

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"
  }
}
```

会话的所有信息交换均使用以下对象定义

名称 | 类型 | 描述
:----: | :----: | ---------
id | string | 会话标识符。 **此编号对每个会话必须唯一** *（必填）*
document_number | string | 被注册个人的 CPF，含点和连字符，符合标准格式。*（必填）*
settings | 对象 | 包含认证会话自定义配置的对象。如未发送，将使用公司默认配置。

## settings 对象

settings 对象包含 `steps` 字段，该字段定义认证步骤的顺序及其各自的配置：
可接受的步骤包括：

* device_scan
* face_recognition
* personal_document

此外还接受以下字段：

名称 | 类型 | 描述
:----: | :----: | ---------
session_expiration_time_in_minutes | integer | 会话过期时间。超过此时间后，会话将不再有效。
token_expiration_seconds | integer | 会话令牌的过期时间（秒）。（必须在 1 到 172800 之间，最大 48 小时。默认值为 1800）
open_mode | string | 定义会话的打开方式，用于完成流程的消息和按钮。（必须为 "iframe" 或 "link"）。

### device_scan

device_scan 步骤表示执行设备信息收集。 **无附加配置**

### face_recognition

face_recognition 步骤表示通过面部生物识别执行活体证明流程的收集。 **无附加配置**

### personal_document

personal_document 步骤表示执行用于文件读取的 OCR 收集流程。

名称 | 类型 | 描述
:----: | :----: | ---------
document_templates | array | 在注册流程中可收集的文件列表。*（必填）*
show_success_screen | boolean | 定义文件捕获流程中是否存在成功画面。默认值 `true`。
show_introduction_screen | boolean | 定义文件捕获流程中是否存在简介画面。默认值 `true`。

可接受的 `document_templates` 类型：

名称 | 类型 | 描述
---- | ---- | ---------
cnh | string | 分两步捕获物理驾驶证正面和背面（**合拢状态**）
rg | string | 分两步捕获物理身份证正面和背面（**合拢状态**）
cnh_digital | string | 上传**数字版**驾驶证（pdf）
passport | string | 分两步上传护照正面和背面（**合拢状态**）。
rne | string | 分两步上传外国人国家注册证正面和背面（**合拢状态**）。
crnm | string | 分两步上传国家移民注册卡正面和背面（**合拢状态**）。
ctps | string | 分两步上传工作和社会保障手册正面和背面（**合拢状态**）。
others | string | 分两步上传任何**无需验证**的文件正面和背面（**合拢状态**）。

## 发送 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",
  }
```

要创建会话，只需将 Auth Session 类型的对象发送到以下端点：

`POST https://api.caas.qitech.app/auth_session_manager/auth_session`

---

# 认证

URL: /zh-Hans/documentation/caas/auth_session_manager/authentication

> 要认证一次调用，请使用以下代码：

```shell
# 在 shell 中，您只需在每个请求中添加适当的 header
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE-OF-API-KEY"
```

> 请将 API Key 'EXAMPLE-OF-API-KEY' 替换为您的密钥，该密钥应通过我们的支持团队获取。

我们使用 API Key 来允许访问我们的 API。它可能已经通过电子邮件发送给您。如果您尚未收到密钥，请发送电子邮件至 suporte.caas@qitech.com.br 。

我们的 API 期望在所有发送到服务器的请求中，以如下 header 的形式接收 API Key：

`Authorization: EXAMPLE-OF-API-KEY`

:::info **注意**

您必须将 EXAMPLE-OF-API-KEY 替换为您的密钥，该密钥应通过我们的支持团队获取。
:::

---

# HTTP 状态码

URL: /zh-Hans/documentation/caas/auth_session_manager/http_status

QI Tech 的所有 API 均遵循以下 HTTP 返回状态码标准，符合 RFC 7231 ：

HTTP 状态码 | 含义 | 描述
---------- | ------- | ---------------------------------
400 | Bad Request | 发送的请求存在格式错误。在大多数情况下，我们会在消息体中说明错误所在。
401 | Unauthorized | 认证出现问题，请检查 API Key 是否正确且在正确的 header 中，参见 认证 部分。
403 | Forbidden | 访问的端点为内部使用，此 API Key 无法访问。
404 | Not Found | 使用该密钥未找到所请求的数据。当请求无效端点时也会返回此状态。
405 | Method Not Allowed | 所使用的 HTTP 方法不适用于该端点。
406 | Not Acceptable | 请求体中发送的数据无效。通常表示发送的数据不是有效的 JSON。
409 | Conflict | 请求 ID 对应之前已处理过的 ID。当向服务器发送重复请求时返回此状态。
500 | Internal Server Error | 我们在处理此请求时遇到问题，一旦出现此错误，我们的专家将自动收到通知并立即开始分析和解决。
503 | Service Unavailable | 您遇到了计划内或计划外的服务器基础设施不可用情况。

---

# 简介

URL: /zh-Hans/documentation/caas/auth_session_manager/introduction

欢迎使用 QI Tech 认证会话管理 API！此 API 专为控制用户完整 KYC 流程而设计！

此服务负责组织认证流程，支持创建具有自定义流程的 KYC 注册会话，并使用 QI Tech 的其他认证服务：

* Device Scan
* Face Recognition
* OCR

这样，可以通过 API 返回的链接开始注册信息收集流程。
一旦启动，网页将负责引导用户执行该会话中定义的 KYC 步骤。

此外，由于它与上述其他服务直接集成，它能够收集完成认证流程所需的信息。有了这些信息，将可以在 QI Tech 的其他服务中进行所需的分析，例如自然人注册或交易前分析。

## 遇到问题？

我们不是躲在 API 后面的公司！请联系我们的 支持团队 ，我们将尽快回复。如果您需要快速回复，请随时致电我们！

### 我们热爱反馈

即使您已经解决了问题，或者问题非常简单（甚至是您发现的一个错别字或不当的组织方式），也请给我们发电子邮件，这样我们可以让文档变得越来越实用，下一个人就不必经历您所经历的痛苦！

## 环境

我们为客户提供两个环境。API 的基本 URL 为：

* 生产环境 - `https://api.caas.qitech.app/auth_session_manager/`
* 沙盒环境 - `https://api.sandbox.caas.qitech.app/auth_session_manager/`

:::danger 重要提示！
不得在 QI Tech 沙盒环境中使用真实的个人和/或法人数据。
:::

在沙盒环境中，提交的分析不计费，并根据为事件配置的规则进行响应。

## 仅限 HTTPS

出于安全原因，与 QI Tech API 的所有通信必须使用 HTTPS 协议。为避免因疏忽或其他原因发出 HTTP 调用，此服务器仅提供使用 TLS 1.2 通信的 443 端口。使用其他协议发出的调用将自动被拒绝。

---

# 会话管理

URL: /zh-Hans/documentation/caas/auth_session_manager/retrieve_session

创建认证会话后，只需使用生成的链接启动用户注册流程。这可以通过发送链接或直接在您的网站上使用（借助 `iframe` 等工具）来实现。

## 返回对象

创建和获取 `auth_session` 的返回对象包含以下信息：

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",
  }
```

此对象在会话获取端点返回：

`GET https://api.caas.qitech.app/auth_session_manager/auth_session/{id}`

响应字段描述：

名称 | 类型 | 描述
:----: | :----: | ---------
id | string | 会话 ID。
status | string | 会话状态。
expiration_date | date | 会话过期日期。超过此日期后，会话将失效。
step_data | object | 会话事件的返回对象。
settings | object | 会话配置对象。
auth_session_hash | string | 会话标识哈希值。
step | string | 用户当前所处步骤。
auth_session_url | string | 能够收集注册信息的 URL。
token | string | 会话认证令牌。
token_expiration_date | date | 临时认证令牌的过期日期。默认设置为会话生成后 2 小时。

### 状态

可能的状态：

* pending
* completed
* expired

### step_data 对象

包含每个步骤收集数据的对象。

:::info 信息
如果步骤未列在会话的 settings 中，则该步骤不会作为 `step_data` 对象的字段出现
:::

`face_recognition`

名称 | 类型 | 描述
---- | ---- | ---------
image_key | string | face_recognition 步骤的标识密钥。
event_date | date | 步骤完成日期。

`personal_document`

名称 | 类型 | 描述
---- | ---- | ---------
document_template | string | 用户在文件收集时选择的模板。
ocr_keys | list | 每个收集文件的标识密钥列表。
event_date | date | 步骤完成日期。

`device_scan`

名称 | 类型 | 描述
---- | ---- | ---------
session_id | string | 设备扫描步骤的标识密钥。
event_date | date | 步骤完成日期。

## 网页流程认证

为了给应用程序提供更高的安全性，我们为网页返回临时令牌。
可以通过以下端点获取令牌或生成新令牌：

`POST https://api.caas.qitech.app/auth_session_manager/auth_session/{id}/token`

Request Body

```json
  {
    "token_expiration_seconds": 3600
  }
```

令牌对象只有一个可选字段：

名称 | 类型 | 描述
---- | ---- | ---------
token_expiration_seconds | integer | 会话令牌的过期时间（秒）。（必须在 1 到 172800 之间，最大 48 小时。默认值为 1800）

Response Body

```json
  {
    "id": "12345678",
    "token": "e7e99a40-0b26-4bb9-a068-9fa4886eeef3",
    "token_expiration_date": "2025-12-10T13:37:15.12-03:00",
  }
```

因此，如果令牌已过期，可以通过生成新令牌继续认证会话。

# Webhook

会话完成将通过发送 Webhook 进行通知。为此，需要通过[支持](mailto:suporte.caas@qitech.com.br)团队配置一个端点地址，我们将通过该地址通知更新，以及一个用于签名请求的 *signature_key*。请注意，所有 Webhook 发送均将发送到单个端点。

:::info **注意**

出于安全原因，所有 Webhook 请求将仅发送到通过 HTTPS 提供服务的端点。
:::

## 与网页通信

网页可以通过名为 `iframe` 的工具集成，方式如下：

```html
<iframe id="iframe" src="" href="{auth_session_url}" allow="camera; microphone" referrerPolicy="no-referrer"></iframe>
```

> ⚠️ **必要配置**
>
> 为使 iframe 在**生产环境**（`auth-session.caas.qitech.app`）和**沙盒环境**（`auth-session.sandbox.caas.qitech.app`）中正常运行，需要配置以下 Permissions-Policy header：
>
> **使用特定 URL 的配置（推荐）：**
> ```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\")"
> }
> ```
>
> **替代配置（限制较少）：**
> ```json
> {
>   "key": "Permissions-Policy",
>   "value": "geolocation=*, microphone=*, camera=*, fullscreen=()"
> }
> ```
>
> 此配置必须应用于托管包含 iframe 的页面的服务器，以确保授予所需权限。

如果以这种方式调用链接，网页将向请求它的页面发送回调消息。可能的回调消息为：

* success
* canceled
* invalid_token
* expired

可以通过以下方式访问：

```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
            }
        });
```

## 流程完成

此服务将管理认证数据收集流程，收集的数据可在其他服务中使用。
有关如何在其他产品中使用返回密钥的更多信息，请参阅自然人注册分析示例 [注册分析](/documentation/caas/onboarding/query_registration)

---

# authentication

URL: /zh-Hans/documentation/caas/banking/authentication

## 认证

> 要认证一次调用，请使用以下代码：

```shell
# 在 shell 中，您只需在每个请求中添加适当的 header
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE_API_KEY"
```

> 请将 API Key 'EXAMPLE_API_KEY' 替换为您从我们支持团队获取的密钥。

我们使用 API Key 来允许访问我们的 API。它可能已经通过电子邮件发送给您。如果您尚未收到密钥，请发送电子邮件至 suporte.caas@qitech.com.br 。

我们的 API 期望在所有发送到服务器的请求中，以如下 header 的形式接收 API Key：

`Authorization: EXAMPLE_API_KEY`

:::info **注意**

您必须将 EXAMPLE_API_KEY 替换为从支持团队收到的 API Key。
:::

---

# Boleto

URL: /zh-Hans/documentation/caas/banking/bankslips

当用户执行或接收 Boleto 支付时，支付数据应发送给 QI Tech。这样，可以根据该数据集对操作所涉及的风险进行分析。

## 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"
    }
}
```

Boleto 支付必须在转发到处理系统之前发送到 API，以便进行预先欺诈验证。

支付状态表示模型对该 Boleto 返回的决策。以下状态用于 **analysis_status** 标志：

* `automatically_approved`
* `automatically_reproved`
* `in_manual_analysis`
* `pending`

以下是 analysis_status 标志中返回的每个决策的含义：

状态 | 描述
:----: | ---------
automatically_approved      | 建议批准此 Boleto 支付。
automatically_reproved      | 建议拒绝此 Boleto 支付。
in_manual_analysis          | 建议对此 Boleto 支付进行人工分析。
pending                     | Boleto 支付正在处理中。

名称 | 类型 | 描述
:----:  | :----:  | ---------
id | string | 客户系统中交易的标识符。 **此编号对每个 Boleto 支付必须唯一**
bankslip_direction        | 枚举                | Boleto 支付方式。定义客户是支付 Boleto 还是接收 Boleto 支付。
document_amount         | 整数                   | 文件金额（分）——如"标准"部分所述。
discount_amount          | 整数                   | 对文件金额应用的折扣或减免金额（分）——如"标准"部分所述。
other_deduction_amount  | 整数                   | 对文件金额应用的其他扣除额（分）——如"标准"部分所述。
interest_amount         | 整数                   | 对文件金额应用的罚款、滞纳金或利息金额（分）——如"标准"部分所述。
amount                  | 整数                   | Boleto 最终支付金额——如"标准"部分所述。
bankslip_payment_date     | datetime                  | Boleto 支付的日期和时间，含时区。
bankslip_due_date         | date                      | Boleto 到期日期，符合标准格式
description             | string                    | Boleto 的描述或备注字段。
face_recognition_key    | string                    | 面部识别密钥，如果已通过我们的面部识别 API 进行面部识别。
validation_key          | string                    | 验证密钥，如果已通过我们的验证 API 对客户进行验证测试。
payer                   | *bankslip_payer*            | 表示支付 Boleto 的自然人或法人的对象。
recipient               | *bankslip_recipient*        | 表示 Boleto 受益的自然人或法人的对象。
final_recipient         | *bankslip_recipient*        | 表示 Boleto 最终受益的自然人或法人的对象。
source                  | *source*                  | Source 类型的对象，描述用于 Boleto 支付的应用程序信息。

*bankslip_direction* 的枚举值为：`payed` 和 `received`。

## 发送 Boleto 支付

Request Body

```json
  {
    "id": "12345",
    ...
  }
```

Response Body

```json
  {
    "bankslip_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf",
    "status": "automatically_approved",
    "reason": "rule_decision_enum"
  }
```

要评估 Boleto 支付，只需将 Boleto 类型的对象发送到以下端点：

`POST https://api.caas.qitech.app/bankslip/bankslip`

## 查询 Boleto 支付

Response Body

```json
  {
    "id": "082373263",
    "bankslip_direction": "received",
    ...
  }
```

要检索 Boleto 支付数据，只需向以下端点发送请求：

`GET https://api.caas.qitech.app/bankslip/bankslip/{bankslip_id}`

其中 *bankslip_id* 是发送 Boleto 时在客户系统中使用的交易标识符。

## 更新 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"
  }
```

Boleto 支付创建并分析后，将发送到清算中心进行处理。因此，需要在支付发送时通过以下端点通知支付状态更新：

`PUT https://api.caas.qitech.app/bankslip/bankslip/{bankslip_id}`

这样可以确保我们的数据库保持更新，并能够识别真正易受欺诈影响的 Boleto 支付。

---

# 账单支付

URL: /zh-Hans/documentation/caas/banking/bill_payments

当用户执行账单支付时，支付数据应发送给 QI Tech。这样，可以根据该数据集对操作所涉及的风险进行分析。

## 账单支付对象定义

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"
    }
}
```

账单支付必须在转发到处理系统之前发送到 API，以便进行预先欺诈验证。

支付状态表示模型对该账单返回的决策。以下状态用于 **analysis_status** 标志：

* `automatically_approved`
* `automatically_reproved`
* `in_manual_analysis`
* `pending`

以下是 analysis_status 标志中返回的每个决策的含义：

状态 | 描述
:----: | ---------
automatically_approved      | 建议批准此账单支付。
automatically_reproved      | 建议拒绝此账单支付。
in_manual_analysis          | 建议对此账单支付进行人工分析。
pending                     | 账单支付正在处理中。

名称 | 类型 | 描述
:----:  | :----:  | ---------
id | string | 客户系统中交易的标识符。 **此编号对每个账单支付必须唯一**
document_amount         | 整数                   | 文件金额（分）——如"标准"部分所述。
other_deduction_amount  | 整数                   | 对文件金额应用的其他扣除额（分）——如"标准"部分所述。
interest_amount         | 整数                   | 对文件金额应用的罚款、滞纳金或利息金额（分）——如"标准"部分所述。
amount                  | 整数                   | 账单最终支付金额——如"标准"部分所述。
bill_payment_date     | datetime                  | 账单支付的日期和时间，含时区。
bill_due_date         | date                      | 账单到期日期，符合标准格式
description             | string                    | 账单的描述或备注字段。
face_recognition_key    | string                    | 面部识别密钥，如果已通过我们的面部识别 API 进行面部识别。
validation_key          | string                    | 验证密钥，如果已通过我们的验证 API 对客户进行验证测试。
client                  | *client*                  | 表示客户数据的对象，无论是执行 Boleto 支付还是接收支付的客户。
company                 | *company*                 | 表示该账单对应的特许经营商或服务提供商的对象。
payer                   | *bill_payer*              | 表示支付账单的自然人或法人的对象。
recipient               | *bill_client*             | 表示账单发出对象的自然人或法人的对象。
source                  | *source*                  | Source 类型的对象，描述用于账单支付的应用程序信息。

## 发送账单支付

Request Body

```json
  {
    "id": "12345",
    ...
  }
```

Response Body

```json
  {
    "bill_payment_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf",
    "status": "automatically_approved",
    "reason": "rule_decision_enum"
  }
```

要评估账单支付，只需将 BillPayment 类型的对象发送到以下端点：

`POST https://api.caas.qitech.app/bill_payment/bill_payment`

## 查询账单支付

Response Body

```json
  {
    "id": "082373263",
    "amount": 12979,
    ...
  }
```

要检索账单支付数据，只需向以下端点发送请求：

`GET https://api.caas.qitech.app/bill_payment/bill_payment/{bill_payment_id}`

其中 *bill_payment_id* 是发送账单支付时在客户系统中使用的交易标识符。

## 更新账单支付

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"
  }
```

账单支付创建并分析后，将发送到清算中心进行处理。因此，需要在支付发送时通过以下端点通知支付状态更新：

`PUT https://api.caas.qitech.app/bill_payment/bill_payment/{bill_payment_id}`

这样可以确保我们的数据库保持更新，并能够识别真正易受欺诈影响的支付。

---

# 存款

URL: /zh-Hans/documentation/caas/banking/deposits/introduction

当用户执行存款时，存款数据应发送给 QI Tech。这样，可以根据该数据集对操作所涉及的欺诈风险和反洗钱风险进行分析。

## 存款对象定义

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
    }
}
```

存款必须在转发到处理系统之前发送到 API，以便进行预先欺诈验证。

存款状态表示模型对该账户返回的决策。以下状态用于 **analysis_status** 标志：

* `automatically_approved`
* `automatically_reproved`

以下是 analysis_status 标志中返回的每个决策的含义：

状态 | 描述
:----: | ---------
automatically_approved      | 建议批准此存款。
automatically_reproved      | 建议拒绝此存款。

名称 | 类型 | 描述
:----:  | :----:  | ---------
id | string | 客户系统中存款的标识符。 **此编号对每笔存款必须唯一**
amount                      | integer                   | 存款金额（分）——如"标准"部分所述。
deposit_date                | datetime                  | 存款执行的日期和时间——如"标准"部分所述。
client                      | *client*                  | 包含来源账户持有人数据的对象。
destination_account         | *account*                 | 确定待存款资金目标账户的对象。
terminal                    | *terminal*                | 包含执行存款的终端数据的对象。
authentication              | *authentication*          | 包含认证信息的对象。

## 存款相关对象

### 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"
}
```

表示用于存款的终端的对象。

名称 | 类型 | 描述
:----:  | :----:  | ---------
id                          | string                    | 客户系统中终端的标识符
latitude                    | number                    | 终端位置的纬度（度）
longitude                   | number                    | 终端位置的经度（度）
address                     | *address*                 | 终端地址
type                        | 枚举                      | 终端类型，可能值："atm"、"counter"

### Authentication 对象

Request Body

```json
{
    "used_password": true,
    "used_card": true,
    "used_fingerprint": true,
    "typed_account_number": false
}
```

定义存款时使用的认证参数的对象。

名称 | 类型 | 描述
:----: | :----: | -----------
used_password               | boolean                           | 确定用户是否使用了密码
used_card                   | boolean                           | 确定用户在认证时是否携带卡片
used_card_chip_and_pin      | boolean                           | 确定用户是否使用了芯片和密码
used_card_magnetic_stripe   | boolean                           | 确定用户是否使用了磁条
used_fingerprint            | boolean                           | 确定用户是否使用了指纹
typed_account_number        | boolean                           | 确定用户是否输入了账户数据

## 发送存款

Request Body

```json
  {
    "id": "12345",
    ...
  }
```

Response Body

```json
  {
		"id": "082373263",
    "analysis_status": "automatically_approved",
    "reason": "2019-10-01T10:37:25-03:00"
  }
```

要评估存款，只需将 deposit 类型的对象发送到以下端点：

`POST https://api.caas.qitech.app/deposit/deposit`

## 查询存款

Response Body

```json
  {
		"id": "082373263",
    "analysis_status": "automatically_approved",
    "reason": "2019-10-01T10:37:25-03:00"
  }
```

要检索存款数据，只需向以下端点发送请求：

`GET https://api.caas.qitech.app/deposit/deposit/{deposit_id}`

其中 *deposit_id* 是发送存款时在客户系统中使用的交易标识符。

## 更新存款

Request Body

```json
  {
    "deposit_status": "completed",
    "event_date": "2020-10-07T15:06:25-03:00"
  }
```

Response Body

```json
  {
		"id": "082373263",
    "deposit_status": "completed"
  }
```

存款创建并分析后，资金将提供给用户。此流程可能因其他业务规则而中断。因此，需要在取款完成时通过以下端点通知取款状态更新：

`PUT https://api.caas.qitech.app/deposit/deposit/{deposit_id}`

这样可以确保我们的数据库保持更新，并能够识别真正易受欺诈影响的存款。

---

# HTTP 状态码

URL: /zh-Hans/documentation/caas/banking/http_status

QI Tech 的所有 API 均遵循以下 HTTP 返回状态码标准，符合 RFC 7231 ：

HTTP 状态码 | 含义 | 描述
---------- | ------- | ---------------------------------
400 | Bad Request | 发送的请求存在格式错误。在大多数情况下，我们会在消息体中说明错误所在。
401 | Unauthorized | 认证出现问题，请检查 API Key 是否正确且在正确的 header 中，参见 认证 部分。
403 | Forbidden | 访问的端点为内部使用，此 API Key 无法访问。
404 | Not Found | 使用该密钥未找到所请求的数据。当请求无效端点时也会返回此状态。
405 | Method Not Allowed | 所使用的 HTTP 方法不适用于该端点。
406 | Not Acceptable | 请求体中发送的数据无效。通常表示发送的数据不是有效的 JSON。
409 | Conflict | 请求 ID 对应之前已处理过的 ID。当向服务器发送重复请求时返回此状态。
500 | Internal Server Error | 我们在处理此请求时遇到问题，一旦出现此错误，我们的专家将自动收到通知并立即开始分析和解决。
503 | Service Unavailable | 您遇到了计划内或计划外的服务器基础设施不可用情况。

---

# 简介

URL: /zh-Hans/documentation/caas/banking/introduction

欢迎使用 QI Tech Banking API！此 API 为银行和数字账户操作提供欺诈预防功能，例如转账分析、账单支付和 Boleto 支付。

以下，您可以看到使用 cUrl 的 API 实现。这样，您就有了示例，可以根据自己喜欢的编程语言进行适当调整。

## 遇到问题？

我们不是躲在 API 后面的公司！请联系我们的 支持团队 ，我们将尽快回复。如果您需要快速回复，请随时致电我们！

### 我们热爱反馈

即使您已经解决了问题，或者问题非常简单（甚至是您发现的一个错别字或不当的组织方式），也请给我们发电子邮件，这样我们可以让文档变得越来越实用，下一个人就不必经历您所经历的痛苦！

## 环境

我们为客户提供两个环境。API 的基本 URL 为：

* 生产环境 - `https://api.caas.qitech.app/`
* 沙盒环境 - `https://api.sandbox.caas.qitech.app/`

:::danger 重要提示！
不得在 QI Tech 沙盒环境中使用真实的个人和/或法人数据。
:::

## 沙盒环境中的分析

在沙盒环境中，分析不计费，并根据简化的规则进行响应。
对于 *wire_transfers*、*bankslips*、*bill_payments* 和 *pix* 的情况，返回的响应将基于请求中发送的操作金额（*amount*）：

最小值 | 最大值 | 决策
------ | ------ | -------
16000 | - | 自动挑战*
10000 | 15999 | 自动批准
6000 | 9999 | 转人工分析
0 | 5999 | 自动拒绝

\* 自动挑战仅适用于 *pix* 服务。

对于 *withdrawal* 和 *deposit* 的情况，返回的响应将基于请求中发送的操作金额（*amount*）：

最小值 | 最大值 | 决策
------ | ------ | -------
10000 | - | 自动批准
0 | 9999 | 自动拒绝

对于 DICT 操作，返回的响应将基于请求中发送的 DICT 绑定密钥（*dict_key*）：

DICT 中的密钥 | 决策
:----------: | -------
"Approve_dict_key"      | 自动批准
任何其他字符串   | 转人工分析
"Reprove_dict_key"      | 自动拒绝

## 仅限 HTTPS

出于安全原因，与 QI Tech API 的所有通信必须使用 HTTPS 协议。为避免因疏忽或其他原因发出 HTTP 调用，此服务器仅提供使用 TLS 1.2 通信的 443 端口。使用其他协议发出的调用将自动被拒绝。

## 流程 - 转账

转账分析流程在两种情况下启动：

- PSP 用户正在执行转账
- PSP 用户正在接收转账

在这两种情况下，都必须调用 *wire_transfer* 端点，可能的结果状态为：

枚举值 | 描述
:--------: | ---------
automatically_approved | 自动批准
automatically_reproved | 自动拒绝
in_manual_analysis     | 转人工分析
pending                | 银行转账对象正在处理中。

如果转账转为人工分析，分析师须批准或拒绝该转账。此时，可以生成 Webhook 向 PSP 通知状态变化，或 PSP 可通过 Polling 跟踪转账进度。在这两种情况下，可以返回以下状态：

枚举值 | 描述
:--------: | ---------
manually_approved | 人工批准
manually_reproved | 人工拒绝

## 流程 - Boletos

Boleto 分析流程在两种情况下启动：

- PSP 用户正在执行 Boleto 支付
- PSP 用户正在接收 Boleto 支付

在这两种情况下，都必须调用 *bankslip* 端点，可能的结果状态为：

枚举值 | 描述
:--------: | ---------
automatically_approved | 自动批准
automatically_reproved | 自动拒绝
in_manual_analysis     | 转人工分析
pending                | Boleto 对象正在处理中。

如果 Boleto 支付转为人工分析，分析师须批准或拒绝该支付。此时，可以生成 Webhook 向 PSP 通知状态变化，或 PSP 可通过 Polling 跟踪支付进度。在这两种情况下，可以返回以下状态：

枚举值 | 描述
:--------: | ---------
manually_approved | 人工批准
manually_reproved | 人工拒绝

## 流程 - 账单支付

账单支付分析流程在以下情况下启动：

- PSP 用户正在执行账单支付

在这种情况下，必须调用 *bill_payment* 端点，可能的结果状态为：

枚举值 | 描述
:--------: | ---------
automatically_approved | 自动批准
automatically_reproved | 自动拒绝
in_manual_analysis     | 转人工分析
pending                | 账单支付对象正在处理中。

如果账单支付转为人工分析，分析师须批准或拒绝该支付。此时，可以生成 Webhook 向 PSP 通知状态变化，或 PSP 可通过 Polling 跟踪支付进度。在这两种情况下，可以返回以下状态：

枚举值 | 描述
:--------: | ---------
manually_approved | 人工批准
manually_reproved | 人工拒绝

## 流程 - 取款

取款分析流程在以下情况下启动：

- PSP 用户正在执行取款

在这两种情况下，都必须调用 *withdrawal* 端点，可能的结果状态为：

枚举值 | 描述
:--------: | ---------
automatically_approved | 自动批准
automatically_reproved | 自动拒绝

如果取款转为人工分析，分析师须批准或拒绝该取款。此时，可以生成 Webhook 向 PSP 通知状态变化，或 PSP 可通过 Polling 跟踪支付进度。在这两种情况下，可以返回以下状态：

枚举值 | 描述
:--------: | ---------
manually_approved | 人工批准
manually_reproved | 人工拒绝

## 流程 - PIX 交易

PIX 支付流程在两种情况下启动：

- 集成到 QI Tech 的 PSP 用户正在执行支付
- 从另一个 PSP 接收支付

在这两种情况下，都必须调用支付端点，可能的结果状态为：

枚举值 | 描述
:--------: | ---------
automatically_approved | 自动批准
automatically_reproved | 自动拒绝
in_manual_analysis     | 转人工分析

如果支付转为人工分析，分析师须批准或拒绝该支付。此时，可以生成 Webhook 向 PSP 通知状态变化，或 PSP 可通过 Polling 跟踪支付进度。在这两种情况下，可以返回以下状态：

枚举值 | 描述
:--------: | ---------
manually_approved | 人工批准
manually_reproved | 人工拒绝

## 流程 - DICT 变更

DICT 变更流程在两种情况下启动：

- 集成到 QI Tech 的 PSP 用户向集成到 QI Tech 的 PSP 请求注册/变更/可携带性/申领
- 集成到 QI Tech 的 PSP 收到可携带性/申领

对于由 PSP 用户发起的注册，在 DICT 中进行变更之前，必须通过 QI Tech 的验证 API 执行密钥验证流程。如果验证由 PSP 自己执行，也可以在向 QI Tech 的请求中发送此信息。

要启动该流程，在这两种情况下，集成到 QI Tech 的 PSP 都必须在相应端点调用，响应以下状态之一：

枚举值 | 描述
:--------: | ---------
automatically_approved | 自动批准
automatically_reproved | 自动拒绝
in_manual_analysis     | 转人工分析

如果变更转为人工分析，分析师须批准或拒绝该变更。此时，可以生成 Webhook 向 PSP 通知状态变化，或 PSP 可通过 Polling 跟踪变更进度。在这两种情况下，可以返回以下状态：

枚举值 | 描述
:--------: | ---------
manually_approved | 人工批准
manually_reproved | 人工拒绝
## 认证

> 要认证一次调用，请使用以下代码：

```shell
# 在 shell 中，您只需在每个请求中添加适当的 header
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE_API_KEY"
```

> 请将 API Key 'EXAMPLE_API_KEY' 替换为您从我们支持团队获取的密钥。

我们使用 API Key 来允许访问我们的 API。它可能已经通过电子邮件发送给您。如果您尚未收到密钥，请发送电子邮件至 suporte.caas@qitech.com.br 。

我们的 API 期望在所有发送到服务器的请求中，以如下 header 的形式接收 API Key：

`Authorization: EXAMPLE_API_KEY`

:::info **注意**

您必须将 EXAMPLE_API_KEY 替换为从支持团队收到的 API Key。
:::

---

# 共享对象

URL: /zh-Hans/documentation/caas/banking/objects

大量数据在账户的不同事件之间共享。以下可以方便地找到这些对象的定义。

## 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é"
}
```

表示账户持有人数据的对象。

名称 | 类型 | 描述
:----:  | :----:  | ---------
type                        | 枚举 *（必填）* | 客户类型："natural_person" 或 "legal_person"
document_number             | string *（必填）* | 文件编号，符合标准化部分
name                        | string *（必填）* | 客户姓名
email                       | string                    | 客户电子邮件
address                     | *address*                 | 客户地址数据
phone                       | *phone*                   | 客户电话数据
sales_channel               | 枚举 *（必填）*| 客户注册的渠道
segment                     | string *（必填）*| 客户在机构内的细分（例如：premium、gold）

电话类型的枚举值为：`inbound_sales`、`app`、`website`、`call_center` 和 `branch`

## 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"
}
```

*address* 对象用于在整个 API 中表示地址，巴西境内地址的表示方式如下：

名称 | 类型 | 描述
---- | :----: | ---------
street | string *（必填）* | 地址的街道，包括公路名称，尽可能避免缩写。
number | string  *（必填）* | 物业编号，如有字母则包含字母。
neighbourhood | string *（必填）*| 区域，不缩写。 **例如：Santa Felicidade**
city | string *（必填）*| 城市全名，不缩写
uf | string *（必填）* | 联邦单位，两个大写字母。 **例如：SP**
complement | string | 用于定位物业的任何补充信息。 **例如：Apartamento 101, Conjunto 12**
postal_code  | string *（必填）* | 该地点的邮政编码，含连字符。
country | string *（必填）* | 地址国家的 ISO 3166-1 alpha-3 代码。

对于国家不是巴西（"BRA"）的地址，postal_code 和联邦单位可以自由填写。

## Phone 对象

Request Body

```json
{
  "international_dial_code": "1",
  "area_code": "11",
  "number": "999999999",
  "type": "mobile"
}
```

*phone* 对象表示巴西境内或境外的电话号码及其分类。字段如下：

名称 | 类型 | 描述
---- | :----: | ---------
international_dial_code | string *（必填）* | 国际拨号代码，不含零或加号，仅数字
area_code | string *（必填）* | 区号，不含零，仅数字
number | string  *（必填）* | 电话号码，不含连字符
type | 枚举  *（必填）* | 号码类型：手机、住宅、商务等。

电话类型的枚举值为：`residential`、`commercial` 和 `mobile`。

## 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"
}
```

表示账户数据的对象。

名称 | 类型 | 描述
:----:  | :----:  | ---------
participant                 | string *（必填）* | 账户所属机构的 ISPB
branch                      | string *（必填）* | 账户支行
account_number              | string *（必填）* | 不含校验位的账户号码
account_digit               | string *（必填）* | 账户校验位
account_type                | 枚举 *（必填）* | 来源账户类型，可能值："CACC"、"SLRY" 和 "SVGS"
opening_date                | datetime | 账户开户日期。

## Source 对象

Request Body

```json

{
    "channel": "app",
    "platform": "android",
    "ip":"255.201.26.1",
    "session_id": "54b8e3cf-15de-41e5-9305-0ecf059d6e2a"
}

```

source 对象表示用户用于执行操作的平台信息集合。字段如下：

名称 | 类型 | 描述
:----: | :----: | ---------
channel     | string | 用户执行操作使用的渠道，例如：网银、app
platform    | string | 应用程序使用的平台
ip          | string | 从设备收集的 IP
session_id  | string | 会话的唯一标识符，用于将 Device Scan 与相关事件关联

## Dict Key 对象

Request Body

```json
  {
    "key_type": "cpf",
    "key_value": "09991222669",
    "assignment_date": "2020-01-15T18:00:00-03:00"
  }
```

**dict_key** 对象用于表示客户（无论是收款人还是付款人）在 DICT 中的绑定密钥数据。该对象的字段为：

名称 | 类型 | 描述
:----: | :----: | ---------
key_type        | string *（必填）* | 包含 DICT 中绑定密钥类型的枚举值。
key_value       | string | 包含在 DICT 中注册的绑定密钥。
assignment_date | datetime  | 绑定密钥在 DICT 中注册的日期。

*key_type* 字段的枚举值与 DICT API 中定义的相同：`cpf`、`cnpj`、`email`、`phone` 和 `evp`。

## 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
      }
  }
}
```

为了更准确地评估交易中的欺诈风险，需要通过 *Destination Statistics* 对象提供被入账方的交易和欺诈历史。此类数据可通过在 DICT 数据库中查询被入账方的绑定密钥获得。BACEN 要求在交易欺诈评估中使用这些数据。

名称 | 类型 | 描述
:----: | :----: | ---------
account | *account* *（必填）* | 包含被入账方账户交易和欺诈历史的对象。
owner   | *owner* *（必填）* | 包含与被入账方文件关联的交易和欺诈历史的对象。
key     | *key* *（必填）* | 包含与被入账方提供的密钥关联的交易和欺诈历史的对象。

上述每个对象具有相同的字段：

名称 | 类型 | 描述
:----: | :----: | ---------
settlements       | *settlements* *（必填）*   | 包含交易历史的对象。
rejected          | *rejected* *（可选）*   | 包含被拒绝操作历史的对象。
reported_frauds   | *reported_frauds*  *（必填）* | 包含欺诈举报历史的对象。
reported_aml_cft  | *reported_aml_cft* *（可选）* | 包含 PLD/FT 举报历史的对象。
confirmed_frauds  | *confirmed_frauds* *（必填）* | 包含已确认欺诈举报历史的对象。
confirmed_aml_cft | *confirmed_aml_cft* *（可选）* | 包含已确认 PLD/FT 举报历史的对象。

其中每个对象包含 **d3**、**d30** 和 **m6** 字段，分别包含过去 3 天、30 天和 6 个月的发生次数，均为必填字段。与 BCB DICT API 定义的方式相同。

---

# PIX Dict Operation

URL: /zh-Hans/documentation/caas/banking/pix_dict_operations

当用户发起 DICT 变更时，数据应发送到我们的服务器，以便我们对该数据集所涉及的风险进行分析。

## 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"
  }
}
```

Dict Operation 必须在转发到 BCB 处理系统之前发送到 API，以便进行注册预先欺诈验证。

Dict Operation 分析状态表示模型对该操作返回的决策。以下状态用于 **analysis_status** 标志：

* `automatically_approved`
* `automatically_reproved`
* `in_manual_analysis`
* `pending`

以下是 analysis_status 标志中返回的每个决策的含义：

状态 | 描述
:----: | ---------
automatically_approved      | 建议批准此操作。
automatically_reproved      | 建议拒绝此操作。
in_manual_analysis          | 建议由分析师对该操作进行人工分析。
pending                     | 操作正在处理中。

名称 | 类型 | 描述
:----:  | :----:  | ---------
id | string | 客户系统中操作的标识符。 **此编号对每个授权流程必须唯一**
client                  | *client*                  | 表示客户数据的对象，无论是捐赠方还是接收方。
transaction_date        | datetime                  | 交易开始的日期和时间，含时区。
dict_key                | *dict_key*                | 表示客户在交易中使用的 DICT 绑定密钥数据的对象。
dict_key_type           | 枚举                | DICT 绑定密钥类型。
dict_operation_direction| 枚举                | DICT 中的操作方向，即密钥是被转让还是被获取。
dict_operation_reason   | 枚举                | 执行 Dict 操作的原因。
dict_operation_creation_date     | datetime                  | DICT 中操作的日期。
dict_operation_type     | 枚举                | DICT 中操作的类型。
source_account          | *source_account*          | 表示正在转让绑定密钥的账户数据的对象。
destination_account     | *destination_account*     | 表示正在接收绑定密钥的账户数据的对象。
destination_statistics  | *destination_statistics*  | 表示正在接收绑定密钥的账户的交易和欺诈历史的对象。
source                  | *source*                  | Source 类型的对象，描述用于发送注册的应用程序信息

*dict_key_type* 字段接受与 DICT API 中定义的相同枚举值：`cpf`、`cnpj`、`email`、`phone` 和 `evp`。

*dict_operation_direction* 字段接受枚举值：`donor` 和 `claimer`。

*dict_operation_type* 字段接受枚举值 `registration`、`claim_ownership` 和 `claim_portability`。
这些是 BCB 定义的 DICT 中所有操作类型。

## 发送 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"
  }
```

要评估支付，只需将 Payment 类型的对象发送到以下端点：

`POST https://api.caas.qitech.app/pix/dict_operation`

## 查询 Dict Operation

Response Body

```json
  {
    "id": "f58e8a19-429d-4e36-a010-ed00a323c2c5",
    ...
  }
```

要查询 Dict Operation，只需向以下端点发送请求：

`GET https://api.caas.qitech.app/pix/dict_operation/{dict_operation_id}`

其中 *dict_operation_id* 是在注册时发送给我们的操作标识符，位于 "id" 字段中。

随后将返回与提供的密钥关联的 Dict Operation 对象。

## 更新 Dict Operation

Request Body

```json
  {
    "dict_operation_status": "cancelled_by_client",
    "reason": "user_requested",
    "event_date": "2020-10-07T15:06:25-03:00"
  }
```

Dict Operation 在 BCB 完成前有多个阶段。因此，需要通过以下端点通知操作的所有状态更新：

`PUT https://api.caas.qitech.app/pix/dict_operation/{dict_operation_id}`

这样可以确保我们的数据库保持更新，与 BCB 数据库始终保持一致。

某些 DICT 操作要求随数据一起提交操作原因。对于这些情况，需要在发送对象中填写 *reason* 字段，包含向 BCB 系统提供的相同枚举值。
这些枚举值为：

枚举值 | 描述
:--------: | ---------
user_requested    | 操作由客户请求。
account_closure   | 操作因客户账户关闭而发起。
branch_transfer   | 操作因客户支行变更而请求。
entry_inactivity  | 操作因客户账户不活跃而请求。
reconciliation    | 操作在对账流程后请求。
default_operation | 操作由参与方的默认操作请求。
fraud             | 操作因与客户账户相关的欺诈而请求。

*dict_operation_status* 字段接受的操作阶段如下：

枚举值 | 描述
:--------: | ---------
created                   | dict_operation 已创建但尚未分析。
reproved                  | dict_operation 在分析中被拒绝，不会发送给 BCB。
waiting_resolution        | dict_operation 已发送给 BCB，等待解决。
cancelled_by_client       | dict_operation 被客户取消。
cancelled_by_counterpart  | dict_operation 被操作对方取消。
confirmed                 | dict_operation 已被操作对方确认。
completed                 | dict_operation 已完成并添加到 BCB 数据库。

---

# PIX Infraction Report

URL: /zh-Hans/documentation/caas/banking/pix_infraction_reports

## 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"
        }
    ]
}
```

如果交易任何一方发现可疑行为，可以创建 Infraction Report 来举报该嫌疑。该 Infraction Report 随后将由对方分析并决定是否确认。根据 BCB 的标准，Infraction Report 应具有以下字段：

名称 | 类型 | 描述
:----: | :----: | ---------
infraction_report_type      | 枚举 | 定义交易中存在的可疑活动类型的枚举值。
infraction_report_details   | string     | 导致 Infraction Report 创建者认为交易可能存在某种违规的情况详情。
infraction_report_creator   | 枚举 | 定义 Infraction Report 创建者的枚举值。
infraction_report_date      | datetime   | 事件日期。

*infraction_report_type* 字段可包含枚举值：`fraud` 和 `compliance`。

*infraction_report_creator* 字段可包含枚举值：`client` 和 `external`。

## 发送 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"
  }
```

要发送 Infraction Report，只需向以下端点发送请求：

`POST https://api.caas.qitech.app/pix/transaction/{transaction_id}/infraction_report`

其中 *transaction_id* 是在注册时发送给我们的交易标识符，位于 "id" 字段中。

## 查询 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",
        ...
      }
  }
```

要查询 Infraction Report，只需向以下端点发送请求：

`GET https://api.caas.qitech.app/pix/transaction/{transaction_id}/infraction_report/{infraction_report_key}`

随后将返回与提供的 *transaction_id* 关联且 *infraction_report_key* 与发送的密钥相同的 Infraction Report 对象。

## 更新 Infraction Report

Request Body

```json
  {
    "infraction_report_status": "acknowledged",
    "event_date": "2020-10-07T15:06:25-03:00"
  }
```

Infraction Report 在 BCB 完成前有多个阶段。因此，需要通过以下端点通知 Infraction Report 的所有状态更新：

`PUT https://api.caas.qitech.app/pix/transaction/{transaction_id}/infraction_report/{infraction_report_key}`

---

# PIX Transaction

URL: /zh-Hans/documentation/caas/banking/pix_transactions

当付款人发起或接收支付时，交易数据应发送到我们的服务器。这样，可以根据该数据集对交易所涉及的风险进行分析。

## 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"
    }
}
```

交易必须在转发到处理系统之前发送到 API，以便进行预先欺诈验证。

交易状态表示模型对该交易返回的决策。以下状态用于 **analysis_status** 标志：

* `automatically_approved`
* `automatically_reproved`
* `in_manual_analysis`
* `pending`

以下是 analysis_status 标志中返回的每个决策的含义：

状态 | 描述
:----: | ---------
automatically_approved      | 建议批准此交易。
automatically_reproved      | 建议拒绝此交易。
approved_by_time            | 交易因人工分析时间到期而被批准
reproved_by_time            | 交易因人工分析时间到期而被批准
in_manual_analysis          | 建议由分析师对该交易进行人工分析。
pending                     | 交易正在处理中。

名称 | 类型 | 描述
:----:  | :----:  | ---------
transaction_direction   | 枚举  | 注册交易的类型。定义客户是收款还是付款。*（必填）*
id | string | 客户系统中支付的标识符。 **此编号对每个支付流程必须唯一** *（必填）*
client                  | *client* | 表示客户数据的对象，无论是付款人还是收款人。*（必填）*
amount                  | 整数  | 支付金额，以分为单位——如"标准"部分所述。*（必填）*
pix_modality            | string   | 注册交易的类型。指示是否表示转账、找零或取款。
transaction_date        | datetime | 交易开始的日期和时间，含时区。*（必填）*
dict_key                | *dict_key*                | 表示客户在交易中使用的 DICT 绑定密钥数据的对象。
capture_method          | 枚举 | 用于发起支付的方法，是否通过静态或动态 QR Code、数据填写或 DICT 密钥。*（必填）*
face_recognition_key    | string                    | 面部识别密钥，如果已通过我们的面部识别 API 进行面部识别。
validation_key          | string                    | 验证密钥，如果已通过我们的验证 API 对客户进行验证测试。
source_account          | *source_account* | 表示被扣款账户数据的对象。*（必填）*
destination_account     | *destination_account* | 表示被入账账户数据的对象。*（必填）*
destination_statistics  | *destination_statistics*  | 表示来自 BACEN DICT API 的被入账账户交易和欺诈历史的对象。*（必填）*
source                  | *source* | Source 类型的对象，描述用于发送支付的应用程序信息

*transaction_direction* 的枚举值为：`sent` 和 `received`。

*pix_modality* 的枚举值为：`transacation`、`change` 和 `withdraw`。

*capture_method* 的枚举值为：`static_qr_code`、`dynamic_qr_code`、`offline_qr_code`、`typed`。

## 发送交易

Request Body

```json
  {
    "id": "12345",
    ...
  }
```

Response Body

```json
  {
    "transaction_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf",
    "analysis_status": "automatically_approved",
    "reason": "rule_decision_enum"
  }
```

要评估交易，只需将 Transaction 类型的对象发送到以下端点：

`POST https://api.caas.qitech.app/pix/transaction`

## 查询交易

Response Body

```json
  {
    "transaction_direction": "received",
    "id": "082373263",
    ...
  }
```

要检索交易数据，只需向以下端点发送请求：

`GET https://api.caas.qitech.app/pix/transaction/{transaction_id}`

其中 *transaction_id* 是在注册时发送给我们的交易标识符，位于 "id" 字段中。

## 更新交易

Request Body

```json
  {
    "transaction_status": "sent",
    "event_date": "2020-10-07T15:06:25-03:00"
  }
```

交易创建并分析后，应发送给 BCB 进行处理。因此，需要在交易发送给 BCB 时通过以下端点通知交易状态更新：

`PUT https://api.caas.qitech.app/pix/transaction/{transaction_id}`

这样可以确保我们的数据库保持更新，与 BCB 数据库始终保持一致。

## 未完成的交易

Request Body

```json
  {
    "transaction_status": "cancelled",
    "reason": "refused_by_counterpart",
    "event_date": "2020-10-07T15:06:25-03:00"
  }
```

如果交易出于任何原因未能完成（即：未从来源账户扣款并入账到目标账户），可以将交易更新为 `cancelled` 状态，并注明取消原因，以便识别与未完成交易相关的欺诈模式。cancelled 状态只能用于仍处于 created 状态的交易，因为 `sent` 状态用于交易已完成的情况。

`PUT https://api.caas.qitech.app/pix/transaction/{transaction_id}`

API 目前接受以下 reason，如果您认为需要将取消原因归入其他 reason，请联系 suporte.caas@qitech.com.br。

reason | 描述
:----:  | ---------
insufficient_balance | 客户账户余额不足以完成交易
fraud_prevention | 交易因未通过反欺诈系统而被取消
system_block | 某些系统锁定阻止了交易执行，例如账户已注销/不活跃或已达到限额
invalid_destination | 对方机构因目标账户不存在而拒绝了交易
refused_by_counterpart | 对方机构拒绝了交易
system_error | 交易因机构自身系统错误而被取消
invalid_authentication | 交易因客户未通过某个认证流程而被取消

---

# 标准

URL: /zh-Hans/documentation/caas/banking/standards

为便于集成并保证信息完整性，整个 API 遵循以下已定义的标准。

## 货币金额
> 示例：

```
10000
12345
98741
1223
1
0
```

金额必须以分为单位作为整数发送。

## 带时区的日期和时间
> 一些示例：

```
2019-10-15T22:35:12-03:00
2018-05-01T13:32:11+00:00
2019-05-01T00:00:00+00:00
```

按照 ISO 8601 表示。在这种情况下，时区紧跟在时间之后，必须表示该数据有效的地点的时区。例如，如果租约计划在巴西利亚机场于 09:30 开始，发送的时间应表示为 09:30-03:00；如果租约计划在马瑙斯于 09:30 开始，则应表示为 09:30-04:00。

用于验证的掩码如下：

`YYYY-MM-ddThh:mm:ss±hh:mm`

## 不带时区的日期和时间
> 一些示例：

```
2019-10-15T22:35:12Z
2018-05-01T13:32:11Z
2019-05-01T00:00:00Z
```

按照 ISO 8601 表示。与时区无关的数据应不带时区发送，始终以 UTC 表示，字母 Z 表示该数据为 UTC。因此，将验证以下格式：

`YYYY-MM-ddThh:mm:ssZ`

## 日期
> 一些示例

``` 
2019-10-15
2019-01-01
2017-03-20
```

对于只接收日期的字段（例如出生日期），应不包含任何时间，使用以下格式发送：

`YYYY-MM-dd`

---

# Webhook

URL: /zh-Hans/documentation/caas/banking/webhook

欺诈状态更新（对于转入人工分析或响应为待处理的事件）通过 Webhook 通知。为此，需要通过[支持](mailto:suporte.caas@qitech.com.br)团队配置一个端点地址，我们将通过该地址通知更新，以及一个用于签名请求的 *signature_key*。

客户也可以使用[轮询](https://en.wikipedia.org/wiki/Polling_(computer_science))技术。在这种情况下，只需不配置 Webhook 端点，并使用查询端点进行轮询即可。

:::info **注意**

出于安全原因，所有 Webhook 请求将仅发送到通过 HTTPS 提供服务的端点。
:::

## 签名

> Python 签名计算示例

```python
    hmac_obj = hmac.new(signature_key.encode('utf-8'), (url + method + payload).encode('utf-8'), hashlib.sha1)
    return hmac_obj.hexdigest()
```

为确保在 Webhook 端点收到的请求来自我们的服务器，HMAC 签名将在 *Signature* Header 中发送，方式与认证过程类似。

在服务器端计算签名的预期值后，需要将计算的签名与发送的签名进行比较。如果签名匹配，则表示请求来自我们的服务器且可信。

## 事件更新 Webhook

Request Body

```json
    {
        "id": "123456",
        "analysis_status": "automatically_approved",
        "event_date": "2019-10-01T10:37:25-03:00"
    }
```

事件分析状态更新请求采用上述格式，并通知欺诈状态的变化。使用的方法为 PUT，端点地址根据客户需求也可包含事件 ID。需要注意的是，请求体以 UTF-8 编码的文本形式发送。

事件更新端点示例：

* https://apidocliente.com.br/\{evento\}
* https://apidocliente.com.br/admin/\{evento\}/123456

请求 URL 中的 \{evento\} 字段可以根据正在通知的事件取以下值：
* bill_payment
* bankslip
* wire_transfer
* withdrawal
* pix

event_date 字段表示通知创建的日期和时间，如果之前的通知发送失败，可能是过去的时间。

## 重试

当收到 HTTP 状态码 200 作为响应时，通知视为已完成。如果通知失败，将进行 7 次重试，重试间隔如下，直到返回 200 或重试结束：

* 10 秒
* 40 秒
* 160 秒
* 640 秒
* 2560 秒
* 10240 秒
* 40960 秒

---

# 转账

URL: /zh-Hans/documentation/caas/banking/wire_transfers

当用户执行或接收转账时，转账数据应发送给 QI Tech。这样，可以根据该数据集对交易所涉及的风险进行分析。

## 转账对象定义

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"
    }
}
```

转账必须在转发到处理系统之前发送到 API，以便进行预先欺诈验证。

转账状态表示模型对该转账返回的决策。以下状态用于 **analysis_status** 标志：

* `automatically_approved`
* `automatically_reproved`
* `in_manual_analysis`
* `pending`

以下是 analysis_status 标志中返回的每个决策的含义：

状态 | 描述
:----: | ---------
automatically_approved      | 建议批准此转账。
automatically_reproved      | 建议拒绝此转账。
in_manual_analysis          | 建议由分析师对该转账进行人工分析。
pending                     | 转账正在处理中。

名称 | 类型 | 描述
:----:  | :----:  | ---------
id | string | 客户系统中交易的标识符。 **此编号对每笔转账必须唯一**
wire_transfer_direction | 枚举                | 注册转账的方式。定义客户是收款还是付款。
wire_transfer_type      | 枚举                | 执行的转账类型，可以是 TED、DOC 或同一机构内账户间的内部转账。
amount                  | 整数                   | 转账金额（分）——如"标准"部分所述。
wire_transfer_date      | datetime                  | 转账开始的日期和时间，含时区。
face_recognition_key    | string                    | 面部识别密钥，如果已通过我们的面部识别 API 进行面部识别。
validation_key          | string                    | 验证密钥，如果已通过我们的验证 API 对客户进行验证测试。
client                  | *client*                  | 表示客户数据的对象，无论是执行转账的客户还是接收方。
source_account          | *source_account*          | 表示被扣款账户数据的对象。
destination_account     | *destination_account*     | 表示被入账账户数据的对象。
source                  | *source* | Source 类型的对象，描述用于发送转账的应用程序信息

*wire_transfer_direction* 的枚举值为：`sent` 和 `received`。

*wire_transfer_type* 的枚举值为：`ted`、`doc`、`internal_transfer`。

## 发送转账

Request Body

```json
  {
    "id": "12345",
    ...
  }
```

Response Body

```json
  {
    "wire_transfer_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf",
    "status": "automatically_approved",
    "reason": "rule_decision_enum"
  }
```

要评估转账，只需将 Wire Transfer 类型的对象发送到以下端点：

`POST https://api.caas.qitech.app/wire_transfer/wire_transfer`

## 查询转账

Response Body

```json
  {
    "id": "082373263",
    "wire_transfer_direction": "received",
    ...
  }
```

要检索转账数据，只需向以下端点发送请求：

`GET https://api.caas.qitech.app/wire_transfer/wire_transfer/{wire_transfer_id}`

其中 *wire_transfer_id* 是发送转账时在客户系统中使用的交易标识符。

## 更新转账

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"
  }
```

转账创建并分析后，将发送到清算中心进行处理。因此，需要在转账发送时通过以下端点通知转账状态更新：

`PUT https://api.caas.qitech.app/wire_transfer/wire_transfer/{wire_transfer_id}`

这样可以确保我们的数据库保持更新，并能够识别真正易受欺诈影响的转账。

---

# 取款

URL: /zh-Hans/documentation/caas/banking/withdrawals

当用户执行取款时，取款数据应发送给 QI Tech。这样，可以根据该数据集对操作所涉及的风险进行分析。

## 取款对象定义

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
    }
}
```

取款必须在转发到处理系统之前发送到 API，以便进行预先欺诈验证。

取款状态表示模型对该账户返回的决策。以下状态用于 **analysis_status** 标志：

* `automatically_approved`
* `automatically_reproved`

以下是 analysis_status 标志中返回的每个决策的含义：

状态 | 描述
:----: | ---------
automatically_approved      | 建议批准此取款。
automatically_reproved      | 建议拒绝此取款。

名称 | 类型 | 描述
:----:  | :----:  | ---------
id | string | 客户系统中取款的标识符。 **此编号对每笔取款必须唯一**
amount                      | 整数                   | 取款金额（分）——如"标准"部分所述。
withdrawal_date             | datetime                  | 取款执行的日期和时间——如"标准"部分所述
source_account              | *account*                 | 确定待取款资金来源账户的对象
client                      | *client*                  | 包含来源账户持有人数据的对象
terminal                    | *terminal*                | 包含执行取款的终端数据的对象
authentication              | *authentication*          | 包含认证信息的对象

## 取款相关对象

### 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"
}
```

表示用于取款的终端的对象。

名称 | 类型 | 描述
:----:  | :----:  | ---------
id                          | string                    | 客户系统中终端的标识符
latitude                    | number                    | 终端位置的纬度（度）
longitude                   | number                    | 终端位置的经度（度）
address                     | *address*                 | 终端地址
type                        | 枚举                      | 终端类型，可能值："atm"、"counter"

### Authentication 对象

Request Body

```json
{
    "used_password": true,
    "used_card": true,
    "used_fingerprint": true,
    "typed_account_number": false
}
```

定义取款时使用的认证参数的对象。

名称 | 类型 | 描述
:----: | :----: | -----------
used_password               | boolean                           | 确定用户是否使用了密码
used_card                   | boolean                           | 确定用户在认证时是否携带卡片
used_card_chip_and_pin      | boolean                           | 确定用户是否使用了芯片和密码
used_card_magnetic_stripe   | boolean                           | 确定用户是否使用了磁条
used_fingerprint            | boolean                           | 确定用户是否使用了指纹
typed_account_number        | boolean                           | 确定用户是否输入了账户数据

## 发送取款

Request Body

```json
  {
    "id": "12345",
    ...
  }
```

Response Body

```json
  {
    "withdrawal_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf",
    "status": "automatically_approved",
    "reason": "rule_decision_enum"
  }
```

要评估账单支付，只需将 withdrawal 类型的对象发送到以下端点：

`POST https://api.caas.qitech.app/withdrawal/withdrawal`

## 查询取款

Request Body

```json
  {
    "id": "082373263",
    "amount": 12979,
    ...
  }
```

要检索取款数据，只需向以下端点发送请求：

`GET https://api.caas.qitech.app/withdrawal/withdrawal/{withdrawal_id}`

其中 *withdrawal_id* 是发送取款时在客户系统中使用的交易标识符。

## 更新取款

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"
  }
```

取款创建并分析后，资金将提供给用户。此流程可能因其他业务规则而中断。因此，需要在取款完成时通过以下端点通知取款状态更新：

`PUT https://api.caas.qitech.app/withdrawal/withdrawal/{withdrawal_id}`

这样可以确保我们的数据库保持更新，并能够识别真正易受欺诈影响的取款。

---

# Status HTTP

URL: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/documentation/caas/car_rental/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

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.

## 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

---

# 持卡人警报

URL: /zh-Hans/documentation/caas/card_issuance/alerts

反欺诈工具生成的警报通过 Webhook 通知。为此，需要通过[支持](mailto:suporte.caas@qitech.com.br)团队配置一个端点地址，我们将通过该地址发送通知，以及一个用于签名请求的 *secret_token*。

在此通知中，我们将发送生成的警报信息以及涉及的持卡人信息，以便客户采取相应行动，例如向持卡人发送 *推送通知*。

## 请求

Request Body

```json
    {
        "alert_key": "123456",
        "cardholder_id": "ef47bc3f-61ac-4b85-ad67-0cfa3a422201",
        "company_name": "Cliente 1",
        "irregularity_type" : "fraud",
        "risk_level": "critical"
    }
```

请求采用上述格式，并通知为某持卡人（由 *cardholder_id* 描述）新开的警报

## Webhook 签名

> Python 签名计算示例

```python
    hmac_obj = hmac.new(signature_key.encode('utf-8'), (endpoint + method + payload).encode('utf-8'), hashlib.sha1)
    return hmac_obj.hexdigest()
```

为确保在 Webhook 端点收到的请求来自我们的服务器，HMAC 签名将在 Signature Header 中发送，类似于认证过程。

在服务器端计算签名的预期值后，需要将计算的签名与发送的签名进行比较。如果签名匹配，则表示请求来自我们的服务器且可信。

## 重试

当收到 HTTP 状态码 200 作为响应时，通知视为已完成。如果通知失败，将进行 5 次重试，重试间隔如下，直到返回 200 或重试结束：

* 30 秒
* 60 秒
* 120 秒
* 240 秒
* 360 秒

---

# authentication

URL: /zh-Hans/documentation/caas/card_issuance/authentication

## 认证

> 要认证一次调用，请使用以下代码：

```shell
# 在 shell 中，您只需在每个请求中添加适当的 header
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE_API_KEY"
```

> 请将 API Key 'EXAMPLE_API_KEY' 替换为您从我们支持团队获取的密钥。

我们使用 API Key 来允许访问我们的 API。它可能已经通过电子邮件发送给您。如果您尚未收到密钥，请发送电子邮件至 suporte.caas@qitech.com.br 。

我们的 API 期望在所有发送到服务器的请求中，以如下 header 的形式接收 API Key：

`Authorization: EXAMPLE_API_KEY`

:::info **注意**

您必须将 EXAMPLE_API_KEY 替换为从支持团队收到的 API Key。
:::

---

# HTTP 状态码

URL: /zh-Hans/documentation/caas/card_issuance/http_status

QI Tech 的所有 API 均遵循以下 HTTP 返回状态码标准，符合 RFC 7231 ：

HTTP 状态码 | 含义 | 描述
---------- | ------- | ---------------------------------
400 | Bad Request | 发送的请求存在格式错误。在大多数情况下，我们会在消息体中说明错误所在。
401 | Unauthorized | 认证出现问题，请检查 API Key 是否正确且在正确的 header 中，参见 认证 部分。
403 | Forbidden | 访问的端点为内部使用，此 API Key 无法访问。
404 | Not Found | 使用该密钥未找到所请求的数据。当请求无效端点时也会返回此状态。
405 | Method Not Allowed | 所使用的 HTTP 方法不适用于该端点。
406 | Not Acceptable | 请求体中发送的数据无效。通常表示发送的数据不是有效的 JSON。
409 | Conflict | 请求 ID 对应之前已处理过的 ID。当向服务器发送重复请求时返回此状态。
500 | Internal Server Error | 我们在处理此请求时遇到问题，一旦出现此错误，我们的专家将自动收到通知并立即开始分析和解决。
503 | Service Unavailable | 您遇到了计划内或计划外的服务器基础设施不可用情况。

---

# 简介

URL: /zh-Hans/documentation/caas/card_issuance/introduction

欢迎使用 QI Tech 卡片发行欺诈预防 API！您可以使用我们的 API 访问端点，以接收交易响应，以及更新交易状态。

:::info **注意**

请注意，此 API 面向卡片发行机构，即向持卡人提供卡片以便其进行交易的公司。其目的是对客户的交易进行全面安全分析，避免欺诈和其他类型的事故（例如因抢劫产生的交易）。
:::

以下，您可以看到使用 cUrl 的 API 实现。这样，您就有了示例，可以根据自己喜欢的编程语言进行适当调整。

## 遇到问题？

我们不是躲在 API 后面的公司！请联系我们的 支持团队 ，我们将尽快回复。如果您需要快速回复，请随时致电我们！

### 我们热爱反馈

即使您已经解决了问题，或者问题非常简单（甚至是您发现的一个错别字或不当的组织方式），也请给我们发电子邮件，这样我们可以让文档变得越来越实用，下一个人就不必经历您所经历的痛苦！

## 环境

我们为客户提供两个环境。API 的基本 URL 为：

* 生产环境 - `https://api.caas.qitech.app/card_issuance/`
* 沙盒环境 - `https://api.sandbox.caas.qitech.app/card_issuance/`

:::danger 重要提示！
不得在 QI Tech 沙盒环境中使用真实的个人和/或法人数据。
:::

在沙盒环境中，提交的分析不计费，并根据预先建立的规则进行响应。

对于交易分析，以下规则适用于交易金额：

最小值 | 最大值 | 决策
------ | ------ | -------
10000 | - | automatically_approved
0 | 9999 | automatically_declined

## 仅限 HTTPS

出于安全原因，与 QI Tech API 的所有通信必须使用 HTTPS 协议。为避免因疏忽或其他原因发出 HTTP 调用，此服务器仅提供使用 TLS 1.2 通信的 443 端口。使用其他协议发出的调用将自动被拒绝。

## 认证

> 要认证一次调用，请使用以下代码：

```shell
# 在 shell 中，您只需在每个请求中添加适当的 header
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE-OF-API-KEY"
```

> 请将 API Key 'EXAMPLE-OF-API-KEY' 替换为您从我们支持团队获取的密钥。

我们使用 API Key 来允许访问我们的 API。它可能已经通过电子邮件发送给您。如果您尚未收到密钥，请发送电子邮件至 suporte.caas@qitech.com.br 。

我们的 API 期望在所有发送到服务器的请求中，以如下 header 的形式接收 API Key：

`Authorization: EXAMPLE-OF-API-KEY`

:::info **注意**

您必须将 EXAMPLE-OF-API-KEY 替换为从支持团队收到的 API Key。
:::

---

# 标准

URL: /zh-Hans/documentation/caas/card_issuance/standards

为便于集成并保证信息完整性，整个 API 遵循以下已定义的标准。

## 货币金额
> 示例：

```
10000
12345
98741
1223
1
0
```

金额必须以分为单位作为整数发送。

## 带时区的日期和时间
> 一些示例：

```
2019-10-15T22:35:12-03:00
2018-05-01T13:32:11+00:00
2019-05-01T00:00:00+00:00
```

按照 ISO 8601 表示。在这种情况下，时区紧跟在时间之后，必须表示该数据有效的地点的时区。例如，如果租约计划在巴西利亚机场于 09:30 开始，发送的时间应表示为 09:30-03:00；如果租约计划在马瑙斯于 09:30 开始，则应表示为 09:30-04:00。

用于验证的掩码如下：

`YYYY-MM-ddThh:mm:ss±hh:mm`

## 不带时区的日期和时间
> 一些示例：

```
2019-10-15T22:35:12Z
2018-05-01T13:32:11Z
2019-05-01T00:00:00Z
```

按照 ISO 8601 表示。与时区无关的数据应不带时区发送，始终以 UTC 表示，字母 Z 表示该数据为 UTC。因此，将验证以下格式：

`YYYY-MM-ddThh:mm:ssZ`

## 日期
> 一些示例

``` 
2019-10-15
2019-01-01
2017-03-20
```

---

# Transaction

URL: /zh-Hans/documentation/caas/card_issuance/transaction

当持卡人发起交易时，数据应发送到我们的服务器，以便我们对该数据集所涉及的风险进行分析。

## 对象定义

Request Body

```json
{
  "id": "678",
  "cardholder_id": "b812da2e-e6be-4712-8e57-6f3f2791625b",
  "group_id" : "8507884b-c30f-4b45-951c-f0bf366926fc",
  "amount": 13725,
  "currency": "BRL",
  "brl_converted_amount": 13725,
  "installments": 6,
  "authorization_date": "2019-11-10T13:25:42.123-03:00",
  "authorization_type": "authorization",
  "transaction_type": "credit",
  "pan_entry_mode": "chip",
  "pin_sent": true,
  "source_account": "saving_account",
  "location": {
    "latitude": -45.2753548,
    "longitude": -15.24587
  },
  "terminal": {
    "id": "123456",
    "country_code": "BRA",
    "terminal_type": "2",
    "pin_entry_capability": true,
    "magnetic_stripe_capability": true,
    "contactless_capability": false,
    "chip_capability": true
  },
  "merchant": {
    "acquirer_id": "250",
    "merchant_id": "123456",
    "name": "VASP LINHAS AEREAS",
    "street" : "RUA CMDTE X, 127",
    "city" : "SAO PAULO, SP",
    "region": "BRA",
    "postal_code": "04570-140",
    "mcc": "3036"
  },
  "card": {
    "brand": "visa",
    "category": "black",
    "issuing_date": "2019-10-08T07:13:12.333-03:00",
    "unblock_date": "2019-10-12T07:13:12.333-03:00",
    "expiration_date": "2019-12-31",
    "bin": "498406",
    "last4": "1234",
    "total_credit_limit": 2500000,
    "used_credit_limit": 732625,
    "issuer_country_code": "BRA"
  },
  "transaction_status" : "authorized",
  "response_code": "05"
}
```

交易应在授权前发送到 API，可用于决定是否生成授权码。发送的数据还可用于根据持卡人的交易历史生成警报，以便在出现异常行为时触发适当的行动，从而降低交易影响。

欺诈状态（**fraud_status** 和 **transaction_status**）分别表示模型对该交易返回的决策，以及交易是否已完成、取消或成为争议。

**transaction_status** 使用以下状态：

* `not_authorized`
* `authorized`
* `cleared`
* `cancelled`
* `partially_cancelled`
* `chargeback`
* `partial_chargeback`

**fraud_status** 使用以下状态：

* `automatically_approved`
* `automatically_declined`
* `not_analyzed`

以下是 **fraud_status** 标志中返回的每个决策的含义：

结果 | 描述
:---------: | ---------
automatically_approved | 建议批准此交易
automatically_declined | 建议拒绝此交易
not_analyzed | 查询以分析标志为假发送，这意味着我们的系统不应返回意见

名称 | 类型 | 描述 | 
:----: | :----: | ---------
id | string | *（必填）* 客户系统中交易的标识符。 **此编号对每个授权流程必须唯一**
cardholder_id | string | *（必填）* 客户系统中持卡人的标识符——如 Onboarding API 中注册的那样
group_id | string | *（可选）* 客户系统中该用户所属组或类别的标识符
amount | 整数 | *（必填）* 交易金额——如"标准"部分所述
currency | string | *（必填）* 交易使用的货币——ISO 4217 和 8583 的 ApplicationCurrencyCode
brl_converted_amount | 整数 | *（必填）* 转换为巴西雷亚尔的交易金额——如"标准"部分所述
installments | 整数 | *（必填）* 交易使用的分期数
authorization_date | datetime | *（必填）* 交易开始的日期和时间，含时区
authorization_type | 枚举 | *（必填）* 授权交易还是预授权交易？
transaction_type | 枚举 | *（必填）* 信用、借记还是预付费
pan_entry_mode | 枚举 | *（必填）* PAN 输入模式——芯片、手动输入、磁条、后备、非接触式——来自 ISO 8583 的字段（DE 22 - 子字段 1）
pin_sent | 布尔值 | *（必填）* 是否在终端输入了密码？——来自 ISO 8583 entry_mode 的字段
source_account | 枚举 | *（可选）* 交易金额应从账单、活期账户还是储蓄账户扣除——来自 ISO 8583 Processing Code 的字段
location.latitude | number | *（可选）* 交易发生地的纬度——如果有关联的手机或其他定位方式
location.longitude | number | *（可选）* 交易发生地的经度
terminal.id | string | *（可选）* 收单机构在认证消息中发送的终端标识符
terminal.country_code | string | *（必填）* 终端所在国家代码，按 ISO 3166-1 alpha-3 在授权消息中发送，来自 ISO 8583 的 Terminal Country Code 字段
terminal.terminal_type | string | *（必填）* 从授权消息中接收到的终端类型——来自 ISO 8583 的 TerminalType 字段
terminal.pin_entry_capability | boolean | *（必填）* 终端是否支持输入卡密码？——来自 ISO 8583 的 TerminalPINEntryCapability 字段
terminal.magnetic_stripe_capability | boolean | *（可选）* 终端是否支持读取磁条？——ISO 8583 的 TerminalPANEntryCapability（DE 123）字段
terminal.contactless_capability | boolean | *（可选）* 终端是否支持非接触式交易？——ISO 8583 的 TerminalPANEntryCapability（DE 123）字段
terminal.chip_capability | boolean |*（必填）* 终端是否支持使用 EMV 芯片进行交易？——ISO 8583 的 TerminalPANEntryCapability（DE 123）字段
merchant.acquirer_id | string | *（必填）* 授权消息中的收单机构标识符——ISO 8583 的 Acquirer Identifier（DE 32）字段
merchant.merchant_id | string | *（必填）* 授权消息中收单机构的商户标识符——ISO 8583 的 Merchant Identifier 字段
merchant.name | string | *（可选）* 授权消息中的商户名称——ISO 8583 的 Merchant Name 字段
merchant.street | string | *（可选）* 商户地址的街道——Card Acceptor Street Address 字段
merchant.city | string | *（可选）* 商户地址的城市——Card Acceptor City 字段
merchant.region | string | *（可选）* 商户地址的城市——Card Acceptor Region Code 字段
merchant.postal_code | string | *（可选）* 商户地址的城市——Card Acceptor Postal Code 字段
merchant.mcc | string | *（必填）* 商户类别码，符合 ISO 18245 和 ISO 8583
card.brand | 枚举 | *（必填）* 卡片品牌（visa、mastercard、elo……）
card.category | 枚举 | *（必填）* 卡片类别（classic、gold、platinum、black、infinite、corporate）
card.issuing_date | datetime | *（必填）* 卡片发行的日期和时间，含时区
card.unblock_date | datetime | *（可选）* 持卡人解锁卡片的日期和时间，含时区
card.expiration_date | date | *（必填）* 卡片有效期（月末最后一天）
card.bin | string | *（必填）* 使用中的卡片 BIN
card.last4 | string | *（必填）* 卡片后四位数字，用于在发行机构内识别卡片
card.total_credit_limit | number | *（可选）* 授予持卡人的总信用额度。若为预付卡，则为卡片上现有的信用金额
card.used_credit_limit | number | *（可选）* 已使用的额度金额（此交易之前）
card.issuer_country_code | string | *（必填）* 发行机构所在国家，符合 ISO 3166-1 alpha-3
transaction_status | 枚举 | *（可选）* 交易状态，如果带有 ***analyze=false*** 标志发送且授权决策已做出。
response_code | 枚举 | *（可选）* 根据 ISO 8583 Response Code 字段的交易响应码，如果带有 ***analyze=false*** 标志发送且授权决策已做出。

## 枚举值
卡片交易对象的枚举值包括 authorization_type、transaction_type、pan_entry_mode、source_account、brand 和 category。每个枚举值的可能值如下所示：

## authorization_type

枚举值 | 含义
---------- | -----------
authorization | 购买授权——MTI x1xx（DMS）和 x2xx（SMS）
pre_authorization | 在卡片上预留额度的预授权（酒店、车辆租赁、设备租赁、加油机）——MTI x1xx（DMS）和 Transaction Type（Processing Code 前两位数字）"60"
reversal | 取消授权（以释放卡片额度并随后继续 Clearing/BASE II）——MTI x4xx

## transaction_type
枚举值 | 含义
---------- | ----------
credit | 信用功能交易
debit | 借记功能交易
prepaid | 预付费功能交易

## pan_entry_mode
枚举值 | ISO 8583 | 含义
---------- | -------- | -----------
unknown | 00 | PAN 输入模式未知。
typed | 01 | PAN 手动输入（键入）。
bar_code | 03 | 通过条码阅读器输入 PAN
ocr | 04 | 通过 OCR（光学字符识别）输入 PAN
chip | 05 | 通过集成电路卡（芯片）输入 PAN
track_1 | 06 | 通过磁条卡的 Track 1 输入 PAN
contactless | 07 | 通过 Contactless EMV 输入 PAN
fallback_typed | 79 | 尝试使用设备的卡片阅读器或磁条阅读器但无法处理（可能是设备或卡片问题），随后手动输入 PAN。某些情况下收单机构未获 CHIP 或磁条授权而发送此代码。
fallback_magnetic_stripe | 80 | 尝试使用设备的卡片阅读器但无法处理（可能是设备或卡片问题），随后使用卡片磁条。
ecommerce | 81 | 电商/非现场交易
magnetic_stripe | 90 | 磁条交易（卡片无芯片或设备无阅读器/未获授权）

还有其他 PAN_ENTRY_MODE 值，但通常不使用。

## source_account
枚举值 | ISO 8583 | 含义
---------- | -------- | -----------
default | 00 | 默认或未指定
saving_account | 10 | 储蓄账户
checking_account | 20 | 活期账户
credit_facility | 30 | 账单
universal_account | 40 | 通用账户
investment_account | 50 | 投资账户
electronic_purse | 60 | 卡片芯片中存储的余额（电子钱包）

## brand
枚举值 | 含义
---------- | -----------
visa | Visa
mastercard | MasterCard
diners_club | Diners Club
elo | Elo
american_express | American Express

## category
枚举值 | 含义
---------- | -----------
classic | Classic
gold | Gold
platinum | Platinum
black | Black/Infinite
travel | Travel
corporate | Corporate/Business
prepaid | 预付费

## terminal_type

枚举值 | 含义
---------- | -----------
0 | Unknown
1 | No terminal used
2 | Magnetic stripe reader
3 | Bar code (reserved for future use)
4 | Optical Character Recognition (reserved for future use)
5 | Magnetic stripe reader and EMV specification compatible integrated circuit card (ICC) reader
6 | Key entry only
7 | Magnetic stripe reader and key entry
8 | Magnetic stripe reader and key entry and EMV-compatible ICC reader
9 | EMV compatible ICC reader

## 发送 Transaction

Request Body

```json
  {
    "id": "12345",
    ...
  }
```

Response Body

```json
  {
    "id": "12345",
    "fraud_status": "automatically_approved"
  }
```

要评估交易，只需将 Transaction 类型的对象发送到以下端点，并适当设置标志：

`POST https://api.production-sa.zaig.com.br/card_issuance/transaction?analyze=true`

*analyze* 参数用于避免不需要分析的交易通过欺诈引擎，从而污染数据库。该参数的默认值为 **true**，因此只有明确标记的交易不会被分析。

## 更新 Transaction 状态

Request Body：授权交易时

```json
{
  "transaction_status": "authorized",
  "response_code": "05"
}
```

Request Body：部分取消交易时

```json
{
  "transaction_status": "partially_cancelled",
  "partial_amount" : 3000,
  "response_code": "05"
}
```

为确保已实施规则和人工智能模型的反馈，需要在交易取消时通知系统。为此，应使用 PUT 方法发送请求，正常认证：

`PUT https://api.production-sa.zaig.com.br/card_issuance/transaction/123456`

## 查询 Transaction

要检索特定 Transaction，只需发送 GET 请求。返回的结果是该 Transaction 的最新 JSON。如果该标识符与任何对象无关联，则返回 HTTP 状态码 404。

`GET https://api.production-sa.zaig.com.br/card_issuance/transaction/12345678`

```shell
curl "https://api.production-sa.zaig.com.br/card_issuance/transaction/12345678"
  -H "Authorization: EXAMPLE_API_KEY"
```

> 上述命令返回表示 Transaction 对象的 JSON。

## 搜索 Transactions

Response Body：Transaction 对象列表。

```json
[
  {
    "id": "12345",
    ...
  },
  {
    "id": "12345",
    ...
  }
]
```

如果需要搜索 Transaction，可以使用带查询参数的 GET 请求。返回的结果是表示 Transaction 列表的 JSON。如果使用发送的参数未找到对象，则返回 HTTP 状态码 200，响应体中包含空列表。

`GET https://api.production-sa.zaig.com.br/card_issuance/transactions?initial_date=2019-10-01&final_date=2019-10-05&page_number=2&page_rows=20`

以下参数可用于搜索：

参数 | 默认值 | 描述
--------- | ----------- | --------------
initial_date | null | 从 transaction_date 字段返回的第一个日期
final_date | null | 从 transaction_date 字段返回的最后一个日期
cardholder_id | null | 发行机构中持卡人的标识符
page_number | 0 | 所需结果页码，从零开始
page_rows | 50 | 单次查询返回的最大对象数

---

# authentication

URL: /zh-Hans/documentation/caas/card_order/authentication

## 认证

> 要认证一次调用，请使用以下代码：

```shell
# 在 shell 中，您只需在每个请求中添加适当的 header
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE_API_KEY"
```

> 请将 API Key 'EXAMPLE_API_KEY' 替换为您从我们支持团队获取的密钥。

我们使用 API Key 来允许访问我们的 API。它可能已经通过电子邮件发送给您。如果您尚未收到密钥，请发送电子邮件至 suporte.caas@qitech.com.br 。

我们的 API 期望在所有发送到服务器的请求中，以如下 header 的形式接收 API Key：

`Authorization: EXAMPLE_API_KEY`

:::info **注意**

您必须将 EXAMPLE_API_KEY 替换为从支持团队收到的 API Key。
:::

---

# HTTP 状态码

URL: /zh-Hans/documentation/caas/card_order/http_status

QI Tech 的所有 API 均遵循以下 HTTP 返回状态码标准，符合 RFC 7231 ：

HTTP 状态码 | 含义 | 描述
---------- | ------- | ---------------------------------
400 | Bad Request | 发送的请求存在格式错误。在大多数情况下，我们会在消息体中说明错误所在。
401 | Unauthorized | 认证出现问题，请检查 API Key 是否正确且在正确的 header 中，参见 认证 部分。
403 | Forbidden | 访问的端点为内部使用，此 API Key 无法访问。
404 | Not Found | 使用该密钥未找到所请求的数据。当请求无效端点时也会返回此状态。
405 | Method Not Allowed | 所使用的 HTTP 方法不适用于该端点。
406 | Not Acceptable | 请求体中发送的数据无效。通常表示发送的数据不是有效的 JSON。
409 | Conflict | 请求 ID 对应之前已处理过的 ID。当向服务器发送重复请求时返回此状态。
500 | Internal Server Error | 我们在处理此请求时遇到问题，一旦出现此错误，我们的专家将自动收到通知并立即开始分析和解决。
503 | Service Unavailable | 您遇到了计划内或计划外的服务器基础设施不可用情况。

---

# 简介

URL: /zh-Hans/documentation/caas/card_order/introduction

欢迎使用 QI Tech 卡片交易欺诈预防 API！您可以使用我们的 API 访问端点，以接收交易响应，向 QI Tech 发送交易以生成欺诈用户或欺诈卖家警报，以及更新交易状态。

:::info **注意**

请注意，此 API 面向接受无卡交易（可能遭受欺诈退款）的商户，即通过应用程序或网站销售并通过信用卡或借记卡接受付款的公司。
:::

以下，您可以看到使用 cUrl 的 API 实现。这样，您就有了示例，可以根据自己喜欢的编程语言进行适当调整。

## 遇到问题？

我们不是躲在 API 后面的公司！请联系我们的 支持团队 ，我们将尽快回复。如果您需要快速回复，请随时致电我们！

### 我们热爱反馈

即使您已经解决了问题，或者问题非常简单（甚至是您发现的一个错别字或不当的组织方式），也请给我们发电子邮件，这样我们可以让文档变得越来越实用，下一个人就不必经历您所经历的痛苦！

## 环境

我们为客户提供两个环境。API 的基本 URL 为：

* 生产环境 - `https://api.caas.qitech.app/card_order/`
* 沙盒环境 - `https://api.sandbox.caas.qitech.app/card_order/`

:::danger 重要提示！
不得在 QI Tech 沙盒环境中使用真实的个人和/或法人数据。
:::

在沙盒环境中，提交的分析不计费，并根据预先建立的规则进行响应。

对于交易分析，以下规则适用于交易金额：

最小值 | 最大值 | 决策
------ | ------ | -------
0 | 1000 | 自动批准
1001 | 2000 | 转人工分析——随后批准
2001 | 3000 | 转人工分析——随后拒绝
3001 | 4000 | 自动拒绝
4001 | 5000 | 未分析
5001 | - | 待处理

## 仅限 HTTPS

出于安全原因，与 QI Tech API 的所有通信必须使用 HTTPS 协议。为避免因疏忽或其他原因发出 HTTP 调用，此服务器仅提供使用 TLS 1.2 通信的 443 端口。使用其他协议发出的调用将自动被拒绝。

## 认证

> 要认证一次调用，请使用以下代码：

```shell
# 在 shell 中，您只需在每个请求中添加适当的 header
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE_API_KEY"
```

> 请将 API Key 'EXAMPLE_API_KEY' 替换为您从我们支持团队获取的密钥。

我们使用 API Key 来允许访问我们的 API。它可能已经通过电子邮件发送给您。如果您尚未收到密钥，请发送电子邮件至 suporte.caas@qitech.com.br 。

我们的 API 期望在所有发送到服务器的请求中，以如下 header 的形式接收 API Key：

`Authorization: EXAMPLE_API_KEY`

:::info **注意**

您必须将 EXAMPLE_API_KEY 替换为从支持团队收到的 API Key。
:::

---

# 对象

URL: /zh-Hans/documentation/caas/card_order/objects

## *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"
}
```

*address* 对象用于在整个 API 中表示地址，巴西境内地址的表示方式如下：

名称 | 类型 | 描述
---- | :----: | ---------
street | string | *（必填）* 地址的街道，包括公路名称，尽可能避免缩写。
number | string | 物业编号，如有字母则包含字母。
neighborhood | string | *（必填）* 区域，不缩写。 **例如：Santa Felicidade**
city | string | *（必填）* 城市全名，不缩写
uf | string | *（必填）* 联邦单位，两个大写字母。 **例如：SP**
complement | string | 用于定位物业的任何补充信息。 **例如：Apartamento 101, Conjunto 12**
postal_code | string | *（必填）* 该地点的邮政编码，含连字符。
country | string | *（必填）* 地址国家的 ISO 3166-1 alpha-3 代码。

对于国家不是巴西（"BRA"）的地址，postal_code 和联邦单位可以自由填写。

## *payment* 对象

Request Body

```json
{
  "total_amount": 10000,
  "shipping_amount": 500,
  "currency": "BRL",
  "is_recurrence": false,
  "transactions": [ . . . ]
}
```

支付由 *payment* 对象表示，具有以下字段：

名称 | 类型 | 描述
---- | :----: | ---------
total_amount | 整数 | *（必填）* 支付的总货币金额
shipping_amount | 整数 | 配送费用
currency | 枚举 | *（必填）* 根据 ISO 4217 的支付货币
is_recurrence | boolean | *（必填）* 如果这是周期性付款，在此标志中指示 true
transactions | Transaction 数组 | *（必填）* 为订单付款执行的交易列表（多卡支付）

## *transaction* 对象 - 信用卡

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"
}
```

交易由 *transaction* 对象表示，具有以下字段：

名称 | 类型 | 描述
---- | :----: | ---------
id | string | *（必填）* 客户系统中交易的标识符，每笔订单必须唯一
amount | integer | *（必填）* 表示支付金额的货币金额
bin | string | *（必填）* 支付使用的卡片 BIN
last4 | string | *（必填）* 支付使用的卡片后四位数字
cardholder_name | string | *（必填）* 持卡人姓名，如卡片上所写
card_fingerprint | string | *（必填）* 客户系统中的卡片标识符（"Token"）
expiration_date | string | 卡片到期日期（YYYY-DD）
installments | integer | *（必填）* 支付分期数
processor | 枚举 | *（必填）* 负责处理交易的收单机构或子收单机构
payment_type | 枚举 | *（必填）* 支付方式类型
status | 枚举 | 可选——发送给 QI Tech 时交易的最新状态——用于发送未授权的交易

processor 可用枚举值：
* cielo
* rede
* stone
* getnet
* adyen
* global_payments
* pagseguro

## *transaction* 对象 - PIX

Request Body

```json
{
  "id": "124234",
  "amount": 10000,
  "payment_type": "pix"
}
```

交易由 *transaction* 对象表示，具有以下字段：

名称 | 类型 | 描述
---- | :----: | ---------
id | string | *（必填）* 客户系统中交易的标识符，每笔订单必须唯一
amount | integer | *（必填）* 表示支付金额的货币金额
payment_type | 枚举 | *（必填）* 支付方式类型

## *dict_key* 对象

Request Body

```json
  {
    "key_type": "cpf",
    "key_value": "09991222669"
  }
```

**dict_key** 对象用于表示客户（无论是收款人还是付款人）在 DICT 中的绑定密钥数据。该对象的字段为：

名称 | 类型 | 描述
:----: | :----: | ---------
key_type        | string | 包含 DICT 中绑定密钥类型的枚举值。
key_value       | string | 包含在 DICT 中注册的绑定密钥。

*key_type* 字段的枚举值与 DICT API 中定义的相同：`cpf`、`cnpj`、`email`、`phone` 和 `evp`。

## *account* 对象

Request Body

```json
{
    "participant": "17315359",
    "branch": "0000",
    "account_number": "10442",
    "account_digit": "6",
    "account_type": "CACC"
}
```

表示账户数据的对象。

名称 | 类型 | 描述
:----:  | :----:  | ---------
participant                 | string | 账户所属机构的 ISPB
branch                      | string | 账户支行
account_number              | string | 不含校验位的账户号码
account_digit               | string | 账户校验位
account_type                | 枚举 | 来源账户类型，可能值："CACC"、"SLRY" 和 "SVGS"

## *phone* 对象

Request Body

```json
{
  "international_dial_code": "1",
  "area_code": "11",
  "number": "999999999",
  "type": "mobile",
  "validated": false
}
```

phone 对象表示巴西境内或境外的电话号码及其分类。字段如下：

名称 | 类型 | 描述
---- | :----: | ---------
international_dial_code | string | *（必填）* 国际拨号代码，不含零或加号，仅数字
area_code | string | *（必填）* 区号，不含零，仅数字
number | string | *（必填）* 电话号码，不含连字符
type | 枚举 | *（必填）* 号码类型：手机、住宅、商务等。
validated | 布尔值 | 如果电话号码已验证（短信或电话），在此字段发送 true

电话类型的枚举值为：`residential`、`commercial`、`mobile`

## *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"
  }
}
```

*seller* 对象表示执行订单销售或交付的商店或卖家。需要发送的数据如下：

名称 | 类型 | 描述
---- | :----: | ---------
id | string | *（必填）* 客户系统中商店（或 MarketPlace 卖家）的标识码
name | string | *（必填）* 商店名称（或 MarketPlace 卖家名称）
type | 枚举 | 表示卖家是自然人还是法人的枚举值
document_number | string | *（必填）* 卖家的 CNPJ 或 CPF
url | string | 平台上卖家页面的地址
email | string | 卖家的电子邮件
registration_date | date | *（必填）* 卖家的注册日期
phone | *phone* | 卖家的电话
address | *address* | *（必填）* 如果是实体店，提供店铺地址

type 枚举值：

* `natural_person`
* `legal_person`

## *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": { . . . }
}
```

customer 对象表示使用自己的信用卡下单的人员数据。由以下字段组成：

名称 | 类型 | 描述
---- | :----: | ---------
id | string | *（必填）* 买家或用户的唯一标识符
name | string | *（必填）* 全名
gender | 枚举 | 客户的性别，根据枚举值列表。
document_number | string | *（必填）* CPF，格式正确
registration_date | date | 用户在客户系统中注册的日期
email | string | *（必填）* 用户的电子邮件
birthdate | date | 客户的出生日期
address | *address* | *（必填）* 买家/用户的住宅地址
phone | *phone* | *（必填）* 收集到的买家/用户电话

性别枚举值：

* `male`
* `female`

## *device* 对象

Request Body

```json
{
  "session_id": "595c46c1-b8c2-449d-8a86-6aeba2e5b0da",
  "platform": "android",
  "browser": "chrome",
  "ip": "243.178.100.37"
}
```

device 对象描述用于购物的设备数据。传递以下数据：

名称 | 类型 | 描述
---- | :----: | ---------
session_id | string | *（必填）* 会话标识符，也在 Device Scan 中传递
platform | 枚举 | 正在使用的操作系统枚举
browser | 枚举 | 正在使用的浏览器（或应用程序）枚举
ip | string | 购物的来源 IP，符合本文档的标准。**注意，以 10.*、172.16.* 和 192.168.* 开头的 IP 通常是内部 IP，因此不适用于欺诈预防**

平台枚举值：
* `android`
* `ios`
* `windows`
* `linux`

浏览器枚举值：
* `firefox`
* `chrome`
* `safari`
* `app`

---

# 订单

URL: /zh-Hans/documentation/caas/card_order/order

在向您的客户或卖家交付/发货产品或释放信用额度之前，您应将订单数据发送到我们的 API，以便我们向您返回关于欺诈的建议。发送的数据必须是最终数据，不会被更改，这一点非常重要。这对于保证以下两点至关重要：

* 反欺诈数据库中的数据一致性
* 真实的风险评估

分析过程包括在相应端点发送一个 Order，并等待响应。有四种可能的结果，通过 **analysis_status** 标志返回：

结果 | 描述
:---------: | ---------
自动批准 | 建议批准该订单
自动拒绝 | 建议拒绝该订单
转人工分析 | 我们的规则或模型对决策不够自信，决定将此订单转交人工分析
人工批准 | 人工分析后，分析师选择批准该订单
人工拒绝 | 人工分析后，分析师选择拒绝该订单
待处理 | 查询耗时超出预期，该订单已进入自动分析队列，将通过 Webhook 返回结果
未分析 | 查询以分析标志为 false 发送，或这是仅用于生成警报的分析，这意味着我们的系统不应在 Order 响应中返回建议

:::info **注意**
如果您的业务模式有需要，QI Tech 的引擎可以配置为不将任何订单转人工分析，也不转至待处理状态。这样，您的用户可以立即收到交易确认。
:::

### 状态动态

检索 Order 类型对象时，状态均可查看。除状态外，还会返回修改历史记录以供将来查询。这些修改被称为 events，包含新状态以及修改日期。

### 状态动态 - **payment_status**

订单的 **payment_status** 状态表示与该订单相关的支付情况，即交易是否被有效批准、是否被取消或是否收到欺诈退款。以下支付状态可用：

* open
* not_authorized
* authorized
* captured
* cancelled
* chargeback

:::info **注意**

向 QI Tech 发送支付状态至关重要，因为它被用作我们模型训练的基础。对于退款情况，正确发送 reason_code 非常重要，如下文所述。
:::

### 状态动态 - **analysis_status**

**analysis_status** 表示欺诈引擎决策的状态，其状态机非常简单：

* created
* automatically_approved
* automatically_reproved
* in_manual_analysis
* manually_approved
* manually_reproved
* pending
* not_analyzed

## 对象定义

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"
}
```

一个订单的所有信息交换均使用以下对象定义。在某些情况下，为便于实现并减少各方之间的数据流，某些信息可能会被省略。

名称 | 类型 | 描述
:----: |:--------------------------------------:| ---------
id | string | 客户系统中的订单标识符。 **此值对于每个订单必须唯一**（必填）
is_one_dollar_auth | 布尔值 | 如果这是仅用于验证卡片的交易，使用此标志发送 true（必填）
seller | Seller 对象 | 完成销售的商店数据。在 MarketPlace 中，是卖家数据。在应用程序中，是取货店铺的数据（必填）
payment | Payment 对象 | 订单支付数据（必填）
customer | Customer 对象 | 客户/用户数据（必填）
shipping | Shipping 对象 | 订单配送数据——适用于实体配送产品的情况
device | Device 对象 | 下单所用设备/浏览器数据
products | Product 数组 | 购买的商品（必填）
order_date | 日期时间 | 下单日期和时间（必填）

## 发送订单

Request Body

```json
  {
    "id": "12345",
    ...
  }
```

Response Body

```json
  {
    "id": "12345",
    "analysis_status": "automatically_approved"
  }
```

要对订单进行评估，只需将 Order 类型对象发送到以下端点：

`POST https://api.caas.qitech.app/card_order/order`

## 更新订单状态

Request Body

```json
{
  "transaction_status": "chargeback"
}
```

为确保规则和人工智能模型的持续优化，必须通知系统交易何时被授权、捕获、取消或收到退款。为此，需要使用 PUT 方法，并正常进行认证：

`PUT https://api.caas.qitech.app/card_order/order/12345678/transaction/124234`

*transaction_status* 的枚举值如下：`open`、`not_authorized`、`authorized`、`captured`、`cancelled`、`chargeback`

## 检索订单

要检索特定订单，只需发出 GET 请求。返回的结果是该订单的最新 JSON。如果该标识符未与任何对象关联，则返回 HTTP Status 404。

`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"
```

> 上述命令返回代表 CardOrder 对象的 JSON。

## 搜索 CardOrders

Response Body

```json
[
  {
    "id": "12345",
    ...
  },
  {
    "id": "12345",
    ...
  }
]
```

> 返回代表 CardOrder 对象列表的 JSON。

如需搜索 CardOrder，可以使用带查询参数的 GET 请求。返回的结果是代表 CardOrders 列表的 JSON。如果未找到符合发送参数的对象，则返回 HTTP Status 200，响应体中包含空列表。

`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`

以下参数可用于搜索 CardOrder 对象：

参数 | 默认值 | 描述
--------- | ----------- | --------------
initial_date | null | 根据 order_date 字段应返回的最早日期
final_date | null | 根据 order_date 字段应返回的最晚日期
page_number | 1 | 所需结果页码
page_rows | 50 | 一次查询返回的最大对象数

---

# 标准

URL: /zh-Hans/documentation/caas/card_order/standards

为便于集成并确保信息完整性，整个 API 遵循以下统一标准。

## 货币金额
> 示例：

```
10000
12345
98741
1223
1
0
```

API 假定所有发送的货币金额均为巴西雷亚尔。金额应以整数（分）形式发送。

## 含时区的日期和时间
> 部分示例：

```
2019-10-15T22:35:12-03:00
2018-05-01T13:32:11+00:00
2019-05-01T00:00:00+00:00
```

按照 ISO 8601 表示。在这种情况下，时区紧跟在时间之后，必须表示该数据有效所在地的时区。例如，如果租赁计划在巴西利亚机场 09:30 开始，则发送的时间应表示为 09:30-03:00；如果租赁计划在马瑙斯 09:30 开始，则应表示为 09:30-04:00。

用于验证的掩码如下：

`YYYY-MM-ddThh:mm:ss±hh:mm`

## 不含时区的日期和时间
> 部分示例：

```
2019-10-15T22:35:12Z
2018-05-01T13:32:11Z
2019-05-01T00:00:00Z
```

按照 ISO 8601 表示。与时区无关的数据应不含时区，始终使用 UTC，字母 Z 表示该数据为 UTC。因此，将验证以下格式：

`YYYY-MM-ddThh:mm:ssZ`

## 日期
> 部分示例

```
2019-10-15
2019-01-01
2017-03-20
```

对于仅接收日期的字段（例如出生日期），应只发送日期，不含任何时间，格式如下：

`YYYY-MM-dd`

## 文件/证件号

由于文件号码种类繁多，且许多包含非数字字符，因此所有文件号码均定义为字符串。将其定义为字符串的另一个好处是避免前导零消失。本页面中规定的文件格式具有明确的掩码，将进行验证。其他文件（如 RG）由于缺乏标准化，不进行验证。

## CPF

> 符合已定义掩码的有效 CPF 示例：

```
123.456.789-12
321.987.543-23
111.283.333-00
```

> 不符合已定义掩码的无效 CPF 示例：

```
8.577.477-8
08.104.627/0001-23
123.456.789-1
23.456.789-01
```

CPF 始终定义为字符串，将按掩码进行验证：

`###.###.###-##`

## CNPJ

> 符合已定义掩码的有效 CNPJ 示例：

```
08.104.627/0001-02
01.079.210/0114-67
32.402.502/0001-35
```

> 不符合已定义掩码的无效 CNPJ 示例：

```
8.577.477-8
123.456.789-12
321.987.543-23
32.402.502/0001-3
032.402.502/0001-3
```

CNPJ 始终定义为字符串，将按掩码进行验证：

`##.###.###/####-##`

## IP

> 符合已定义掩码的有效 IP 示例：

```
201.81.161.86
201.081.161.86
201.81.161.086
201.81.0.1
```

> 无效 IP 示例：

```
201.81..86
358.81.161.86
201.81.161
```

IP 地址始终以 IPv4 格式发送，可以带也可以不带前导零，遵循以下掩码：

`###.###.###.###`

---

# Webhook

URL: /zh-Hans/documentation/caas/card_order/webhook

欺诈状态更新（针对转人工分析或响应为待处理的订单）以及卖家封锁，均通过 Webhook 进行通知。为此，需要通过[支持](mailto:suporte.caas@qitech.com.br)团队配置一个端点地址，我们将通过该地址通知更新，同时还需配置一个用于签署请求的 *signature_key*。

对于订单状态更新，客户也可以使用[轮询](https://en.wikipedia.org/wiki/Polling_(computer_science))技术。在这种情况下，不需要配置 webhook 端点，只需使用 Order 检索端点进行轮询即可。

:::info **注意**

出于安全原因，所有 Webhook 请求仅在 HTTPS 提供的端点上执行。
:::

## 签名

> Python 签名计算示例

```python
    hmac_obj = hmac.new(signature_key.encode('utf-8'), (url + method + payload).encode('utf-8'), hashlib.sha1)
    return hmac_obj.hexdigest()
```

为确保接收到的 webhook 端点请求来自我们的服务器，类似于认证过程，在 *Signature* Header 中发送 HMAC 签名。

在服务器端计算出签名预期值后，需要将计算出的签名与发送的签名进行比较。如果签名匹配，则意味着请求来自我们的服务器并且是可信的。

## 订单更新 Webhook

Request Body

```json
    {
        "order_id": "123456",
        "fraud_status": "automatically_approved",
        "event_date": "2019-10-01T10:37:25-03:00"
    }
```

更新订单分析状态的请求具有上述格式，并通知欺诈状态的变更。所用方法为 PUT，端点地址可以根据客户需要包含订单 ID。重要提示：请求体以 UTF-8 编码文本形式发送。

订单更新端点示例：

* https://apidocliente.com.br/order
* https://apidocliente.com.br/admin/order/1214

event_date 字段表示通知创建的日期和时间，如果之前的通知发送失败，该时间可能在过去。

## 卖家更新 Webhook

> 结算封锁请求示例

Request Body

```json
    {
        "document_number": "000.000.000-00",
        "settlement_status": "blocked",
        "event_date": "2019-10-01T10:37:25-03:00"
    }
```

> 交易封锁请求示例

Request Body

```json
    {
        "document_number": "000.000.000-00",
        "transactional_status": "blocked",
        "event_date": "2019-10-01T10:37:25-03:00"
    }
```

当需要封锁或解封卖家时，QI Tech 系统将发送上述格式的请求。使用的方法为 PUT，发送至可配置端点，客户可根据需要在端点地址中包含文件号码。

:::info **注意**

settlement_status 或 transactional_status 字段的存在决定了卖家封锁或解封的类型。
:::

卖家更新端点示例：

* https://apidocliente.com.br/seller
* https://apidocliente.com.br/admin/seller/000.000.000-00

可通知的结算状态如下：

枚举值 | 描述
---- | ---------:
blocked | 卖家的结算应被封锁
unblocked | 卖家的结算应被解除封锁

event_date 字段表示通知创建的日期和时间，如果之前的通知发送失败，该时间可能在过去。

## 重试

当收到 HTTP Status 200 响应时，通知被视为已送达。如果通知失败，将进行 7 次重试，时间间隔如下，直到收到 200 或重试结束：

* 10 秒
* 40 秒
* 160 秒
* 640 秒
* 2560 秒
* 10240 秒
* 40960 秒

---

# authentication

URL: /zh-Hans/documentation/caas/credit_analysis/authentication

## 认证

> 要认证一次调用，请使用以下代码：

```shell
# 在 shell 中，您只需在每个请求中添加适当的 header
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE-OF-API-KEY"
```

> 请将 API Key 'EXAMPLE-OF-API-KEY' 替换为您从我们支持团队获取的密钥。

我们使用 API Key 来允许访问我们的 API。它可能已经通过电子邮件发送给您。如果您尚未收到密钥，请发送电子邮件至 suporte.caas@qitech.com.br 。

我们的 API 期望在所有发送到服务器的请求中，以如下 header 的形式接收 API Key：

`Authorization: EXAMPLE-OF-API-KEY`

:::info **注意**

您必须将 EXAMPLE-OF-API-KEY 替换为从支持团队收到的 API Key。
:::

---

# 挑战流程

URL: /zh-Hans/documentation/caas/credit_analysis/challenge_flow

分析执行后，可能会决定向用户发起挑战，要求其在您的平台上执行新的操作。例如，此流程可用于向尚未确定是否应通过或未通过信用分析的用户请求收入证明。

通过此流程，您可以配置一条规则，决定向您的客户发起挑战，要求其向系统提交额外信息（例如工资单照片或其他相关信息），收集完成后，利用这些额外信息执行新规则以重新评估用户。

此流程有两种使用方式，一种是自动方式，另一种是分析师手动决策的结果。前者返回的 *analysis_status* 为 *automatically_challenged*，后者为 *manually_challenged*。以下是流程说明。

## 流程步骤

**1.** 提案提交分析（参见 信用分析 - 自然人 或 信用分析 - 法人 部分），将返回状态 *automatically_challenge* 或 *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"
}
```

如果请求响应中返回 *in_manual_analysis* 状态，分析师可以通过仪表板对用户发起挑战。在这种情况下，webhook 请求中发送的状态为 *manually_challenged*。

Response Body

```json
{
  "id": "12345",
  "analysis_status": "manually_challenged"
}
```

**2.** 在第一次分析请求返回两种挑战 *analysis_status* 之一后，需要发送一个新请求，包含从客户处收集的额外信息，例如新提交的文件图片。此请求必须包含与之前请求相同的 *registration_id*，因为该字段将被用于平台识别两个请求属于同一用户，并将从客户处收集的额外信息关联起来。

Request Body: 包含额外信息的发送

```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"
}
```

请注意使用与第一次分析相同的 registration_id。

---

# 检索信用分析

URL: /zh-Hans/documentation/caas/credit_analysis/get_credit_analysis

要检索特定信用分析，只需发出 GET 请求。返回的结果是该分析的最新 JSON。如果该标识符未与任何对象关联，则返回 HTTP Status 404。

* **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"
```

> 上述命令返回代表 Natural Person 对象的 JSON。

```shell
curl "https://api.caas.qitech.app/credit_analysis/legal_person/12345678"
  -H "Authorization: EXAMPLE-OF-API-KEY"
```

> 上述命令返回代表 Legal Person 对象的 JSON。

---

# HTTP 状态码

URL: /zh-Hans/documentation/caas/credit_analysis/http_status

QI Tech 的所有 API 均遵循以下 HTTP 返回状态码标准，符合 RFC 7231 ：

HTTP 状态码 | 含义 | 描述
---------- | ------- | ---------------------------------
400 | Bad Request | 发送的请求存在格式错误。在大多数情况下，我们会在消息体中说明错误所在。
401 | Unauthorized | 认证出现问题，请检查 API Key 是否正确且在正确的 header 中，参见 认证 部分。
403 | Forbidden | 访问的端点为内部使用，此 API Key 无法访问。
404 | Not Found | 使用该密钥未找到所请求的数据。当请求无效端点时也会返回此状态。
405 | Method Not Allowed | 所使用的 HTTP 方法不适用于该端点。
406 | Not Acceptable | 请求体中发送的数据无效。通常表示发送的数据不是有效的 JSON。
409 | Conflict | 请求 ID 对应之前已处理过的 ID。当向服务器发送重复请求时返回此状态。
500 | Internal Server Error | 我们在处理此请求时遇到问题，一旦出现此错误，我们的专家将自动收到通知并立即开始分析和解决。
503 | Service Unavailable | 您遇到了计划内或计划外的服务器基础设施不可用情况。

---

# 图像

URL: /zh-Hans/documentation/caas/credit_analysis/image

在许多情况下，需要向我们的 API 发送图像，以执行 OCR、FaceMatch 和文档验证操作。为此，需要先上传图像，然后再将其发送进行分析。

使用 /image 端点发送图像后，将返回一个 GUID（全局唯一标识符）。该值应在后续调用中用于引用此图像。

接受的图像最大大小为 10MB。

目前，仅接受 jpeg 格式的图像。

## 上传

> 使用 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"
    }
```

要发送图像，只需以 `multipart/form-data` 格式将 .jpeg 格式的图像通过 POST 请求发送至端点：

`https://api.caas.qitech.app/api/image?type=$type`

其中 $type 是图像的分类，必须按照以下枚举值之一发送（如果发送的图像不属于任何分类，请联系[支持团队](mailto:suporte.caas@qitech.com.br)以添加）：

* face
* driver_license
* id
* contract

发送后，将返回一个包含指向已发送图像的 GUID 的 JSON 对象。

## 文件检索

> 读取图像

```shell
    curl "https://api.caas.qitech.app/api/image/f4b5337a-7b50-406e-8c8e-7d0e77b5aa02/file" \
         -H "Authorization: EXAMPLE-OF-API-KEY"
```

向 API 发送图像后，可以通过在端点发出经适当认证的 GET 请求来检索图像：

`https://api.caas.qitech.app/api/image/{image_key}/file`

其中 image_key 是图像发送时返回的值。

## 文件元数据检索

> 读取元数据

```shell
    curl "https://api.caas.qitech.app/api/image/f4b5337a-7b50-406e-8c8e-7d0e77b5aa02" \
         -H "Authorization: EXAMPLE-OF-API-KEY"
```

向 API 发送图像后，可以使用以下端点检索图像的元数据：

`https://api.caas.qitech.app/api/image/{image_key}`

其中 image_key 是图像发送时返回的值。

---

# 简介

URL: /zh-Hans/documentation/caas/credit_analysis/introduction

欢迎使用 QI Tech 信用分析 API！您可以使用我们的 API 访问端点，以执行信用分析，以及更新已授予信用的状态。

:::info **注意**
请注意，此 API 面向向自然人和法人授予信贷的企业。其目的是根据发送的数据、征信机构和外部来源的数据以及 QI Tech 数据湖的数据，对客户的所有信贷业务进行完整的信用分析，从而明确每笔业务的收益与风险。

此 API 针对小型自然人和法人设计，不适用于大型企业的信用风险评估，因为后者需要对其运营和所在市场有深入了解。
:::

## 遇到问题？

我们不是躲在 API 后面的公司！请联系我们的 支持团队 ，我们将尽快回复。如果您需要快速回复，请随时致电我们！

### 我们热爱反馈

即使您已经解决了问题，或者问题非常简单（甚至是您发现的一个错别字或不当的组织方式），也请给我们发电子邮件，这样我们可以让文档变得越来越实用，下一个人就不必经历您所经历的痛苦！

## 环境

我们为客户提供两个环境。API 的基本 URL 为：

* 生产环境 - `https://api.caas.qitech.app/credit_analysis/`
* 沙盒环境 - `https://api.sandbox.caas.qitech.app/credit_analysis/`

:::danger 重要提示！
不得在 QI Tech 沙盒环境中使用真实的个人和/或法人数据。
:::

在沙盒环境中，提交的分析不计费，按照预先制定的规则进行响应，并返回虚构数据，其唯一目的是模拟生产环境，以协助客户集成。

在沙盒环境中，信贷业务分析决策基于待授予信贷的总金额（ financial.amount ），规则如下：

最小值 | 最大值 | 决策
------ | ------ | -------
10001 | - | 拒绝
8001 | 10000 | 人工分析——1 分钟后发送人工拒绝 webhook
6001 | 8000 | 人工分析——1 分钟后发送人工批准 webhook
4001 | 6000 | 等待数据——1 分钟后发送自动批准 webhook
2001 | 4000 | 待处理
0 | 2000 | 批准

## 仅限 HTTPS

出于安全原因，与 QI Tech API 的所有通信必须使用 HTTPS 协议。为避免因疏忽或其他原因发出 HTTP 调用，此服务器仅提供使用 TLS 1.2 通信的 443 端口。使用其他协议发出的调用将自动被拒绝。

## 认证

> 要认证一次调用，请使用以下代码：

```shell
# 在 shell 中，您只需在每个请求中添加适当的 header
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE-OF-API-KEY"
```

> 请将 API Key 'EXAMPLE-OF-API-KEY' 替换为您从我们支持团队获取的密钥。

我们使用 API Key 来允许访问我们的 API。它可能已经通过电子邮件发送给您。如果您尚未收到密钥，请发送电子邮件至 suporte.caas@qitech.com.br 。

我们的 API 期望在所有发送到服务器的请求中，以如下 header 的形式接收 API Key：

`Authorization: EXAMPLE-OF-API-KEY`

:::info **注意**

您必须将 EXAMPLE-OF-API-KEY 替换为从支持团队收到的 API Key。
:::

---

# 信用分析 - 法人

URL: /zh-Hans/documentation/caas/credit_analysis/legal_person

要对法人进行信用分析，请使用 Legal Person 端点。

在进行法人信用分析时，需要将以下数据发送到我们的服务器。

## 定义 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" : {
    ...
  }
}
```

信用分析应在放款前提交至 API，可用于决定是否批准信用申请。根据与客户的协议，所提交的数据也可用于欺诈预防。

本节未定义的、用于组成 CreditProposal 对象的其他对象，请参阅[共享对象](#objetos-compartilhados)部分。

|                   名称                   |      类型      | 描述                                                                                                                                                                      |
| :--------------------------------------: | :------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|                    id                    |    string     | 您系统中信用提案的标识符。<br /> **每个信用分析流程的该编号必须唯一**                                |
|registration_id | string | 客户系统中的注册标识符。用于对同一注册进行多次分析时使用。 |
|           credit_request_date            |    datetime    | 借款人申请信用的日期和时间                                                                                                                    |
|               credit_type                |   enum   | 正在授予的信用类型。目前支持：**clean**、**student_loan**、**credit_card_limit**                                                                 |
| legal_name        |         string          | 公司全称                                                                   |
| trading_name      |         string          | 商号名称                                                                  |
| document_number   |         string          | CNPJ，按本文档规定的格式填写              |
| monthly_revenue   |         integer         | 月总收入（以分为单位）                                               |
|client_category    |         string          | 根据您的平台或忠诚度计划对客户进行的分类    |
|client_since    |         date | 开始为该客户提供服务的日期   
| constitution_date |          date           | 公司注册成立日期，依据商业登记                  |
| constitution_type |       enum        | 公司组织形式：**LLC**、**corp**                           |
| email             |         string          | 公司代表的电子邮件                                            |
| address           |        _Address_        | 公司总部地址                                              |
| phones            |    list of _Phones_     | 公司联系电话列表                                             |
| shareholders      | list of _NaturalPerson_ | 公司股东，以自然人模式（**NaturalPerson** 对象）表示 |
|                guarantors                | list of _Person_ | 操作的担保人，可为自然人（**NaturalPerson**）或法人（**LegalPerson**）                                                                                       |
|             financial.amount             |    integer     | 借款人申请的总金额，批准后将予以释放                                                                                                                    |
|             financial.currency           |    enum     | 总金额对应的货币单位：**BRL**、**USD**、**EUR**                                                                                          |
|              interest_type               |   enum   | 将使用的债务指数：**cdi_plus**、**cdi_percentage**、**price**、**pre_fixed**                                                                           |
|           annual_interest_rate           |     number     | 年利率中的固定利率部分（百分比）                                                                                                                     |
|              cdi_percentage              |     number     | 将收取的 CDI 百分比（浮动部分）                                                                                                                               |
|          number_of_installments          |    integer     | 分期数                                                                                                                                                             |
|                 warrants                 |     _Warrant_     | 操作中提供的实物担保数据。需在投产前协商确定。目前接受以下类型：**real_estate**                  |
|              source               |     _Source_     | 信用销售渠道。目前接受：**website** 和 **app**                                                                                                     |
| scr_parameters| _ScrParameters_ | 包含在信用分析中使用 SCR 信息所需内容的对象 |

## 提交信用提案 - 法人

Request Body

```json
  {
    "id": "12345678",
    ...
  }
```

Response Body

```json
{
  "id": "12345678",
  "analysis_status": "automatically_approved",
  "reason": "rule_decision_enum"
}
```

要评估信用提案，只需将 LegalPerson 类型的对象发送到以下端点：

`POST https://api.caas.qitech.app/credit_analysis/legal_person`

---

# 信用分析 - 自然人

URL: /zh-Hans/documentation/caas/credit_analysis/natural_person

要对自然人进行信用分析，请使用 NaturalPerson 端点。

在执行自然人信用分析时，需要将以下数据发送到我们的服务器。

## 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" : {
    ...
  }
}
```

信用分析应在放款前发送至 API，可用于决定是否授予信贷。在与客户协商后，发送的数据也可用于欺诈预防。

**CreditProposal** 对象中使用但本节未定义的对象可在[共享对象](#objetos-compartilhados)部分查看。

|                   名称                   |      类型      | 描述                                                                                                                                                                      |
| :--------------------------------------: | :------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|                    id                    |    string     | 您系统中信贷提案的标识符。<br /> **此数字对于每次信用分析流程必须唯一** *（必填）*|
|registration_id | string | 客户系统中的注册标识符。用于针对同一注册执行多次分析|
|           credit_request_date            |    datetime    | 借款人申请信贷的日期和时间 *（必填）*|
|               credit_type                |   枚举   | 授予的信贷类型。目前支持：**clean**、**student_loan**、**credit_card_limit** |
| name | string | 被注册个人的全名 |
| document_number | string | 被注册个人的 CPF，含点和连字符，符合标准 *（必填）* |
| birthdate | date | 个人出生日期，符合标准
| gender | 枚举 | 个人性别：'male'、'female' 或 'undefined'
| nationality | string | ISO 3166-1 alfa-3 格式的注册国籍
| mother_name | string | 母亲全名
| father_name | string | 父亲全名
| monthly_income | integer | 月总收入，以分为单位
| declared_assets | integer | 申报资产，以分为单位
|client_category    |         string          | 根据您平台或忠诚度计划分类的客户类别
|client_since    |         date | 开始为该客户提供服务的日期
| occupation | string | 被注册个人的职业
| email | string | 个人电子邮件
| documents | Document | CNH 和 RG 类型对象
| address | _Address_ | Address 类型对象，描述个人住宅地址
| phones | _Phones_ 列表 | phone 类型对象列表，包含个人电话列表
|                guarantors                | _Person_ 列表 | 业务担保人，自然人（**NaturalPerson**）或法人（**LegalPerson**）                                                                                       |
|             financial.amount             |    integer     | 借款人申请的总金额（分），批准后将予以释放                                                                                             |
|             financial.currency           |    枚举     | 总金额的货币单位：**BRL**、**USD**、**EUR**                                                                                          |
|              interest_type               |   枚举   | 使用的债务基准利率：**cdi_plus**、**cdi_percentage**、**price**、**pre_fixed**                                                                           |
|           annual_interest_rate           |     number     | 固定利率部分的年利率百分比                                                                                                                     |
|              cdi_percentage              |     number     | 收取的 CDI（后置）利率百分比                                                                                                                               |
|          number_of_installments          |    integer     | 分期数                                                                                                                                                             |
|                 warrants                 |     _Warrant_     | 业务中提供的实物担保数据。必须在投产前商定。目前接受以下类型：**real_estate**                  |
|              source               |     _Source_     | 信贷销售渠道。目前接受：**website** 和 **app**                                                                                                     |
| scr_parameters| _ScrParameters_ | 包含在信用分析中使用 SCR 信息所需数据的对象 |

:::info **注意**
仅当客户已购买且希望在信用分析中使用 SCR 查询时， scr_parameters 属性才是必填项。
:::

## 发送信贷提案 - 自然人

Request Body

```json
  {
    "id": "12345678",
    ...
  }
```

Response Body

```json
{
  "id": "12345678",
  "analysis_status": "automatically_approved",
  "reason": "rule_decision_enum"
}
```

要对信贷提案进行评估，只需将 **NaturalPerson** 类型对象发送到以下端点：

`POST https://api.caas.qitech.app/credit_analysis/natural_person`

---

# 共享对象

URL: /zh-Hans/documentation/caas/credit_analysis/objects

以下是文档中使用的其他对象的定义。

## 对象 _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"
}
```

_Address_ 对象用于在整个 API 中表示地址，巴西境内的地址格式如下：

| 名称         |  类型  | 描述                                                                                    |
| ------------ | :----: | -------------------------------------------------------------------------------------------- |
| street       | string | 地址街道，包含地址类型，尽量避免缩写 *（必填）*。 |
| number       | string | 门牌号，包含字母（如有）*（必填）*。                              |
| neighborhood | string | 街区，不使用缩写 *（必填）*。<br />**例：Santa Felicidade**                    |
| city         | string | 城市全称，不使用缩写 *（必填）*。                                    |
| uf           | string | 两位大写字母的州代码 *（必填）*。<br />**例：SP**         |
| complement   | string | 用于定位物业的任何补充信息。<br />**例：Apartamento 101, Conjunto 12** |
| postal_code  | string | 包含连字符的邮政编码 *（必填）*。                             |
| country      | string | 地址所在国家的 ISO 3166-1 alpha-3 代码 *（必填）*。                                |

对于非巴西（"BRA"）地址，postal_code 和州代码可自由填写。

## 对象 _Phone_

Request Body

```json
{
  "international_dial_code": "1",
  "area_code": "11",
  "number": "999999999",
  "type": "mobile"
}
```

_Phone_ 对象表示国内或国际电话号码及其分类，包含以下字段：

| 名称                    |  类型  | 描述                                                        |
| ----------------------- | :----: | ---------------------------------------------------------------- |
| international_dial_code | string | 国际拨号代码，不含零或加号，仅数字 *（必填）*。 |
| area_code               | string | 区号，不含前置零，仅数字 *（必填）*。                        |
| number                  | string | 电话号码，不含连字符 *（必填）*。                                  |
| type                    |  enum  | 号码类型：手机、住宅、商务等。            |

电话类型枚举值：`residential`、`commercial`、`mobile`

## 对象 _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"
}
```

*cnh* 对象用于在整个 API 中表示 CNH（驾驶证），以及是否使用了某种验证手段。格式如下：

名称 | 类型 | 描述
---- | :----: | ---------
register_number | string | 已注册 CNH 的登记编号。
issuer_state | enum | 颁发 CNH 的州代码枚举值
first_issuance_date | date | 首次颁发日期。
issuance_date | date | 颁发日期
expiration_date | date | 到期日期
category | enum | CNH 类别（大写字母）
validation_type | enum | 文件注册时使用的验证类型。
ocr_key | guid | [QI Tech 文件验证 API](https://docs.zaig.com.br/ocr/#introducao) 返回的 ID。

*validation_type* 枚举值：`zaig_api` 和 `zaig_sdk`。

## 对象 _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"
}
```

*rg* 对象用于在整个 API 中表示 RG（身份证），以及是否使用了某种验证手段。格式如下：

名称 | 类型 | 描述
---- | :----: | ---------
number | string | 已注册文件的编号，包含格式（点号、连字符、斜杠等）。
issuer | string | 文件颁发机构（缩写，例：II、SESP...）
issuer_state | enum | 文件颁发州代码。
issuance_date | date | 文件颁发日期。
validation_type | enum | 文件注册时使用的验证类型。
ocr_key | guid | QI Tech 文件验证 API 返回的 ID。

*validation_type* 枚举值：`zaig_api` 和 `zaig_sdk`。

## 对象 _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"
    }
  ]
}
```

_NaturalPerson_ 对象表示借款人本人、担保人或借款企业的股东数据，由以下字段组成：

| 名称             |       类型       | 描述                                                                                      |
| ---------------- | :--------------: | ---------------------------------------------------------------------------------------------- |
| name             |      string      | 全名 *（必填）*。                                                                                 |
| document_number  |      string      | CPF，格式正确 *（必填）*。                                                                |
| birthdate        |       date       | 出生日期。                                                              |
| email            |      string      | 电子邮件地址。                                                                              |
| gender           |       enum       | 性别，依据枚举列表。                                  |
| address          |    _Address_     | 居住地址。                                                               |
| phones           | list of _Phone_ | 联系电话列表。                                                                |

性别枚举值：

- `male`
- `female`
- `undefined`

## 对象 _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": [ { ... }]
}
```

_LegalPerson_ 对象表示借款企业或担保企业（保证人）的数据，由以下字段组成：

| 名称              |          类型           | 描述                                                                      |
| ----------------- | :---------------------: | ------------------------------------------------------------------------------ |
| legal_name        |         string          | 公司全称 *（必填）*。                                                                   |
| trading_name      |         string          | 商号名称                                                                  |
| document_number   |         string          | CNPJ，按本文档规定的格式填写 *（必填）*。              |
| constitution_date |          date           | 公司注册成立日期，依据商业登记                  |
| constitution_type |       enum        | 公司组织形式：**LLC**、**corp**                           |
| email             |         string          | 公司代表的电子邮件                                            |
| address           |        _Address_        | 公司总部地址                                              |
| phones            |    list of _Phone_     | 公司联系电话列表                                             |
| shareholders      | list of _NaturalPerson_ | 公司股东，以自然人模式（**NaturalPerson** 对象）表示 |

## 对象 _Source_

Request Body: 通过自有网站进行的信用申请

```json
{
  "channel": "website",
  "ip": "201.81.161.86",
  "session_id": "b8da64db-e8f8-47fc-8d8e-11ce26da499f"
}
```

Request Body: 通过自有应用程序进行的信用申请

```json
{
  "channel": "app",
  "platform": "android",
  "ip": "201.81.161.86",
  "session_id": "b8da64db-e8f8-47fc-8d8e-11ce26da499f"
}
```

source 对象表示信用申请的来源渠道。

注意，如果所需销售渠道不属于上述任何类别，请联系 支持团队

## 对象 _Warrant_

> 对于具有某种担保的信用分析，可以使用 warrant 对象将其告知我们的 API。目前仅接受不动产担保，如需其他类型的担保，请联系我们的 支持团队

Request Body

```json
  {
    "warrant_type": "real_estate",
    "address": { ... },
    "property_type": "house",
    "estimated_value": 100000000,
    "forced_selling_value": 60000000
  }
```

对于 **real_estate** 类型的担保，对象由以下字段组成：

| 名称                 |  类型   | 描述                                                                                                                 |
| -------------------- | :-----: | ------------------------------------------------------------------------------------------------------------------------- |
| warrant_type         |  enum   | 定义担保类型。目前仅实现了 **real_estate**。                                          |
| address              | _Address_  | 作为担保的不动产的 Address 类型对象                                                         |
| property_type        |  enum   | 不动产类型，目前可用：**house**、**commercial_building**、**office**、**appartment** |
| estimated_value      | integer | 不动产估计价值                                                                                                |
| forced_selling_value | integer | 不动产估计强制拍卖价值                                                                               |

注意，如果所需担保类型不属于上述任何类别，请联系 支持团队

## 对象 _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."
        }
      }
    }
  }
```

| 名称                 |  类型   | 描述                                                                                                                 |
| -------------------- | :-----: | ------------------------------------------------------------------------------------------------------------------------- |
| signers |  List of _Signer_ | 将要签署或已签署 SCR 查询同意授权的人员列表。此对象仅在法人信用分析时需要发送。 |
| signature_evidence | _SignatureEvidence_  | 当在客户平台上请求授权时，用于发送在授权同意时收集的信息的对象。 |

## 对象 *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"
    }
  }
```

| 名称                 |  类型   | 描述                                                                                                                 |
| -------------------- | :-----: | ------------------------------------------------------------------------------------------------------------------------- |
| document_number        |  string   | 签署人的文件编号。 |
| name | string | 签署人姓名。 |
| email | string | 签署人电子邮件。 |
| phone | _Phone_ | 签署人电话。 |

## 对象 *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."
      }
    }
  }
```

| 名称                 |  类型   | 描述                                                                                                                 |
| -------------------- | :-----: | ------------------------------------------------------------------------------------------------------------------------- |
| ip_address | string  | 签署人的 IP 地址 |
| session_id | string | 用户在您平台上的会话标识符，应为可通过该标识符请求审计您平台 OptIn 操作的某个标识符。 |
| access_token |  string | 已登录用户在您平台上的标识符，应可通过该标识符请求该用户的注册审计。 |
| additional_data | object | 可配置的 JSON 对象，用于容纳合作伙伴认为相关的、能增加其平台内签署操作可信度/真实性的附加信息。 |
| signed_term | _SignedTerm_ | 包含用于收集同意的条款相关信息的对象。 |

## 对象 *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."
  }
```

| 名称                 |  类型   | 描述                                                                                                                 |
| -------------------- | :-----: | ------------------------------------------------------------------------------------------------------------------------- |
| raw_text | string | 正在签署的条款的纯文本内容。 |

---

# 信贷信息系统数据（SCR - BACEN）

URL: /zh-Hans/documentation/caas/credit_analysis/scr

如果客户有需求，我们提供在信用分析时使用 SCR 中自然人或法人可用数据的选项。使用 SCR 数据的前提是必须收集被查询方的同意。此同意可由 QI Tech 或客户自行收集，这会影响同意流程以及需要发送给 API 的数据，具体如下：

**1. 通过 QI Tech 收集同意 -** 如果选择通过 QI Tech 收集同意，QI Tech 将通过电子邮件直接向被查询用户发送电子签名链接，当用户签署链接并完成流程后，SCR 信息将自动变为可用。使用此流程时，集成时需要发送最终签署同意书的用户数据。

**2. 由客户自行收集同意 -** 您可以在自己的环境或信贷流程中收集同意书签名（可通过签署文件或条款选择框完成）。为此，所使用的同意书必须经过 QI Tech 法律团队验证，并且需要通过 *scr_parameters* 对象发送可审计地证明已收集 SCR 信息访问同意的信息。

注意，两种 SCR 信息访问配置（包括使用哪种流程）必须在产品购买期间商定，以便该功能可供使用。

## 通过 QI Tech 收集同意 - 自然人

对于自然人，QI Tech 发送同意请求，只需在 CreditProposal 对象中填写被查询方的个人数据即可。QI Tech 将通过电子邮件向被查询方发送同意请求，并在获得授权后自动执行查询，提供结果以供信用分析。

通过 QI Tech 收集自然人同意时，必须发送 _document_number_ 、 name 、 email 字段和 phone 对象。

## 通过 QI Tech 收集同意 - 法人

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"
          }
        }
      ]
    }
  }
```

对于法人，QI Tech 发送同意请求时，需要在分析请求中包含额外的 scr_parameters 对象。在该对象中，需要添加公司法定代表人列表，将向他们发送电子签名请求。该列表应在 signers 属性中发送。所有法定代表人签署后，QI Tech 将执行查询，提供结果以供信用分析。上面是上述情况的 scr_parameters 对象示例。

## 由客户自行收集同意 - 自然人

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."
        }
      }
    }
  }
```

对于自然人，当同意由客户自行收集时，需要在分析请求中包含额外的 scr_parameters 对象。在该对象中，需要添加证明被分析人已授权查询的信息。这些信息应在 signature_evidence 属性中发送。上面是上述情况的 scr_parameters 对象示例。

## 由客户自行收集同意 - 法人

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."
        }
      }
    }
  }
```

对于法人，当同意由客户自行收集时，需要在分析请求中包含额外的 scr_parameters 对象。在该对象中，需要添加证明被分析人已授权查询的信息，以及授权查询的公司法定代表人列表。授权信息应在 signature_evidence 属性中发送，授权查询的人员列表应在 signers 属性中发送。上面是上述情况的 scr_parameters 对象示例。

---

# 标准

URL: /zh-Hans/documentation/caas/credit_analysis/standards

为便于集成并确保信息完整性，整个 API 遵循以下统一标准。

## 货币金额
> 示例：

```
10000
12345
98741
1223
1
0
```

API 假定所有发送的货币金额均为巴西雷亚尔。金额应以整数（分）形式发送。

## 含时区的日期和时间
> 部分示例：

```
2019-10-15T22:35:12-03:00
2018-05-01T13:32:11+00:00
2019-05-01T00:00:00+00:00
```

按照 ISO 8601 表示。在这种情况下，时区紧跟在时间之后，必须表示该数据有效所在地的时区。例如，如果租赁计划在巴西利亚机场 09:30 开始，则发送的时间应表示为 09:30-03:00；如果租赁计划在马瑙斯 09:30 开始，则应表示为 09:30-04:00。

用于验证的掩码如下：

`YYYY-MM-ddThh:mm:ss±hh:mm`

## 不含时区的日期和时间
> 部分示例：

```
2019-10-15T22:35:12
2018-05-01T13:32:11
2019-05-01T00:00:00
```

按照 ISO 8601 表示。与时区无关的数据应不含时区，始终使用 UTC，字母 Z 表示该数据为 UTC。因此，将验证以下格式：

`YYYY-MM-ddThh:mm:ssZ`

## 日期
> 部分示例

```
2019-10-15
2019-01-01
2017-03-20
```

对于仅接收日期的字段（例如出生日期），应只发送日期，不含任何时间，格式如下：

`YYYY-MM-dd`

## 文件/证件号

由于文件号码种类繁多，且许多包含非数字字符，因此所有文件号码均定义为字符串。将其定义为字符串的另一个好处是避免前导零消失。本页面中规定的文件格式具有明确的掩码，将进行验证。其他文件（如 RG）由于缺乏标准化，不进行验证。

## CPF

> 符合已定义掩码的有效 CPF 示例：

```
123.456.789-12
321.987.543-23
111.283.333-00
```

> 不符合已定义掩码的无效 CPF 示例：

```
8.577.477-8
08.104.627/0001-23
123.456.789-1
23.456.789-01
```

CPF 始终定义为字符串，将按掩码进行验证：

`###.###.###-##`

## CNPJ

> 符合已定义掩码的有效 CNPJ 示例：

```
08.104.627/0001-02
01.079.210/0114-67
32.402.502/0001-35
```

> 不符合已定义掩码的无效 CNPJ 示例：

```
8.577.477-8
123.456.789-12
321.987.543-23
32.402.502/0001-3
032.402.502/0001-3
```

CNPJ 始终定义为字符串，将按掩码进行验证：

`##.###.###/####-##`

## IP

> 符合已定义掩码的有效 IP 示例：

```
201.81.161.86
201.081.161.86
201.81.161.086
201.81.0.1
```

> 无效 IP 示例：

```
201.81..86
358.81.161.86
201.81.161
```

IP 地址始终以 IPv4 格式发送，可以带也可以不带前导零，遵循以下掩码：

`###.###.###.###`

---

# 状态动态

URL: /zh-Hans/documentation/caas/credit_analysis/status_dynamics

信用分析过程包括在相应端点发送 **NaturalPerson** 或 **LegalPerson** 请求，并等待响应。

QI Tech 完成信用分析后，将返回一个包含分析相关状态的响应。该状态名为 **analysis_status**，代表 QI Tech 信用分析的结果。

除 **analysis_status** 外，QI Tech 还具有 **credit_proposal_status**，旨在表示已分析信贷在您平台上每个时刻的状态。

## **analysis_status**

如前所述，QI Tech 共有九种 **analysis_status**，用于指示信用分析决策的状态，其状态机非常简单：

analysis_status | 描述
:---------: | ---------
automatically_approved | QI Tech 的算法建议批准此注册
automatically_reproved | QI Tech 的算法建议拒绝此注册
in_manual_analysis | QI Tech 的算法将此注册转至人工分析
manually_approved | 人工分析后，分析师决定批准该注册
manually_reproved | 人工分析后，分析师决定拒绝该注册
waiting_for_data | 信用分析正在等待某些征信机构或数据提供商的信息返回，将通过 Webhook 进行响应
automatically_challenged | QI Tech 的算法建议对此注册发起挑战
manually_challenged | 人工分析后，分析师决定对该注册发起挑战
pending | 信用分析耗时超出预期，该注册已进入自动分析队列，将通过 Webhook 进行响应

:::info **注意**

您必须将 EXAMPLE-OF-API-KEY 替换为从支持团队收到的 API Key。
:::

## **credit_proposal_status**

**credit_proposal_status** 表示客户操作的状态，即信贷提案在您的企业或平台中的状态。此状态具有以下枚举值：

credit_proposal_status | 描述
:---------: | ---------
created | 信贷提案已在您的平台创建
disbursed | 信贷提案已在您的平台完成放款
paid | 客户已全额还款
defaulted | 客户在您的平台处于违约状态

---

# 更新信用分析状态

URL: /zh-Hans/documentation/caas/credit_analysis/update_credit_analysis

Request Body: 将信用标记为已授予

```json
{
  "credit_proposal_status": "disbursed",
  "event_date": "2021-11-05T13:34:12-03:00"
}
```

为确保规则和人工智能模型的持续优化，必须通知系统操作何时被有效执行。为此，需要使用 PUT 方法，并正常进行认证：

* **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: /zh-Hans/documentation/caas/credit_analysis/webhook

状态更新（针对转人工分析或响应为待处理的注册）通过 Webhook 进行通知。为此，需要通过[支持](mailto:suporte.caas@qitech.com.br)团队配置一个端点地址，我们将通过该地址通知更新，同时还需配置一个用于签署请求的 *secret_token*。

尽管不推荐，客户也可以使用[轮询](https://en.wikipedia.org/wiki/Polling_(computer_science))技术。在这种情况下，不需要配置 webhook 端点，只需使用注册检索端点进行轮询即可。

## 签名

> Python 签名计算示例

```python
    hmac_obj = hmac.new(signature_key.encode('utf-8'), (endpoint + method + payload).encode('utf-8'), hashlib.sha1)
    return hmac_obj.hexdigest()
```

为确保接收到的 webhook 端点请求来自我们的服务器，类似于认证过程，在 Signature Header 中发送 HMAC 签名。

在服务器端计算出签名预期值后，需要将计算出的签名与发送的签名进行比较。如果签名匹配，则意味着请求来自我们的服务器并且是可信的。

## 请求

```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"}'
```

请求具有上述格式，并通知状态变更。重要提示：请求使用 HTTP POST 方法，请求体以 UTF-8 编码文本形式发送。

## 重试

当收到 HTTP Status 200 响应时，通知被视为已送达。如果通知失败，将进行 5 次重试，时间间隔如下，直到收到 200 或重试结束：

* 30 秒
* 60 秒
* 120 秒
* 240 秒
* 360 秒

---

# Account 对象

URL: /zh-Hans/documentation/caas/device_manager/account

account（账户）是一个组织实体，允许注册设备。该 API 旨在满足[巴西央行第 491 号规范](https://www.bcb.gov.br/estabilidadefinanceira/exibenormativo?tipo=Instru%C3%A7%C3%A3o%20Normativa%20BCB&numero=491)，因此账户数据必须遵循巴西中央银行定义的信息标准，但任何其他必要字段都可以添加到账户数据中。

## 定义 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"
    ...
  }
}
```

account 的所有信息交换均使用以下对象定义。在某些情况下，为了方便实现并减少双方之间的数据流，部分信息可以省略。

名称 | 类型 | 描述
:----: | :----: | ---------
account_id | string | account 的标识符。 **每个 account 的该编号必须唯一** *（必填）*
account_type | string | 在设备注册系统中注册的 account 类型标识符。账户可以是自然人类型 `natural_person` 或法人类型 `legal_person`。*（必填）*
registration_date | datetime | account 注册的日期和时间，含时区。*（必填）*
account_data | object | 可以包含任何 account 数据的对象，但如果包含账户号码 `account_number` 和机构号 `agency_number`，则两者必须为 string 类型。

## 提交 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"
      ...
    }
  }
```

要创建 account，只需将 Account 类型的对象发送到以下端点：

`POST https://api.caas.qitech.app/device_manager/account`

---

# 认证

URL: /zh-Hans/documentation/caas/device_manager/authentication

> 要认证一个调用，请使用以下代码：

```shell
# 在 shell 中，您只需在每次请求时添加适当的 header
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE-OF-API-KEY"
```

> 将 API Key 'EXAMPLE-OF-API-KEY' 替换为您的密钥，该密钥应通过我们的支持团队获取。

我们使用 API Key 来允许访问我们的 API。它可能已经通过电子邮件发送给您了。如果您还没有收到密钥，请发送电子邮件至 suporte.caas@qitech.com.br 。

我们的 API 期望在所有向我们服务器的请求中，通过以下 header 接收 API Key：

`Authorization: EXAMPLE-OF-API-KEY`

:::info **注意**

您必须将 EXAMPLE-OF-API-KEY 替换为您的密钥，该密钥应通过我们的支持团队获取。
:::

---

# Device 对象

URL: /zh-Hans/documentation/caas/device_manager/device_registration

具有唯一标识的设备（device）注册必须通过 Device 端点完成。为使注册生效，必须使用 Device Scan 记录该设备的标识，以便后续识别。

### 状态动态 - **status**

**status** 状态表示设备的当前状态。以下状态可用：

* registered
* not_registered
* deactivated

### 状态动态 - **analysis_status**

**analysis_status** 状态表示欺诈检测引擎的决策状态，具有以下状态流：

* automatically_approved
* automatically_reproved
* pending

## 定义 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"
}
```

注册的所有信息交换均使用以下对象定义。在某些情况下，为了方便实现并减少双方之间的数据流，部分信息可以省略。

名称 | 类型 | 描述
:----: | :----: | ---------
device_id | string | 设备标识符。 **每个设备的该编号必须唯一** *（必填）*
session_id | string | Device Scan 中的会话标识符。*（必填）*
face_recognition_key | string | 如果人脸识别产品作为注册的双因素认证，则为人脸生物特征图像标识符。
document_number | string | 用于人脸验证的用户文件编号。仅当在注册 person 对象时未提供时才需要发送。
mfa_status | string | 注册的 MFA 状态，可为以下值之一：*approved* *reproved*
registration_date | datetime | 注册开始的日期和时间，含时区。*（必填）*

:::warning 注意
`document_number` 字段是在数据库中进行人脸验证所必需的，因此，如果在用户注册时未提供，则为必填项。其值绝不能与 person 中注册的值不同。
:::

## 提交 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"
  }
```

要注册设备，只需将 Device 类型的对象发送到以下端点：

`POST https://api.caas.qitech.app/device_manager/account/{account_id}/person/{person_id}/device`

---

# HTTP 状态码

URL: /zh-Hans/documentation/caas/device_manager/http_status

QI Tech 所有 API 均遵循以下 HTTP 返回状态标准，符合 RFC 7231 ：

HTTP 状态码 | 含义 | 描述
:----------: | :-------: | ---------------------------------
400 | Bad Request | 发送的请求存在格式错误。通常，我们会在消息正文中返回错误位置的说明。
401 | Unauthorized | 认证过程中出现问题，请检查 API Key 是否正确以及是否在正确的 header 中，参见 认证 部分。
403 | Forbidden | 访问的端点仅供内部使用，此 API Key 无法访问。
404 | Not Found | 使用的密钥未找到所请求的数据。当请求无效端点时也会返回此状态。
405 | Method Not Allowed | 使用的 HTTP 方法不适用于此端点。
406 | Not Acceptable | 请求正文中发送的数据无效。通常，这意味着发送的数据不是有效的 JSON。
409 | Conflict | 请求的 id 对应于之前已处理的 id。当向服务器发送重复请求时返回此状态。
500 | Internal Server Error | 处理此请求时出现问题。遇到此错误时，我们的专家会自动收到通知并立即开始分析和解决。
503 | Service Unavailable | 表示我们服务器基础设施的临时不可用状态，无论是计划内还是计划外。

---

# 简介

URL: /zh-Hans/documentation/caas/device_manager/introduction

欢迎使用 QI Tech 设备注册 API！该 API 旨在满足[巴西央行第 491 号规范](https://www.bcb.gov.br/estabilidadefinanceira/exibenormativo?tipo=Instru%C3%A7%C3%A3o%20Normativa%20BCB&numero=491)的要求。结合 Device Scan，该 API 能够为每台设备生成唯一标识。

该 API 管理设备识别流程，使您能够在后续验证同一设备。该流程通过以下实体构建：

* Account - 账户
* Person - 人员
* Device - 设备

您可以使用我们的 API 通过以下服务创建和检索设备注册：

* **Device Registration** - 用于将设备与人员关联。通过此注册，可以对同一人员的后续访问进行设备验证。

## 环境

我们为客户提供两个环境。API 的基础 URL 为：

* 生产环境 - `https://api.caas.qitech.app/device_manager/`
* 沙盒环境 - `https://api.sandbox.caas.qitech.app/device_manager/`

:::danger 重要提示！
QI Tech 沙盒环境中不得使用真实的个人或法人数据。
:::

在沙盒环境中，提交的分析不收费，并根据为该事件配置的规则进行响应。

## 仅限 HTTPS

出于安全考虑，与 QI Tech API 的所有通信必须使用 HTTPS。为确保不会因疏忽或其他原因发生 HTTP 调用，该服务器仅开放使用 TLS 1.2 通信的 443 端口。使用其他协议的调用将被自动拒绝。

## 遇到问题？

我们不是一家躲在 API 背后的公司！请联系我们的 支持团队 ，我们将尽快回复。如需快速响应，欢迎致电！

### 我们热爱反馈

即使您已经解决了问题，或者问题非常简单（如错别字或组织不当），也请发送电子邮件给我们。这样，我们可以使文档越来越实用，避免其他开发者遇到相同的困难。

---

# Person 对象

URL: /zh-Hans/documentation/caas/device_manager/person

一个账户可以有多个用户访问，因此每个用户都必须有其注册信息，以区分联名账户中的操作。以下信息必须遵循既定标准，但如有需要，任何字段都可以添加到账户数据中。

## 定义 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"
    }
  }
}
```

人员的所有信息交换均使用以下对象定义。在某些情况下，为了方便实现并减少双方之间的数据流，部分信息可以省略。

名称 | 类型 | 描述
:----: | :----: | ---------
person_id | string | 人员标识符。 **每个人员的该编号必须唯一** *（必填）*
document_number | string | 文件编号，可以是带格式的 CPF 或 CNPJ。
registration_date | datetime | 与账户关联的人员注册日期和时间，含时区。*（必填）*
person_data | object | 可以包含任何人员数据的对象。如果包含姓名 `name`、电子邮件 `email` 和电话 `phone`（及其字段 `number`、`international_dial_code` 和 `area_code`），则上述所有对象必须为 string 类型。

## 创建 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"
      }
    }
  }
```

要创建人员，只需将 Person 类型的对象发送到以下端点：

`POST https://api.caas.qitech.app/device_manager/account/{account_id}/person`

---

# 检索或停用 Account、Person 或 Device

URL: /zh-Hans/documentation/caas/device_manager/query_registration

## 查询特定 Device

要检索特定 Device，只需发送 GET 请求。返回的结果是该 Device 最新的 JSON 数据。如果该标识符未与任何对象关联，则返回 HTTP 状态码 404。

`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"
```

## 查询 Device 列表

要检索多个 Device，只需发送 GET 请求。返回的结果是包含某个用户所有 Device 基本信息列表的 JSON。

`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"
```

## 停用特定 Device

要停用特定 Device，只需发送 DELETE 请求。如果该标识符未与任何对象关联，则返回 HTTP 状态码 404。Device 停用后将无法再被验证。

`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"
```

## 查询特定账户

通过标识符检索账户数据。返回账户详情，如不存在则返回 404。

`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"
```

## 查询特定人员

检索账户中特定人员的数据。返回该人员的最新数据，如不存在则返回 404。

`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"
```

---

## 停用账户

停用一个账户。停用后，该账户将无法再用于注册或验证设备。

`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"
```

## 停用人员

停用账户中的一个人员。停用后，该人员将无法再注册或验证设备。

`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"
```

---

# 标准规范

URL: /zh-Hans/documentation/caas/device_manager/standards

为便于集成并保证信息完整性，整个 API 遵循以下定义的标准。

## 货币金额
> 示例：

```
10000
12345
98741
1223
1
0
```

API 假定所有发送的货币金额均为巴西雷亚尔。金额必须以整数形式发送，代表分（centavos）。

## 带时区的日期和时间
> 部分示例：

```
2019-10-15T22:35:12.232-03:00
2018-05-01T13:32:11.297+00:00
2019-05-01T00:00:00.000+00:00
```

按 ISO 8601 格式表示。在此情况下，时区紧跟在时间之后，必须代表该数据有效的本地时区。

用于验证的掩码如下：

`YYYY-MM-ddThh:mm:ss.sss±hh:mm`

## 不带时区的日期和时间
> 部分示例：

```
2019-10-15T22:35:12
2018-05-01T13:32:11
2019-05-01T00:00:00
```

按 ISO 8601 格式表示。与时区无关的数据应使用 UTC，以字母 Z 表示该数据为 UTC 时间。因此，将验证以下格式：

`YYYY-MM-ddThh:mm:ss.sssZ`

## 日期
> 部分示例

```
2019-10-15
2019-01-01
2017-03-20
```

对于仅接收日期（不含时间）的字段，应使用以下格式发送：

`YYYY-MM-dd`

## 文件编号
由于文件编号差异很大，许多文件编号包含非数字字符，因此所有文件编号均定义为字符串类型。将其定义为字符串的另一个好处是避免前置零丢失。本页面中规定的文件编号具有明确的掩码并将进行验证。其他文件编号，如 RG，由于缺乏标准化，将不进行验证。

## CPF

> 符合定义掩码的有效 CPF 示例：

```
123.456.789-12
321.987.543-23
111.283.333-00
```

> 不符合定义掩码的无效 CPF 示例：

```
8.577.477-8
08.104.627/0001-23
123.456.789-1
23.456.789-01
```

CPF 始终定义为字符串，并将根据以下掩码进行验证：

`###.###.###-##`

## CNPJ

> 符合定义掩码的有效 CNPJ 示例：

```
08.104.627/0001-02
01.079.210/0114-67
32.402.502/0001-35
```

> 不符合定义掩码的无效 CNPJ 示例：

```
8.577.477-8
123.456.789-12
321.987.543-23
32.402.502/0001-3
032.402.502/0001-3
```

CNPJ 始终定义为字符串，并将根据以下掩码进行验证：

`##.###.###/####-##`

## IP

> 符合定义掩码的有效 IP 示例：

```
201.81.161.86
201.081.161.86
201.81.161.086
201.81.0.1
```

> 无效 IP 示例：

```
201.81..86
358.81.161.86
201.81.161
```

IP 地址必须始终以 IPv4 格式发送，前置零可以发送也可以不发送，需遵循以下掩码：

`###.###.###.###`

---

# 状态动态

URL: /zh-Hans/documentation/caas/device_manager/status_dynamics

分析过程包括在相应端点发送事件（例如 Device Validation），然后等待响应。

QI Tech 完成事件分析后，将返回一个包含分析状态的响应。**analysis_status** 字段代表 QI Tech 进行事件分析的结果。

### **analysis_status**

如前所述，QI Tech 有三种 **analysis_status** 来指示分析引擎决策的状态，具有以下状态机：

analysis_status | 描述
:---------: | ---------
automatically_approved | QI Tech 的算法建议批准此事件。
automatically_reproved | QI Tech 的算法建议拒绝此事件。
pending | 查询耗时超过预期，此事件已进入自动分析队列，将尽快给出响应。

---

# 库兼容性

URL: /zh-Hans/documentation/caas/device_scan/android/compatibility

| 配置 | 最低版本 |
|------------|--------------|
|minSdkVersion|21|

---

# DeviceScan 对象

URL: /zh-Hans/documentation/caas/device_scan/android/device_scan_object

要使用 DeviceScanSDK，需要实例化 DeviceScan 类。该实例接收 currentContext，并可以使用 token/session、环境和回调（notifier）进行配置。

:::danger 重要提示！
从版本 5.0.0 开始，认证系统已更新为使用临时 **token** 替代 **mobileToken**。
:::

## 版本 5.0.0+

| 参数 | 功能 | 必需 |
|------------|--------------|--------------|
|currentContext|应用程序上下文，用于访问所需数据。 |是。|
|token（通过 .setToken(this.token)）| 认证令牌，标识所收集数据来自您的应用程序。通过向 Device Scan API 发送请求获取令牌。 |是。|
|sessionId（通过 .setSessionId(this.sessionId)）|所收集数据所属会话的标识符。|是。|
|notifier（通过 .setNotifier(this.deviceScanNotifier)）|DeviceScanNotifier 实例。作为回调，返回发送状态（成功或失败）。 |否。|
|sandbox（通过 .setSandboxEnvironment()）|将库配置为向 `sandbox` 环境发送数据。如果未配置，请求将发送至 `production`。 |否。|

 **默认环境**：如果未调用 `setSandboxEnvironment()`，则发送至 `production`。

## 旧版本（4.x 及以下）

| 参数 | 功能 | 必需 |
|------------|--------------|--------------|
|currentContext|应用程序上下文，用于访问所需数据。|是。|
|mobileToken（通过 .setMobileToken(this.mobileToken)）|标识所收集数据来自您的应用程序的客户端密钥。如果您尚未收到 **mobile-token**，请联系支持团队：<a href='mailto:suporte.caas@qitech.com.br'>suporte.caas@qitech.com.br</a>。|是。|
|sessionId（通过 .setSessionId(this.sessionId)）|所收集数据所属会话的标识符。|是。|
|notifier（通过 .setNotifier(this.deviceScanNotifier)）|DeviceScanNotifier 实例。作为回调，返回发送状态（成功或失败）。|否。|
|sandbox（通过 .setSandboxEnvironment()）|将库配置为向 `sandbox` 环境发送数据。如果未配置，请求将发送至 `production`。 |否。|

## 快速摘要（迁移）
- 5.0.0+：使用临时 `token`（`setToken(this.token)`）
- < 5.0.0：使用 `mobileToken`（`setMobileToken(this.mobileToken)`）
- 两者均需：`currentContext` 和 `sessionId` 为必填项。`notifier` 和 `sandbox` 为可选项。

---

# 实现

URL: /zh-Hans/documentation/caas/device_scan/android/example

:::danger 重要提示！
从版本 5.0.0 开始，认证系统已更新为使用动态 **token** 替代 **mobileToken**。在配置 SDK 之前，您必须通过向我们的 Device Scan API 发送服务器间请求来生成临时 **token**。
:::

```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){
            // 此方法可自定义，可用于存储 Activity，用于操作 UI
            this.activity = myActivity;
        }

        public void onSuccess(){
            Log.i("DeviceScan", "DeviceScan successfully submitted");
            runOnUiThread(new Runnable() {
                @Override
                public void run() {
                    // 在设备扫描成功发送后，在此处添加所需的任何 UI 更改
                }
            });
        }

        public void onError(){
            Log.i("DeviceScan", "DeviceScan submission failed");
            runOnUiThread(new Runnable() {
                @Override
                public void run() {
                    // 在设备扫描成功发送后，在此处添加所需的任何 UI 更改
                }
            });
        }
    }
}

```

要使用 Android Device Scan SDK，需要执行以下步骤：

* 在应用程序 manifest 中添加权限；
* 将库导入应用程序项目；
* 在应用程序启动时，实例化库，并在构造函数中传入适当的参数，包括负责返回操作结果的 Notifier；
* 使用 Activity 的 `onRequestPermissionsResult` 函数获取权限请求批准或拒绝的结果通知；
* 向用户请求权限。互联网访问权限对于库的正常运行是必需的；
* 收到权限批准或拒绝结果后，通过 `collectData` 方法收集并发送数据。

---

# 混合解决方案

URL: /zh-Hans/documentation/caas/device_scan/android/hybrid_solutions

除了提供 Java 原生集成外，我们的 SDK 还与多种跨平台框架兼容。这通过集成针对每个框架的特定原生插件来实现。利用每个解决方案的原生系统，可以在 Android 环境中集成我们的原生 SDK。

一些最常用的混合技术包括 React Native（[Native Modules](https://reactnative.dev/docs/turbo-native-modules-introduction)）、Cordova（[Plugin Development Guide](https://cordova.apache.org/docs/en/latest/guide/hybrid/plugins/index.html)）、Ionic（[Native](https://ionicframework.com/docs/v3/native/)）、Unity（[Native Plug-in for Android](https://docs.unity3d.com/Manual/PluginsForAndroid.html)）、Xamarin（[Native Libraries](https://learn.microsoft.com/en-us/xamarin/android/platform/native-libraries)）、Appcelerator、Phonegap 和 Node。

为简化与我们原生解决方案的集成过程，我们为 React Native 和 Flutter 框架提供了插件。如有需要，我们可在私有仓库中提供文档和集成示例。对于其他技术，我们也有一些与原生代码桥接的实现示例。欢迎联系我们的支持团队 suporte.caas@qitech.com.br 获取访问权限。

---

# 信息收集

URL: /zh-Hans/documentation/caas/device_scan/android/information_gathering

要触发信息的收集和发送，需要（在获取用户权限后）调用 `collectData` 方法。该方法除了获取设备信息外，还旨在映射客户在应用程序中的使用流程。因此，该方法还接受 `eventId` 和 `eventType` 字段。该方法具有以下参数：

名称 | 类型 | 描述
---- | ---- | ---------
documentNumber | String | 用户的文件号码（如果可用）。（CPF/CNPJ，不含点、连字符和斜杠）
eventId | String | 正在报告的事件的标识符
eventType | String | 定义正在报告的事件类型的枚举值。建议注意，非常相似的事件应使用相同的枚举值进行报告，以便可以基于这些数据构建智能。

调用数据收集后，在 `DeviceScan` 类构造函数中传入的 `DeviceScanNotifier` 实例的两个方法之一将被调用：一切正常时调用 `onSuccess`，出现错误时调用 `onError`。

---

# 简介

URL: /zh-Hans/documentation/caas/device_scan/android/introduction

欢迎使用 QI Tech Android Device Scan 集成手册！您应使用我们的 SDK 收集应用程序中设备信息和用户行为数据，从而提高决策的准确性。

## 遇到问题？

我们不是躲在 API 后面的公司！请联系我们的[支持团队](mailto:suporte.caas@qitech.com.br)，我们将尽快回复。如果您需要快速回复，请随时致电我们！

### 我们热爱反馈

即使您已经解决了问题，或者问题非常简单（例如一个拼写错误或不当的组织方式），也请给我们发电子邮件。这样，我们可以让文档变得越来越实用，下一个人就不必经历同样的痛苦。

## 环境

我们为客户提供两个环境。通过 SDK 构造函数中传入的枚举值进行选择。目前，以下环境可用：

* 生产环境 - `production`
* 沙盒环境 - `sandbox`

:::danger 重要提示！
不得在 QI Tech 沙盒环境中使用真实的个人和/或法人数据。
:::

---

# 原生集成

URL: /zh-Hans/documentation/caas/device_scan/android/native_java

要导入我们的 SDK，需要对项目和应用程序的 build.gradle 文件进行更改。

## 添加到项目
在项目的 build.gradle 文件中（在 Android Studio 中，此文件显示为 "Project: \{项目名称\}"）添加我们 Maven 仓库的地址，如下例所示：

```java
buildscript {
    ...
}

allprojects {
    repositories {
        ...
        maven { url 'https://sdks.qitech.com.br/' }
    }
}
```

## 添加到应用程序
然后，在应用程序的 build.gradle 文件中（在 Android Studio 中，此文件显示为 **"Module: \{项目名称\}.app"**）添加您想要导入的库，包含以下依赖项：

```java
dependencies {
    ...
    implementation 'com.qitech.android:devicescan:v6.0.0'
}
```

:::warning
自 **2025 年 4 月**起，Google Play 新政策要求应用程序使用 **Android API Level 35** 才能在 Google Play Store 上发布或更新。因此，我们强烈建议您至少使用 **targetSdkVersion 35**。
:::

:::info
使用 **targetSdkVersion 35** 意味着使用 **compileSdkVersion 35**，这对 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+
:::

## Manifest 文件

要使用 SDK，您必须在应用程序的 AndroidManifest 中添加以下配置：

```java
<meta-data
            android:name="com.google.android.gms.ads.AD_MANAGER_APP"
            android:value="true"/>
```

您还必须至少添加互联网权限，该权限用于将收集的数据发送到 QI Tech 服务器：

` `

权限列表应根据需要进行调整。

---

# 权限

URL: /zh-Hans/documentation/caas/device_scan/android/permissions

SDK 根据收集时可用的权限收集用户设备数据：您的应用请求的权限越多，用户授予的权限越多，可以收集的信息就越多。

:::info **注意**

INTERNET 权限是 SDK 能够将信息发送到 QI Tech 服务器的必要条件。
:::

## SDK 使用的权限

在当前版本的 SDK 中，以下权限在可用时可以使用：

| 权限 | 功能 | 必填 |
|------------|--------------|--------------|
|INTERNET|向 QI Tech 服务器发送信息。|是。|
|BLUETOOTH|捕获蓝牙硬件信息。|否。|
|BLUETOOTH_CONNECT|捕获蓝牙连接信息。|否。|
|READ_CONTACTS|读取联系人列表。|否。|
|ACCESS_COARSE_LOCATION|访问网络信息（基站、运营商等）及通过此方式获取位置（精度较低）。|否。|
|ACCESS_FINE_LOCATION|通过 GPS 访问位置（精度较高）。|否。|
|READ_PHONE_STATE|网络、SIM 卡、IMEI 及其他电话信息。|否。|
|QUERY_ALL_PACKAGES|设备上已安装应用的信息。Android 11 及以上版本的设备需要此权限。|否。|

:::info **重要**

我们的 SDK 不会主动请求上述权限。因此，为确保设备扫描更完整，建议在执行设备扫描调用前请求并获取这些权限。
:::

:::info **注意**

QUERY_ALL_PACKAGES 权限在应用发布时可能会与 Google Play 产生摩擦。为了解决这一问题，可以描述请求该权限的原因。
:::

---

# 认证

URL: /zh-Hans/documentation/caas/device_scan/api/authentication

:::danger 重要提示！
从 iOS 和 Android SDK 的 5.0.0 版本开始，认证系统已更新为使用临时令牌替代 mobileToken。
:::

我们使用 API Key 来允许访问我们的 API。通常，该密钥通过电子邮件发送。如果您尚未收到密钥，请发送邮件至 suporte.caas@qitech.com.br 。

## 临时认证令牌

在配置 SDK 之前，您必须通过向我们的 API 发送服务器间请求来生成临时令牌。

### 生成令牌

```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" }'
```

**端点**

| 环境 | URL |
|----------|-----|
| 沙盒 | https://d.sandbox.viewpkg.com/device_scan/token |
| 生产 | https://d.viewpkg.com/device_scan/token |

**请求详情**

| 字段 | 类型 | 必需 | 描述|
|-------|------|------------|---------|
| session_id | string | 是 | 由您的系统生成的唯一会话标识符（例如，UUID）。 |

**Request Body**
```json
{
  "session_id": "unique_session_identifier" 
}
```

**Response Body**

成功响应将包含 `token` 字段。
```json
{
  "token": "eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6..."
}
```

:::info 注意
请将 `EXAMPLE_API_KEY` 替换为从支持团队收到的 API Key。
:::

---

# 库兼容性

URL: /zh-Hans/documentation/caas/device_scan/flutter/compatibility

| 配置 | 最低版本 |
|------------|--------------|
|Dart SDK|2.15|
|iOS|12|
|minSdkVersion|21|

---

# QitechDeviceScan 对象

URL: /zh-Hans/documentation/caas/device_scan/flutter/device_scan_object

## 调用

要使用 Device Scan 插件，需要调用 'startDeviceScan' 方法，该方法具有以下参数：

| 参数 | 类型 | 功能 | 必需 |
|------------|--------------|--------------|--------------|
|mobileToken|String|标识所收集数据来自您的应用程序的客户端密钥。如果您尚未收到 mobile-token，请联系<a href='mailto:suporte.caas@qitech.com.br'>支持团队</a>。|是。|
|environment|CaaSEnvironment|用于将执行环境配置为 `sandbox` 或 `production` 的枚举值。 |是。|
|sessionId|String|标识所收集数据所属会话的密钥。|是。|
|eventType|String|定义正在报告的事件类型的枚举值——建议注意，非常相似的事件应使用相同的枚举值进行报告，以便可以基于这些数据构建智能。|是。|
|eventId|String|正在报告的事件的标识符|是。|
|documentNumber|String|用户的文件号码（如果可用）。（CPF/CNPJ，不含点、连字符和斜杠）|否。|

## 返回值

该方法返回一个字符串，表示信息收集期间的成功或失败：

### 成功

```javascript
DeviceScan data sent successfully
```

### 错误

```javascript
Device Scan fail. Check mobileToken, environment and permissions
```

---

# 实现

URL: /zh-Hans/documentation/caas/device_scan/flutter/example

```dart

import 'package:qitech_device_scan/qitech_device_scan.dart';

final _qitechDeviceScanPlugin = QitechDeviceScan();

final result = await _qitechDeviceScanPlugin.startDeviceScan(
    mobileToken: '<MOBILE_TOKEN_SENT_BY_QITECH>',
    environment: CaaSEnvironment.sandbox,
    sessionId: '<SESSION_ID>',
    eventType: '<EVENT_TYPE>',
    eventId: '<EVENT_ID>',
    documentNumber: '<USER_DOCUMENT_NUMBER>'
);

print('QiTech Device Scan result: ' + result);

```

## Flutter 设置

要使用 Device Scan 插件，需要执行以下步骤：

### 安装

首先，需要执行以下命令安装插件：

```bash
flutter pub add qitech_device_scan
```

该命令应安装最新版本，可在 `pubspec.yaml` 文件中验证：

```yaml
dependencies:
  qitech_device_scan: ^0.0.1
```

### 导入

现在，只需导入包即可开始使用：

```dart
import 'package:qitech_device_scan/qitech_device_scan.dart';
```

## Android 设置

在您的 `build.gradle` 文件中添加 Qi Tech Android 仓库引用：

```gradle
allprojects {
    repositories {
        maven { url 'https://sdks.qitech.com.br/' }
        ...
    }
}
```

通过在 `AndroidManifest.xml` 中添加以下代码来初始化 AdMob 服务：

```xml
<meta-data
    android:name="com.google.android.gms.ads.APPLICATION_ID"
    android:value="<ADMOB_APP_ID>"/>
```

如果您没有 `ADMOB_APP_ID`，请联系 suporte.caas@qitech.com.br 。

## iOS 设置

在您的 `Podfile` 文件中添加 Qi Tech Android 仓库引用：

```ruby
source 'https://cdn.cocoapods.org/'
source 'https://github.com/QITechSDKs/iOS.git'
```

直接通过 cocoapods 安装依赖项：

```bash
cd ios
pod install
```

或通过 flutter 安装：

```bash
flutter build ios
```

---

# 简介

URL: /zh-Hans/documentation/caas/device_scan/flutter/introduction

欢迎使用 QI Tech Flutter Device Scan 集成手册！您应使用我们的插件收集手机信息和应用程序中的用户行为数据，从而提高决策的准确性。

## 遇到问题？

我们不是躲在 API 后面的公司！请联系我们的[支持团队](mailto:suporte.caas@qitech.com.br)，我们将尽快回复。如果您需要快速回复，请随时致电我们！

### 我们热爱反馈

即使您已经解决了问题，或者问题非常简单（甚至是一个您已经理解的拼写错误或不当的组织方式），也请给我们发电子邮件，这样我们可以让文档变得越来越实用，下一个人就不必经历您所经历的痛苦！

## 环境

我们为客户提供两个环境。通过在插件调用参数中传入的枚举值进行选择。目前，以下环境可用：

* 生产环境 - `production`
* 沙盒环境 - `sandbox`

:::danger 重要提示！
不得在 QI Tech 沙盒环境中使用真实的个人和/或法人数据。
:::

---

# 权限

URL: /zh-Hans/documentation/caas/device_scan/flutter/permissions

插件根据收集时可用的权限来收集用户设备数据：您的应用程序请求的权限越多，用户授予的权限越多，能够从用户设备收集的信息就越多。

:::info **注意**

INTERNET 权限是 SDK 向 QI Tech 服务器发送信息的必要条件。
:::

## 插件使用的权限

:::info **重要**

我们的插件不会请求上述权限。因此，为确保更完整的设备扫描，我们建议在执行设备扫描调用之前收集这些权限。
:::

### Android

对于 Android 平台，如果以下权限可用，则使用：

| 权限 | 功能 | 必需 |
|------------|--------------|--------------|
|INTERNET|必需，用于向 QI Tech 服务器发送信息。| 是。 |
|BLUETOOTH|获取蓝牙硬件信息。| 否。 |
|BLUETOOTH_CONNECT|获取蓝牙连接信息。| 否。 |
|READ_CONTACTS|读取联系人列表。| 否。 |
|ACCESS_COARSE_LOCATION|访问网络信息（天线、运营商...）及通过此方式获取位置（精度较低）。| 否。 |
|ACCESS_FINE_LOCATION|通过 GPS 获取位置（精度较高）。| 否。 |
|READ_PHONE_STATE|网络、SIM 卡、IMEI 及其他电话功能信息。| 否。 |
|QUERY_ALL_PACKAGES|设备上已安装应用程序的信息。Android 11 及以上版本的设备需要此权限。| 否。 |

:::info **注意**

QUERY_ALL_PACKAGES 权限在应用程序发布时可能与 Google Play 产生摩擦。为解决此问题，可以描述请求该权限的原因。
:::

### iOS

对于 iOS 平台，如果以下权限可用，则使用：

* location - 获取设备地理位置数据

#### Info.plist 文件

为插件提供权限的第一步是在应用程序的 Info.plist 文件中配置权限，为每个所需权限使用以下代码行：

* location - 获取设备地理位置数据：

` NSLocationWhenInUseUsageDescription `
` 添加您希望在 iOS 请求地理位置访问权限时向用户显示的消息 `

:::info **注意**

为改善权限请求时的用户体验，您应按照前述方式自定义弹出请求中显示的消息。
:::

---

# QITechIosDeviceScan 对象

URL: /zh-Hans/documentation/caas/device_scan/ios/device_scan_object

要使用 QI Tech iOS DeviceScan，需要导入 QITechIosDeviceScan 框架，然后实例化 QITechIosDeviceScan 类，其构造函数具有以下参数：

:::danger 重要提示！
从版本 5.0.0 开始，认证系统已更新为使用临时 **token** 替代 **mobileToken**。
:::

## 版本 5.0.0+

名称 | 类型 | 描述
---- | ----- | ------
environment | String | 应用程序运行环境的枚举值 - `sandbox` 或 `production` - 如果发送了不同的值，将生成异常 **必填**
token | String | 认证令牌，标识所收集数据来自您的应用程序。通过向 Device Scan API 发送请求获取。**必填**
sessionId | String | 会话标识符（**必须与生成令牌时使用的相同**），将在事件评估时（例如交易、入驻）一同发送，用于关联设备扫描数据与待评估事件。**必填**

## 旧版本

名称 | 类型 | 描述
---- | ----- | ------
environment | String | 应用程序运行环境的枚举值 - `sandbox` 或 `production` - 如果发送了不同的值，将生成异常 **必填**
mobileToken | String | QI Tech 支持团队发送的客户端密钥，标识所收集数据来自您的应用程序。出于安全原因，如果此密钥不正确，QI Tech 服务器会接收但不处理该调用。**必填**
sessionId | String | 会话标识符，将在事件评估时（例如交易、入驻）一同发送，用于关联设备扫描数据与待评估事件。**必填**

---

# 实现

URL: /zh-Hans/documentation/caas/device_scan/ios/example

:::danger 重要提示！
从版本 5.0.0 开始，认证系统已更新为使用动态 **token** 替代 **mobileToken**。在配置 SDK 之前，您必须通过向我们的 Device Scan API 发送服务器间请求来生成临时 **token**。
:::

```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")
        }
    }
}
```

要使用 iOS Device Scan SDK，需要执行以下步骤：

在 Info.plist 文件中添加权限
将框架添加到应用程序项目
在应用程序启动时，实例化库，并传入适当的参数
如果您的应用程序尚未向用户请求权限，请通过之前实例化的对象的 `requestPermissions` 函数向用户请求权限
通过 `collectData` 方法收集并发送数据

---

# 混合解决方案

URL: /zh-Hans/documentation/caas/device_scan/ios/hybrid_solutions

除了提供 Swift 原生集成外，我们的 SDK 还与多种混合框架兼容。这通过集成针对每个框架的特定原生插件来实现。利用每个解决方案的原生系统，可以在 iOS 环境中集成我们的原生 SDK。

一些最常用的混合技术包括 React Native（[Native Modules](https://reactnative.dev/docs/turbo-native-modules-introduction)）、Cordova（[Plugin Development Guide](https://cordova.apache.org/docs/en/latest/guide/hybrid/plugins/index.html)）、Ionic（[Native](https://ionicframework.com/docs/v3/native/)）、Unity（[Native Plug-in for Android](https://docs.unity3d.com/Manual/PluginsForAndroid.html)）、Xamarin（[Native Libraries](https://learn.microsoft.com/en-us/xamarin/android/platform/native-libraries)）、Appcelerator、Phonegap 和 Node。

为简化与我们原生解决方案的集成过程，我们为 React Native 和 Flutter 框架提供了插件。如有需要，我们可在私有仓库中提供文档和集成示例。对于其他混合技术，我们也有一些与原生代码桥接的实现示例。欢迎联系我们的 支持团队 获取访问权限。

---

# 信息收集

URL: /zh-Hans/documentation/caas/device_scan/ios/information_gathering

要触发信息的收集和发送，需要调用 `collectData` 方法。该方法除了获取设备信息外，还旨在映射客户在应用程序中的使用流程。正因如此，该方法还接受 `eventId` 和 `eventType` 字段。另一个重要点是，该方法通过异步 HTTP 请求将信息发送到 QI Tech 服务器，因此请求成功或错误的通知是通过完成处理程序（Completion Handlers）完成的。该方法具有以下参数：

名称 | 类型 | 描述
---- | ---- | ---------
documentNumber | String | 用户的文件号码（如果可用）。（CPF/CNPJ，不含点、连字符和斜杠）
eventId | String | 正在报告的事件的标识符
eventType | String | 定义正在报告的事件类型的枚举值（例如：'login'）——注意，非常相似的事件应使用相同的枚举值进行报告，以便可以基于这些数据构建智能
onSuccessHandler | func() &#8209;> Void | 成功向 QI Tech 服务器发送数据时将调用的函数 **必填**
onErrorHandler | func() &#8209;> Void | 向 QI Tech 服务器发送数据时出现错误时将调用的函数 **必填**

---

# 简介

URL: /zh-Hans/documentation/caas/device_scan/ios/introduction

欢迎使用 QI Tech iOS Device Scan 集成手册！您应使用我们的 Framework 收集手机信息和应用程序中的用户行为数据，从而提高决策的准确性。

## 遇到问题？

我们不是躲在 API 后面的公司！请联系我们的[支持团队](mailto:suporte.caas@qitech.com.br)，我们将尽快回复。如果您需要快速回复，请随时致电我们！

### 我们热爱反馈

即使您已经解决了问题，或者问题非常简单（甚至是一个您已经理解的拼写错误或不当的组织方式），也请给我们发电子邮件，这样我们可以让文档变得越来越实用，下一个人就不必经历您所经历的痛苦！

## 环境

我们为客户提供两个环境。通过在 QITechIosDeviceScan 类构造函数中传入的枚举值进行选择。目前，以下环境可用：

* 生产环境 - `production`
* 沙盒环境 - `sandbox`

:::danger 重要提示！
不得在 QI Tech 沙盒环境中使用真实的个人和/或法人数据。
:::

---

# 原生集成

URL: /zh-Hans/documentation/caas/device_scan/ios/native_swift

## 远程安装

> 开始安装

```shell
  pod init
```

我们的 SDK 可以使用 CocoaPods 导入。

SDK | 当前版本
---- | -----
QITechIosDeviceScan | `pod 'QITechIosDeviceScan', '~> 6.0.0'`

:::info iOS Minimum Deployment Target
15.5
:::

要开始安装，请在项目根目录中执行左侧命令。

> 在 podfile 中添加 source

```ruby
   source 'https://github.com/QITechSDKs/iOS.git'
```

下一步是在 `podfile` 文件中添加 QI Tech source。

> 在 podfile 中添加 pod

```ruby
  pod 'QITechIosDeviceScan', '~> <version>'
```
最后，只需按照上述格式添加 `pod` 名称即可。

:::danger 注意：
架构变更（v5.0.0+）从版本 5.0.0 开始，SDK 以纯静态方式分发。在您的 Podfile 中，必须使用 :linkage => :static 配置。
:::

> Podfile 示例（版本 5.0.0 或更高）

```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
```

> Podfile 示例（旧版本）

```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 **注意**

需要为监控依赖项 'Datadog' 启用模块稳定性，以避免不同 Swift 版本可能存在的编译问题。因此，请将描述的块添加到 Podfile 的 post_install 中（如果已有 post_install 块，则将其包含在现有块中）。
:::

:::warning 注意
在 iOS 中集成依赖项时，可能需要对某些库使用静态链接，对其他库使用动态链接。此配置对于确保兼容性、避免构建错误和优化项目性能非常重要。
:::

### 依赖项混合链接（如有需要）
混合链接的需求是因为某些库有特定要求，有些需要静态链接以避免内部冲突和符号重复，而其他依赖项可能需要动态链接，因为它们是为模块化和项目间共享而设计的。

静态链接与动态链接的区别：
* 静态（static_framework）：库代码直接嵌入最终二进制文件，减少运行时加载时间，消除执行时的外部依赖。
* 动态（dynamic_framework）：库在运行时作为单独文件加载。这减小了最终二进制文件的大小，便于独立更新/修改。

> 在 Podfile 中配置混合链接

```ruby
...

use_frameworks! :linkage => :dynamic # 将默认链接模式配置为动态

...

static_frameworks = ['framework_1', 'framework_2', ...] # 包含所有需要静态链接的依赖项
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
```

> 安装依赖项

```shell
  pod install
```

最后，执行 `pod install` 命令下载并安装依赖项。

---

# 权限

URL: /zh-Hans/documentation/caas/device_scan/ios/permissions

SDK 收集设备数据，根据 iOS 操作系统的运行方式，每个要收集的数据都需要特定权限。为了在嵌入 SDK 的应用中为用户提供自定义体验，我们实现了一种机制，使用开发者传入的参数向用户请求权限，遵循以下机制：

作为 `requestPermissions` 方法参数（以 String 格式）发送的权限将被请求给用户 - 除非之前已经请求过。
用户通过操作系统本身提供的对话框被询问框架认为必要的权限。
权限被批准或拒绝，当调用 `collectData` 方法时，它只会收集已获得权限的数据。

:::info **注意**

如果您的应用程序已经请求了必要的权限，则无需再次调用 `requestPermissions` 方法，SDK 将继承应用程序已请求的权限。
:::

## SDK 使用的权限

在当前版本的 SDK 中，以下权限在可用时可以使用：

* location - 捕获设备地理位置数据

## Info.plist 文件

为 SDK 提供权限的第一步是在应用的 Info.plist 文件中配置权限，对每个所需权限使用以下代码行：

* location - 捕获设备地理位置数据：

` NSLocationWhenInUseUsageDescription `
` 添加当 iOS 请求地理位置访问权限时您希望向用户显示的消息 `

:::info **注意**

为了在请求权限时提供更好的用户体验，您应该按照上述说明自定义弹出请求中显示的消息。
:::

---

# Desktop Device Scan

URL: /zh-Hans/documentation/caas/device_scan/web/desktop

这是 **Desktop Device Scan**，我们与 **Web Device Scan** 互补的 *white label* 模块。您可以使用我们的程序深度采集设备信息，并识别恶意软件的存在！

本软件是为满足 [Instrução Normativa BCB nº 491](https://www.bcb.gov.br/estabilidadefinanceira/exibenormativo?tipo=Instru%C3%A7%C3%A3o%20Normativa%20BCB&numero=491) 而开发的。它与 Web Device Scan 结合使用，能够为每台设备生成**唯一且可靠的标识**！

:::warning 注意
我们的应用程序是 *White Label* 的！您可以在安装程序中使用您自己的徽标，并自定义可执行文件名称和显示的消息，为您的用户提供更友好的体验。
:::

## 使用方法

在本步骤指南中，您将找到有关如何将程序与库结合使用的详细信息，以及 JavaScript 实现示例。通过这些，您将拥有将解决方案适配到您的用例所需的工具。

```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>
```

使用 `deviceScan.setDesktop(true)` 标志时，Web SDK 将尝试识别已安装应用程序的存在。如果未安装或出现问题，您可能会收到以下错误之一：

| 错误                        | 描述                                                                                                                                                                                         |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Timeout in Secure App**   | 应用程序存在但未正确响应。请重新安装应用程序以解决问题。                                                                               |
| **Invalid desktop data**    | 应用程序已被修改或损坏。请重新安装应用程序以恢复完整性。                                                                                                                                                                                   |
| **Desktop App Not Present** | 应用程序未安装。请向用户提供 QI Tech 提供的下载链接。                                                                                                                                                                                   |
| **Unexpected App Error**    | 与应用程序通信时发生意外错误。如果重新安装后问题仍然存在，请联系支持团队：<a href='mailto:suporte.caas@qitech.com.br'>支持</a>。 |

## 支持的操作系统

**Desktop Device Scan** 适用于主流现代操作系统，在每个平台上提供原生兼容性和优化性能。

Windows 10/11 x64
macOS Intel (x86_64)
macOS Apple Silicon (M1/M2/M3)

---

# DeviceScan 对象

URL: /zh-Hans/documentation/caas/device_scan/web/device_scan_object

要使用设备扫描服务，需要实例化 DeviceScan 类，该类的构造函数具有以下参数：

| 参数 | 功能 | 是否必填 |
|------------|--------------|--------------|
|.setSandbox()|若在构造函数中使用此参数，库将配置为向 `sandbox` 环境发送数据。若不存在，请求将发送到 `production` 环境。|否。|
|.setGeoLocation(true)|若此参数设置为 `true`，库将请求收集 GPS 数据的权限。若不存在或设置为 `false`，则不会提取地理位置信息。|否。|

:::info **注意**
如果用户拒绝访问位置数据，库将正常运行，但不会收集这些信息。
:::

## deviceScan.info() 函数

要执行用户数据分析功能，需要向库发送以下参数，这些参数将标识您的公司以及信息所属的用户会话。此外，尽管 event_id 和 event_type 参数是可选的，但它们有助于我们识别用户在您页面上的导航模式，从而进一步防范欺诈。

以下是每个参数的详细说明：

名称 | 类型 | 描述
---- | ---- | ---------
web_token | String | 客户密钥，用于标识收集的数据来源于您的应用程序。如果尚未收到您的 web-token，请联系 支持团队 。**必填**
session_id | String | 标识收集数据所属会话的密钥。**必填**
event_id | String | 正在报告的事件的标识符
event_type | String | 定义正在报告的事件类型的枚举器 - 请注意，非常相似的事件应使用相同的枚举器报告，以便能够基于这些数据构建智能分析。

## 实现示例
一个简单的实现示例如下所示：

```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>
```

在上面的示例中，创建了一个辅助函数 **callDeviceScan**，以便将 Device Scan 的使用与按钮点击关联，数据收集函数可以被调用两次：

* 第一次是当用户按下登录按钮时，用户在此事件之前的特征和行为将与 web_token、session_id、event_type（"login"）和 event_id（"1"）标识符一起发送到 QI Tech 服务器。

* 第二次是当用户按下购买按钮时，使用相同的 web_token（指您的公司）和 session_id（指您用户的会话）标识符收集用户行为，但使用不同的 event_type（"buy"）和 event_id（"2"），表明在此步骤中执行了与之前不同的事件，从而映射用户在您网站上的完整旅程。

---

# 实现

URL: /zh-Hans/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>
```

库通过调用属于 **DeviceScan** 类的 **.info()** 函数来执行用户分析，该类包含在我们的 **vPkg** 库中，如上例所示。变量 'web_token'、'session_id'、'event_type'（**可选**）和 'event_id'（**可选**）应替换为**各自的真实值**。成功时，库将返回一个表示收集成功的字符串；失败时，将返回一个表示错误类型的字符串。

---

# 导入库

URL: /zh-Hans/documentation/caas/device_scan/web/import

要导入我们的库，请在您网站 HTML 的 **src** 标签中添加以下 URL：

```html
    <script src = "https://ds.viewpkg.com/device-scan-2-1-1.js"></script>
```

---

# 收集返回值

URL: /zh-Hans/documentation/caas/device_scan/web/information_gathering

Web Device Scan SDK 返回一个 _Promise_，成功情况下将返回一个**字符串**，表示流程已完成。
而在错误情况下，将返回一个包含错误描述的**字符串**。以下是如何映射每种情况并获取其结果的示例：

```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>
```

### 成功返回值

返回值 | 描述
--------- | ---------
Device Scan Successfully Sent | 设备扫描已成功完成，提取的信息也已成功发送。

### 错误返回值

错误 | 描述
--------- | ---------
Web Token Error | 使用的 Web Token 无效。如果您确认使用的是 QI Tech 提供的正确 Web Token，请立即联系我们的支持团队（suporte.caas@qitech.com.br）。
Invalid Request | 设备信息未正确收集。
Internal Server Error | 发生意外错误，请检查网络连接。

---

# 简介

URL: /zh-Hans/documentation/caas/device_scan/web/introduction

欢迎使用 QI Tech Web Device Scan 集成手册！您可以使用我们的库收集您网站上设备、浏览器和用户行为的信息，从而提高决策的准确性。

在本步骤指南中，您将找到库的详细信息以及 JavaScript 实现示例。通过这些，您拥有了将解决方案适配到您应用程序用例所需的工具。

## 遇到问题？

我们不是一个躲在 API 背后的公司！请联系我们的 支持团队 ，我们将尽快回复。如果您想要快速响应，也欢迎直接给我们打电话！

### 我们热爱反馈

即使您已经解决了问题，或者问题非常简单（哪怕只是一个拼写错误或您已经理解的组织问题），也请给我们发送电子邮件，这样我们可以让文档变得越来越实用，下一个人就不必经历您所经历的痛苦！

## 环境

我们为客户提供两个环境。通过在 SDK 构造函数中传递的枚举器进行选择，目前以下环境可用：

* 生产环境 - `production`
* 沙盒环境 - `sandbox`

:::danger 重要提示！
不得在 QI Tech 的沙盒环境中使用真实的个人和/或法人数据。
:::

---

# 发送文件

URL: /zh-Hans/documentation/caas/document_analysis/document_submission

## **发送文件进行标准分析**

要开始文件分析，请使用 `multipart/form-data` 格式向 `/document` 端点发送 POST 请求。

端点：`https://api.caas.qitech.app/document_analysis/document`

**请求格式**

请求必须以 `multipart/form-data` 格式发送，包含数据字段和文件字段。分析所需的必填字段为 `id`、`document_analysis_type`、`document_bytes`。

请求示例：

``` 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" \
-F "document_bytes=@/caminho/para/seu/comprovante.pdf"
```

## **发送属性说明**

| **属性** | **描述** |
| --- | --- |
| id（必填）| 由您提供的请求唯一标识符。此 ID 可在以后用于检索分析结果。 |
| document_analysis_type（必填）| 一个字符串，指定要对文档执行的分析类型。支持的类型请参见下表。 |
| document_bytes（必填）| 待分析的文档文件。必须作为 multipart 请求体中的文件发送。注意：请勿将此字段作为 base64 编码字符串发送。|
| async（可选，默认=false）| 一个布尔值（true 或 false），定义处理模式。<br/>- false（同步）：API 将尝试处理文档并在同一请求中返回结果。<br/>- true（异步）：API 将确认接收并在后台处理。结果将通过 webhook 发送到预先配置的 URL（更多信息请参见关于 webhooks 的部分）。 |

:::info **注意**

async 字段应用于指示异步请求。同步请求应仅用于小型文档和需要立即响应的快速分析。如果请求超过 30 秒，将自动重定向到队列，返回状态为 `202 Accepted`，分析结果将发送到预先配置的 webhook URL（更多信息请参见关于 webhooks 的部分）。
:::

## **支持的分析类型**

`document_analysis_type` 字段确定将应用于您文档的数据提取模型。以下是目前支持的类型。

| **分析类型** | 文档类型 | **描述** |
| --- | --- | --- |
| company_statute_default | 公司章程/合同 | 执行公司章程的基本提取和验证。提取公司和股东的一般信息。 |
| company_statute_credit_assignment | 公司章程/合同 | 执行公司章程的高级提取，包括验证签署信贷转让合同的权限。 |
| proof_of_address_default | 居住证明（水电费账单、燃气费、网费、政府信函、声明等） | 提取并验证居住证明信息，如邮政编码、完整地址、姓名和日期。 |
| invoice | 发票、DANFEs | 提取发票中的关键信息，包括供应商/客户详情、总额和项目。 |
| bankslip | 银行付款单 | 提取银行付款单信息，如受益人、金额和到期日。 |
| ccb_default | 银行信贷票据（CCBs） | 提取银行信贷票据的数据。 |

对于此处未列出的分析类型，请通过 `suporte.caas@qitech.com.br` 联系我们的支持团队，咨询自定义实现。

## **响应**

### 成功响应（`200 OK`）

如果同步分析中的文档处理成功，API 将返回 `HTTP 200 OK` 状态和包含提取数据的 JSON 对象。此 JSON 对象的结构将根据请求的 `document_analysis_type` 而有所不同。如果请求超时，API 将返回 `HTTP 202 Accepted` 状态，请求将异步处理。稍后可以使用 GET 请求检索文档分析， 如下所述 。

### 接受响应（`202 OK`）

如果文档以异步方式处理，API 将返回 `HTTP 202 Accepted` 状态，请求将异步处理。稍后可以使用 GET 请求检索文档分析， 如下所述 。

## **错误响应（`4xx`）**

如果请求或文档存在问题，API 将返回 `4xx` 状态码和描述错误的 JSON 正文。

## 错误代码参考

以下表格列出了 API 返回的所有可能的错误代码。您可以使用这些代码在应用程序中实现健壮的错误处理。

### **类别 1：请求错误（DOC001xx）**

| 代码 | 标题 | 描述 |
| --- | --- | --- |
| `DOC00100` | Missing required field | 请求在 `multipart/form-data` 正文中不包含必填字段。 |
| `DOC00101` | Invalid field length | `form-data` 字段中某个值的长度无效。 |
| `DOC00102` | Invalid content type at request | 请求的 `Content-Type` 头不是 `multipart/form-data`。 |
| `DOC00103` | Invalid field at request | 请求在 `form-data` 正文中包含意外或无效字段。 |

### **类别 2：文件处理错误（DOC002xx）**

当发送的文件本身存在阻止处理的问题时，会发生这些错误。

| 代码 | 标题 | 描述 |
| --- | --- | --- |
| `DOC00200` | Invalid Document Analysis Type | `document_analysis_type` 对发送的文档无效。（例如：对水电费账单使用 `company_statute_default` 分析。） |
| `DOC00201` | Invalid File Size | 发送的文档大小超过允许的最大限制。 |
| `DOC00202` | Invalid File Type | 由于类型或格式不一致，文件无法处理（例如：发送了一个 `.jpg` 文件，但类型为 `application/pdf`）。 |
| `DOC00203` | PDF exceeds page limit | 提供的 PDF 文件包含的页数超过了处理允许的最大限制（当前限制为 200 页）。 |

### **类别 3：文档分析错误（DOC003xx）**

这些错误发生在数据提取和分析阶段，即文件成功打开之后。

| 代码 | 标题 | 描述 |
| --- | --- | --- |
| `DOC00300` | Missing Information | 文档不包含完成分析所需的基本信息。 |
| `DOC00301` | Bad Quality | 文档质量（例如：分辨率、可读性、清晰度）太低，无法准确分析。 |
| `DOC00302` | Invalid Data | 文档包含不一致或无效的数据（例如：校验和不正确、字段相互矛盾）。 |
| `DOC00303` | Incorrect Document Type | 文档内容与所选 `document_analysis_type` 的预期文档类型不符。 |
| `DOC00304` | Invalid PDF File | 提供的文件不是有效或格式良好的 PDF，无法打开。 |
| `DOC00305` | Password Protected PDF | 发送的 PDF 已用密码加密，无法处理。 |
| `DOC00306` | Parsing Error | 无法处理文档分析。 |

# **检索文档分析**

您可以随时使用其唯一的 `id` 检索之前提交的文档分析结果。

`https://api.caas.qitech.app/document_analysis/document/{document_id}` 

将 document_id 替换为您发送 `POST` 请求时使用的相同值。

---

# HTTP 状态码

URL: /zh-Hans/documentation/caas/document_analysis/http_status

所有 QI Tech API 均按照 RFC 7231 使用以下 HTTP 返回状态标准化：

HTTP 状态 | 含义 | 描述
---------- | ------- | ---------------------------------
400 | Bad Request | 发送的请求存在格式错误。大多数情况下，我们会在消息正文中返回错误位置的说明。在此 API 中，我们实现了 一系列特定错误代码 ，以帮助理解可能出错的地方。
401 | Unauthorized | 身份验证出现问题，请检查 API Key 是否正确以及是否在正确的头部中，详见 身份验证 部分。
403 | Forbidden | 访问的端点仅供内部使用，此 API Key 不可用。
404 | Not Found | 使用所提供的密钥未找到请求的数据。当请求无效端点时也会返回此状态。
405 | Method Not Allowed | 使用的 HTTP 方法（POST、GET、PUT 等）不适用于所使用的端点。
406 | Not Acceptable | 请求正文中发送的数据无效。通常，这意味着发送的数据不是有效的 JSON。
409 | Conflict | 发送的文档 ID 对应于之前已处理的 ID。当向服务器发送重复请求，或者两个文档具有相同 ID 的请求时，会返回此状态。
500 | Internal Server Error | 处理此请求时出现问题。当此错误发生时，我们的团队会自动收到通知并立即开始分析和解决。
503 | Service Unavailable | 您遇到了我们服务器基础设施的计划内或计划外停机。

---

# 简介

URL: /zh-Hans/documentation/caas/document_analysis/introduction

欢迎使用 QI Tech 文档分析 API。此 API 专为分析不遵循标准格式的复杂文档而设计，例如居住证明、合同、发票、CCBs、付款单等。

## **支持与反馈**

如遇任何技术问题或需要协助，请通过电子邮件 suporte.caas@qitech.com.br 联系我们的支持团队。我们承诺及时响应。

## **我们热爱反馈**

我们非常重视客户的反馈！如果您发现任何不准确之处、不清晰的部分或有改进建议，我们鼓励您与我们的团队分享。您的贡献帮助我们改善所有用户的体验！

## **环境**

API 在两个不同的环境中供客户使用。API 的基础 URL 如下：

- 生产环境 - `https://api.caas.qitech.app/document_analysis/`
- 沙盒环境 - `https://api.sandbox.caas.qitech.app/document_analysis/`

**重要提示！**

在 QI Tech 的沙盒环境中，严格禁止使用真实的个人和/或法人数据。

## **仅限 HTTPS**

出于安全考虑，与 QI Tech API 的所有通信必须使用 HTTPS 进行。为确保合规并防止数据不安全传输，服务器配置为仅接受使用 TLS 1.2 协议的 443 端口连接。使用其他协议的调用将被自动拒绝。

## **身份验证**

API 访问通过使用 API 密钥（API Key）授予。您的访问密钥已经或将要发送到您的电子邮件。如果您尚未收到，请通过 suporte.caas@qitech.com.br 联系我们的支持团队。

API 期望在每个发送到服务器的请求的 `Authorization` 头部中包含密钥。

**请求示例：**

```bash
# -H 标志将必要的授权头添加到请求中。
curl "endpoint_da_api_aqui" \
  -H "Authorization: EXAMPLE_API_KEY"
```

:::info **注意**

您必须将 EXAMPLE-OF-API-KEY 替换为从支持团队收到的 API Key。
:::

---

# Webhook

URL: /zh-Hans/documentation/caas/document_analysis/webhook

当异步分析完成时，将发送包含分析结果的 webhook。为此，需要配置一个地址以接收更新通知，以及一个用于签署请求的 *signature_key*。如果尚未配置 webhook，请联系[支持团队](mailto:suporte.caas@qitech.com.br)。

## 签名

为确保 webhook 端点收到的请求来自我们的服务器，将随 webhook 一起发送 HMAC 签名。您可以使用此签名验证 webhook 确实来自我们的服务器。

> Python 签名计算示例
```python
    hmac_obj = hmac.new(signature_key.encode('utf-8'), (endpoint + method + payload).encode('utf-8'), hashlib.sha1)
    return hmac_obj.hexdigest()
```

## 请求

请求具有以下格式，并通知分析已完成。请求使用 HTTP POST 方法，请求正文以 UTF-8 编码的文本发送。

### 成功 Webhook

```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
```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."}'
```

---

# builder

URL: /zh-Hans/documentation/caas/face_recognition/android/builder

## FaceRecognition.Builder

| 参数                                                                                                                                     | 功能                                                                                                                                                                                                                                                                                                                                                                    | 是否必填                                                                                                                                                                                                  |
| --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---- |
| mobileToken                                                                                                                                   | 客户密钥，用于标识收集的数据来源于您的应用程序。如果尚未收到您的 mobile-token，请联系<a href='mailto:suporte.caas@qitech.com.br'>支持团队</a>。                                                                                                                                              | 是。                                                                                                                                                                                                         |
| .setSandboxEnvironment()                                                                                                                      | 若在构造函数中使用此参数，库将配置为向沙盒环境发送数据。若不存在，请求将发送到生产环境。                                                                                                                                                                                                                                                        | 否。                                                                                                                                                                                                         |
| .showIntroductionScreens(Boolean showIntroductionScreens)                                                                                     | 设置为 "false" 时，禁用向用户显示的照片采集介绍屏幕。                                                                                                                                                                                                                                                                                                                                              | 否。默认值为 "true"。                                                                                                                                                                                      |
| .setShowSuccessScreen(Boolean showSuccessScreen)                                                                                              | 设置为 "false" 时，禁用照片采集后的成功屏幕。                                                                                                                                                                                                                                                                                                                                          | 否。默认值为 "true"。                                                                                                                                                                                      |
| .setBackgroundColor(String backgroundColor)                                                                                                   | 允许配置 SDK activities 的背景颜色。                                                                                                                                                                                                                                                                                                                                        | 否。默认值为 "#ffffff"。                                                                                                                                                                                   |
| .setFontColor(String fontColor)                                                                                                               | 允许配置 SDK activities 的字体和图标颜色。                                                                                                                                                                                                                                                                                                                                                | 否。默认值为 "#000000"。                                                                                                                                                                                   |
| .setFontFamily(FontFamily fontFamily)                                                                                                         | 允许配置 SDK activities 的字体。                                                                                                                                                                                                                                                                                                                                                    | 否。若未指定，默认为 FontFamily.open_sans。可用字体：FontFamily.open_sans、FontFamily.futura、FontFamily.verdana、FontFamily.roboto、FontFamily.poppins 和 FontFamily.helvetica。 | 否。 |
| .activeFaceLiveness(Boolean activeFaceLiveness)                                                                                               | 指示 SDK 是否执行用户自拍采集或主动活体检测程序。                                                                                                                                                                                                                                                                                                                                                  | 否。默认值为 _false_。                                                                                                                                                                                     |
| .audioConfiguration(AudioConfiguration audioConfiguration)                                                                                    | 指示 SDK 是否为用户播放提示音频。接受的配置为 _AudioConfiguration.enable_（播放提示音频）、_AudioConfiguration.disable_（不播放音频）和 _AudioConfiguration.accessibility_（当用户设备启用了无障碍配置时播放音频）。 | 否。默认值为 _AudioConfiguration.disable_。                                                                                                                                                                |
| .setVisualConfiguration([VisualConfiguration](https://docs.zaig.com.br/android_facerecon/#o-objeto-visualconfiguration). visualConfiguration) | 用于自定义 SDK 执行过程中向用户显示的图片。                                                                                                                                                                                                                                                                                                                                                | 否。                                                                                                                                                                                                         |
| .setTextConfiguration([TextConfiguration](https://docs.zaig.com.br/android_facerecon/#o-objeto-textconfiguration). textConfiguration)         | 用于自定义 SDK 执行过程中向用户显示的引导屏幕上的文本。                                                                                                                                                                                                                                                                                                                              | 否。                                                                                                                                                                                                         |
| .setSessionId(String sessionId)                                                                                                               | 用于设置标识 SDK 启动会话的密钥。用于通过日志跟踪用户在 FaceRecon 执行过程中的完整流程。此字段最多接受 255 个字符。                                                                                                                                                                          | 否。                                                                                                                                                                                                         |
| .setLogLevel(FaceRecognition.LogLevel logLevel)                                                                                               | 用于自定义 SDK 日志的详细级别。可用级别：LogLevel.debug、LogLevel.info、LogLevel.warn、LogLevel.error 和 LogLevel.trace。默认为 LogLevel.debug。                                                                                                                                                                                                                           | 否。                                                                                                                                                                                                         |
| .setDocumentNumber(String documentNumber)                                                                                                     | 用于设置用户的文档号码。此字段接受格式为 000.000.000-00 的 14 位 CPF 字符。                                                                                                                                                                                                                              | 如果某次调用使用了 1:1 验证，则所有调用均必填。                                                                                                                                                          |
| .setValidation(Boolean validation)                                                                                                            | 用于定义 SDK 是否对用户的自拍照执行 1:1 验证。在用户的第一次会话中，此标志**必须为 false**。此功能需要填写 setDocumentNumber 方法。                                                                                                                                                                      | 否。默认值为 _false_。                                                                                                                                                                                     |

## VisualConfiguration 对象

| 参数                                                             | 功能                                                                                                                                                                                                                                        | 是否必填             |
| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| .setOnboardingDrawable(int onboarding_drawable, int onboarding_width) | 用于配置在 SDK 引导屏幕上向用户显示的图片。参数 _onboarding_drawable_ 应引用要显示的图片 ID，_onboarding_width_ 是该图片的预期显示尺寸。 | 否。                    |
| .setButtonBorderSize(int border_size)                                 | 用于配置 SDK 按钮的边框宽度。                                                                                                                                                                                                                               | 否。默认值为 _1_。    |
| .setButtonShadow(boolean button_shadow)                               | 设置为 _false_ 时，移除 SDK 按钮使用的 Android 默认阴影效果。                                                                                                                                                                                                                       | 否。默认值为 _true_。 |

## TextConfiguration 对象

| 参数                                      | 功能                                                                                    | 是否必填 |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------- | ----------- |
| .setCustomText(CustomLabel label, String text) | 用于配置在 SDK 引导屏幕上向用户显示的文本 | 否。        |

```

```

---

# 收集结果

URL: /zh-Hans/documentation/caas/face_recognition/android/collecting_response

要获取包含 SDK 采集结果的 **FaceReconResponse** 对象（包括在 QI Tech 系统中发送的图片标识符），请在启动 **FaceReconActivity** 的同一 activity 中覆盖 *onActivityResult* 方法：

```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);
            }
        }
    }
```

## FaceReconResponse 对象属性说明

:::info 注意：
与 Device Scan 集成 从版本 5.2.0 起，Face Recognition 服务会自动内部调用 Device Scan。因此，成功返回值将包含 `device_scan_session_id` 字段。此密钥标识内部执行的设备扫描会话，可在 QI Tech 生态系统的其他服务中集成使用。
:::

属性 | 描述 | 结果 | 版本
--------- | --------- | --------- | ---------
image_key | 提供的图片标识密钥，可用于 QI Tech 系统的任何其他服务。 | **RESULT_OK** | **所有版本**
device_scan_session_id | 内部执行的设备扫描会话标识密钥，可用于 QI Tech 系统的任何其他服务。 | **RESULT_OK** |  **5.2.0+**
status_code | 请求的状态码。 | **RESULT_CANCELED** | **5.0.0+**
reason | 错误标识符 | **RESULT_CANCELED** | **5.0.0+**
description | 错误描述。 | **RESULT_CANCELED** | **5.0.0+**

## 错误结构（SDK 5.0.0+）

:::danger 重要提示！
从版本 **5.0.0** 起，错误结构已重构以提供更详细的诊断信息。
:::

### 示例：InvalidToken

```java
{
   status_code = 401
    reason = "INVALID_TOKEN"
    description = "Authentication token expired or invalid"
}
```
### 示例：UserCanceled

```java
{
    status_code = 0
    reason = "USER_CANCELED"
    description = "User pressed the back button."
}
```

## 旧版本

```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");
            }
        }
    }
```

---

# 1:1 验证 - Face Match

URL: /zh-Hans/documentation/caas/face_recognition/android/face_match

要使用 1:1 验证（Face Match）功能，需要在 SDK 构造函数中将 _validation_ 参数设置为 _true_，这可以通过调用 `setValidation()` 方法来实现。此外，需要在 _documentNumber_ 参数中填写用户的 CPF。如下例所示：

```java
FaceRecognition faceRecognition = new FaceRecognition.Builder("YOUR_MOBILE_TOKEN_SENT_BY_QITECH")
    // ... 其他配置
    .setDocumentNumber("000.000.000-00")
    .setValidation(true)
    // ...
    .build();
```

> **注意：** 1:1 验证只能在用户的第二次会话起使用，即在第一次会话之后，当 _documentNumber_ 参数填写了用户 CPF 且 _validation_ 参数为 `false` 时，需要有记录才能进行验证。

---

# 混合解决方案

URL: /zh-Hans/documentation/caas/face_recognition/android/hybrid_solutions

除了提供原生 Java 集成外，我们的 SDK 还兼容多种混合框架。这通过为每个框架集成特定的原生插件来实现。利用每种解决方案的原生系统，可以在 Android 环境中嵌入我们的原生 SDK。

一些最常用的混合技术包括 React Native（[Native Modules](https://reactnative.dev/docs/turbo-native-modules-introduction)）、Cordova（[Plugin Development Guide](https://cordova.apache.org/docs/en/latest/guide/hybrid/plugins/index.html)）、Ionic（[Native](https://ionicframework.com/docs/v3/native/)）、Unity（[Native Plug-in for Android](https://docs.unity3d.com/Manual/PluginsForAndroid.html)）、Xamarin（[Native Libraries](https://learn.microsoft.com/en-us/xamarin/android/platform/native-libraries)）、Appcelerator、Phonegap 和 Node。

为了简化与我们原生解决方案的集成过程，我们为 React Native 和 Flutter 框架提供了插件。如有兴趣，我们在私有存储库中提供文档和集成示例。对于其他混合技术，我们有一些实现这个与原生代码桥接的示例。欢迎联系我们的 支持团队 获取访问权限。

---

# 简介

URL: /zh-Hans/documentation/caas/face_recognition/android/introduction

欢迎使用 QI Tech Android 人脸识别 SDK。此 SDK 执行面部采集并将其发送到 QI Tech Face Recognition API 。您可以使用它通过您的应用程序采集客户的面部图像，并通过密钥在 QI Tech 系统的其他产品中引用。

## 遇到问题？

我们不是一个躲在 API 背后的公司！请联系我们的[支持团队](mailto:suporte.caas@qitech.com.br)，我们将尽快回复。如果您想要快速响应，也欢迎直接给我们打电话！

### 我们热爱反馈

即使您已经解决了问题，或者问题非常简单（哪怕只是一个拼写错误或您已经理解的组织问题），也请给我们发送电子邮件，这样我们可以让文档变得越来越实用，下一个人就不必经历您所经历的痛苦！

:::danger 重要提示！
不得在 QI Tech 的沙盒环境中使用真实的个人和/或法人数据。
:::

---

# 原生集成

URL: /zh-Hans/documentation/caas/face_recognition/android/native_java

要导入我们的 SDK，需要修改项目和应用程序的 _build.gradle_ 文件。

## 添加到项目

在项目的 _build.gradle_ 中添加我们的 Maven 仓库地址（在 Android Studio 中，该文件显示为：**"Project: \{project_name\}"**），如下例所示。

```java
buildscript {
    ...
}

allprojects {
    repositories {
        ...
        maven { url 'https://sdks.qitech.com.br/' }
    }
}
```

## 添加到应用程序

之后，在应用程序的 build.gradle 中添加您要导入的库（在 Android Studio 中，该文件显示为：**"Module: \{project_name\}.app"**），包含以下依赖项。

```java
android {
    ...
}
...
dependencies {
    ...
    implementation 'com.qitech.android:facerecon:v7.0.0'
}
```

:::warning
自 **2025 年 4 月**起，Google Play 的新政策要求应用程序必须使用 **Android API Level 35** 才能在 Google Play Store 上发布或更新。因此，我们强烈建议至少使用 **targetSdkVersion 35**。
:::

:::info
使用 **targetSdkVersion 35** 意味着使用 **compileSdkVersion 35**，这对 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+
:::

## 启动 SDK

:::danger 重要提示！
从版本 5.0.0 起，认证系统已更新，使用 **clientSessionKey** 代替 **mobileToken**。此外，还添加了新的反馈屏幕配置选项。
:::

### 获取 Client Session Key

在配置 SDK 之前，您必须通过服务器到服务器的请求向我们的人脸识别 API 生成一个临时的 **clientSessionKey**。

### 端点

| 环境 | URL |
|----------|-----|
| **沙盒** | `https://api.sandbox.zaig.com.br/face_recognition/client_session` |
| **生产** | `https://api.zaig.com.br/face_recognition/client_session` |

### 请求

**Method:** `POST`

**Headers:**
```json
{
  "Authorization": "YOUR_FACE_RECON_API_KEY"
}
```

**Body（可选，但推荐）：**
```json
{
  "user_id": "unique_user_identifier"
}
```

> **重要：** `user_id` 字段**强烈建议**用于安全和反欺诈措施。请使用您应用程序中用户的唯一标识符。

### 响应

成功响应将包含需要传递给 SDK 配置的 `client_session_key`。

```json
{
  "client_session_key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

要将 SDK 嵌入到您的应用程序中，您必须通过 Builder 组件配置自定义采集应用程序，并通过 Intent Extra 作为参数提交给 FaceReconActivity。

### SDK 初始化示例
```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

| 参数 | 功能 | 是否必填 |
|------------|--------------|--------------|
|clientSessionKey |客户密钥，用于标识收集的数据来源于您的应用程序。通过向 Face Recognition API 发送请求获取。|是。|
|.setSandboxEnvironment()|若在构造函数中使用此参数，库将配置为向沙盒环境发送数据。若不存在，请求将发送到生产环境。|否。|
|.showIntroductionScreens(Boolean showIntroductionScreens)|设置为 "false" 时，禁用向用户显示的照片采集介绍屏幕。|否。默认值为 "true"。|
|.setShowSuccessScreen(Boolean showSuccessScreen)|设置为 "false" 时，禁用照片采集后的成功屏幕。|否。默认值为 "true"。|
|.setShowInvalidTokenScreen(Boolean showSuccessScreen)|设置为 "false" 时，禁用认证失败屏幕。|否。默认值为 "true"。|
|.setBackgroundColor(String backgroundColor)|允许配置 SDK activities 的背景颜色。|否。默认值为 "#ffffff"。|
|.setFontColor(String fontColor)|允许配置 SDK activities 的字体和图标颜色。|否。默认值为 "#000000"。|
| .setFontFamily(FontFamily fontFamily)| 允许配置 SDK activities 的字体。| 否。若未指定，默认为 FontFamily.open_sans。可用字体：FontFamily.open_sans、FontFamily.futura、FontFamily.verdana、FontFamily.roboto、FontFamily.poppins 和 FontFamily.helvetica。|否。|
|.activeFaceLiveness(Boolean activeFaceLiveness)|指示 SDK 是否执行用户自拍采集或主动活体检测程序。|否。默认值为 *false*。|
|.audioConfiguration(AudioConfiguration audioConfiguration)|指示 SDK 是否为用户播放提示音频。接受的配置为 _AudioConfiguration.enable_（播放提示音频）、_AudioConfiguration.disable_（不播放音频）和 _AudioConfiguration.accessibility_（当用户设备启用了无障碍配置时播放音频）。|否。默认值为 _AudioConfiguration.disable_。|
|.setVisualConfiguration(VisualConfiguration visualConfiguration)|用于自定义 SDK 执行过程中向用户显示的图片。|否。|
|.setTextConfiguration(TextConfiguration textConfiguration)|用于自定义 SDK 执行过程中向用户显示的引导屏幕上的文本。|否。|
|.setSessionId(String sessionId)| 用于设置标识 SDK 启动会话的密钥。用于通过日志跟踪用户在 FaceRecon 执行过程中的完整流程。此字段最多接受 255 个字符。|否。|
|.setLogLevel(FaceRecognition.LogLevel logLevel)| 用于自定义 SDK 日志的详细级别。可用级别：LogLevel.debug、LogLevel.info、LogLevel.warn、LogLevel.error 和 LogLevel.trace。默认为 LogLevel.debug。|否。|
|.setDocumentNumber(String documentNumber)| 用于设置用户的文档号码。此字段接受 14 个字符。|仅适用于某次调用使用了 1:1 验证的情况。|
|.setValidation(Boolean validation)| 用于定义 SDK 是否对用户的自拍照执行 1:1 验证。在用户的第一次会话中，此标志**必须**为 false。此功能需要填写 setDocumentNumber 方法。|否。默认值为 *false*。|

## VisualConfiguration 对象

| 参数                                                             | 功能                                                                                                                                                                                                                                        | 是否必填             |
| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| .setOnboardingDrawable(int onboarding_drawable, int onboarding_width) | 用于配置在 SDK 引导屏幕上向用户显示的图片。参数 _onboarding_drawable_ 应引用要显示的图片 ID，_onboarding_width_ 是该图片的预期显示尺寸。 | 否。                    |
| .setButtonBorderSize(int border_size)                                 | 用于配置 SDK 按钮的边框宽度。                                                                                                                                                                                                                               | 否。默认值为 _1_。    |
| .setButtonShadow(boolean button_shadow)                               | 设置为 _false_ 时，移除 SDK 按钮使用的 Android 默认阴影效果。                                                                                                                                                                                                                       | 否。默认值为 _true_。 |

## TextConfiguration 对象

| 参数                                      | 功能                                                                                    | 是否必填 |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------- | ----------- |
| .setCustomText(CustomLabel label, String text) | 用于配置在 SDK 引导屏幕上向用户显示的文本 | 否。        |

## 旧版本

### 启动 SDK

```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);
```

我们使用 Mobile Token 来允许您的应用程序对我们的 API 进行认证访问。它可能已通过电子邮件发送给您。如果您尚未收到 token，请发送电子邮件至 suporte.caas@qitech.com.br 。

我们的 API 期望在所有来自 SDK 的请求中接收 Mobile Token，因此必须通过上述方法将其作为配置参数包含在内。

:::info **注意**

您必须将 "YOUR_MOBILE_TOKEN_SENT_BY_QITECH" 替换为从支持团队收到的 Mobile Token。
:::

### FaceRecognition.Builder

| 参数 | 功能 | 是否必填 |
|------------|--------------|--------------|
|mobileToken |客户密钥，用于标识收集的数据来源于您的应用程序。如果尚未收到您的 mobile-token，请联系 suporte.caas@qitech.com.br。|是。|
|.setSandboxEnvironment()|若在构造函数中使用此参数，库将配置为向沙盒环境发送数据。若不存在，请求将发送到生产环境。|否。|
|.showIntroductionScreens(Boolean showIntroductionScreens)|设置为 "false" 时，禁用向用户显示的照片采集介绍屏幕。|否。默认值为 "true"。|
|.setShowSuccessScreen(Boolean showSuccessScreen)|设置为 "false" 时，禁用照片采集后的成功屏幕。|否。默认值为 "true"。|
|.setBackgroundColor(String backgroundColor)|允许配置 SDK activities 的背景颜色。|否。默认值为 "#ffffff"。|
|.setFontColor(String fontColor)|允许配置 SDK activities 的字体和图标颜色。|否。默认值为 "#000000"。|
| .setFontFamily(FontFamily fontFamily)| 允许配置 SDK activities 的字体。| 否。若未指定，默认为 FontFamily.open_sans。可用字体：FontFamily.open_sans、FontFamily.futura、FontFamily.verdana、FontFamily.roboto、FontFamily.poppins 和 FontFamily.helvetica。|否。|
|.activeFaceLiveness(Boolean activeFaceLiveness)|指示 SDK 是否执行用户自拍采集或主动活体检测程序。|否。默认值为 *false*。|
|.audioConfiguration(AudioConfiguration audioConfiguration)|指示 SDK 是否为用户播放提示音频。接受的配置为 _AudioConfiguration.enable_（播放提示音频）、_AudioConfiguration.disable_（不播放音频）和 _AudioConfiguration.accessibility_（当用户设备启用了无障碍配置时播放音频）。|否。默认值为 _AudioConfiguration.disable_。|
|.setVisualConfiguration(VisualConfiguration visualConfiguration)|用于自定义 SDK 执行过程中向用户显示的图片。|否。|
|.setTextConfiguration(TextConfiguration textConfiguration)|用于自定义 SDK 执行过程中向用户显示的引导屏幕上的文本。|否。|
|.setSessionId(String sessionId)| 用于设置标识 SDK 启动会话的密钥。用于通过日志跟踪用户在 FaceRecon 执行过程中的完整流程。此字段最多接受 255 个字符。|否。|
|.setLogLevel(FaceRecognition.LogLevel logLevel)| 用于自定义 SDK 日志的详细级别。可用级别：LogLevel.debug、LogLevel.info、LogLevel.warn、LogLevel.error 和 LogLevel.trace。默认为 LogLevel.debug。|否。|
|.setDocumentNumber(String documentNumber)| 用于设置用户的文档号码。此字段接受 14 个字符。|仅适用于某次调用使用了 1:1 验证的情况。|
|.setValidation(Boolean validation)| 用于定义 SDK 是否对用户的自拍照执行 1:1 验证。在用户的第一次会话中，此标志**必须**为 false。此功能需要填写 setDocumentNumber 方法。|否。默认值为 *false*。|

---

# using_sdk

URL: /zh-Hans/documentation/caas/face_recognition/android/using_sdk

## 启动 SDK

要将 SDK 嵌入到您的应用程序中，您必须通过 Builder 组件配置自定义采集应用程序，并通过 Intent Extra 作为参数提交给 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);
```

我们使用 Mobile Token 来允许您的应用程序对我们的 API 进行认证访问。它可能已通过电子邮件发送给您。如果您尚未收到 token，请发送电子邮件至 suporte.caas@qitech.com.br 。

我们的 API 期望在所有来自 SDK 的请求中接收 Mobile Token，因此必须通过上述方法将其作为配置参数包含在内。

:::info **注意**

您必须将 "YOUR_MOBILE_TOKEN_SENT_BY_QITECH" 替换为从支持团队收到的 Mobile Token。
:::

---

# 身份验证

URL: /zh-Hans/documentation/caas/face_recognition/api/authentication

:::danger 重要提示！
从 iOS 和 Android SDK 5.0.0 版本以及 Web SDK 3.0.0 版本起，认证系统已更新，使用 clientSessionKey 代替 mobileToken。
:::

我们使用 API Key 来允许访问我们的 API。它可能已通过电子邮件发送给您。如果您尚未收到密钥，请发送电子邮件至 suporte.caas@qitech.com.br 。

## Client Session Key

在配置 SDK 之前，您必须通过服务器到服务器的请求向我们的 API 生成一个临时的 clientSessionKey。

### 生成 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" }'
```

**端点**

| 环境 | URL |
|----------|-----|
| 沙盒 | https://api.sandbox.zaig.com.br/face_recognition/client_session |
| 生产 | https://api.zaig.com.br/face_recognition/client_session |

**请求详情**

| 字段 | 类型 | 是否必填 | 描述|
|----------|----------|----------|----------|
| user_id | string | 否 | 您应用程序中用户的唯一标识符（如：CPF、RG 等） |

请求体中的 `user_id` 字段强烈建议用于安全和反欺诈措施。

**Request Body**
```json
{
  "user_id": "unique_user_identifier"
}
```

**Response Body**

成功响应将包含 `client_session_key`。
```json
{
  "client_session_key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

:::info 注意
您必须将 `EXAMPLE_API_KEY` 替换为从支持团队收到的 API Key。
:::

---

# Registro de rosto (1:1)

URL: /zh-Hans/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"
}
```

---

---

# HTTP 状态码

URL: /zh-Hans/documentation/caas/face_recognition/api/http_status

所有 QI Tech API 均按照 RFC 7231 使用以下 HTTP 返回状态标准化：

HTTP 状态 | 含义 | 描述
---------- | ------- | ---------------------------------
400 | Bad Request | 发送的请求存在格式错误。大多数情况下，我们会在消息正文中返回错误位置的说明。
401 | Unauthorized | 身份验证出现问题，请检查 API Key 是否正确以及是否在正确的头部中，详见 身份验证 部分。
403 | Forbidden | 访问的端点仅供内部使用，此 API Key 不可用。
404 | Not Found | 使用所提供的密钥未找到请求的数据。当请求无效端点时也会返回此状态。
405 | Method Not Allowed | 使用的 HTTP 方法不适用于所使用的端点。
406 | Not Acceptable | 请求正文中发送的数据无效。通常，这意味着发送的数据不是有效的 JSON。
409 | Conflict | 请求 ID 对应于之前已处理的 ID。当向服务器发送重复请求时会返回此状态。
500 | Internal Server Error | 处理此请求时出现问题，遇到此错误时，我们的专家会自动收到通知并立即开始分析和解决。
503 | Service Unavailable | 您遇到了我们服务器基础设施的计划内或计划外停机。

---

# 图片

URL: /zh-Hans/documentation/caas/face_recognition/api/image

向我们的人脸识别 API 发送人脸照片是必须的。为了确保执行分析的更高可靠性，客户在拍照时需要遵守以下规则：

* 照片中只能有一张人脸；
* 整个人脸必须在照片中可见；
* 人脸必须至少占照片面积的 15%；
* 人脸必须正对相机并与相机平行；
* 人脸眼睛必须睁开；
* 人脸嘴巴必须闭合；
* 人脸必须保持中性表情，不得微笑；
* 人脸不得被任何类型的配件（帽子、眼镜或面具）遮挡。

此外，只接受最大 3MB 的 .jpeg 和 .png 图片。

## 文件发送

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"
}
```

在需要发送图片而不立即执行注册或人脸验证流程的情况下，应发送包含图片 Base64 的 JSON 对象。
为此，需要向以下端点发送 **POST** 类型的请求：

`https://api.caas.qitech.app/face_recognition/image`

发送后，图片将进行质量测试，如果通过，将返回包含图片访问密钥的 JSON。此密钥应在人脸注册或验证期间用于引用该照片。

:::info **注意**

只应发送与图片对应的 Base64 代码。
:::

## 图片质量验证

Response Body：无效图片情况

```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"
}
```

在图片端点发送 POST 请求时，如果图片不足以进行验证，将返回 HTTP Status Code 400。

*description* 字段的值是解释图片无效原因的消息。

此外，我们返回一个 *image_status* 枚举器以映射图片无效的原因。以下是可能的 *image_status* 列表：

image_status |  描述
:----: | :---------:
no_faces | 未识别到人脸。
multiple_faces | 识别到多张人脸。
close_face | 人脸离相机太近。
distant_face | 人脸离相机太远。
not_centered | 人脸未充分居中。
inclined_face | 人脸倾斜。
wearing_acessories | 人员正在使用遮挡部分脸部的配件。
facial_expression | 人员嘴巴张开、在微笑或闭着眼睛。
brightness_problem | 图片光照不足。
sharpness_problem | 图片不够清晰。

**注意 -** 还有其他原因会导致我们返回 400（均与无效数据相关）。只有 title 为 "image_quality" 的返回才是图片质量验证的结果，因此才应转达给用户。

## 文件检索
> 图片检索

```shell
    curl "https://api.caas.qitech.app/face_recognition/image/f4b5337a-7b50-406e-8c8e-7d0e77b5aa02/file" \
         -H "Authorization: EXAMPLE_API_KEY"
```

随时可以检索已发送的图片。只需在端点发送经过适当认证的 **GET** 请求：

`https://api.caas.qitech.app/face_recognition/image/{image_key}/file`

其中 image_key 是在发送图片时返回的值。

## 检索已处理文件
> 检索已处理图片

```shell
    curl "https://api.caas.qitech.app/face_recognition/image/f4b5337a-7b50-406e-8c8e-7d0e77b5aa02/cropped_file" \
         -H "Authorization: EXAMPLE_API_KEY"
```
将图片与注册或验证关联后，该图片将被处理，并生成一张仅包含用于人脸识别流程的面部的新图片。

此图片可通过在以下端点发送经过适当认证的 **GET** 请求来检索：

`https://api.caas.qitech.app/face_recognition/image/{image_key}/cropped_file`

其中 image_key 是在发送基础图片时返回的值。

## 检索文件元数据
> 检索元数据

```shell
    curl "https://api.caas.qitech.app/face_recognition/image/f4b5337a-7b50-406e-8c8e-7d0e77b5aa02" \
         -H "Authorization: EXAMPLE_API_KEY"
```

将图片发送到 API 后，可以使用以下端点检索图片的元数据：

`https://api.caas.qitech.app/face_recognition/image/{image_key}`

其中 image_key 是在发送图片时返回的值。

---

# 简介

URL: /zh-Hans/documentation/caas/face_recognition/api/introduction

欢迎使用 QI Tech 人脸识别 API！您可以使用我们的 API 访问端点、注册客户照片并在执行交易前对其进行人脸识别。

## 遇到问题？

我们不是一个躲在 API 背后的公司！请联系我们的 支持团队 ，我们将尽快回复。如果您想要快速响应，也欢迎直接给我们打电话！

### 我们热爱反馈

即使您已经解决了问题，或者问题非常简单（哪怕只是一个拼写错误或您已经理解的组织问题），也请给我们发送电子邮件，这样我们可以让文档变得越来越实用，下一个人就不必经历您所经历的痛苦！

## 环境

我们为客户提供两个环境。API 的基础 URL 为：

* 生产环境 - `https://api.caas.qitech.app/face_recognition/`
* 沙盒环境 - `https://api.sandbox.caas.qitech.app/face_recognition/`

:::danger 重要提示！
不得在 QI Tech 的沙盒环境中使用真实的个人和/或法人数据。
:::

## 仅限 HTTPS

出于安全考虑，与 QI Tech API 的所有通信必须使用 HTTPS 进行。为避免因疏忽或其他原因进行 HTTP 调用，此服务器仅开放使用 TLS 1.2 通信的 443 端口。使用其他协议的调用将被自动拒绝。

---

# Registration

URL: /zh-Hans/documentation/caas/face_recognition/api/registration

在使用 API 人脸验证资源之前，需要先注册客户。此操作将在数据库中生成一条初始记录，提供一张在验证过程中用作基准的图片。

## 对象定义

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"
} 
```

注册客户时，我们的 API 将生成一个包含与此注册相关所有信息的 JSON 对象。此对象将在对该客户执行交易前进行人脸识别时用作参考。

名称 | 类型 | 描述
:----: | :----: | ---------
registration_key | string | Registration 对象的密钥
document_number | string | 客户的 CPF
image | image | 携带注册时发送的图片属性的对象
status | string | 客户注册状态
registration_status_events | registration_status_events | 携带注册状态修改历史记录的对象
registration_date | datetime | UTC 注册日期

## 状态动态 - **status**
注册客户后，将在 **status** 标志下返回此注册的状态。可能的结果为：

结果 | 描述
--------- | ---------
authentic | 此注册有成功完成交易的历史记录
undefined | 此注册没有欺诈历史记录，也没有成功完成交易的历史记录
fraud | 此注册有与之关联的欺诈历史记录

## 创建 Registration

Request Body：同时发送图片（Base64）

```json
{
    "document_number": "123.456.789-00",
    "image": "base_64_image_code",
}
```

Request Body：提前发送图片

```json
{
    "document_number": "123.456.789-00",
    "image_key": "f1c0d2e1-f950-4360-896d-36588e443fc9",
}
```

要注册客户，只需向以下端点发送带有注册 JSON 对象的 **POST** 请求：

`https://api.caas.qitech.app/face_recognition/registration`

支持两种类型的注册 JSON 对象。一种是通过 `/image` 端点提前发送图片的情况，另一种是在注册请求时同时发送图片的情况。

名称 | 类型 | 描述
:----: | :----: | ---------
document_number | String | 客户的 CPF
image | String | 不含头部或附加信息的图片 Base64
image_key | String | 通过 /image 端点发送图片时返回的 UUID4

发送后，将返回包含用户注册数据的 Registration 对象。

**注意 -** 在注册时同时发送图片时，该图片将接受与通过 `/image` 端点发送图片时相同的质量测试。因此，发送的图片受本文档**图片**部分描述的相同规则约束。

## 状态更新 - **status**

Request Body

```json
{
    "registration_status": "fraud",
    "incident": "misappropriation",
    "event_date": "2029-08-25T13:34:12-03:00"                  
}
```

为了保证欺诈者数据库的反馈，需要在客户发生任何类型的欺诈或客户首次成功完成交易时通知系统。

为此，将客户注册状态更新为欺诈者需要向以下端点发送 **PUT** 类型的请求：

`https://api.caas.qitech.app/face_recognition/registration/{registration_key}/status`

以下值可用于 **incident** 字段，该字段指示客户犯下的欺诈类型：

枚举值 | 描述
--------- | ---------
misappropriation | 个人对某产品进行了不当占有
misrepresentation | 个人使用虚假或第三方文件注册
successfull_transaction | 个人成功完成了一次交易
status_restoration | 用于希望将状态恢复为 **undefined** 的情况

## 对象检索

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"
}   
```

随时可以通过向以下端点发送 **GET** 请求来检索客户的注册数据：

`https://api.caas.qitech.app/face_recognition/registration/{registration_key}`

---

# 标准

URL: /zh-Hans/documentation/caas/face_recognition/api/standards

为了简化集成并确保信息完整性，定义了一些在整个 API 中遵循的标准。

## 带时区的日期和时间
> 一些示例：

```
2019-10-15T22:35:12-03:00
2018-05-01T13:32:11+00:00
2019-05-01T00:00:00+00:00
```

按照 ISO 8601 表示。在这种情况下，时区紧跟在时间后面，应表示该数据有效的当地时区。例如，如果租用计划在巴西利亚机场 09:30 开始，发送的时间应表示为 09:30-03:00；如果租用计划在马瑙斯 09:30 开始，则应表示为 09:30-04:00。

用于验证的掩码如下：

`YYYY-MM-ddThh:mm:ss±hh:mm`

## 不带时区的日期和时间
> 一些示例：

```
2019-10-15T22:35:12Z
2018-05-01T13:32:11Z
2019-05-01T00:00:00Z
```

按照 ISO 8601 表示。与时区无关的数据应以不带时区的形式发送，始终使用 UTC，字母 Z 表示该数据为 UTC。因此，将验证以下格式：

`YYYY-MM-ddThh:mm:ssZ`

## 日期
> 一些示例

``` 
2019-10-15
2019-01-01
2017-03-20
```

对于只接受日期的字段（例如出生日期），只应发送日期，不含任何时间，格式如下：

`YYYY-MM-dd`
 

## 文档
由于文档号码种类繁多，其中许多包含非数字字符，所有文档号码均定义为字符串。将其定义为字符串的另一个好理由是避免前导零消失。本页中规定的文档具有明确的掩码，将进行验证。其余文档（如 RG）由于缺乏标准化，将不进行验证。

## CPF

> 对照定义掩码的有效 CPF 示例：

```
123.456.789-12
321.987.543-23
111.283.333-00
```

> 对照定义掩码的无效 CPF 示例：

```
8.577.477-8
08.104.627/0001-23
123.456.789-1
23.456.789-01
```

CPF 始终定义为字符串，将对照以下掩码进行验证：

`###.###.###-##`

---

# Validation

URL: /zh-Hans/documentation/caas/face_recognition/api/validation

要通过人脸识别执行客户验证，需要发送一张人脸照片以及已注册客户的 CPF。

随后，系统将在数据库中搜索该用户的记录，然后在数据库中存储的客户照片与发送的图片之间进行 1:1 验证。

## 对象定义

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"
}   
```

所有通过人脸识别的客户验证都将生成一个 Validation 对象。如果需要，此对象可以在将来通过适当的端点检索。

名称 | 类型 | 描述
:----: | :----: | ---------
validation_key | string | Validation 对象的密钥
document_number | string | 客户的 CPF
image | image | 携带验证时发送的图片属性的对象
registration | registration | 携带在验证中用作参考的注册属性的对象
similarity_ratio | integer | 注册图片与发送图片之间的相似度比率
validation_result | string | 执行的 1:1 分析结果
validation_date | datetime | UTC 人脸识别验证日期

## 创建 Validation

Request Body：同时发送图片（Base64）

```json
{
    "document_number": "123.456.789-00",
    "image": "base_64_image_code",
}
```

Request Body：提前发送图片

```json
{
    "document_number": "123.456.789-00",
    "image_key": "f1c0d2e1-f950-4360-896d-36588e443fc9",
}
```

与注册一样，也接受两种 JSON 格式，一种包含图片 Base64，另一种包含通过 `/image` 端点发送图片时收到的 **image_key**。

`https://api.caas.qitech.app/face_recognition/validation`

发送后，将返回包含分析结果以及指向发送图片的 UUID 的 JSON 对象。

**注意 -** 在通过人脸识别执行验证时同时发送图片时，该图片将接受与通过 `/image` 端点发送图片时相同的质量测试。因此，发送的图片受本文档**图片**部分描述的相同规则约束。

## 状态动态 - **validation_result**
执行分析后，将在 **validation_result** 标志下发送分析结果。可能的结果为：

结果 | 描述
--------- | ---------
match | 发送的照片与注册用户匹配
mismatch | 发送的照片与注册用户不匹配

## 对象检索

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"
}   
```

随时可以通过向以下端点发送 **GET** 请求来检索验证数据：

`https://api.caas.qitech.app/face_recognition/validation/{validation_key}`

---

# 收集 SDK 返回值

URL: /zh-Hans/documentation/caas/face_recognition/ios/collecting_response

要获取 SDK 的响应，您必须在您的 controller 中实现 **QITechIosFaceRecognitionControllerDelegate** 代理，如旁边的示例所示。

```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

**QITechIosFaceRecognitionControllerResponse** 类用于接收来自 QI Tech SDK 的响应。

下表中包含此类所有属性的详细信息：

### 属性

:::info 注意：
与 Device Scan 集成 从版本 6.1.0 起，Face Recognition 服务会自动内部调用 Device Scan。因此，成功返回值将包含 `DeviceScanSessionId` 字段。此密钥标识内部执行的设备扫描会话，可在 QI Tech 生态系统的其他服务中集成使用。
:::

| 名称 | 类型 | 描述 |
|------|------|-----------|
| `FaceRecognitionKey` | `String` | 存储在 QI Tech 中的面部照片唯一标识符。**重要：** 请保存此值以便在验证 API 中发送（例如：Onboarding API）。 |
`DeviceScanSessionId` | `String` | 内部执行的设备扫描会话唯一标识符。 |

## QITechIosFaceRecognitionControllerError

当发生导致 SDK 关闭的错误时，将触发 **QITechIosFaceRecognitionControllerError** 类。

:::danger 重要提示！
从版本 **5.0.0** 起，错误结构已重构以提供更详细的诊断信息。
:::
#### 主要变化：

1. **新错误类型**：`InvalidToken`（替代 `InvalidMobileToken`）
2. **新增可用属性**：
   - `status_code`：错误的 HTTP 状态码
   - `reason`：错误原因标识符
   - `description`：错误的详细描述

### 错误结构（SDK 5.0.0+）

#### 示例：InvalidToken

```swift
{
    status_code: 401,
    reason: "INVALID_TOKEN",
    description: "Authentication token expired or invalid"
}
```

## 错误类型

### SDK 5.0.0 及以后版本

| 错误 | Status Code | 描述 |
|------|-------------|-----------|
| `InvalidToken` | 401 | 认证令牌已过期或无效（替代 `InvalidMobileToken`） |

### 5.0.0 之前的版本

| 错误类 | 描述 |
|----------------|-----------|
| `InvalidMobileToken` | 配置中发送的 MobileToken 无效 *（在 v5.0.0+ 中被 `InvalidToken` 替代）* |
| `MissingPermission` | 某些必要权限未被授予 |
| `NetworkFailure` | 验证期间网络连接中断 |
| `ServerFailure` | QI Tech 服务器返回错误响应 |
| `MissingStorage` | 存储空间不足 |
| `LowImageQuality` | 图片质量不足以进行验证 |

---

# QITechIosFaceRecognitionConfiguration

URL: /zh-Hans/documentation/caas/face_recognition/ios/configuration

## SDK 5.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)

```

**QITechIosFaceRecognitionConfiguration** 类用于配置环境、凭据、视觉和文本方面，即 SDK 个性化和运行所需的所有配置。

下表包含实例化时必须使用的所有参数的详细信息：

| 名称                    |               类型                | 描述                                                                                                                                                                                                                                                                                                                                   |
| ----------------------- | :-------------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| environment             | QITechIosFaceRecognitionEnvironment | _（必填）_ 描述环境的枚举器。                                                                                                                                                                                                                                                                                                         |
| sessionId               |              string               | _（可选）_ 用于通过日志跟踪用户在 FaceRecon 执行过程中完整流程的唯一 ID。此字段最多接受 255 个字符。                                                                                                                                                                                                |
| clientSessionKey        |              string               | _（必填）_ 由 face recognition API 发送的用于 SDK 认证的令牌。                                                                                                                                                                                                                                                                        |
| backgroundColor         |              string               | _（可选）_ 屏幕背景颜色的十六进制值。若未指定，默认为 #FFFFFF。                                                                                                                                                                                                                                             |
| fontColor               |              string               | _（可选）_ 字体颜色的十六进制值。若未指定，默认为 #000000。                                                                                                                                                                                                                                                       |
| fontFamily              |            FontFamily             | _（可选）_ 字体系列。若未指定，默认为 .open_sans。可用字体：.open_sans、.futura、.verdana、.trebuchetms、.tamilsangammn 和 .system_font。                                                                                                                                               |
| showIntroductionScreens |             boolean              | _（可选）_ 指示是否显示介绍屏幕（包含照片拍摄方式的说明）的标志。若未指定，默认为 _true_。                                                                                                                                                                                   |
| showSuccessScreen       |             boolean              | _（可选）_ 指示是否显示成功屏幕（包含采集成功消息）的标志。若未指定，默认为 _true_。                                                                                                                                                                                                                                                      |
| showInvalidTokenScreen  |             boolean              | _（可选）_ 指示是否显示认证失败屏幕（包含令牌过期消息）的标志。若未指定，默认为 _true_。 |
| activeFaceLiveness      |             boolean              | _（可选）_ 指示 SDK 是否执行用户自拍采集或主动活体检测程序。若未指定，默认为 _false_。                                                                                                                                                                                                                                                           |
| audioConfiguration      |        AudioConfiguration         | _（可选）_ 指示 SDK 是否为用户播放提示音频。接受的配置为：_Enable_（始终播放提示音频）、_Disable_（从不播放音频）和 _Accessibility_（当用户设备启用了无障碍配置时播放音频）。 |
| logLevel                |             LogLevel              | _（可选）_ 用于自定义 SDK 日志的详细级别。可用级别：LogLevel.debug、LogLevel.info、LogLevel.warn、LogLevel.error 和 LogLevel.trace。若未指定，默认为 LogLevel.debug。 |

下表包含实例可接受的所有配置方法：

| 方法                 |                                                                                                                     参数                                                                                                                     | 描述                                                                                                     |
| ---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | --------------------------------------------------------------------------------------------- |
| setVisualConfiguration |                                                                 visualConfiguration : VisualConfiguration                                                             | _（可选）_ 允许修改 SDK 执行过程中显示的图片的类；|
| setTextConfiguration   |                                                                                                       textConfiguration : TextConfiguration                                                                                                        | _（可选）_ 允许修改 SDK 执行过程中显示的文本的类；  |
| setDocumentNumber      |                                                    用于设置用户的文档号码。此字段接受格式为 000.000.000-00 的 14 位 CPF 字符                                                    | 如果某次调用使用了 1:1 验证，则所有调用均必填。                                                                                         |
| setValidation          | 用于定义 SDK 是否对用户的自拍照执行 1:1 验证。在用户的第一次会话中，此标志**必须为 false**。此功能需要填写 setDocumentNumber 方法。 | 否。默认值为 _false_。                                                                      |

## 旧版本

### 配置

```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,
                                            mobileToken: "41fb4755-9bcf-4ae3-b981-b6009e51ce4a",
                                            sessionId: "7d8c6f9a-f222-450d-9501-a07c68eb2388",
                                            backgroundColor: "#C9CCD3",
                                            fontColor: "#337DFF",
                                            fontFamily: .open_sans,
                                            showIntroductionScreens: true,
                                            showSuccessScreen: false,
                                            activeFaceLiveness: true,
                                            audioConfiguration: AudioConfiguration.Enable,
                                            logLevel: .debug
                                            )

faceRecognitionConfig.setVisualConfiguration(visualConfiguration: visualConfiguration)
faceRecognitionConfig.setTextConfiguration(textConfiguration: textConfiguration)

```

### 参数表

| 名称                    |               类型                | 描述                                                                                                                                                                                                                                                                                                                                   |
| ----------------------- | :-------------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| environment             | QITechIosFaceRecognitionEnvironment | _（必填）_ 描述环境的枚举器。                                                                                                                                                                                                                                                                                                         |
| sessionId               |              string               | _（可选）_ 用于通过日志跟踪用户在 FaceRecon 执行过程中完整流程的唯一 ID。此字段最多接受 255 个字符。                                                                                                                                                                                                |
| mobileToken             |              string               | _（必填）_ QI Tech 发送的用于 SDK 认证的令牌。                                                                                                                                                                                                                                                                        |
| backgroundColor         |              string               | _（可选）_ 屏幕背景颜色的十六进制值。若未指定，默认为 #FFFFFF。                                                                                                                                                                                                                                             |
| fontColor               |              string               | _（可选）_ 字体颜色的十六进制值。若未指定，默认为 #000000。                                                                                                                                                                                                                                                       |
| fontFamily              |            FontFamily             | _（可选）_ 字体系列。若未指定，默认为 .open_sans。可用字体：.open_sans、.futura、.verdana、.trebuchetms、.tamilsangammn 和 .system_font。                                                                                                                                               |
| showIntroductionScreens |             boolean              | _（可选）_ 指示是否显示介绍屏幕（包含照片拍摄方式的说明）的标志。若未指定，默认为 _true_。                                                                                                                                                                                   |
| showSuccessScreen       |             boolean              | _（可选）_ 指示是否显示成功屏幕（包含采集成功消息）的标志。若未指定，默认为 _true_。                                                                                                                                                                                                                                                      |
| activeFaceLiveness      |             boolean              | _（可选）_ 指示 SDK 是否执行用户自拍采集或主动活体检测程序。若未指定，默认为 _false_。                                                                                                                                                                                                                                                           |
| audioConfiguration      |        AudioConfiguration         | _（可选）_ 指示 SDK 是否为用户播放提示音频。接受的配置为：_Enable_（始终播放提示音频）、_Disable_（从不播放音频）和 _Accessibility_（当用户设备启用了无障碍配置时播放音频）。
| logLevel | LogLevel | _（可选）_ 用于自定义 SDK 日志的详细级别。可用级别：LogLevel.debug、LogLevel.info、LogLevel.warn、LogLevel.error 和 LogLevel.trace。若未指定，默认为 LogLevel.debug。 |

---

# 混合解决方案

URL: /zh-Hans/documentation/caas/face_recognition/ios/hybrid_solutions

除了提供原生 Swift 集成外，我们的 SDK 还兼容多种混合框架。这通过为每个框架集成特定的原生插件来实现。利用每种解决方案的原生系统，可以在 iOS 环境中嵌入我们的原生 SDK。

一些最常用的混合技术包括 Xamarin（[Native Libraries](https://learn.microsoft.com/en-us/xamarin/android/platform/native-libraries)）、React Native（[Native Modules](https://reactnative.dev/docs/native-modules-intro)）、Cordova（[Plugin Development Guide](https://cordova.apache.org/docs/en/10.x/guide/hybrid/plugins/)）、Ionic（[Native](https://ionicframework.com/docs/v3/native/)）、Flutter（[Platform-Specific Code](https://docs.flutter.dev/platform-integration/platform-channels)）、Unity（[Native Plug-in for iOS](https://docs.unity3d.com/Manual/PluginsForIOS.html)）、Appcelerator、Phonegap 和 Node。

为了简化与我们原生解决方案的集成过程，我们为 React Native 和 Flutter 框架提供了插件。如有兴趣，我们在私有存储库中提供文档和集成示例。对于其他混合技术，我们有一些实现这个与原生代码桥接的示例。欢迎联系我们的 支持团队 获取访问权限。

---

# 简介

URL: /zh-Hans/documentation/caas/face_recognition/ios/introduction

欢迎使用 QI Tech iOS 人脸识别 SDK。此 SDK 执行面部采集并将其发送到 QI Tech Face Recognition API 。您可以使用它通过您的应用程序采集客户的面部图像，并通过密钥在 QI Tech 系统的其他产品中引用。

## 遇到问题？

我们不是一个躲在 API 背后的公司！请联系我们的[支持团队](mailto:suporte.caas@qitech.com.br)，我们将尽快回复。如果您想要快速响应，也欢迎直接给我们打电话！

### 我们热爱反馈

即使您已经解决了问题，或者问题非常简单（哪怕只是一个拼写错误或您已经理解的组织问题），也请给我们发送电子邮件，这样我们可以让文档变得越来越实用，下一个人就不必经历您所经历的痛苦！

:::danger 重要提示！
不得在 QI Tech 的沙盒环境中使用真实的个人和/或法人数据。
:::

---

# 导入 SDK

URL: /zh-Hans/documentation/caas/face_recognition/ios/native_swift

## 远程安装

> 开始安装

```shell
  pod init
```

我们的 SDK 可以使用 CocoaPods 导入。

| SDK              | 当前版本                         |
| ---------------- | ------------------------------------ |
| QITechIosFaceRecon | `pod 'QITechIosFaceRecon', '~> 8.0.0'` |

:::info iOS Minimum Deployment Target
15.5
:::

:::danger 在搭载 arm64 芯片的 MacBook 上使用模拟器
目前，我们的 iOS FaceRecon SDK 不幸地不支持在搭载 **arm64 架构芯片**（M1/M2/M3/M4）的 MacBook 上运行的模拟器进行编译，**除非使用 Rosetta**（将 x86_64 架构翻译为 arm64）。
:::

要开始安装，请在项目根目录中执行旁边的命令。

> 在 podfile 中添加 source

```ruby
   source 'https://github.com/QITechSDKs/iOS.git'
   source 'https://cdn.cocoapods.org/'
```

下一步是在 `podfile` 文件中添加 QI Tech 的 source。

> 在 podfile 中添加 pod

```ruby
  pod 'QITechIosFaceRecon', '~> <version>'
```

最后，只需按照旁边的格式添加 `pod` 名称即可。

:::danger 注意：
架构变更（v6.0.0+）从版本 6.0.0 起，SDK 开始以独占静态方式分发。在您的 Podfile 中，必须使用 :linkage => :static 配置。
:::

> Podfile 示例（版本 6.0.0 或更高）

```ruby
  source 'https://github.com/QITechSDKs/iOS.git'
  source 'https://cdn.cocoapods.org/'
  target 'ExampleApp' do
    use_frameworks! :linkage => :static
    pod 'QITechIosFaceRecon', '~> 8.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
```

> Podfile 示例（旧版本）

```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 注意
在 iOS 中集成依赖项时，可能需要对某些库使用静态链接，对其他库使用动态链接。此配置对于确保兼容性、避免构建错误和优化项目性能非常重要。
:::

### 混合依赖链接（如有必要）
混合链接的需求源于某些库有特定要求，一些库需要静态链接以避免内部冲突和符号重复，而其他依赖项可能需要动态链接，因为它们是为模块化和项目间共享而设计的。

静态链接与动态链接的区别
* 静态（static_framework）：库的代码直接嵌入到最终二进制文件中，减少运行时加载时间并消除运行时的外部依赖。
* 动态（dynamic_framework）：库在运行时作为单独文件加载。这减小了最终二进制文件的大小，便于独立更新/修改。

> 在 Podfile 中配置混合链接

```ruby
...

use_frameworks! :linkage => :dynamic # 将默认链接模式设置为动态

...

static_frameworks = ['framework_1', 'framework_2', ...] # 包含所有需要静态链接的依赖项
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
```

> 安装依赖项

```shell
  pod install
```

最后，执行 `pod install` 命令以下载和安装依赖项。

## 必要权限

为使 SDK 能够访问设备资源以采集用户自拍，需要向用户请求权限。

在 **info.plist** 文件中，添加以下权限：

| 权限                          | 原因                                             |
| ---------------------------------- | -------------------------------------------------- |
| Privacy - Camera Usage Description | 访问相机以采集用户自拍。 |

## 启动 SDK

:::danger 重要提示！
从版本 5.0.0 起，认证系统已更新，使用 **clientSessionKey** 代替 **mobileToken**。此外，还添加了新的反馈屏幕配置选项。
:::

### 获取 Client Session Key

在配置 SDK 之前，您必须通过服务器到服务器的请求向我们的人脸识别 API 生成一个临时的 **clientSessionKey**。

### 端点

| 环境 | URL |
|----------|-----|
| **沙盒** | `https://api.sandbox.zaig.com.br/face_recognition/client_session` |
| **生产** | `https://api.zaig.com.br/face_recognition/client_session` |

### 请求

**Method:** `POST`

**Headers:**
```json
{
  "Authorization": "YOUR_FACE_RECON_API_KEY"
}
```

**Body（可选，但推荐）：**
```json
{
  "user_id": "unique_user_identifier"
}
```

> **重要：** `user_id` 字段**强烈建议**用于安全和反欺诈措施。请使用您应用程序中用户的唯一标识符。

### 响应

成功响应将包含需要传递给 SDK 配置的 `client_session_key`。

```json
{
  "client_session_key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

### 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

        // 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) {

    }
}
```

要将 SDK 嵌入到您的应用程序中，您必须通过 **QITechIosFaceRecognitionConfiguration** 类配置自定义采集应用程序，然后实例化 **ViewController QITechIosFaceRecognitionController**，并将自定义配置作为参数传递。

要启动面部分析过程，只需调用 _present_ 函数来调用 QI Tech 的 ViewController 执行自拍采集。

重要的是要实现负责接收成功、错误或用户在验证任何步骤中中断旅程时的返回值的 _Delegate_。

旁边是完整的实现示例。

## 旧版本

### 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  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) {

    }
}
```

### Mobile Token

我们使用 Mobile Token 来允许您的应用程序对我们的 API 进行认证访问。它可能已通过电子邮件发送给您。如果您尚未收到 token，请发送电子邮件至 suporte.caas@qitech.com.br 。

我们的 API 期望在所有来自 SDK 的请求中接收 Mobile Token，因此必须通过上述方法将其作为配置参数包含在内。

:::info **注意**

您必须将 "YOUR_MOBILE_TOKEN_SENT_BY_QITECH" 替换为从支持团队收到的 Mobile Token。
:::

---

# necessary_permissions

URL: /zh-Hans/documentation/caas/face_recognition/ios/necessary_permissions

## 必要权限

为使 SDK 能够访问设备资源以采集用户自拍，需要向用户请求权限。

在 **info.plist** 文件中，添加以下权限：

| 权限                          | 原因                                             |
| ---------------------------------- | -------------------------------------------------- |
| Privacy - Camera Usage Description | 访问相机以采集用户自拍。 |

---

# using_sdk

URL: /zh-Hans/documentation/caas/face_recognition/ios/using_sdk

## 启动 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) {

    }
}
```

要将 SDK 嵌入到您的应用程序中，您必须通过 **QITechIosFaceRecognitionConfiguration** 类配置自定义采集应用程序，然后实例化 **ViewController QITechIosFaceRecognitionController**，并将自定义配置作为参数传递。

要启动面部分析过程，只需调用 _present_ 函数来调用 QI Tech 的 ViewController 执行自拍采集。

重要的是要实现负责接收成功、错误或用户在验证任何步骤中中断旅程时的返回值的 _Delegate_。

旁边是完整的实现示例。

## Mobile Token

我们使用 Mobile Token 来允许您的应用程序对我们的 API 进行认证访问。它可能已通过电子邮件发送给您。如果您尚未收到 token，请发送电子邮件至 suporte.caas@qitech.com.br 。

我们的 API 期望在所有来自 SDK 的请求中接收 Mobile Token，因此必须通过上述方法将其作为配置参数包含在内。

:::info **注意**

您必须将 "YOUR_MOBILE_TOKEN_SENT_BY_QITECH" 替换为从支持团队收到的 Mobile Token。
:::

---

# 收集 SDK 返回值

URL: /zh-Hans/documentation/caas/face_recognition/web/collecting_response

## .initialize() 方法
.initialize() 方法负责初始化人脸识别和活体检测组件。执行此方法后，相机在组件内初始化以进行照片采集。

**拒绝场景：**

- **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.'
}
```

## .open() 方法

此方法负责启动采集，将开始与用户的交互以收集活体证明。此方法返回一个 _Promise_，在采集完成后以采集照片的密钥（image_key）响应。

**Promise resolution:**

```javascript
{ 
  status: string //
  image_key: string; // Image key that identifies the image on the server to later be used for validation.
}
```

 ```javascript
  {
    status: "SUCCESS",
    image_key: "d8a3b1c4-9e2f-47a5-8c3d-1b2e5...";
  }
  ```

**Promise rejection:**

```javascript
{
  status: string; 
  reason: string;  
  description: string; 
}
```

**拒绝场景：**

- **User Canceled:**

  ```javascript
  {
    status: "FAILURE",
    reason: "USER_CANCELED",
    description: "User pressed the back button."
  }
  ```

- **Invalid Token:**（当 `client_session_key` 无效或过期时发生）

  ```javascript
  {
    status: "FAILURE",
    reason: "INVALID_TOKEN",
    description: "Authentication token expired or invalid"
  }
  ```

---

# 实现

URL: /zh-Hans/documentation/caas/face_recognition/web/example

:::danger 重要提示！
从版本 **3.0.0** 起，与 Web SDK 的集成需要在流程开始前向我们的人脸识别 API 发送请求以获取认证密钥，并且我们更改了结果的返回方式。
:::

库的实现通过 QITechWebFaceRecon 组件实例和 .WebFaceRecon() 构造函数调用来完成。其初始化发生在 .initialize() 方法中，在该方法中我们创建一些元素并加载必要的组件。

要开始与用户的交互和活体证明收集，只需调用 .open() 方法并等待其返回。

## 获取 Client Session Key

在配置 SDK 之前，您必须通过服务器到服务器的请求向我们的人脸识别 API 生成一个临时的 **clientSessionKey**。

### 端点

| 环境 | URL |
|----------|-----|
| **沙盒** | `https://api.sandbox.zaig.com.br/face_recognition/client_session` |
| **生产** | `https://api.zaig.com.br/face_recognition/client_session` |

### 请求

**Method:** `POST`

**Headers:**
```json
{
  "Authorization": "YOUR_FACE_RECON_API_KEY"
}
```

**Body（可选，但推荐）：**
```json
{
  "user_id": "unique_user_identifier"
}
```

> **重要：** `user_id` 字段**强烈建议**用于安全和反欺诈措施。请使用您应用程序中用户的唯一标识符。

### 响应

成功响应将包含需要传递给 SDK 配置的 `client_session_key`。

```json
{
  "client_session_key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

## 示例
```html
<script>
  const hostComponent = document.getElementById('webfacerecon');
  const webFaceRecon = new QITechWebFaceRecon.WebFaceRecon(hostComponent)
    .setThemeConfiguration({
      buttonColor: "#2848A8",
      fontColor: "#FFFFFF",
      backgroundColor: "#FFFFFF"
    })
    .setSandboxEnvironment()
    .setLogLevel('debug')
    .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>
```

## 旧版本
```html
<script>
 var hostComponent = document.getElementById('webfacerecon')
      var webFaceRecon = new QITechWebFaceRecon.WebFaceRecon(
        hostComponent,
        'YOUR_TOKEN_SENT_BY_QITECH'
      )
        .setThemeConfiguration(
        {
          "buttonColor": "#2848A8",
          "fontColor": "#FFFFFF",
          "backgroundColor": "#FFFFFF"
        }
        )
        .setSandboxEnvironment()
        .setLogLevel('debug')
        .setSessionId('UNIQUE_SESSION_ID')
        .build()
      webFaceRecon.initialize().then(res => {
        var promise = webFaceRecon.open()
        promise
          .then(image_key => {
            console.log(image_key)
          })
          .catch(err => {
            console.log(err)
          })
      })
</script>
```

---

# QITechWebFaceRecon.WebFaceRecon() 构造函数

URL: /zh-Hans/documentation/caas/face_recognition/web/example_zaigwebfacerecon

:::danger 重要提示！
从版本 **3.0.0** 起，WebFaceRecon 构造函数已更改。
:::
.WebFaceRecon 方法负责配置您的人脸识别组件实例。此方法具有以下配置。

| 名称 | 描述 | 是否必填 |
|----------|----------|----------|
| .setSandboxEnvironment() | 用于将环境配置为沙盒模式的方法。 | 否 |
| .setShowInvalidTokenScreen(Boolean) | 用于配置是否显示认证失败屏幕的方法。若未指定，默认为 false。 | 否 |
| .setShowBackButton(Boolean) | 用于配置是否显示返回按钮（按下后将终止流程）的方法。若未指定，默认为 true。 | 否 |
| .setSessionId(String) | 用于设置标识 SDK 启动会话的密钥。用于通过日志跟踪用户在 Web FaceRecon 执行过程中的完整流程。此字段接受最多 255 个字符的字符串。 | 否 |
| .setThemeConfiguration(object) | 用于自定义 webfacerecon 元素组件视觉标识的方法。 | 否 |
| .setLogLevel(String) | 用于自定义 Web FaceRecon 日志的详细级别。可用级别："info"、"debug"、"warn" 和 "error"。默认为 "info"。 | 否 |

.setThemeConfiguration 方法必须接收包含以下字段的对象：

| 名称 | 类型 | 描述 |
| -------- | -------- | -------- |
| buttonColor | String | _（必填）_ 屏幕按钮颜色的十六进制值。若未指定，默认为 #FFFFFF。 |
| fontColor | String | _（必填）_ 屏幕上显示的文本颜色的十六进制值。若未指定，默认为 #000000。 |
| backgroundColor | String | _（必填）_ 屏幕背景颜色的十六进制值。若未指定，默认为 #FFFFFF。 |

## 旧版本

| 名称 | 描述 | 是否必填 |
|----------|----------|----------|
| web_token | 客户密钥，用于标识收集的数据来源于您的应用程序。如果尚未收到您的 web-token，请联系<a href='mailto:suporte.caas@qitech.com.br'>支持团队</a>。 | 是 |
| .setSandboxEnvironment() | 用于将环境配置为沙盒模式的方法。 | 否 |
| .setSessionId(String) | 用于设置标识 SDK 启动会话的密钥。用于通过日志跟踪用户在 Web FaceRecon 执行过程中的完整流程。此字段接受最多 255 个字符的字符串。 | 否 |
| .setThemeConfiguration(object) | 用于自定义 webfacerecon 元素组件视觉标识的方法。 | 否 |
| .setLogLevel(String) | 用于自定义 Web FaceRecon 日志的详细级别。可用级别："info"、"debug"、"warn" 和 "error"。默认为 "info"。 | 否 |

---

# 导入库

URL: /zh-Hans/documentation/caas/face_recognition/web/import

要导入我们的库，请在您网站 HTML 的 **src** 标签中添加我们库的地址：

```html
<script src="https://facerecon.caas.qitech.app/face-recognition-4-2-1.js"></script>
```

---

# 简介

URL: /zh-Hans/documentation/caas/face_recognition/web/introduction

欢迎使用 QI Tech Web Face Recognition 集成手册！此库执行面部采集并将其发送到 QI Tech Face Recognition API 。您可以使用此库通过您的网站采集客户的面部图像，并通过密钥在 QI Tech 系统的其他产品中引用。

在本步骤指南中，您将找到库的详细信息以及 JavaScript 实现示例。通过这些，您拥有了将解决方案适配到您应用程序用例所需的工具。

## 遇到问题？

我们不是一个躲在 API 背后的公司！请联系我们的 支持团队 ，我们将尽快回复。如果您想要快速响应，也欢迎直接给我们打电话！

### 我们热爱反馈

即使您已经解决了问题，或者问题非常简单（哪怕只是一个拼写错误或您已经理解的组织问题），也请给我们发送电子邮件，这样我们可以让文档变得越来越实用，下一个人就不必经历您所经历的痛苦！

## 环境

我们为客户提供两个环境。

* 生产环境
* 沙盒环境

:::danger 重要提示！
不得在 QI Tech 的沙盒环境中使用真实的个人和/或法人数据。
:::

通过在人脸识别组件初始化时调用 .setSandboxEnvironment() 方法来进行选择，这将把环境更改为沙盒。如果未调用该方法，则使用生产环境。

---

# 面部注册和 1:1 验证

URL: /zh-Hans/documentation/caas/face_recognition/web/registration_and_validation

## 注册
要将用户的面部与其 CPF 关联注册，需要在 `.setDocumentNumber()` 函数的 _documentNumber_ 参数中填写该用户的 CPF，并且在 SDK 构造函数中将 `.setValidation()` 函数的 _shouldValidate_ 参数设置为 _false_，或者不调用 `.setValidation()` 函数。请查看以下注册示例：

```js
<script>
    var hostComponent = document.getElementById('webfacerecon')
        var webFaceRecon = new QITechWebFaceRecon.WebFaceRecon(hostComponent)
        ... Outras configurações
        .setDocumentNumber('000.000.000-00')
        //.setValidation(false) a função setValidation não deve ser utilizada ou utilizada com o parâmetro false
        .build()
<script/>
```

## 1:1 验证 - Face Match
要使用 **1:1 验证（Face Match）**功能，需要在 SDK 构造函数中将 _shouldValidate_ 参数设置为 _true_。这应通过调用 `.setValidation()` 方法来完成。此外，`.setDocumentNumber()` 函数的 _documentNumber_ 参数需要填写已预先注册面部的用户的 CPF。请查看以下验证示例：

```js
<script>
    var hostComponent = document.getElementById('webfacerecon')
        var webFaceRecon = new QITechWebFaceRecon.WebFaceRecon(hostComponent)
        ... Outras configurações
        .setDocumentNumber('000.000.000-00')
        .setValidation(true)
        .build()
<script/>
```

> **注意：** 1:1 验证只能在用户的第二次会话起使用，即在第一次会话之后，当 _documentNumber_ 参数填写了用户 CPF 且 _validation_ 参数为 `false` 时，需要有记录才能进行验证。

## 旧版本
:::danger 重要提示！
**3.0.0** 之前的版本需要在 WebFaceRecon 构造函数中传递 mobileToken。
:::
使用示例
```html
<script>
    var hostComponent = document.getElementById('webfacerecon')
        var webFaceRecon = new QITechWebFaceRecon.WebFaceRecon(
            hostComponent,
            'YOUR_TOKEN_SENT_BY_QITECH'
        )
        ... Outras configurações
<script/>
```

---

# authentication

URL: /zh-Hans/documentation/caas/limits/authentication

## 身份验证

> 要认证调用，请使用以下代码：

```shell
# 在 shell 中，只需在每个请求中添加适当的头部
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE_API_KEY"
```

> 将 API key 'EXAMPLE_API_KEY' 替换为您从我们的支持团队获取的密钥。

我们使用 API Key 来允许访问我们的 API。它可能已通过电子邮件发送给您。如果您尚未收到密钥，请发送电子邮件至 suporte.caas@qitech.com.br 。

我们的 API 期望在所有向服务器发送的请求中，在如下头部中接收 API Key：

`Authorization: EXAMPLE_API_KEY`

:::info **注意**

您必须将 EXAMPLE_API_KEY 替换为从支持团队收到的 API Key。
:::

---

# HTTP 状态码

URL: /zh-Hans/documentation/caas/limits/http_status

所有 QI Tech API 均按照 RFC 7231 使用以下 HTTP 返回状态标准化：

HTTP 状态 | 含义 | 描述
---------- | ------- | ---------------------------------
400 | Bad Request | 发送的请求存在格式错误。大多数情况下，我们会在消息正文中返回错误位置的说明。
401 | Unauthorized | 身份验证出现问题，请检查 API Key 是否正确以及是否在正确的头部中，详见 身份验证 部分。
403 | Forbidden | 访问的端点仅供内部使用，此 API Key 不可用。
404 | Not Found | 使用所提供的密钥未找到请求的数据。当请求无效端点时也会返回此状态。
405 | Method Not Allowed | 使用的 HTTP 方法不适用于所使用的端点。
406 | Not Acceptable | 请求正文中发送的数据无效。通常，这意味着发送的数据不是有效的 JSON。
409 | Conflict | 请求 ID 对应于之前已处理的 ID。当向服务器发送重复请求时会返回此状态。
500 | Internal Server Error | 处理此请求时出现问题，遇到此错误时，我们的专家会自动收到通知并立即开始分析和解决。
503 | Service Unavailable | 您遇到了我们服务器基础设施的计划内或计划外停机。

---

# 简介

URL: /zh-Hans/documentation/caas/limits/introduction

欢迎使用 QI Tech PIX 限额 API！您可以使用我们的 API 管理您的 PIX 限额：
- 注册新的 PIX 限额；
- 修改预先存在的 PIX 限额；
- 检索预先存在的 PIX 限额。

以下是使用 cUrl 的 API 实现示例。通过这些，您拥有了适配您首选编程语言所需的示例。

## 遇到问题？

我们不是一个躲在 API 背后的公司！请联系我们的 支持团队 ，我们将尽快回复。如果您想要快速响应，也欢迎直接给我们打电话！

### 我们热爱反馈

即使您已经解决了问题，或者问题非常简单（哪怕只是一个拼写错误或您已经理解的组织问题），也请给我们发送电子邮件，这样我们可以让文档变得越来越实用，下一个人就不必经历您所经历的痛苦！

## 环境

我们为客户提供两个环境。API 的基础 URL 为：

* 生产环境 - `https://api.caas.qitech.app/limits_pix/`
* 沙盒环境 - `https://api.sandbox.caas.qitech.app/limits_pix/`

:::danger 重要提示！
不得在 QI Tech 的沙盒环境中使用真实的个人和/或法人数据。
:::

在沙盒环境中，发送的分析不收费，并按照预先设定的规则响应。

对于交易分析，以下规则适用于交易金额：

最小值 | 最大值 | 决策
------ | ------ | -------
0 | 1000 | 自动批准
1001 | 2000 | 转入人工分析 - 随后批准
2001 | 3000 | 转入人工分析 - 随后拒绝
3001 | 4000 | 自动拒绝
4001 | 5000 | 未分析
5001 | - | 待处理

## 仅限 HTTPS

出于安全考虑，与 QI Tech API 的所有通信必须使用 HTTPS 进行。为避免因疏忽或其他原因进行 HTTP 调用，此服务器仅开放使用 TLS 1.2 通信的 443 端口。使用其他协议的调用将被自动拒绝。

## 身份验证

> 要认证调用，请使用以下代码：

```shell
# 在 shell 中，只需在每个请求中添加适当的头部
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE_API_KEY"
```

> 将 API key 'EXAMPLE_API_KEY' 替换为您从我们的支持团队获取的密钥。

我们使用 API Key 来允许访问我们的 API。它可能已通过电子邮件发送给您。如果您尚未收到密钥，请发送电子邮件至 suporte.caas@qitech.com.br 。

我们的 API 期望在所有向服务器发送的请求中，在如下头部中接收 API Key：

`Authorization: EXAMPLE_API_KEY`

:::info **注意**

您必须将 EXAMPLE_API_KEY 替换为从支持团队收到的 API Key。
:::

---

# 注册新限额

URL: /zh-Hans/documentation/caas/limits/limit_registration

要注册新限额，只需向以下端点发送一个 _Account_ 类型的对象：

`POST https://api.caas.qitech.app/limits_pix/account`

> 示例

```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
            }
        }
    }
}
```

所有注册信息交换都使用以下对象定义。在某些情况下，为了方便实现并减少双方之间的数据流，某些信息可能会被省略。

名称 | 类型 | 描述
:----: | :----: | ---------
account_id | string | 账户唯一标识符。 **对于每个请求，此编号必须是唯一的**
registration_date |	string (ISO 8601) | 注册日期和时间。
limit |	limit | _limit_ 类型的对象。

## 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 
        }
    }
}
```

此对象表示适用于不同类型交易在一天中不同时间段的金额限制，考虑到日间和夜间时段的划分。

该对象分为四个主要类别（或限额类型）："withdraw"（指 PIX 取款模式）、"change"（指 PIX 找零模式）、"transaction_natural_person"（指个人 PIX 交易模式）和 "transaction_legal_person"（指企业 PIX 交易模式）。每个类别包含 2 个时段，"daytime" 和 "nighttime"，分别代表日间和夜间时段，描述开始时间和要应用于该模式的相应金额限制。值得注意的是，limit 对象的 4 个 PIX 类别是必填的，在创建账户时必须存在。

限额窗口结构：

名称 |	类型 |	描述
:----: | :----: | ---------
start_time |	string (ISO 8601) |	指示 PIX 交易金额限制开始应用的时刻。请注意根据您打算使用的时区正确配置限额窗口的开始时间。
amount |	整数 |	以巴西雷亚尔分（centavos）为单位，在 "start_time" 指定的时段内对该模式允许的最大限额值。

根据巴西中央银行的规定，PIX 限额的日间窗口必须强制性地从上午 6 点开始，因此对于这些窗口的 start_time 配置，目前只接受 "06:00:00-03:00" 值。

类似地，由于 PIX 限额的夜间窗口必须从晚上 8 点或 10 点开始，因此对于这些窗口的 start_time 配置，只接受 "20:00:00-03:00" 和 "22:00:00-03:00" 值。

*使用示例：*
假设用户在 12:00:00-03:00 进行个人 PIX 交易。查询对象时，我们找到 "transaction_natural_person" 类别。在该类别中，我们找到 2 个时段，"daytime" 和 "nighttime"：第一个从 "06:00:00-03:00" 开始，第二个从 "20:00:00-03:00" 开始。如果交易在这些时间之间进行，则允许的最大金额为 5,000.00（五千）巴西雷亚尔，如第一个限额窗口所规定。

但是，如果交易在 "20:00:00-03:00" 之后且在下一个开始时间之前（在此示例中，为次日 06:00），则允许的最大金额将为 3,000.00（三千）巴西雷亚尔，如第二个限额窗口（夜间窗口）所示。

# 创建限额修改提案

要请求修改限额，只需向以下端点发送一个 Limit 类型的对象：

`POST https://api.caas.qitech.app/limits_pix/account/{account_id}/limit_update_request`

> 示例

```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 
        }
    }
}
```

请求的返回将由所有已进行的修改列表组成，按时段和 PIX 限额类别分隔。在上面的示例中，修改在 "change"（PIX 找零）类别中进行，请求增加两个时段的限额。因此，请求的响应如下：

```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"
        },
    ]
}
```

名称 |	类型 |	描述
:----: | :----: | ---------
limit_update_request_id |	string |	限额修改提案的唯一标识符
analysis_status |	string |	提案的 analysis_status 枚举值
client_notification_status |	string |	提案的 client_notification_status 枚举值
limit_update_request_status |	string |	提案的 limit_update_request_status 枚举值
limit_update_request_type |	  string |	提案的 limit_update_request_type 枚举值
event_date |	string (ISO 8601) |	限额修改提案的创建日期和时间

要更好地了解返回状态，请访问 状态动态 。

---

# 创建受益人列表

URL: /zh-Hans/documentation/caas/limits/recipient_list

根据巴西中央银行的 PIX 限额规定，可以创建一个将使用相同差异化限额的受益人列表。

要请求为账户创建受益人列表，只需向以下端点发送一个 Limit 类型的对象：

`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 
            }
        }
    }
}
```

将返回以下内容：

```json
{
    "event_date": "2019-10-01T10:37:25-03:00"
}
```

名称 |	类型 |	描述
:----: | :----: | ---------
event_date |	string (ISO 8601) |	受益人列表的创建日期和时间

# 向受益人列表添加新受益人

要向之前创建的受益人列表添加新受益人，只需执行以下请求：

`POST https://api.caas.qitech.app/limits_pix/account/{account_id}/recipient_list/recipient`

```json
{
    "document_number": "123.456.789-10"
}
```

将返回以下内容：

```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"
}
```

名称 |	类型 |	描述
:----: | :----: | ---------
recipient_id |	string |	此限额修改提案中受益人的唯一标识符
analysis_status |	string |	提案的 analysis_status 枚举值
client_notification_status |	string |	提案的 client_notification_status 枚举值
recipient_status |	string |	提案的 recipient_status 枚举值
event_date |	string (ISO 8601) |	限额修改提案的创建日期和时间

要更好地了解返回状态，请访问 状态动态 。

# 删除受益人

要删除账户的特定受益人，只需向以下地址发送 DELETE 类型的请求：

`DELETE https://api.caas.qitech.app/limits_pix/account/{account_id}/recipient_list/recipient/{recipient_id}`

# 编辑受益人列表的限额

要请求更改给定账户的受益人限额，只需执行以下请求：

`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 
            }
        }
    }
}
```

请求的返回将由所有已进行的修改列表组成，按时段分隔。在上面的示例中，修改在 "transaction" 类别中进行，请求增加两个时段的限额。因此，请求的响应如下：

```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"
        },
    ]
}
```

名称 |	类型 |	描述
:----: | :----: | ---------
recipient_id |	string |	此限额修改提案中受益人的唯一标识符
analysis_status |	string |	提案的 analysis_status 枚举值
client_notification_status |	string |	提案的 client_notification_status 枚举值
recipient_status |	string |	提案的 recipient_status 枚举值
recipient_list_limit_update_request_type |	  string |	提案的 recipient_list_limit_update_request_type 枚举值
event_date |	string (ISO 8601) |	限额修改提案的创建日期和时间

---

# 标准

URL: /zh-Hans/documentation/caas/limits/standards

为了简化集成并确保信息完整性，定义了一些在整个 API 中遵循的标准。

## 货币金额
> 示例：

```
10000
12345
98741
1223
1
0
```

API 假设所有发送的货币金额均以巴西雷亚尔为单位。金额必须以整数（分，centavos）形式发送。

## 带时区的日期和时间
> 一些示例：

```
2019-10-15T22:35:12-03:00
2018-05-01T13:32:11+00:00
2019-05-01T00:00:00+00:00
```

按照 ISO 8601 表示。在这种情况下，时区紧跟在时间后面，应表示该数据有效的当地时区。例如，如果租用计划在巴西利亚机场 09:30 开始，发送的时间应表示为 09:30-03:00；如果租用计划在马瑙斯 09:30 开始，则应表示为 09:30-04:00。

用于验证的掩码如下：

`YYYY-MM-ddThh:mm:ss±hh:mm`

## 不带时区的日期和时间
> 一些示例：

```
2019-10-15T22:35:12Z
2018-05-01T13:32:11Z
2019-05-01T00:00:00Z
```

按照 ISO 8601 表示。与时区无关的数据应以不带时区的形式发送，始终使用 UTC，字母 Z 表示该数据为 UTC。因此，将验证以下格式：

`YYYY-MM-ddThh:mm:ssZ`

## 日期
> 一些示例

``` 
2019-10-15
2019-01-01
2017-03-20
```

对于只接受日期的字段（例如出生日期），只应发送日期，不含任何时间，格式如下：

`YYYY-MM-dd`
 

## 文档
由于文档号码种类繁多，其中许多包含非数字字符，所有文档号码均定义为字符串。将其定义为字符串的另一个好理由是避免前导零消失。本页中规定的文档具有明确的掩码，将进行验证。其余文档（如 RG）由于缺乏标准化，将不进行验证。

## CPF

> 对照定义掩码的有效 CPF 示例：

```
123.456.789-12
321.987.543-23
111.283.333-00
```

> 对照定义掩码的无效 CPF 示例：

```
8.577.477-8
08.104.627/0001-23
123.456.789-1
23.456.789-01
```

CPF 始终定义为字符串，将对照以下掩码进行验证：

`###.###.###-##`

## CNPJ

> 对照定义掩码的有效 CNPJ 示例：

```
08.104.627/0001-02
01.079.210/0114-67
32.402.502/0001-35
```

> 对照定义掩码的无效 CNPJ 示例：

```
8.577.477-8
123.456.789-12
321.987.543-23
32.402.502/0001-3
032.402.502/0001-3
```

CNPJ 始终定义为字符串，将对照以下掩码进行验证：

`##.###.###/####-##`

## IP

> 对照定义掩码的有效 IP 示例：

```
201.81.161.86
201.081.161.86
201.81.161.086
201.81.0.1
```

> 无效 IP 示例：

```
201.81..86
358.81.161.86
201.81.161
```

IP 必须始终以 IPv4 格式发送，前导零可以发送也可以不发送，遵循以下掩码：

`###.###.###.###`

---

# 状态动态

URL: /zh-Hans/documentation/caas/limits/status_dynamics

## 分析状态（analysis_status）

"analysis_status" 指示限额政策决策的状态。

"analysis_status" 的可能值如下：

analysis_status | 描述
:---------: | ---------
automatically_approved | 限额政策已自动批准此限额修改请求。
automatically_reproved | 限额政策已自动拒绝此限额修改请求。
in_manual_analysis | 限额政策已将此限额修改请求委托给人工分析。
manually_approved | 人工分析后，分析师决定批准限额修改。
manually_reproved | 人工分析后，分析师决定拒绝限额修改。
reproved_by_time | 请求因分析时间过期而被拒绝。
pending | 请求待处理。

## 客户通知状态（client_notification_status）

"client_notification_status" 与需要通知客户限额修改请求进展情况的时间段相关。

client_notification_status | 描述
:---------: | ---------
awaiting_notification_period | 指示客户通知时间窗口尚未开始。
in_notification_period | 指示我们正处于客户通知时间窗口内。
notification_period_expired | 指示客户通知时间窗口已过期。

## 限额修改状态（limit_update_request_status）

"limit_update_request_status" 与限额修改请求的状态相关。

limit_update_request_status | 描述
:---------: | ---------
created | 指示限额修改请求已创建。
applied | 指示限额修改请求已应用。
canceled | 指示限额修改请求已取消。

## 受益人列表修改状态（recipient_list_append_request_status）

"recipient_list_append_request_status" 与受益人列表修改请求的状态相关。

recipient_list_append_request_status | 描述
:---------: | ---------
created | 指示受益人列表修改请求已创建。
applied | 指示受益人列表修改请求已应用。
canceled | 指示受益人列表修改请求已取消。

---

# Webhook

URL: /zh-Hans/documentation/caas/limits/webhook

欺诈状态的更新（对于被转入人工分析或响应为待处理的订单）以及被阻止的卖家，通过 Webhook 进行通知。为此，需要通过[支持团队](mailto:suporte.caas@qitech.com.br)配置一个端点地址以接收更新通知，以及一个用于签署请求的 *signature_key*。值得注意的是，所有 webhook 发送都将发送到单一端点。

对于订单状态更新，客户也可以使用[轮询](https://en.wikipedia.org/wiki/Polling_(computer_science))技术。在这种情况下，只需不配置 webhook 端点，并使用订单检索端点来进行轮询。

:::info **注意**

出于安全考虑，所有 Webhook 请求只会在通过 HTTPS 服务的端点上执行。
:::

## 签名

> Python 签名计算示例

```python
    hmac_obj = hmac.new(signature_key.encode('utf-8'), (url + method + payload).encode('utf-8'), hashlib.sha1)
    return hmac_obj.hexdigest()
```

为确保 webhook 端点收到的请求来自我们的服务器，HMAC 签名以类似于认证过程的方式在 *Signature* 头部中发送。

在服务器端计算预期签名值后，需要将计算出的签名与发送的签名进行比较。如果签名匹配，则表明请求来自我们的服务器且是可信任的。

## 事件更新 Webhook

Request Body

```json
    {
        "id": "123456",
        "analysis_status": "automatically_approved",
        "event_date": "2019-10-01T10:37:25-03:00"
    }
```

事件分析状态更新请求具有上述格式，通知欺诈状态的变化。使用的方法是 PUT，端点地址也可以根据客户需求包含事件 ID。重要的是要注意，请求正文以 UTF-8 编码的文本发送。

## 重试

当收到 HTTP Status 200 作为响应时，通知被认为已完成。如果通知失败，将以以下间隔进行 7 次重试，直到返回 200 或尝试结束：

* 10 秒
* 40 秒
* 160 秒
* 640 秒
* 2560 秒
* 10240 秒
* 40960 秒

---

# builder

URL: /zh-Hans/documentation/caas/ocr/android/builder

## DocumentRecognition.Builder

| 参数 | 功能 | 是否必填 |
|------------|--------------|--------------|
|mobileToken |客户密钥，用于标识收集的数据来源于您的应用程序。如果尚未收到您的 mobile-token，请联系<a href='mailto:suporte.caas@qitech.com.br'>支持团队</a>。|是。|
|.setDocumentSteps(DocumentRecognitionStep[] documentSteps)|定义用户进行的文档采集流程。更多信息请[点击这里](https://docs.zaig.com.br/android_ocr/#documentdetectorstep)|是。|
|.setSandboxEnvironment()|若在构造函数中使用此参数，库将配置为向沙盒环境发送数据。若不存在，请求将发送到生产环境。|否。|
|.showIntroductionScreens(Boolean showIntroductionScreens)|设置为 "false" 时，禁用向用户显示的文档照片采集介绍屏幕。|否。默认值为 "true"。|
|.setShowSuccessScreen(Boolean showSuccessScreen)|设置为 "false" 时，禁用照片采集后的成功屏幕。|否。默认值为 "true"。|
|.setBackgroundColor(String backgroundColor)|允许配置 SDK activities 的背景颜色。|否。默认值为 "#ffffff"。|
|.setFontColor(String fontColor)|允许配置 SDK activities 的字体和图标颜色。|否。默认值为 "#000000"。|
| .setFontFamily(FontFamily fontFamily)| 允许配置 SDK activities 的字体。| 否。若未指定，默认为 FontFamily.open_sans。可用字体：FontFamily.open_sans、FontFamily.futura、FontFamily.verdana、FontFamily.roboto、FontFamily.poppins 和 FontFamily.helvetica。|否。|
|.setVisualConfiguration([VisualConfiguration](https://docs.zaig.com.br/android_ocr/#o-objeto-visualconfiguration). visualConfiguration)| 用于自定义 SDK 执行过程中向用户显示的图片。|否。|
|.setTextConfiguration([TextConfiguration](https://docs.zaig.com.br/android_ocr/#o-objeto-textconfiguration). textConfiguration) | 用于自定义 SDK 执行过程中向用户显示的引导屏幕上的文本。|否。|
|.setSessionId(String sessionId)| 用于设置标识 SDK 启动会话的密钥。用于通过日志跟踪用户在 FaceRecon 执行过程中的完整流程。此字段最多接受 255 个字符。|否。|
|.setLogLevel(DocumentRecognition.LogLevel logLevel)| 用于自定义 SDK 日志的详细级别。可用级别：LogLevel.debug、LogLevel.info、LogLevel.warn、LogLevel.error 和 LogLevel.trace。默认为 LogLevel.debug。|否。|

## VisualConfiguration 对象

| 参数                                                                      | 功能                                                                                                                                                                                                                                                              | 是否必填             |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| .setOnboardingDrawable(int onboarding_drawable, int onboarding_width)          | 用于配置在 SDK 引导屏幕上向用户显示的图片。参数 _onboarding_drawable_ 应引用要显示的图片 ID，_onboarding_width_ 是该图片的预期显示尺寸。                       | 否。                    |
| .setDocumentFullDrawable(int documentfull_drawable, int documentfull_width)    | 用于配置在 SDK 完整驾照采集屏幕上向用户显示的图片。参数 _documentfull_drawable_ 应引用要显示的图片 ID，_documentfull_width_ 是该图片的预期显示尺寸。       | 否。                    |
| .setDocumentFrontDrawable(int documentfront_drawable, int documentfront_width) | 用于配置在 SDK 驾照和身份证正面采集屏幕上向用户显示的图片。参数 _documentfront_drawable_ 应引用要显示的图片 ID，_documentfront_width_ 是该图片的预期显示尺寸。 | 否。                    |
| .setDocumentBackDrawable(int documentback_drawable, int documentback_width)    | 用于配置在 SDK 驾照和身份证背面采集屏幕上向用户显示的图片。参数 _documentback_drawable_ 应引用要显示的图片 ID，_documentback_width_ 是该图片的预期显示尺寸。    | 否。                    |
| .setButtonBorderSize(int border_size)                                          | 用于配置 SDK 按钮的边框宽度。                                                                                                                                                                                                                                     | 否。默认值为 _1_。    |
| .setButtonShadow(boolean button_shadow)                                        | 设置为 _false_ 时，移除 SDK 按钮使用的 Android 默认阴影效果。                                                                                                                                                                                                     | 否。默认值为 _true_。 |

## TextConfiguration 对象

| 参数                                                                      | 功能                                                                                                                                                                                                                                                              | 是否必填             |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| .setCustomText(CustomLabel label, String text) | 用于配置在 SDK 引导屏幕上向用户显示的文本| 否。|

---

# 收集返回值

URL: /zh-Hans/documentation/caas/ocr/android/collecting_response

要获取包含 SDK 采集结果的 **RequestResponseObject** 对象，请在启动 **DocumentRecognitionActivity** 的同一 *activity* 中覆盖 *onActivityResult* 方法：

```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");
            }
        }
    }
```

### RequestResponseObject 对象属性说明

属性 | 描述
--------- | ---------
ocr_key | 提供的图片标识密钥，可用于 QI Tech 系统的任何其他服务。

---

# DocumentDetectorStep

URL: /zh-Hans/documentation/caas/ocr/android/document_step

用户将执行的文档采集流程通过一个 **DocumentRecognitionStep**（SDK 中提供）类型对象的数组来定义，其中每个元素是用户执行的采集步骤之一。

```java
DocumentSteps = new DocumentRecognitionStep[]{
        new DocumentRecognitionStep(Document.cnh_front),
        new DocumentRecognitionStep(Document.cnh_back)
};
```

上面实现了一个流程，将首先从用户处采集其驾照正面（cnh_front），在验证采集到高质量照片后，采集驾照背面。

DocumentRecognitionStep 对象可以取以下值：

```java
public enum Document {
    cnh, // 巴西完整驾驶证
    cnh_front, // 巴西驾驶证正面（照片面）
    cnh_back, // 巴西驾驶证背面（签名面）
    cnh_digital, // 巴西数字驾驶证的 PDF
    rg_front, // 巴西身份证正面（照片面）
    rg_back, // 巴西身份证背面（数据面）
    proof_of_address, // 居住证明
    other // 其他身份证件
}
```

---

# 混合解决方案

URL: /zh-Hans/documentation/caas/ocr/android/hybrid_solutions

除了提供原生 Java 集成外，我们的 SDK 还兼容多种混合框架。这通过为每个框架集成特定的原生插件来实现。利用每种解决方案的原生系统，可以在 Android 环境中嵌入我们的原生 SDK。

一些最常用的混合技术包括 React Native（[Native Modules](https://reactnative.dev/docs/turbo-native-modules-introduction)）、Cordova（[Plugin Development Guide](https://cordova.apache.org/docs/en/latest/guide/hybrid/plugins/index.html)）、Ionic（[Native](https://ionicframework.com/docs/v3/native/)）、Unity（[Native Plug-in for Android](https://docs.unity3d.com/Manual/PluginsForAndroid.html)）、Xamarin（[Native Libraries](https://learn.microsoft.com/en-us/xamarin/android/platform/native-libraries)）、Appcelerator、Phonegap 和 Node。

为了简化与我们原生解决方案的集成过程，我们为 React Native 和 Flutter 框架提供了插件。如有兴趣，我们在私有存储库中提供文档和集成示例。对于其他混合技术，我们有一些实现这个与原生代码桥接的示例。欢迎联系我们的 支持团队 获取访问权限。

---

# DocumentDetectorStep

URL: /zh-Hans/documentation/caas/ocr/android/implementation_demo

以下代码是在 _activity_ 中正确实现 SDK 的参考示例：

```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 {
                // 用户关闭了 activity
            }
        }
        super.onActivityResult(requestCode, resultCode, data);
    }
}

```

---

# 简介

URL: /zh-Hans/documentation/caas/ocr/android/introduction

欢迎使用 QI Tech Android OCR（光学字符识别）文档读取 SDK。此 SDK 执行文档采集并将其发送到 QI Tech OCR API 。您可以使用它通过您的应用程序采集客户文档的图像（如驾驶证或身份证），并通过密钥在 QI Tech 系统的其他产品中引用。

## 遇到问题？

我们不是一个躲在 API 背后的公司！请联系我们的[支持团队](mailto:suporte.caas@qitech.com.br)，我们将尽快回复。如果您想要快速响应，也欢迎直接给我们打电话！

### 我们热爱反馈

即使您已经解决了问题，或者问题非常简单（哪怕只是一个拼写错误或您已经理解的组织问题），也请给我们发送电子邮件，这样我们可以让文档变得越来越实用，下一个人就不必经历您所经历的痛苦！

:::danger 重要提示！
不得在 QI Tech 的沙盒环境中使用真实的个人和/或法人数据。
:::

---

# 原生集成

URL: /zh-Hans/documentation/caas/ocr/android/native_java

要导入我们的 SDK，需要修改项目和应用程序的 _build.gradle_ 文件。

## 添加到项目

在项目的 _build.gradle_ 中添加我们的 Maven 仓库地址（在 Android Studio 中，该文件显示为：**"Project: \{project_name\}"**），如下例所示。

```java
buildscript {
    ...
}

allprojects {
    repositories {
        ...
        maven { url 'https://sdks.qitech.com.br/' }
    }
}
```

## 添加到应用程序

之后，在应用程序的 build.gradle 中添加您要导入的库（在 Android Studio 中，该文件显示为：**"Module: \{project_name\}.app"**），包含以下依赖项。

```java
android {
    ...
    packagingOptions {
        pickFirst '**/*.so'
    }
    ...
    splits {
        abi {
            enable true
            universalApk true
            reset()
            include 'armeabi-v7a', 'x86', 'x86_64', 'arm64-v8a'
        }
    }
}
...
dependencies {
    ...
    implementation 'com.qitech.android:documentrecognition:v5.0.0'
}
```

:::warning
自 **2025 年 4 月**起，Google Play 的新政策要求应用程序必须使用 **Android API Level 35** 才能在 Google Play Store 上发布或更新。因此，我们强烈建议至少使用 **targetSdkVersion 35**。
:::

:::info
使用 **targetSdkVersion 35** 意味着使用 **compileSdkVersion 35**，这对 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+
:::

## 启动 SDK

要将 SDK 嵌入到您的应用程序中，您必须通过 Builder 组件配置自定义采集应用程序，并通过 Intent Extra 作为参数提交给 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(DocumentRecognition.LogLevel.debug)
          .build();
  intent.putExtra("settings", mDocumentRecognition);
  startActivityForResult(intent, REQUEST_CODE);
```

我们使用 Mobile Token 来允许您的应用程序对我们的 API 进行认证访问。它可能已通过电子邮件发送给您。如果您尚未收到 token，请发送电子邮件至 suporte.caas@qitech.com.br 。

我们的 API 期望在所有来自 SDK 的请求中接收 Mobile Token，因此必须通过上述方法将其作为配置参数包含在内。

:::info **注意**

您必须将 "YOUR_MOBILE_TOKEN_SENT_BY_QITECH" 替换为从支持团队收到的 Mobile Token。
:::

## DocumentRecognition.Builder

| 参数 | 功能 | 是否必填 |
|------------|--------------|--------------|
|mobileToken |客户密钥，用于标识收集的数据来源于您的应用程序。如果尚未收到您的 mobile-token，请联系 suporte.caas@qitech.com.br。|是。|
|.setDocumentSteps(DocumentRecognitionStep[] documentSteps)|定义用户进行的文档采集流程。更多信息请[点击这里](/documentation/caas/ocr/android/document_step)|是。|
|.setSandboxEnvironment()|若在构造函数中使用此参数，库将配置为向沙盒环境发送数据。若不存在，请求将发送到生产环境。|否。|
|.showIntroductionScreens(Boolean showIntroductionScreens)|设置为 "false" 时，禁用向用户显示的文档照片采集介绍屏幕。|否。默认值为 "true"。|
|.setShowSuccessScreen(Boolean showSuccessScreen)|设置为 "false" 时，禁用照片采集后的成功屏幕。|否。默认值为 "true"。|
|.setBackgroundColor(String backgroundColor)|允许配置 SDK activities 的背景颜色。|否。默认值为 "#ffffff"。|
|.setFontColor(String fontColor)|允许配置 SDK activities 的字体和图标颜色。|否。默认值为 "#000000"。|
| .setFontFamily(FontFamily fontFamily)| 允许配置 SDK activities 的字体。| 否。若未指定，默认为 FontFamily.open_sans。可用字体：FontFamily.open_sans、FontFamily.futura、FontFamily.verdana、FontFamily.roboto、FontFamily.poppins 和 FontFamily.helvetica。|否。|
|.setVisualConfiguration(VisualConfiguration visualConfiguration)| 用于自定义 SDK 执行过程中向用户显示的图片。|否。|
|.setTextConfiguration(TextConfiguration textConfiguration) | 用于自定义 SDK 执行过程中向用户显示的引导屏幕上的文本。|否。|
|.setSessionId(String sessionId)| 用于设置标识 SDK 启动会话的密钥。用于通过日志跟踪用户在 OCR 执行过程中的完整流程。此字段最多接受 255 个字符。|否。|
|.setLogLevel(DocumentRecognition.LogLevel logLevel)| 用于自定义 SDK 日志的详细级别。可用级别：LogLevel.debug、LogLevel.info、LogLevel.warn、LogLevel.error 和 LogLevel.trace。默认为 LogLevel.debug。|否。|

## VisualConfiguration 对象

| 参数                                                                      | 功能                                                                                                                                                                                                                                                              | 是否必填             |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| .setOnboardingDrawable(int onboarding_drawable, int onboarding_width)          | 用于配置在 SDK 引导屏幕上向用户显示的图片。参数 _onboarding_drawable_ 应引用要显示的图片 ID，_onboarding_width_ 是该图片的预期显示尺寸。                       | 否。                    |
| .setDocumentFullDrawable(int documentfull_drawable, int documentfull_width)    | 用于配置在 SDK 完整驾照采集屏幕上向用户显示的图片。参数 _documentfull_drawable_ 应引用要显示的图片 ID，_documentfull_width_ 是该图片的预期显示尺寸。       | 否。                    |
| .setDocumentFrontDrawable(int documentfront_drawable, int documentfront_width) | 用于配置在 SDK 驾照和身份证正面采集屏幕上向用户显示的图片。参数 _documentfront_drawable_ 应引用要显示的图片 ID，_documentfront_width_ 是该图片的预期显示尺寸。 | 否。                    |
| .setDocumentBackDrawable(int documentback_drawable, int documentback_width)    | 用于配置在 SDK 驾照和身份证背面采集屏幕上向用户显示的图片。参数 _documentback_drawable_ 应引用要显示的图片 ID，_documentback_width_ 是该图片的预期显示尺寸。    | 否。                    |
| .setButtonBorderSize(int border_size)                                          | 用于配置 SDK 按钮的边框宽度。                                                                                                                                                                                                                                     | 否。默认值为 _1_。    |
| .setButtonShadow(boolean button_shadow)                                        | 设置为 _false_ 时，移除 SDK 按钮使用的 Android 默认阴影效果。                                                                                                                                                                                                     | 否。默认值为 _true_。 |

## TextConfiguration 对象

| 参数                                      | 功能                                                                                    | 是否必填 |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------- | ----------- |
| .setCustomText(CustomLabel label, String text) | 用于配置在 SDK 引导屏幕上向用户显示的文本 | 否。        |

---

# using_sdk

URL: /zh-Hans/documentation/caas/ocr/android/using_sdk

## 启动 SDK

要将 SDK 嵌入到您的应用程序中，您必须通过 Builder 组件配置自定义采集应用程序，并通过 Intent Extra 作为参数提交给 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);
```

我们使用 Mobile Token 来允许您的应用程序对我们的 API 进行认证访问。它可能已通过电子邮件发送给您。如果您尚未收到 token，请发送电子邮件至 suporte.caas@qitech.com.br 。

我们的 API 期望在所有来自 SDK 的请求中接收 Mobile Token，因此必须通过上述方法将其作为配置参数包含在内。

:::info **注意**

您必须将 "YOUR_MOBILE_TOKEN_SENT_BY_QITECH" 替换为从支持团队收到的 Mobile Token。
:::

---

# authentication

URL: /zh-Hans/documentation/caas/ocr/api/authentication

## 身份验证
> 要认证调用，请使用以下代码：

```shell
# 在 shell 中，只需在每个请求中添加适当的头部
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE_API_KEY"
```

> 将 API key 'EXAMPLE_API_KEY' 替换为您从我们的支持团队获取的密钥。

我们使用 API Key 来允许访问我们的 API。它可能已通过电子邮件发送给您。如果您尚未收到密钥，请发送电子邮件至 suporte.caas@qitech.com.br 。

我们的 API 期望在所有向服务器发送的请求中，在如下头部中接收 API Key：

`Authorization: EXAMPLE_API_KEY`

:::info **注意**

您必须将 EXAMPLE_API_KEY 替换为从支持团队收到的 API Key。
:::

---

# HTTP 状态码

URL: /zh-Hans/documentation/caas/ocr/api/http_status

所有 QI Tech API 均按照 RFC 7231 使用以下 HTTP 返回状态标准化：

HTTP 状态 | 含义 | 描述
---------- | ------- | ---------------------------------
400 | Bad Request | 发送的请求存在格式错误。大多数情况下，我们会在消息正文中返回错误位置的说明。
401 | Unauthorized | 身份验证出现问题，请检查 API Key 是否正确以及是否在正确的头部中，详见 身份验证 部分。
403 | Forbidden | 访问的端点仅供内部使用，此 API Key 不可用。
404 | Not Found | 使用所提供的密钥未找到请求的数据。当请求无效端点时也会返回此状态。
405 | Method Not Allowed | 使用的 HTTP 方法不适用于所使用的端点。
406 | Not Acceptable | 请求正文中发送的数据无效。通常，这意味着发送的数据不是有效的 JSON。
409 | Conflict | 请求 ID 对应于之前已处理的 ID。当向服务器发送重复请求时会返回此状态。
500 | Internal Server Error | 处理此请求时出现问题，遇到此错误时，我们的专家会自动收到通知并立即开始分析和解决。
503 | Service Unavailable | 您遇到了我们服务器基础设施的计划内或计划外停机。

---

# 简介

URL: /zh-Hans/documentation/caas/ocr/api/introduction

欢迎使用 QI Tech OCR（光学字符识别）文档读取 API。您可以使用此 API 发送要识别的文档图像（如驾驶证或身份证），并通过密钥在 QI Tech 系统的其他产品中引用。

## 遇到问题？

我们不是一个躲在 API 背后的公司！请联系我们的 支持团队 ，我们将尽快回复。如果您想要快速响应，也欢迎直接给我们打电话！

### 我们热爱反馈

即使您已经解决了问题，或者问题非常简单（哪怕只是一个拼写错误或您已经理解的组织问题），也请给我们发送电子邮件，这样我们可以让文档变得越来越实用，下一个人就不必经历您所经历的痛苦！

## 环境

我们为客户提供两个环境。API 的基础 URL 为：

* 生产环境 - `https://api.caas.qitech.app/ocr/`
* 沙盒环境 - `https://api.sandbox.caas.qitech.app/ocr/`

:::danger 重要提示！
不得在 QI Tech 的沙盒环境中使用真实的个人和/或法人数据。
:::

## 仅限 HTTPS

出于安全考虑，与 QI Tech API 的所有通信必须使用 HTTPS 进行。为避免因疏忽或其他原因进行 HTTP 调用，此服务器仅开放使用 TLS 1.2 通信的 443 端口。使用其他协议的调用将被自动拒绝。

## 身份验证
> 要认证调用，请使用以下代码：

```shell
# 在 shell 中，只需在每个请求中添加适当的头部
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE_API_KEY"
```

> 将 API key 'EXAMPLE_API_KEY' 替换为您从我们的支持团队获取的密钥。

我们使用 API Key 来允许访问我们的 API。它可能已通过电子邮件发送给您。如果您尚未收到密钥，请发送电子邮件至 suporte.caas@qitech.com.br 。

我们的 API 期望在所有向服务器发送的请求中，在如下头部中接收 API Key：

`Authorization: EXAMPLE_API_KEY`

:::info **注意**

您必须将 EXAMPLE_API_KEY 替换为从支持团队收到的 API Key。
:::

---

# quality

URL: /zh-Hans/documentation/caas/ocr/api/quality

## 图片质量验证

Request Body：无效图片情况

```json
    {
        "title": "document_quality",
        "description": "A imagem enviada não pode ser processada com êxito."
    }
```

在图片端点发送 POST 请求时，如果图片不足以进行验证，将返回 HTTP Status Code 400，如旁边示例所示。当文档不满足前面提到的图片要求时，也会返回 Status Code 400。

**注意 -** 还有其他原因会导致我们返回 400（均与无效数据相关）。只有 title 为 "document_quality" 的返回才是图片质量验证的结果，因此才应转达给用户。

---

# 发送文档

URL: /zh-Hans/documentation/caas/ocr/api/send_image

使用 `/image` 端点发送文档，如下所示。此端点将返回文档的 GUID（全局唯一标识符），之后可在 QI Tech 系统的其他服务中引用。

## 发送
要发送文档，只需通过 POST 方法以 JSON 格式将图片的 base64 代码发送至以下地址：

`https://api.caas.qitech.app/ocr/image`

Request Body

```json
  {
    "document_b64": "\<BASE64_IMAGE\>",
    "template": "cnh",
    "file_type": "jpeg"
  }
```

将您的文档 base64 代码替换占位符。

### 发送属性说明

属性 | 描述
--------- | ---------
document_b64 | 必填字段。以 base64 格式提交的待分析文档图片。
template | 必填字段。声明应用于图片分析的模板。
file_type | 可选字段。标识发送文件的格式，`jpeg` 或 `pdf`。如未提交，则默认值为 `jpeg`。

### 可用模板
目前，QI Tech 提供以下可用于 OCR 分析的模板。如果您所需的文档不在此列表中，请发送电子邮件至 suporte.caas@qitech.com.br 了解此功能实施的详细信息。

模板 | 描述
--------- | ---------
cnh | 完整的巴西国家驾驶执照。
cnh_front | 巴西国家驾驶执照正面（照片面）。
cnh_back | 巴西国家驾驶执照正面（签名面）。
cnh_digital | 巴西数字国家驾驶执照 PDF。
rg_front | 巴西身份证正面（照片面）。
rg_back | 巴西身份证背面（数据面）。
danfe | 电子发票辅助文档（NF-e）。
proof_of_address | 住址证明。
letter_of_attorney | 授予公司相关权限的授权书。
company_statute | 公司章程或合同。

## 图片
为确保执行分析的可靠性，客户拍照时需遵循以下规则：

* 从塑料袋中取出文档；
* 确保文档在照片中居中；
* 确保文档光线充足；
* 确保文档的所有数据清晰、可见且可读；
* 确保照片清晰可见。

## 图片要求
为使 API 正常运行，请注意以下参数。

* 图片必须为 JPEG 或 PDF 格式；
* 图片必须至少有 500 像素高和 500 像素宽；
* API 不支持手写文档的识别；
* 图片的最大大小根据所选格式而有所不同，遵循以下限制：

格式 | 最大支持大小
--------- | ---------
.JPEG | 3MB
.PNG | 10MB
.PDF | 30MB

## 响应
如果您的文档读取请求处理成功，将返回 HTTP status 200 和包含指向已发送文档的标识符的 JSON 对象。

Response Body

```json
    {
        "ocr_key": "f1c0d2e1-f950-4360-896d-36588e443fc9"
    }   
```

### 响应属性说明

属性 | 描述
--------- | ---------
ocr_key | 所提供图片的标识密钥，可用于 QI Tech 系统的任何其他服务。

## 文档恢复
> 图片恢复

```shell
    curl "https://api.caas.qitech.app/ocr/image/f4b5337a-7b50-406e-8c8e-7d0e77b5aa02/file" \
         -H "Authorization: EXAMPLE_API_KEY"
```

任何时候都可以恢复已发送的图片。只需向以下端点发送经适当身份验证的 **GET** 请求：

`https://api.caas.qitech.app/ocr/image/{image_key}/file`

其中 image_key 是发送图片时返回的值。

## 图片质量验证

Response Body：无效图片情况

```json
    {
        "title": "document_quality",
        "description": "A imagem enviada não pode ser processada com êxito."
    }
```

在图片端点发送 POST 请求时，如果图片不足以进行验证，将返回 HTTP Status Code 400，如旁边示例所示。当文档不满足前面提到的图片要求时，也会返回 Status Code 400。

**注意 -** 还有其他原因会导致我们返回 400（均与无效数据相关）。只有 title 为 "document_quality" 的返回才是图片质量验证的结果，因此才应转达给用户。

## 面部质量验证

图片质量验证**仅适用于包含面部的文档**，如 RG、CNH 和护照。当图片发送至系统时，如果被识别为以下类型之一，将**自动执行面部分析**：

- `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`

在此分析过程中，系统会验证图片中是否有**可见的面部**，并评估以下方面：

- 适当的光照（亮度）；
- 是否佩戴太阳镜等配件；
- 面部过近或过远；
- 图片中完全没有面部。

如果上述任一标准表明图片不合适，将返回 `title: "face_validation"` 的错误和相应的 `description`，详情如下。

```json
{
    "title": "face_validation",
    "description": "<错误代码>"
}
```

### 返回示例：

**未检测到面部**

```json
{
    "title": "face_validation",
    "description": "no_faces"
}
```

---

### 向用户显示消息的翻译表

| 错误代码（`description`） | 友好提示信息 |
|-------------------------------|-------------------|
| `close_face`                  | 图片拍摄时距离面部过近，请重新定位文档。 |
| `distant_face`                | 图片拍摄时距离面部过远，请重新定位文档。 |
| `wearing_acessories`          | 图片中的人佩戴了太阳镜或遮住眼睛的配件。 |
| `brightness_problem`          | 图片太暗，请在更充足的光线下重新发送。 |
| `no_faces`                    | 无法在图片中检测到面部，请确认面部是否可见。 |

---

# 收集返回值

URL: /zh-Hans/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) {

    }
}
```
要获取 SDK 的响应，您需要在 controller 中实现 **QITechIosOcrControllerDelegate** 委托，如旁边示例所示。

## QITechIosOcrControllerResponse

**QITechIosOcrControllerResponse** 类用于接收 QI Tech SDK 的响应。

下表详细列出了此类的所有属性：

名称 | 类型 | 描述 
---- | :----: | --------- 
OcrResponses | OcrResponse 列表 | 标识

## OcrResponse 对象

名称 | 类型 | 描述 
---- | :----: | --------- 
OcrKey | string | QI Tech 中图片的唯一标识符。您必须存储此标识符，以便在执行验证的 QI Tech API 中发送（例如：Onboarding API）
DocumentTemplate | QITechIosOcrDocumentTemplate | 标识该 OCR Key 对应照片的枚举值。

**QITechIosOcrDocumentTemplate** 枚举的可能值为：

* `QITechIosOcrDocumentTemplate.CnhFull` - 标识完整 CNH 验证的结果。
* `QITechIosOcrDocumentTemplate.CnhFront` - 标识 CNH 正面验证的结果。
* `QITechIosOcrDocumentTemplate.CnhBack` - 标识 CNH 背面验证的结果。
* `QITechIosOcrDocumentTemplate.RgFront` - 标识 RG 正面验证的结果。
* `QITechIosOcrDocumentTemplate.RgBack` - 标识 RG 背面验证的结果。
* `QITechIosOcrDocumentTemplate.NationalRegistryOfForeignersFront` - 标识外国人国家登记证正面验证的结果。
* `QITechIosOcrDocumentTemplate.NationalRegistryOfForeignersBack` - 标识外国人国家登记证背面验证的结果。

## QITechIosOcrControllerError

**QITechIosOcrControllerError** 类在出现导致 SDK 终止的错误时触发。发生此情况时，QI Tech 将返回一个子类，其名称对应于导致 SDK 终止的错误，如下表所示：

类 | 描述 
---- | --------- 
InvalidMobileToken | 配置中发送的 MobileToken 无效。
MissingPermission | 验证所需的某些权限不足。
NetworkFailure | 用户在验证过程中失去了互联网连接。
ServerFailure | QI Tech 服务器向 SDK 返回了错误响应。
MissingStorage | 用户设备没有足够的存储空间进行图片采集。
LowImageQuality | 由于某种原因，采集的图片质量不足以进行验证。

要确定是哪个子类（即错误原因），请使用 Swift 的 *isKindOfClass()* 方法。

---

# QITechIosOcrConfiguration

URL: /zh-Hans/documentation/caas/ocr/ios/configuration

```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)

```

**QITechIosOcrConfiguration** 类用于配置环境、凭证、视觉和文本方面，以及文档图片采集流程，即 SDK 个性化和运行所需的所有配置。

下表详细列出了实例化时需使用的所有参数：

| 名称                    |          类型          | 描述                                                                                                                                                                                                                              |
| ----------------------- | :--------------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| environment             | QITechIosOcrEnvironment  | _（必填）_ 描述环境的枚举值。                                                                                                                                                                                                      |
| mobileToken             |         string         | _（必填）_ QI Tech 发送的用于 SDK 身份验证的 Token。                                                                                                                                                                               |
| sessionId               |         string         | _（可选）_ 用于通过日志跟踪用户在 OCR 执行过程中所经历的完整流程的唯一 ID。此字段最多接受 255 个字符。                                                                                                                             |
| documentSteps           | QITechIosOcrDocumentFlow | _（必填）_ 描述将遵循的验证流程的枚举值，定义将采集的文档及图片采集顺序。                                                                                                                                                         |
| backgroundColor         |         string         | _（可选）_ 界面背景色的十六进制值。如未提供，默认值为 #FFFFFF。                                                                                                                                                                    |
| fontColor               |         string         | _（可选）_ 字体颜色的十六进制值。如未提供，默认值为 #000000。                                                                                                                                                                      |
| fontFamily              |       FontFamily       | _（可选）_ 字体系列。如未提供，默认值为 .open_sans。可用字体：.open_sans、.futura、.verdana、.trebuchetms、.tamilsangammn 和 .system_font。                                                                                          |
| showIntroductionScreens |        boolean         | _（可选）_ 表示是否应显示介绍界面（包含照片拍摄说明）的标志。如未提供，默认值为 _true_。                                                                                                                                            |
| showSuccessScreen       |        boolean         | _（可选）_ 表示是否应显示成功界面（包含采集成功消息）的标志。如未提供，默认值为 _true_。                                                                                                                                            |
| logLevel                |        LogLevel        | _（可选）_ 用于自定义 SDK 日志详细程度级别。可用级别：LogLevel.debug、LogLevel.info、LogLevel.warn、LogLevel.error 和 LogLevel.trace。如未提供，默认值为 LogLevel.debug。 |

下表列出了实例接受的所有配置方法：

| 方法                   |                              参数                               | 描述                                                                                     |
| ---------------------- | :-------------------------------------------------------------: | ---------------------------------------------------------------------------------------- |
| setVisualConfiguration | visualConfiguration : VisualConfiguration | _（可选）_ 允许修改 SDK 执行过程中显示的图片的类； |
| setTextConfiguration   |                textConfiguration : TextConfiguration           | _（可选）_ 允许修改 SDK 执行过程中显示的文本的类；  |

---

# 混合解决方案

URL: /zh-Hans/documentation/caas/ocr/ios/hybrid_solutions

除了提供 Swift 原生集成外，我们的 SDK 还与多种混合框架兼容。这通过集成每个框架的特定原生插件来实现。利用每种解决方案的原生系统，可以在 iOS 环境中集成我们的原生 SDK。

一些最常用的混合技术包括 React Native（[Native Modules](https://reactnative.dev/docs/turbo-native-modules-introduction)）、Cordova（[Plugin Development Guide](https://cordova.apache.org/docs/en/latest/guide/hybrid/plugins/index.html)）、Ionic（[Native](https://ionicframework.com/docs/v3/native/)）、Unity（[Native Plug-in para Android](https://docs.unity3d.com/Manual/PluginsForAndroid.html)）、Xamarin（[Native Libraries](https://learn.microsoft.com/en-us/xamarin/android/platform/native-libraries)）、Appcelerator、Phonegap 和 Node。

为方便与我们原生解决方案的集成过程，我们为 React Native 和 Flutter 框架提供了插件。如有需要，我们在私有存储库中提供文档和集成示例。对于其他混合技术，我们有一些将其桥接到原生代码的实现示例。欢迎联系我们的 支持团队 获取访问权限。

---

# 简介

URL: /zh-Hans/documentation/caas/ocr/ios/introduction

欢迎使用 QI Tech iOS OCR（光学字符识别）文档读取 SDK。此 SDK 可采集文档并将其发送至 QI Tech OCR API 。您可以使用它通过您的应用采集客户文档图片（如驾驶执照或身份证）进行识别，并通过密钥在 QI Tech 系统的其他产品中引用。

## 遇到问题？

我们不是一个躲在 API 背后的公司！请联系我们的[支持团队](mailto:suporte.caas@qitech.com.br)，我们将尽快回复。如果您想要快速响应，也欢迎直接给我们打电话！

### 我们热爱反馈

即使您已经解决了问题，或者问题非常简单（哪怕只是一个拼写错误或您已经理解的组织问题），也请给我们发送电子邮件，这样我们可以让文档变得越来越实用，下一个人就不必经历您所经历的痛苦！

:::danger 重要提示！
不得在 QI Tech 的沙盒环境中使用真实的个人和/或法人数据。
:::

---

# 导入 SDK

URL: /zh-Hans/documentation/caas/ocr/ios/native_swift

## 远程方式

> 开始安装

```shell
  pod init
```

我们的 SDK 可使用 CocoaPods 导入。

| SDK        | 当前版本                       |
| ---------- | ------------------------------ |
| QITechIosOCR | `pod 'QITechIosOCR', '~> 8.0.0'` |

:::info iOS Minimum Deployment Target
15.5
:::

:::danger 在搭载 arm64 芯片的 MacBook 上使用模拟器
目前，我们的 iOS OCR SDK 不幸不支持在搭载 **arm64 架构芯片**（M1/M2/M3/M4）的 MacBook 上运行的模拟器中编译，**除非使用 Rosetta**，它能将 x86_64 架构转换为 arm64。
:::

要开始安装，请在您的项目根目录运行旁边的命令。

> 在 podfile 中添加 source

```ruby
   source 'https://github.com/QITechSDKs/iOS.git'
```

下一步是在 `podfile` 文件中添加 QI Tech 的 source。

> 在 podfile 中添加 pod

```ruby
  pod 'QITechIosOCR', '~> <version>'
```

最后，只需按照旁边的格式添加 `pod` 名称。

:::danger 注意：
架构变更（v6.0.0+）从 6.0.0 版本开始，SDK 改为仅以静态方式分发。在您的 Podfile 中，必须使用配置 :linkage => :static。
:::

> podfile 示例（6.0.0 或更高版本）

```ruby
  source 'https://github.com/QITechSDKs/iOS.git'
  source 'https://cdn.cocoapods.org/'
  target 'ExampleApp' do
    use_frameworks! :linkage => :static
    pod 'QITechIosOCR', '~> 8.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'] = '12.0'
          config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
        end
      end
    end
  end
```

> podfile 示例（早期版本）

```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'] = '12.0'
          config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
        end
      end
    end
  end
```

:::warning 注意
在 iOS 中集成依赖项时，可能需要对某些库使用静态链接，对其他库使用动态链接。此配置对于确保兼容性、避免构建错误和优化项目性能至关重要。
:::

### 混合依赖链接（如有必要）
混合链接的需求源于某些库有特定要求：一些库需要静态链接以避免内部冲突和符号重复，而另一些依赖项可能需要动态链接，因为它们是为模块化和项目间共享而设计的。

静态链接与动态链接的区别
* 静态（static_framework）：库代码直接嵌入到最终二进制文件中，减少运行时加载时间，并消除执行期间的外部依赖。
* 动态（dynamic_framework）：库在运行时作为单独文件加载。这减少了最终二进制文件的大小，并便于独立更新/修改。

> 在 Podfile 中配置混合链接

```ruby
...

use_frameworks! :linkage => :dynamic # 将默认链接模式配置为动态

...

static_frameworks = ['framework_1', 'framework_2', ...] # 包含所有需要静态链接的依赖项
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
```

> 安装依赖项

```shell
  pod install
```

最后，执行 `pod install` 命令下载并安装依赖项。

## 必要权限

为使 SDK 能够访问设备资源以采集照片，需要向用户请求权限。

在 **info.plist** 文件中，添加以下权限：

| 权限                               | 原因                                     |
| ---------------------------------- | ---------------------------------------- |
| Privacy - Camera Usage Description | 访问摄像头以采集文档照片。 |

## 启动 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' ou 'RgFrontAndBack'
        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) {

    }
}
```

要将 SDK 嵌入您的应用，需要通过 **QITechIosOcrConfiguration** 类配置自定义采集应用，然后将自定义配置作为参数实例化 **ViewController QITechIosOcrController**。

要启动文档分析流程，只需调用 _present_ 函数来调用 QI Tech 的 ViewController 进行图片采集。

重要的是实现 _Delegate_，负责在成功、错误或用户在验证的任何步骤中断流程时接收返回值。

旁边提供了完整的实现示例。

:::info **注意**

在您的应用中启用 _Portrait_ 和 _Landscape Right_ 方向支持，以确保 SDK 正常运行。
:::

## Mobile Token

我们使用 Mobile Token 允许您的应用对我们的 API 进行身份验证访问。它可能已通过电子邮件发送给您。如果您尚未收到 Token，请发送电子邮件至 suporte.caas@qitech.com.br 。

我们的 API 期望在所有来自 SDK 的服务器请求中接收 Mobile Token，因此必须通过前面提到的方法将其作为配置参数必选包含。

:::info **注意**

您必须将 "YOUR_MOBILE_TOKEN_SENT_BY_QITECH" 替换为从支持团队收到的 Mobile Token。
:::

---

# necessary_permissions

URL: /zh-Hans/documentation/caas/ocr/ios/necessary_permissions

## 必要权限

为使 SDK 能够访问设备资源以采集照片，需要向用户请求权限。

在 **info.plist** 文件中，添加以下权限：

| 权限                               | 原因                                     |
| ---------------------------------- | ---------------------------------------- |
| Privacy - Camera Usage Description | 访问摄像头以采集文档照片。 |

---

# 导入 SDK

URL: /zh-Hans/documentation/caas/ocr/ios/using_sdk

## 远程方式

> 开始安装

```shell
  pod init
```

我们的 SDK 可使用 CocoaPods 导入。

| SDK        | 当前版本                       |
| ---------- | ------------------------------ |
| QITechIosOCR | `pod 'QITechIosOCR', '~> 8.0.0'` |

要开始安装，请在您的项目根目录运行旁边的命令。

> 在 podfile 中添加 source

```ruby
   source 'https://github.com/QITechSDKs/iOS.git'
```

下一步是在 `podfile` 文件中添加 QI Tech 的 source。

> 在 podfile 中添加 pod

```ruby
  pod 'QITechIosOCR', '~> <version>'
```

最后，只需按照旁边的格式添加 `pod` 名称。

> podfile 示例

```ruby
  source 'https://github.com/QITechSDKs/iOS.git'
  source 'https://cdn.cocoapods.org/'
  target 'ExampleApp' do
    use_frameworks!
    pod 'QITechIosOCR', '~> 8.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'] = '12.0'
          config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
        end
      end
    end
  end
```

:::warning 注意
在 iOS 中集成依赖项时，可能需要对某些库使用静态链接，对其他库使用动态链接。此配置对于确保兼容性、避免构建错误和优化项目性能至关重要。
:::

### 混合依赖链接（如有必要）
混合链接的需求源于某些库有特定要求：一些库需要静态链接以避免内部冲突和符号重复，而另一些依赖项可能需要动态链接，因为它们是为模块化和项目间共享而设计的。

静态链接与动态链接的区别
* 静态（static_framework）：库代码直接嵌入到最终二进制文件中，减少运行时加载时间，并消除执行期间的外部依赖。
* 动态（dynamic_framework）：库在运行时作为单独文件加载。这减少了最终二进制文件的大小，并便于独立更新/修改。

> 在 Podfile 中配置混合链接

```ruby
...

use_frameworks! :linkage => :dynamic # 将默认链接模式配置为动态

...

static_frameworks = ['framework_1', 'framework_2', ...] # 包含所有需要静态链接的依赖项
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
```

> 安装依赖项

```shell
  pod install
```

最后，执行 `pod install` 命令下载并安装依赖项。

## 必要权限

为使 SDK 能够访问设备资源以采集照片，需要向用户请求权限。

在 **info.plist** 文件中，添加以下权限：

| 权限                               | 原因                                     |
| ---------------------------------- | ---------------------------------------- |
| Privacy - Camera Usage Description | 访问摄像头以采集文档照片。 |

## 启动 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' ou 'RgFrontAndBack'
        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) {

    }
}
```

要将 SDK 嵌入您的应用，需要通过 **QITechIosOcrConfiguration** 类配置自定义采集应用，然后将自定义配置作为参数实例化 **ViewController QITechIosOcrController**。

要启动文档分析流程，只需调用 _present_ 函数来调用 QI Tech 的 ViewController 进行图片采集。

重要的是实现 _Delegate_，负责在成功、错误或用户在验证的任何步骤中断流程时接收返回值。

旁边提供了完整的实现示例。

:::info **注意**

在您的应用中启用 _Portrait_ 和 _Landscape Right_ 方向支持，以确保 SDK 正常运行。
:::

## Mobile Token

我们使用 Mobile Token 允许您的应用对我们的 API 进行身份验证访问。它可能已通过电子邮件发送给您。如果您尚未收到 Token，请发送电子邮件至 suporte.caas@qitech.com.br 。

我们的 API 期望在所有来自 SDK 的服务器请求中接收 Mobile Token，因此必须通过前面提到的方法将其作为配置参数必选包含。

:::info **注意**

您必须将 "YOUR_MOBILE_TOKEN_SENT_BY_QITECH" 替换为从支持团队收到的 Mobile Token。
:::

---

# 收集返回值

URL: /zh-Hans/documentation/caas/ocr/web/collecting_results

Web OCR SDK 返回一个 _Promise_，成功时将返回包含所选文档采集信息的对象，出错时将返回包含错误描述的 **String**。以下是如何映射每种情况并获取其结果的示例：

```html
<script>
    webOCR.initialize(document_type)
    .then((ocr_key) => {
        console.log(ocr_key)
    })
    .catch((error) => {
        console.log(error)
    })
</script>
```

## Web OCR 返回值说明

属性 | 类型 | 描述
--------- | --------- | --------- 
ocr_info | Object | 包含所选文档采集信息的成功对象。
error | String | 包含错误描述的字符串（如发生错误）

### 成功对象的属性

属性 | 类型 | 描述
--------- | --------- | ---------
ocr_key | String | 已采集文档图片的标识密钥，可用于 QI Tech 系统的任何其他服务。
template | String| 已采集文档的类型

### 错误类型

错误 | 描述
--------- | ---------
Invalid Web Token! Please verify your Web Token. | 使用的 Web Token 无效。如果您确定正确使用了 QI Tech 提供的 Web Token，请立即联系我们的支持团队（suporte.caas@qitech.com.br）。
Invalid Document Type! Please provide a valid document type. | 传递给 **WebOCR.initialize()** 函数的文档类型无效。请在 [initialize 函数](./initialize_info.md)页面查看允许的文档类型。
User left Web OCR. | 用户在完成文档提交之前退出了 Web OCR SDK。

---

# QiTechWebOCR.WebOCR() 构造函数

URL: /zh-Hans/documentation/caas/ocr/web/constructor_info

.WebOCR 方法负责配置您的文档检查组件实例。此方法具有以下配置选项。

| 名称 | 描述 | 必填 |
|----------|----------|----------|
| htmlComponent | 将承载 SDK HTML 的父 HTML 组件。 | 是 |
| webToken | 标识所收集数据来自您应用的客户密钥。如果您尚未收到 web-token，请联系<a href='mailto:suporte.caas@qitech.com.br'>支持团队</a>。 | 是 |
| sessionId | 用于定义在 SDK 中启动会话的标识密钥。用于通过日志跟踪用户在 Web OCR 执行过程中的完整流程。此字段接受最多 255 个字符的字符串。每个会话必须唯一。 | 是 |
| .setThemeConfiguration(object) | 用于自定义 WebOCR 元素组件视觉标识的方法。 | 否 |
| .setShowInstructionScreen(boolean) | 用于渲染带有所选文档采集提示的介绍界面的方法。接受 true 或 false。如未使用，默认值为 true。 | 否 |
| .setShowSuccessScreen(boolean) | 用于在采集流程结束时渲染成功界面的方法。接受 true 或 false。如未使用，默认值为 true。 | 否 |
| .setSandboxEnvironment() | 用于将环境配置为沙盒模式的方法。如未使用，默认值为 Production。 | 否 |

.setThemeConfiguration 方法应接受包含以下字段的对象：

| 名称 | 类型 | 描述 |
| -------- | -------- | -------- |
| companyLogo | String | _（推荐）_ 您公司徽标资源的路径或**公开 URL**（**PNG**）。如未提供，默认为占位符。 |
| buttonColor | String | _（推荐）_ 界面按钮颜色的十六进制值。如未提供，默认为 #1C49AD。 |
| fontColor | String | _（推荐）_ 界面显示文本颜色的十六进制值。如未提供，默认为 #FCFCFC。 |
| backgroundColor | String | _（推荐）_ 界面背景颜色的十六进制值。如未提供，默认为 #1C49AD。 |
| fontFamily | String | _（推荐）_ 要配置到 SDK 文本中的 _Font Family_ 名称。如未提供，将配置默认字体。 |

---

# 实现

URL: /zh-Hans/documentation/caas/ocr/web/example

Web OCR SDK 的初始化通过调用属于 `WebOCR` 类的 `.initialize()` 函数来完成，该类包含在我们的 `QiTechWebOCR` 库中。流程分为两个主要步骤：

1. 配置与实例化：准备和配置 SDK 实例。

2. 采集初始化：为最终用户启动文档采集流程。

以下是一个完整示例，展示如何实例化和初始化 SDK，以及每个步骤的详细说明。

## 完整示例：

```html
<script>
    var htmlComponent = document.getElementById('webOCR')
    var webOCR = new QiTechWebOCR.WebOCR(
        htmlComponent,
        "<WEB_TOKEN>",
        "<SESSION_ID>"
    )
    .setThemeConfiguration(
        {
            "companyLogo": "<PATH_OR_URL_TO_YOUR_COMPANY_LOGO>",
            "backgroundColor": "<BACKGROUND_COLOR_HEX>",
            "fontColor": "<FONT_COLOR_HEX>",
            "buttonColor": "<BUTTON_COLOR_HEX>",
            "fontFamily": "<FONT_FAMILY>"
        }
    )
    .setShowInstructionScreen(true)
    .setShowSuccessScreen(true)
    .setShowAllowedTemplatesScreen(false)
    .setSandboxEnvironment()
    .build()

    function initOCR(document_types) {
        webOCR.initialize(document_types)
        .then((ocr_key) => {
            console.log(ocr_key)
        })
        .catch((error) => {
            console.log(error)
        })
    }

    initOCR(['cnh', 'rg', 'cnh_digital'])

</script>
```

## 配置与实例化：

首先，创建 WebOCR 类的新实例。构造函数需要三个必填参数，必须按照下面指定的确切顺序传递：

- htmlComponent（String）：您的 DOM 中 SDK 将渲染的 HTML 元素的 id。

- webToken（String）：您的 API 使用身份验证 Token。

- sessionId（String）：用户会话的唯一标识符。

### 自定义（可选）

创建实例后，您可以使用以下链式方法来自定义用户体验，使 SDK 的外观与您的应用相符。`setShow...` 方法允许您决定使用我们 SDK 的默认界面还是实现您自己的界面和指示流程。

- `setThemeConfiguration`（object）：允许自定义 SDK 外观。此方法接受包含以下键的对象：

    - `companyLogo`（String）：您公司徽标的 URL 或路径。

    - `backgroundColor`（String）：十六进制格式的背景颜色（例如：'#FFFFFF'）。

    - `fontColor`（String）：十六进制格式的字体颜色（例如：'#000000'）。

    - `buttonColor`（String）：十六进制格式的按钮颜色（例如：'#0000FF'）。

    - `fontFamily`（String）：要使用的字体系列（例如：'Arial'）。

- `setShowInstructionScreen`（boolean）：定义是否显示初始指示界面。

- `setShowAllowedTemplateScreen`（boolean）：定义是否显示告知可接受文档的界面。我们建议启用此功能或实现此界面的自定义版本，以便用户知道可以提交哪些文档。

- `setShowSuccessScreen`（boolean）：定义是否在采集结束时显示成功界面。

- `setSandboxEnvironment`：将 SDK 配置为指向沙盒（Sandbox）环境。在测试期间使用此方法。

### 构建

最后，您**必须**调用 **build()** 函数，以使用传入的配置实例化 **WebOCR** 类。有关构造函数的更多信息和详细信息，请参阅[构造函数](./constructor_info.md)页面。

## 初始化文档采集

正确配置 WebOCR 实例后，调用 `initialize()` 方法启动采集流程。此方法接受一个字符串数组作为参数，其中每个字符串代表用户可以提交的文档类型。如果用户尝试提交不在列表中的文档，将显示错误消息，指示其使用有效文档重试。要允许提交未列出的其他文档，请在列表中包含字符串 'others'。

### 可接受模板表：

名称 | 类型 | 描述
---- | ---- | ---------
cnh | String | 采集实体 CNH（折叠），分两步，正面和背面
rg | String | 采集实体 RG（折叠），分两步，正面和背面
cin_digital | String | 提交由官方应用生成的**数字** RG 或数字国家身份证（CIN）（pdf）
rne | String | 采集实体 RNE，分两步，正面和背面
crnm | String | 采集实体 CRNM，分两步，正面和背面
others | String | 用于允许提交上述以外的其他文档

:::caution 注意
在允许的模板中添加 `others` 类型会使所有提交的文档都被接受。因此，即使是非官方文档也会被接受。
:::

### 返回值处理

`initialize()` 方法返回一个 Promise：

 - 成功：在流程结束时，Promise 将被解析，返回包含 `ocr_keys` 属性的对象。此属性是已采集图片的密钥（ocr_key）列表。

 - 错误：如果流程中发生任何错误，Promise 将被拒绝。您可以使用 `.catch()` 方法捕获这些错误。

有关更多详细信息，请参阅 `initialize()` 函数页面。

[函数](./initialize_info.md)。

---

# 导入库

URL: /zh-Hans/documentation/caas/ocr/web/import

要导入我们的库，请在您网站 HTML 中的 **script** 标签的 _src_ 中添加 URL，如下例所示：

```html
    <script src="https://ocr.caas.qitech.app/4-1-1/ocr.js"></script>
```

---

# initialize() 函数

URL: /zh-Hans/documentation/caas/ocr/web/initialize_info

要启动 Web OCR SDK，在实例化 **WebOCR** 类后，只需调用 **initialize()** 函数，并传入允许的文档列表作为参数。

以下是每种可能文档类型的详细说明：

名称 | 类型 | 描述
---- | ---- | ---------
cnh | String | 采集实体 CNH（折叠），分两步，正面和背面
rg | String | 采集实体 RG（折叠），分两步，正面和背面
cin_digital | String | 提交由官方应用生成的**数字**国家身份证（CIN）（pdf）
rg_digital | String | 提交由官方应用生成的**数字** RG（pdf）
national_registry_of_foreigners | String | 采集实体 RNE，分两步，正面和背面
national_migration_registry | String | 采集实体 CRNM，分两步，正面和背面
others | String | 用于允许提交上述以外的其他文档

:::caution 注意
在允许的模板中添加 `others` 类型会使所有提交的文档都被接受。因此，即使是非官方文档也会被接受。
:::

## 实现示例
Web OCR SDK 的实现示例如下：

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <link rel="icon" type="image/x-icon" href="/public/favicon.ico">
    <link rel="stylesheet" href="./demo-styles.css">
    <title>Web OCR</title>
    <script src="https://ocr.caas.qitech.app/4-1-1/ocr.js"></script>
</head>
<body>
    <div id="webOCR"></div>
    <div class="demo-app-container">
        <p>
        Agora vamos coletar imagens do seu documento.
        </p>
        <div class="personalDocumentTypesContainer">
            <div class="personalDocumentTypes" onclick="initOCR(['rg', 'cnh', 'rg_digital', 'cnh_digital']);">
                <p>Iniciar coleta do documento</p>
                <img src="./images/personal-document-icon.png" style="width: 100px;">
            </div>
        </div>
    </div>
</body>

<script>
    var htmlComponent = document.getElementById('webOCR')
    var webOCR = new QiTechWebOCR.WebOCR(
        htmlComponent,
        "<WEB_TOKEN>",
        "<SESSION_ID>"
    )
    .setThemeConfiguration(
        {
            "companyLogo": "https://my_company/logo.png",
            "backgroundColor": "#FF9900",
            "fontColor": "#FFFFFF",
            "buttonColor": "#146EB4",
            "fontFamily": "Verdana"
        }
    )
    .setShowInstructionScreen(true)
    .setShowSuccessScreen(true)
    .setShowAllowedTemplatesScreen(true)
    .setSandboxEnvironment()
    .build()

    function initOCR(document_type) {
        webOCR.initialize(document_type)
        .then((ocr_key) => {
            console.log(ocr_key)
        })
        .catch((error) => {
            console.log(error)
        })
    }
</script>
</html>
```

在上述示例中，首先实例化 **WebOCR** 类，传入所有必填和可选参数以自定义 SDK 外观。SDK 实例化后，创建了一个名为 **initOCR()** 的辅助函数，它使用 **initialize()** 函数初始化 SDK，并在文档采集流程结束时记录返回的 **ocr_key** 或错误（如发生）。此函数被分配为按钮的 onClick 回调，允许通过单击按钮为所需文档初始化 SDK。

---

# 简介

URL: /zh-Hans/documentation/caas/ocr/web/introduction

欢迎使用 QI Tech 文档读取 Web OCR SDK（光学字符识别）。此 SDK 可采集文档并将其发送至 QI Tech OCR API 。您可以使用它通过您的 Web 应用采集客户文档图片（如驾驶执照或身份证）进行识别，并通过密钥在 QI Tech 系统的其他产品中引用。

## 遇到问题？

我们不是一个躲在 API 背后的公司！请联系我们的[支持团队](mailto:suporte.caas@qitech.com.br)，我们将尽快回复。如果您想要快速响应，也欢迎直接给我们打电话！

### 我们热爱反馈

即使您已经解决了问题，或者问题非常简单（哪怕只是一个拼写错误或您已经理解的组织问题），也请给我们发送电子邮件，这样我们可以让文档变得越来越实用，下一个人就不必经历您所经历的痛苦！

:::danger 重要提示！
不得在 QI Tech 的沙盒环境中使用真实的个人和/或法人数据。
:::

---

# 认证

URL: /zh-Hans/documentation/caas/onboarding/authentication

> 要对调用进行认证，请使用以下代码：

```shell
# No shell, você somente precisa adicionar o header adequado em cada requisição
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE-OF-API-KEY"
```

> 请将 API Key 'EXAMPLE-OF-API-KEY' 替换为您的密钥，该密钥应通过我们的支持团队获取。

我们使用 API Key 来允许访问我们的 API。它可能已通过电子邮件发送给您。如果您尚未收到密钥，请发送邮件至 suporte.caas@qitech.com.br 。

我们的 API 期望在所有向服务器发出的请求中，以如下 header 的形式接收 API Key：

`Authorization: EXAMPLE-OF-API-KEY`

:::info **注意**

您必须将 EXAMPLE-OF-API-KEY 替换为您的密钥，该密钥应通过我们的支持团队获取。
:::

---

# HTTP 状态码

URL: /zh-Hans/documentation/caas/onboarding/http_status

QI Tech 的所有 API 均使用以下 HTTP 返回状态标准，遵循 RFC 7231 ：

HTTP 状态码 | 含义 | 描述
---------- | ------- | ---------------------------------
400 | Bad Request | 发送的请求存在格式错误。在大多数情况下，我们会在消息正文中返回错误说明。
401 | Unauthorized | 认证过程中出现问题，请检查 API Key 是否正确以及是否放在正确的 header 中，参见 认证 章节。
403 | Forbidden | 访问的端点为内部使用，该 API Key 无法使用。
404 | Not Found | 使用该密钥未找到所请求的数据。当请求无效端点时也会返回此状态。
405 | Method Not Allowed | 使用的 HTTP 方法不适用于所使用的端点。
406 | Not Acceptable | 请求正文中发送的数据无效。通常这意味着发送的数据不是有效的 JSON。
409 | Conflict | 请求的 id 与之前已处理的 id 相符。当向服务器发送重复请求时返回此状态。
500 | Internal Server Error | 我们在处理此请求时遇到了问题，发现此错误后，我们的专家将自动收到通知并立即开始分析和解决。
503 | Service Unavailable | 您遇到了我们服务器基础设施的计划内或计划外停机。

---

# 集成

URL: /zh-Hans/documentation/caas/onboarding/integrations

我们的移动端解决方案兼容多种技术，例如 Flutter、Ionic Cordova、Capacitor、React Native、Java、Swift 等。如果您对其中某种集成方式感兴趣，请联系我们的 支持团队 ，以便我们开放私有仓库的访问权限。

---

# 简介

URL: /zh-Hans/documentation/caas/onboarding/introduction

欢迎使用 QI Tech Onboarding API！该 API 可让您访问反欺诈、反洗钱以及 KYC 服务，将其集成到您平台的注册流程中！

该 API 可用于以下场景的客户注册验证：

* 数字账户或钱包开户
* 卡片发行
* 应用程序用户验证
* 信用授予注册
* 保险合同注册
* 注册数据验证

您可以使用我们的 API 访问端点来评估以下类型的注册：

* **Natural Person** - 用于自然人的注册验证
* **Legal Person** - 用于法人的注册验证

上述不同类型的注册各有其专属对象和端点，以涵盖每种实体的特殊性。

## 遇到问题？

我们不是一家躲在 API 背后的公司！请联系我们的 支持团队 ，我们将尽快回复。如果您需要快速响应，欢迎直接致电！

### 我们热爱反馈

即便您已经解决了问题，或者问题非常简单（哪怕只是发现了一个错别字或不合理的组织结构），也请发送邮件告知我们，这样我们可以不断完善文档，让下一个人不必重蹈覆辙！

## 环境

我们为客户提供两个环境。API 的基础 URL 分别为：

* 生产环境 - `https://api.caas.qitech.app/onboarding/`
* 沙盒环境 - `https://api.sandbox.caas.qitech.app/onboarding/`

:::danger 重要提示！
请勿在 QI Tech 的沙盒环境中使用真实的自然人和/或法人数据。
:::

在沙盒环境中，提交的分析不收费，并根据以下规则响应——规则基于文件号码的第一位数字（自然人使用 CPF，法人使用 CNPJ）：

数字 | 决策
------ | -------
0 | 进入人工审核
1 | 进入人工审核
2 | 进入人工审核
3 | 进入人工审核
4 | 自动拒绝
5 | 转至人工审核 - 随后拒绝
6 | 转至人工审核 - 随后批准
7 | 待处理
8 | 自动拒绝
9 | 自动批准

对于以数字 1 或 2 开头的 CPF 或 CNPJ，需要联系我们的 支持团队 以正确处理人工流程。

## 仅限 HTTPS

出于安全考虑，与 QI Tech API 的所有通信必须使用 HTTPS。为防止因疏忽或其他原因发出 HTTP 调用，该服务器仅开放 443 端口，使用 TLS 1.2 通信。使用其他协议发出的调用将被自动拒绝。

---

# Legal Person 对象

URL: /zh-Hans/documentation/caas/onboarding/legal_person

在您的平台完成企业注册后，需要对该公司进行反欺诈和 KYC 评估，这应通过 Legal Person 端点完成。提交的数据必须是最终数据，不得以任何方式更改，即在此流程之后，不应存在修改基本注册数据（如 CNPJ、公司名称、成立日期等）的可能性。这对于保证以下两点至关重要：

* 反欺诈数据库中数据的一致性
* 真实的风险评估，避免后续操作中的欺诈行为

## Legal Person 对象定义

Request Body

```json
{
  "id": "12345678",
  "registration_id": "12345678",
  "registration_date": "2019-12-11T11:37:15.12-03:00",
  "client_category" : "Premium Account",
  "legal_name": "John's Company",
  "trading_name": "John's Barbershop",
  "document_number": "11.111.111/0001-11",
  "foundation_date": "1992-09-15",
  "website": "www.johnsbarbershop.com.br",
  "activity": "Barber Shops",
  "activity_code": "96.02-5-01",
  "merchant_category_code": "0742",
  "tier" : "epp",
  "annual_revenues": 72000000,
  "emails":[
    {
      "email": "johnsample@test.com",
      "validation_type":"zaig_api",
      "validation_key": "ccc4b4b4-f91c-4475-8290-07152550aefc"
    }
  ],
  "documents": {
    "ie": {
      "number": "388.108.598.269",
      "issuer": "JUCESP",
      "issuer_state": "SP",
      "issuance_date":"2002-01-12",
      "validation_type": "zaig_api",
      "ocr_key": "c64627db-1ba4-48b6-979d-06222a25d5e9"
    },
    "company_statute": {
      "ocr_key": "60ed79c4-5aba-4cc7-aebb-5de5f92b7d0d"
    }
  },
  "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",
    "validation_type": "visit",
    "ocr_key": "265b1b74-4b93-41dc-ac78-e1c37467225d"
  },
  "phones": [
    {
      "international_dial_code": "1",
      "area_code": "11",
      "number": "999999999",
      "type": "mobile",
      "validation_type": "zaig_sms",
      "validation_key": "82473dec-8e14-4570-997a-59652818c908"
    }
  ],
  "source": {
    "channel": "app",
    "platform": "android",
    "ip":"201.6.142.66",
    "session_id": "c90ad2df-7307-4f82-8938-1da81dff2be6"
  },
  "legal_representatives": [
    {
      "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",
          "validation_type":"zaig_api",
          "validation_key": "d174d522-6003-4b05-adb2-e92e92632c67"
        }
      ],
      "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",
          "validation_type":"zaig_sdk",
          "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",
        "validation_type":"visit",
        "ocr_key": "265b1b74-4b93-41dc-ac78-e1c37467225d"
      },
      "phones": [
        {
          "international_dial_code": "55",
          "area_code": "11",
          "number": "999998877",
          "type": "mobile",
          "validation_type": "zaig_sms",
          "validation_key": "e390d2b3-cb71-4991-9d94-1b7f8b43a04e"
        }
      ],
      "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"
      }
    }
  ],
  "partners": [
    {
      "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",
          "validation_type":"zaig_api",
          "validation_key": "1fac6f8c-1a16-4a12-9afc-9a2d9ae0a31e"
        }
      ],
      "documents": {
        "rg": {
          "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"
        },
        "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",
          "validation_type":"zaig_sdk",
          "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",
        "validation_type":"visit",
        "ocr_key": "265b1b74-4b93-41dc-ac78-e1c37467225d"
      },
      "phones": [
        {
          "international_dial_code": "1",
          "area_code": "11",
          "number": "999999999",
          "type": "mobile",
          "validation_type": "zaig_sms",
          "validation_key": "d1713959-4ae4-4180-befc-6931c658e908"
        }
      ],
      "source": {
        "channel": "app",
        "platform": "android",
        "ip":"255.201.26.1",
        "session_id": "79d5e442-2cb7-4a9e-82c5-7fa3717d7ada"
      },
      "face":
      {
        "type":"zaig_sdk",
        "registration_key":"a2b6ae92-1394-4f9b-b8ee-5be188f93609"
      }
    }
  ]
}
```

所有注册的信息交换均使用以下对象定义。在某些情况下，为了简化实现并减少各方之间的数据流量，部分信息可以省略。

名称 | 类型 | 限制条件 | 描述
:----: | :----: | :----: | ---------
id | string | 1–50 个字符 | 分析的标识符。 **该编号对于每次请求必须唯一** *(必填)*
registration_id | string | 1–50 个字符 | 客户系统中注册的标识符。如需对同一注册进行多次分析，只需在不同分析中使用相同的 _registration_id_。未发送时将与 _id_ 取相同值。
registration_date | datetime | ISO 8601 含时区 | 注册的日期和时间。格式：`YYYY-MM-DDTHH:MM:SS[.ffffff]±HH:MM` 或 `...Z`。示例：`2019-12-11T11:37:15.12-03:00` *(必填)*
client_category | string | 1–100 个字符 | 根据您的平台分类或忠诚度计划划分的客户类别
legal_name | string | 1–1000 个字符 | 被注册公司的法定名称
trading_name | string | 1–1000 个字符 | 被注册公司的商业名称
document_number | string | 格式 `XX.XXX.XXX/XXXX-XX` | 公司的 CNPJ。必须恰好为 18 个字符，含点、斜杠和连字符 *(必填)*
foundation_date | date | 格式 `YYYY-MM-DD` | 公司的成立日期
website | string | 最多 10,000 个字符 | 被注册公司的网站
activity | string | 1–1000 个字符 | 被注册公司的经营范围
activity_code | string | 格式 `XX.XX-X-XX` | 公司经营活动的 CNAE 代码，含分隔符共 **10 个字符**。示例：`96.02-5-01`
merchant_category_code | string | 枚举值（见列表） | 根据卡片品牌标准划分的 MCC（Merchant Category Code）代码
tier | string | 1–10 个字符 | 公司规模（如：`mei`、`epp`、`me`、`medio`、`grande`）
annual_revenues | integer | 0 至 10,000,000,000,000 | 被注册公司的年度毛收入，以**分**为单位（雷亚尔）
monthly_revenues | integer | 0 至 10,000,000,000,000 | 被注册公司的月度毛收入，以**分**为单位（雷亚尔）
emails | Email 列表 | — | Email 类型对象列表，描述公司的电子邮件地址
documents | Document | — | 文件类型对象（州注册号 - *ie*，公司章程 - *company_statute*）
address | Address | — | Address 类型对象，描述公司的注册地址
phones | Phone 列表 | — | Phone 类型对象列表，描述公司的电话号码
source | Source | — | Source 类型对象，描述用于提交注册的应用程序特征
partners | Partner 列表 | — | Partner 类型对象列表，描述公司各股东的信息
legal_representatives | 法定代表人列表 | — | LegalRepresentative 类型对象列表，描述公司各法定代表人的信息

### 字段格式说明

#### `registration_date`

必须遵循 ISO 8601 格式，且**必须包含时区**。有效值示例：

```
2019-12-11T11:37:15-03:00        （无秒级小数，带时区偏移）
2019-12-11T11:37:15.123456-03:00 （带秒级小数，最多 6 位）
2019-12-11T14:37:15Z             （UTC 时间）
```

> 该字段**不接受**不含时区的日期（例如 `2019-12-11T11:37:15` 为无效值）。

#### `document_number` — CNPJ

CNPJ 必须**带标点**发送，格式为 `XX.XXX.XXX/XXXX-XX`，其中每个 `X` 为数字。字段长度恰好为 **18 个字符**。

有效示例：`11.222.333/0001-81`

#### `foundation_date`

日期格式为 `YYYY-MM-DD`（年-月-日），符合 ISO 8601 标准。

有效示例：`1992-09-15`

#### `activity_code` — CNAE

CNAE 代码必须以 `XX.XX-X-XX` 格式发送，含分隔符共恰好 **10 个字符**。

有效示例：`96.02-5-01`

#### `annual_revenues` 与 `monthly_revenues`

两个字段均为整数，表示以**分（雷亚尔）**为单位的货币金额。将雷亚尔转换为所需格式时，乘以 100 即可。

示例：BRL 720,000.00 → `72000000`

## 提交 Legal Person

Request Body

```json
  {
    "id": "12345",
    ...
  }
```

Response Body

```json
  {
    "id": "12345",
    "analysis_status": "automatically_approved",
    "reason": "rule_decision_enum"
  }
```

要对注册进行评估，只需将 Legal Person 类型的对象发送到以下端点，并相应设置参数标志：

`POST https://api.caas.qitech.app/onboarding/legal_person?analyze=true`

参数 *analyze* 用于标识所提交的注册是否应由 QI Tech 的算法进行分析。如果提交注册时该参数值为 **false**，则不会对其进行分析或计费，但其数据将被 QI Tech 的算法用于未来的分析。该参数的默认值为 **true**，因此只有明确以 **false** 标志提交的注册才不会被分析。

---

# Natural Person 对象

URL: /zh-Hans/documentation/caas/onboarding/natural_person

在您的平台完成自然人注册后，需要对该客户进行反欺诈和 KYC 评估，这应通过 Natural Person 端点完成。提交的数据必须是最终数据，不得以任何方式更改，即在此流程之后，不应存在修改基本注册数据（如 CPF、姓名、出生日期等）的可能性。这对于保证以下两点至关重要：

* 反欺诈数据库中数据的一致性
* 真实的风险评估，避免后续操作中的欺诈行为

## Natural Person 对象定义

Request Body

```json
{
  "id": "12345678",
  "registration_id": "12345678",
  "registration_date": "2019-12-11T11:37:15.12-03:00",
  "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",
  "emails":[
    {
      "email": "johnsample@test.com",
      "validation_type":"zaig_api",
      "validation_key": "e9f0de49-16fb-431e-be1a-ee4bf1096eda"
    }
  ],
  "documents": {
    "rg": {
      "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"
    },
    "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",
      "validation_type":"zaig_sdk",
      "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",
    "validation_type":"visit",
    "ocr_key": "265b1b74-4b93-41dc-ac78-e1c37467225d"
  },
  "phones": [
    {
      "international_dial_code": "1",
      "area_code": "11",
      "number": "999999999",
      "type": "mobile",
      "validation_type": "zaig_sms",
      "validation_key": "82589b39-e34f-44f9-b0fe-d8fc0ee6129c"
    }
  ],
  "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"
  }
}
```

所有注册的信息交换均使用以下对象定义。在某些情况下，为了简化实现并减少各方之间的数据流量，部分信息可以省略。

名称 | 类型 | 限制条件 | 描述
:----: | :----: | :----: | ---------
id | string | 1–50 个字符 | 分析的标识符。 **该编号对于每次请求必须唯一** *(必填)*
registration_id | string | 1–50 个字符 | 客户系统中注册的标识符。如需对同一注册进行多次分析，只需在不同分析中使用相同的 _registration_id_。未发送时将与 _id_ 取相同值。
registration_date | datetime | ISO 8601 含时区 | 注册的日期和时间。格式：`YYYY-MM-DDTHH:MM:SS[.ffffff]±HH:MM` 或 `...Z`。示例：`2019-12-11T11:37:15.12-03:00` *(必填)*
client_category | string | 1–100 个字符 | 根据您的平台分类或忠诚度计划划分的客户类别
name | string | 1–500 个字符 | 被注册个人的完整姓名
document_number | string | 格式 `XXX.XXX.XXX-XX` | 个人的 CPF。必须恰好为 14 个字符，含点和连字符 *(必填)*
birthdate | date | 格式 `YYYY-MM-DD` | 个人的出生日期
gender | enum | `male` 或 `female` | 个人的性别
nationality | string | 3 个大写字母 | 采用 ISO 3166-1 alpha-3 的国籍代码。示例：`BRA`
mother_name | string | 1–500 个字符 | 母亲的完整姓名
father_name | string | 1–500 个字符 | 父亲的完整姓名
monthly_income | integer | 1 至 100,000,000,000 | 月度税前收入，以**分**为单位（雷亚尔）
declared_assets | integer | 1 至 100,000,000,000,000 | 申报资产，以**分**为单位（雷亚尔）
occupation | string | 1–100 个字符 | 被注册个人的职业
emails | Email 列表 | — | Email 类型对象列表，描述个人的电子邮件地址
documents | Document | — | CNH、RG 及其他身份证件类型的文件对象
address | Address | — | Address 类型对象，描述个人的居住地址
phones | Phone 列表 | — | Phone 类型对象列表，包含个人的电话号码列表
source | Source | — | Source 类型对象，描述用于提交注册的应用程序信息
face | Face | — | Face 类型对象，描述注册时执行的人脸验证信息（如有）

### 字段格式说明

#### `registration_date`

必须遵循 ISO 8601 格式，且**必须包含时区**。有效值示例：

```
2019-12-11T11:37:15-03:00        （无秒级小数，带时区偏移）
2019-12-11T11:37:15.123456-03:00 （带秒级小数，最多 6 位）
2019-12-11T14:37:15Z             （UTC 时间）
```

> 该字段**不接受**不含时区的日期（例如 `2019-12-11T11:37:15` 为无效值）。

#### `document_number` — CPF

CPF 必须**带标点**发送，格式为 `XXX.XXX.XXX-XX`，其中每个 `X` 为数字。字段长度恰好为 **14 个字符**。

有效示例：`123.456.789-09`

#### `birthdate`

日期格式为 `YYYY-MM-DD`（年-月-日），符合 ISO 8601 标准。

有效示例：`1992-09-15`

#### `nationality`

遵循 ISO 3166-1 alpha-3 标准的 3 位**大写字母**国家代码。

示例：`BRA`（巴西）、`USA`（美国）、`ARG`（阿根廷）。

#### `monthly_income` 与 `declared_assets`

两个字段均为整数，表示以**分（雷亚尔）**为单位的货币金额。将雷亚尔转换为所需格式时，乘以 100 即可。

示例：BRL 5,000.00 → `500000`

## 提交 Natural Person

Request Body

```json
  {
    "id": "12345",
    ...
  }
```

Response Body

```json
  {
    "id": "12345",
    "analysis_status": "automatically_approved",
    "reason": "rule_decision_enum"
  }
```

要对注册进行评估，只需将 Natural Person 类型的对象发送到以下端点，并相应设置参数标志：

`POST https://api.caas.qitech.app/onboarding/natural_person?analyze=true`

参数 *analyze* 用于标识所提交的注册是否应由 QI Tech 的算法进行分析。如果提交注册时该参数值为 **false**，则不会对其进行分析或计费，但其数据将被 QI Tech 的算法用于未来的分析。该参数的默认值为 **true**，因此只有明确以 **false** 标志提交的注册才不会被分析。

---

# 共享对象

URL: /zh-Hans/documentation/caas/onboarding/objects

许多数据在各 API 之间共享。以下是这些对象定义的集中说明，方便查阅。

## *email* 对象

Request Body

```json
{
  "email": "johnsample@test.com",
  "validation_type":"zaig_api",
  "validation_key": "e9f0de49-16fb-431e-be1a-ee4bf1096eda"
}
```

*email* 对象用于在整个 API 中表示电子邮件地址，以及是否使用了某种验证方式。其结构如下：

名称 | 类型 | 限制条件 | 描述
---- | :----: | :----: | ---------
email | string | 1–100 个字符 | 注册的电子邮件地址。*(必填)*
validation_type | enum | `zaig_api` 或 `company_email` | 注册电子邮件时使用的验证类型。
validation_key | guid | UUID（`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`） | QI Tech 邮件验证 API 返回的 Id。

## *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"
}
```

*cnh* 对象用于在整个 API 中表示驾驶证（CNH），以及是否使用了某种验证方式。其结构如下：

名称 | 类型 | 描述
---- | :----: | ---------
register_number | string | 注册的驾驶证编号。
issuer_state | enum | 驾驶证签发州的枚举值。
first_issuance_date | date | 首次领证日期。
issuance_date | date | 签发日期。
expiration_date | date | 到期日期。
category | enum | 驾驶证类别，大写字母。
validation_type | enum | 注册文件时使用的验证类型。
ocr_key | guid | QI Tech 文件验证 API 返回的 Id。

*validation_type* 的枚举值如下：`zaig_api` 和 `zaig_sdk`。

## *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"
}
```

*rg* 对象用于在整个 API 中表示身份证（RG），以及是否使用了某种验证方式。其结构如下：

名称 | 类型 | 描述
---- | :----: | ---------
number | string | 注册文件的编号，包含格式（点、连字符、斜杠等）。
issuer | string | 文件签发机构（缩写，如：II、SESP...）
issuer_state | enum | 文件签发州。
issuance_date | date | 文件签发日期。
validation_type | enum | 注册文件时使用的验证类型。
ocr_key | guid | QI Tech 文件验证 API 返回的 Id。

*validation_type* 的枚举值如下：`zaig_api` 和 `zaig_sdk`。

## *ie* 对象

Request Body

```json
{
  "number": "388.108.598.269",
  "issuer": "JUCESP",
  "issuer_state": "SP",
  "issuance_date":"2002-01-12",
  "validation_type": "zaig_api",
  "ocr_key": "c64627db-1ba4-48b6-979d-06222a25d5e9"
}
```

*ie* 对象用于在 *legal_person* 端点的 *documents* 对象中表示州注册证（Inscrição Estadual），以及是否使用了某种验证方式。其结构如下：

名称 | 类型 | 描述
---- | :----: | ---------
number | string | 注册文件的编号，包含格式（点、连字符、斜杠等）。
issuer | string | 文件签发机构（缩写，如：JUCESP、JUCEGO...）
issuer_state | enum | 文件签发州。
issuance_date | date | 文件签发日期。
validation_type | enum | 注册文件时使用的验证类型。
ocr_key | guid | QI Tech 文件验证 API 返回的 Id。

*validation_type* 的枚举值如下：`zaig_api`。

## *company_statute* 对象

Request Body

```json
{
  "ocr_key": "60ed79c4-5aba-4cc7-aebb-5de5f92b7d0d"
}
```

*company_statute* 对象用于在 *legal_person* 端点的 *documents* 对象中表示公司设立文件，例如公司章程。其结构如下：

名称 | 类型 | 描述
---- | :----: | ---------
ocr_key | guid | QI Tech OCR API 在收到公司设立文件图片或 PDF 后返回的 Id。

## *letter_attorney* 对象

Request Body

```json
{
  "ocr_key": "13571175-b1d9-4507-82e0-d266516fc5ae"
}
```

*letter_attorney* 对象用于在 *legal_person* 端点的 *documents* 对象中表示授予法定代表人权限的授权书。其结构如下：

名称 | 类型 | 描述
---- | :----: | ---------
ocr_key | guid | QI Tech OCR API 在收到授权书图片或 PDF 后返回的 Id。

## *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",
  "validation_type":"visit",
  "ocr_key": "265b1b74-4b93-41dc-ac78-e1c37467225d"
}
```

*address* 对象用于在整个 API 中表示地址，巴西境内的地址表示如下：

名称 | 类型 | 限制条件 | 描述
---- | :----: | :----: | ---------
street | string | 1–100 个字符 | 地址的街道名称，包含地址类型，尽量避免缩写。
number | string | 1–50 个字符 | 房产编号，如有字母也需包含。
neighborhood | string | 1–100 个字符 | 社区名称，不使用缩写。 **例如：Santa Felicidade**
city | string | 1–100 个字符 | 城市全名，不使用缩写。
uf | enum | 巴西州缩写（2 个字母） | 联邦州。 **例如：SP、GO、MG**
complement | string | 1–500 个字符 | 定位房产的任何补充信息。 **例如：Apartamento 101, Conjunto 12**
postal_code | string | 格式 `XXXXX-XXX` | 含连字符的巴西邮政编码（CEP），恰好 9 个字符。示例：`01310-100` *(必填)*
country | string | 3 个大写字母 | 地址所在国家的 ISO 3166-1 alpha-3 代码。示例：`BRA`
validation_type | enum | `visit` 或 `zaig_ocr` | 注册地址时使用的验证类型。
ocr_key | guid | UUID（`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`） | QI Tech OCR API 或 SDK 在收到居住证明图片后返回的 Id。

对于国家非巴西（`BRA`）的地址，`postal_code` 和 `uf` 字段可自由填写。

## *phone* 对象

Request Body

```json
{
  "international_dial_code": "1",
  "area_code": "11",
  "number": "999999999",
  "type": "mobile",
  "validation_type": "zaig_sms",
  "validation_key": "82589b39-e34f-44f9-b0fe-d8fc0ee6129c"
}
```

*phone* 对象表示一个电话号码（巴西境内或境外）及其分类。各字段如下：

名称 | 类型 | 限制条件 | 描述
---- | :----: | :----: | ---------
international_dial_code | string | 1–7 个字符，仅数字 | 国际拨号代码，不含零或 `+`。示例：巴西为 `55` *(必填)*
area_code | string | 1–10 个字符，仅数字 | 区号，不含零。示例：`11` *(必填)*
number | string | 1–20 个字符 | 电话号码，不含连字符 *(必填)*
type | enum | `residential`、`commercial` 或 `mobile` | 号码类型。
validation_type | enum | `zaig_sms`、`zaig_call`、`company_sms` 或 `company_call` | 注册电话时使用的验证类型。
validation_key | guid | UUID（`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`） | QI Tech 电话验证 API 返回的 Id。

## *source* 对象

Request Body

```json
  {
    "channel": "app",
    "platform": "android",
    "ip":"211.7.142.62",
    "session_id": "733adf2c-a994-4113-aa59-beb646091fea",
  }
```

*source* 对象表示客户用于注册的平台信息集合。各字段如下：

名称 | 类型 | 描述
---- | :----: | ---------
channel | string | 客户的销售/注册渠道
platform | string | 客户用于注册的平台
ip | string | 客户注册所用设备采集的 IP 地址
session_id | string | 会话的唯一标识符，用于将设备扫描与对应注册进行关联

## *face* 对象

Request Body

```json
  {
    "type":"zaig_face_sdk",
    "registration_key":"46f38cf4-07b2-4de6-93e9-64b51a68378a"
  }
```

*face* 对象表示您在提交注册前，通过 QI Tech 的 API 或 SDK 对客户真实性进行人脸识别验证的结果。各字段如下：

名称 | 类型 | 描述
---- | :----: | ---------
validation_type | enum | 执行的人脸识别验证类型。
registration_key | guid | QI Tech API 或 SDK 返回的用于识别该注册记录的标识符。
validation_key | guid | QI Tech API 或 SDK 返回的用于识别该验证记录的标识符。

人脸验证类型的枚举值如下：`zaig_api` 和 `zaig_sdk`。

## *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",
        "validation_type":"zaig_api",
        "validation_key": "e9f0de49-16fb-431e-be1a-ee4bf1096eda"
      }
    ],
    "documents": {
      "rg": {
        "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"
      },
      "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",
        "validation_type":"zaig_sdk",
        "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",
      "validation_type":"visit",
    },
    "phones": [
      {
        "international_dial_code": "1",
        "area_code": "11",
        "number": "999999999",
        "type": "mobile",
        "validation_type": "zaig_sms",
        "validation_key": "82589b39-e34f-44f9-b0fe-d8fc0ee6129c"
      }
    ],
    "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"
    }
  }
```

*partner* 对象表示被注册公司的股东数据，以及该股东在注册过程中接受的各类验证信息。各字段如下：

名称 | 类型 | 描述
:----: | :----: | ---------
name | string | 被注册股东的完整姓名
document_number | string | 被注册股东的 CPF，含点和连字符，遵循标准格式 *(必填)*
birthdate | date | 股东的出生日期，遵循标准格式
gender | enum | 股东的性别：'male' 或 'female'
nationality | string | 股东的国籍，采用 ISO 3166-1 alpha-3 格式
mother_name | string | 股东母亲的完整姓名
occupation | string | 被注册股东的职业
emails | Email | Email 类型对象列表，描述股东的电子邮件地址
documents | Document | Document 类型对象，包含股东注册时提交的任何文件
address | Address | Address 类型对象，描述股东的居住地址
phones | Phone 列表 | Phone 类型对象列表，包含股东的电话号码列表
source | Source | Source 类型对象，描述用于提交注册的应用程序特征
face | Face | Face 类型对象，描述人脸验证信息

## *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",
        "validation_type":"zaig_api",
        "validation_key": "d174d522-6003-4b05-adb2-e92e92632c67"
      }
    ],
    "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",
        "validation_type":"zaig_sdk",
        "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",
      "validation_type":"proof_of_address",
      "ocr_key": "265b1b74-4b93-41dc-ac78-e1c37467225d"
    },
    "phones": [
      {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "999998877",
        "type": "mobile",
        "validation_type": "zaig_sms",
        "validation_key": "e390d2b3-cb71-4991-9d94-1b7f8b43a04e"
      }
    ],
    "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"
    }
  }
```

*legal_representative* 对象表示被注册公司的法定代表人数据，以及该代表人在注册过程中接受的各类验证信息。各字段如下：

名称 | 类型 | 描述
:----: | :----: | ---------
name | string | 被注册法定代表人的完整姓名
document_number | string | 被注册法定代表人的 CPF，含点和连字符，遵循标准格式
birthdate | date | 法定代表人的出生日期，遵循标准格式
gender | enum | 法定代表人的性别：'male' 或 'female'
nationality | string | 法定代表人的国籍，采用 ISO 3166-1 alpha-3 格式
mother_name | string | 法定代表人母亲的完整姓名
occupation | string | 被注册法定代表人的职业
emails | Email | Email 类型对象列表，描述法定代表人的电子邮件地址
documents | Document | Document 类型对象，包含法定代表人注册时提交的任何文件
address | Address | Address 类型对象，描述法定代表人的居住地址
phones | Phone 列表 | Phone 类型对象列表，包含法定代表人的电话号码列表
source | Source | Source 类型对象，描述用于提交注册的应用程序特征
face | Face | Face 类型对象，描述人脸验证信息

---

# 查询注册信息

URL: /zh-Hans/documentation/caas/onboarding/query_registration

## 查询特定注册

要查询特定注册，只需发送 GET 请求。返回结果为该注册最新的 JSON 数据。如果该标识符未关联任何对象，则返回 HTTP Status 404。

* **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"
```

> 上述命令返回表示 Natural Person 对象的 JSON。

```shell
curl "https://api.caas.qitech.app/onboarding/legal_person/12345678"
  -H "Authorization: EXAMPLE-OF-API-KEY"
```

> 上述命令返回表示 Legal Person 对象的 JSON。

## 获取 PDF

要获取某个注册的 PDF 文件，只需发送 GET 请求。返回结果为分析生成的 PDF 文件。如有需要，可添加名为 base64、值为 true 的查询字符串，以 base64 格式返回 PDF 文件。

:::info **注意**

平台的 PDF 生成是异步的，需要几秒钟时间。如果在 PDF 实际生成之前发送 GET 请求，将返回 404 错误并附带相应说明。几秒后重试即可获取 PDF。
:::

* **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"
```

> 上述命令返回查询生成的 PDF 文件。

```shell
curl "https://api.caas.qitech.app/onboarding/legal_person/12345678/pdf"
  -H "Authorization: EXAMPLE-OF-API-KEY"
```

> 上述命令返回查询生成的 PDF 文件。

---

# 标准规范

URL: /zh-Hans/documentation/caas/onboarding/standards

为了简化集成并保证数据完整性，整个 API 遵循以下统一标准。

## 货币金额
> 示例：

```
10000
12345
98741
1223
1
0
```

API 假定所有发送的货币金额均以巴西雷亚尔（BRL）为单位。金额必须以分为单位以整数形式发送。

## 带时区的日期时间
> 部分示例：

```
2019-10-15T22:35:12.232-03:00
2018-05-01T13:32:11.297+00:00
2019-05-01T00:00:00.000+00:00
```

遵循 ISO 8601 标准表示。时区紧随时间之后，应表示该数据所在地点的时区。

验证所用格式如下：

`YYYY-MM-ddThh:mm:ss.sss±hh:mm`

## 不带时区的日期时间
> 部分示例：

```
2019-10-15T22:35:12
2018-05-01T13:32:11
2019-05-01T00:00:00
```

遵循 ISO 8601 标准表示。与时区无关的数据应不带时区发送，始终以 UTC 时间表示，并用字母 Z 表示该数据为 UTC 时间。因此将验证以下格式：

`YYYY-MM-ddThh:mm:ss.sssZ`

## 日期
> 部分示例：

``` 
2019-10-15
2019-01-01
2017-03-20
```

对于仅接受日期的字段（例如出生日期），只需发送日期，不含任何时间，格式如下：

`YYYY-MM-dd`
 

## 文件号码
由于文件号码种类繁多，且许多包含非数字字符，所有文件号码均定义为字符串类型。将其定义为字符串的另一个重要原因是防止前导零丢失。本页面涵盖的文件号码均有明确的格式掩码，并将进行验证。其余文件（如 RG）因缺乏标准化而不作验证。

## CPF

> 符合掩码定义的有效 CPF 示例：

```
123.456.789-12
321.987.543-23
111.283.333-00
```

> 不符合掩码定义的无效 CPF 示例：

```
8.577.477-8
08.104.627/0001-23
123.456.789-1
23.456.789-01
```

CPF 始终定义为字符串，并将根据以下掩码进行验证：

`###.###.###-##`

## CNPJ

> 符合掩码定义的有效 CNPJ 示例：

```
08.104.627/0001-02
01.079.210/0114-67
32.402.502/0001-35
```

> 不符合掩码定义的无效 CNPJ 示例：

```
8.577.477-8
123.456.789-12
321.987.543-23
32.402.502/0001-3
032.402.502/0001-3
```

CNPJ 始终定义为字符串，并将根据以下掩码进行验证：

`##.###.###/####-##`

## IP

> 符合掩码定义的有效 IP 示例：

```
201.81.161.86
201.081.161.86
201.81.161.086
201.81.0.1
```

> 无效 IP 示例：

```
201.81..86
358.81.161.86
201.81.161
```

IP 地址必须始终以 IPv4 格式发送，可以带或不带前导零，遵循以下掩码：

`###.###.###.###`

---

# 状态动态

URL: /zh-Hans/documentation/caas/onboarding/status_dynamics

分析流程包括向相应端点提交注册信息（Natural Person 或 Legal Person），然后等待响应。

QI Tech 完成注册分析后，将返回一个包含分析状态的响应。该状态称为 **analysis_status**，代表 QI Tech 对注册分析的结果。

除 **analysis_status** 外，QI Tech 还有 **client_status**，其目的是表示客户在您平台生命周期各阶段的状态。

### **analysis_status**

如前所述，QI Tech 共有七种 **analysis_status**，用于指示 onboarding 引擎的决策状态，其状态机相当简单：

analysis_status | 描述
:---------: | ---------
automatically_approved | QI Tech 的算法建议批准该注册
automatically_reproved | QI Tech 的算法建议拒绝该注册
in_manual_analysis | QI Tech 的算法将该注册转交人工分析
manually_approved | 人工分析后，分析师决定批准该注册
manually_reproved | 人工分析后，分析师决定拒绝该注册
in_queue | 注册正在异步处理中，注册结果将通过 Webhook 返回
pending | 查询耗时超过预期，该注册已进入自动分析队列，结果将通过 Webhook 返回
not_analysed | 注册提交时分析标志为 false，表示我们的系统不会返回建议

### **client_status**

**client_status** 表示客户的注册状态，即个人或企业在您平台的状态。该状态的枚举值如下：

client_status | 描述
:---------: | ---------
registered | 客户已在您的平台注册，但尚未做出批准或拒绝决定
approved | 客户在您的平台已获批准
reproved | 客户在您的平台已被拒绝
fraud_blocked | 由于涉嫌或确认欺诈，客户被封锁，无法使用您的平台
default_blocked | 由于违约，客户被封锁，无法使用您的平台
canceled | 客户已取消使用您的服务

---

# 更新注册信息

URL: /zh-Hans/documentation/caas/onboarding/update_registration

Request Body：因欺诈或涉嫌欺诈封锁注册时

```json
{
  "client_status": "fraud_blocked",
  "event_date": "2019-11-05T13:34:12-03:00"
}
```

Request Body：因违约封锁注册时

```json
{
  "client_status": "default_blocked",
  "event_date": "2019-11-05T13:34:12-03:00"
}
```

Request Body：因客户申请取消注册时

```json
{
  "client_status": "cancelled",
  "event_date": "2019-11-05T13:34:12-03:00"
}
```

为确保规则和人工智能模型的持续优化，每当注册状态发生变更时（例如被封锁或取消），需要及时通知系统。用于这些变更的状态为 **client_status**，每当客户生命周期发生变化时均应更新。为此，需使用 PUT 方法发送经过正常认证的请求，状态应遵循前文描述的规范：

* **Natural Person：**

`PUT https://api.caas.qitech.app/onboarding/natural_person/123456`

* **Legal Person：**

`PUT https://api.caas.qitech.app/onboarding/legal_person/123456`

---

# Webhook

URL: /zh-Hans/documentation/caas/onboarding/webhook

欺诈状态的更新（针对被转交人工分析或以"待处理"状态响应的注册）将通过 Webhook 进行通知。为此，需通过[支持团队](mailto:suporte.caas@qitech.com.br)配置一个端点地址，用于接收我们发送的状态更新通知，以及一个 *secret_token*，用于对请求进行签名。

客户也可以使用[轮询](https://en.wikipedia.org/wiki/Polling_(computer_science))技术（虽然不建议这样做）。在这种情况下，无需配置 webhook 端点，直接使用注册查询端点进行轮询即可。

## 签名

> Python 签名计算示例

```python
    hmac_obj = hmac.new(signature_key.encode('utf-8'), (endpoint + method + payload).encode('utf-8'), hashlib.sha1)
    return hmac_obj.hexdigest()
```

为确保 webhook 端点收到的请求来自我们的服务器，在 Header Signature 中会发送 HMAC 签名，与认证流程类似。

在服务器端计算出预期的签名值后，需将计算出的签名与发送的签名进行比对。如果两者匹配，则说明请求来自我们的服务器，是可信的。

## 请求

```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"}'
```

请求格式如上所示，用于通知欺诈状态的变更。需要注意的是，请求使用 HTTP POST 方法，请求正文以 UTF-8 编码的文本形式发送。

## 重试机制

当收到 HTTP Status 200 的响应时，通知视为已成功送达。如果通知失败，将进行最多 5 次重试，重试间隔如下，直到收到 200 响应或重试次数用尽：

* 30 秒
* 60 秒
* 120 秒
* 240 秒
* 360 秒

---

# 授权请求（可选）

URL: /zh-Hans/documentation/cards/autorizacao/

---

程序配置完成、持卡人已添加并拥有一张有效卡片后，该卡片即可在世界各地的多个销售点进行消费。每当在某个受理终端发起交易时，系统将创建一个 `Authorization`（授权）来授权该操作。系统将向客户系统发送 `Authorization Request`（授权请求），由客户根据请求中包含的信息决定是否批准该授权。

`Authorization` 实体包含已授权和已捕获金额的当前状态，可取以下状态值：

| 状态 | 描述 |
|---|---|
| pending | 授权请求已获批准，尚无捕获或取消事件被处理 |
| unauthorized | 授权请求未获批准 |
| completed | 对该授权至少已成功捕获一个金额（可等于、小于或大于所有授权请求中批准的总金额）|
| reversed | 授权已被完全冲正，或已过期而未捕获 |

授权字段详情请参阅[查询授权](/documentation/cards/search/buscar_autorizacao/)

发送给客户的 `Authorization Request` 将包含[认证头信息](/documentation/primeiros_passos/teste_de_autenticacao/webhook_v2/index.html)，其结构如下：

### 授权请求

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

| 字段 | 类型 | 描述 |
|---|---| ---|
| `authorization_request_key` | string  | 授权请求的唯一标识符 |
| `authorization_key` | string  | 与本请求关联的授权实体的唯一标识符 |
| `card` | object |**[Card 对象](#objeto-card)**  |
| `terminal_id` | string | 收单机构在授权消息中发送的终端标识符 |
| `terminal_country_code` | string | 终端所在国家代码，依据 ISO 3166-1 alpha-3 在授权消息中发送 |
| `terminal_type` | string | 授权消息中收到的终端类型 |
| `terminal_pin_entry_capability` | boolean | 终端是否支持输入卡密码？ |
| `terminal_magnetic_stripe_capability` | boolean | 终端是否能读取磁条？ |
| `terminal_contactless_capability` | boolean | 终端是否能发起非接触式交易？ |
| `terminal_chip_capability` | boolean | 终端是否能使用 EMV 芯片发起交易？ |
| `merchant_acquirer_code` | string | 授权消息中收单机构的标识符 |
| `merchant_code` | string | 授权消息中商户在收单机构的标识符 |
| `merchant_name` | string | 授权消息中的商户名称 |
| `merchant_street` | string | 商户地址的街道 |
| `merchant_city` | string | 商户地址的城市 |
| `merchant_region` | string | 商户地址的地区 |
| `merchant_postal_code` | string | 商户地址的邮政编码（CEP）|
| `merchant_mcc` | string | 商户类别代码 - 识别商户类型 - [最新列表可在此处查阅](https://usa.visa.com/content/dam/VCOM/download/merchants/visa-merchant-data-standards-manual.pdf) |
| `authorization_code` | string | 6 位授权码 |
| `nsu` | string | 定义一次授权的唯一顺序号 |
| `acquirer_reference_number` | string | 收单机构的唯一授权标识符 |
| `merchant_currency_code` | string | 交易使用的货币 - ISO 4217-alpha |
| `merchant_amount` | decimal | 交易发生货币下的交易金额 |
| `billing_currency_code` | string | 持卡人账单货币 - ISO 4217-alpha |
| `billing_amount` | decimal | 持卡人账单货币下的交易金额 |
| `processing_datetime` | timestamp utc | 授权请求的处理时间 |
| `number_of_installments` | int | 本次请求授权的分期数 |
| `authorization_request_type` | enum | **[授权请求类型枚举](#tipos-de-autorizacao)** |
| `pan_entry_mode` | enum | **[PAN 输入模式](#modos-de-entrada-do-pan)** - 芯片、手动输入、磁条、降级、非接触式 |
| `pin_sent` | boolean | 终端是否输入了密码？ |
| `authorization` | object | 授权对象，详见 [GET 授权](/documentation/cards/search/buscar_autorizacao/)，仅在授权类型为增量时存在。 |

#### Card 对象

| 字段 | 类型 | 描述 |
|---| ---| ---|
| `card_key` | string | 卡片识别密钥 |
| `account_key` | string | 持卡人账户标识符 |
| `type` | string | 卡片类型 |
| `card_name` | string | 卡片字母数字标识符 |
| `printed_name` | string | 印在卡片上的姓名 |
| `status` | string | 卡片当前状态 |
| `brand` | string | 卡片所属卡组织 |
| `bin` | string | 卡片 BIN |
| `last_four_digits` | string | 卡号后四位 |

#### 授权请求类型

| 枚举值 | 描述 |
|---|---|
| **authorization** | 普通授权请求 |
| **incremental_authorization** | 对已有授权的增量授权请求 |
| **partial_reversal_authorization** | 对之前交易进行部分冲正的授权，仅出现在事件中，不由客户明确授权 |
| **reversal_authorization** | 对之前交易进行冲正的授权，仅出现在事件中，不由客户明确授权 |

#### PAN 输入模式

枚举值 | ISO 8583 | 描述
---------- | -------- | -----------
unknown | 00 | 未知的 PAN 输入模式。
typed | 01 | 手动输入（键入）PAN。
bar_code | 03 | 通过条形码读取器输入 PAN
ocr | 04 | 通过 OCR（光学字符识别）输入 PAN
chip | 05 | 通过集成电路卡（芯片）输入 PAN
track_1 | 06 | 通过卡片磁条 Track 1 输入 PAN
contactless | 07 | 通过非接触式 EMV 输入 PAN
fallback_typed | 79 | 尝试使用设备读卡器或磁条时无法处理交易（可能是设备或卡片问题），随后手动键入 PAN。某些情况下收单机构未获授权使用芯片或磁条并发送此代码。
fallback_magnetic_stripe | 80 | 尝试使用设备读卡器时无法处理交易（可能是设备或卡片问题），随后改用卡片磁条。
ecommerce | 81 | 电商/非当面交易
magnetic_stripe | 90 | 磁条交易（卡片无芯片或设备无读卡器/未获授权）

### 对授权请求的批准或拒绝响应

对授权请求的响应必须始终使用 HTTP Status 201，审批意见在 *approve* 字段中说明。若审批为否定，需选择一个拒绝原因枚举值，并可发送文字描述来详述拒绝原因。

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 transaction value."
```

| 字段 | 类型 | 描述 |
|---|---| ---|
| `authorization_request_response` | enum | *authorized* 或 *unauthorized* |
| `denial_reason` | enum | **[拒绝原因枚举](#razoes-de-negacao)** — 仅在 `authorization_request_response` 为 *unauthorized* 时必填 |
| `denial_reason_details` | string | 拒绝原因的文字描述 |

#### 拒绝原因

| 枚举值 | 描述 |
|---|---|
| insufficient_funds | 余额不足 |
| invalid_pin | PIN 无效 |
| card_blocked | 卡片已被封锁 |
| card_expired | 卡片已过期 |
| card_not_active | 卡片未激活 |
| fraud_suspicion | 疑似欺诈 |
| transaction_not_allowed | 不允许此交易 |
| invalid_amount | 金额无效 |
| generic_error | 通用错误 |

---

# QI Conta 交易

URL: /zh-Hans/documentation/cards/autorizacao/balance_transaction

---

在预付卡场景中，借记或贷记操作会反映在持卡人的 QI Conta 上。这些交易由 `Balance Transaction` 实体表示。这些交易必须在持卡人的 QI Conta 上执行，即使存在延迟。因此，若某笔借记因任何原因无法执行，`Balance Transaction` 将保持待处理状态，并由 QI 系统自动重试，直到全部金额被扣除。

跟踪这些交易非常重要，若某笔 `Balance Transaction` 长期处于待处理状态，客户应联系持卡人，确保 QI Conta 处于可用状态且有足够余额来处理该待付款项。

每当创建 `Balance Transaction` 时，系统将发送 `Balance Transaction Event` webhook。

QI Conta 交易事件 Webhook

```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"
}
```

#### 详情

| 字段 | 类型 | 描述 |
|---|---| ---|
| `balance_transaction_key` | string  | 授权请求的唯一标识符 |
| `transaction_key` | string  | 与本请求关联的授权实体的唯一标识符 |
| `amount` | string | 本次事件在 QI Conta 中的交易金额 |
| `transacted_at` | string | 交易执行的时间 |
| `balance_transaction_status` | string | 本次事件后 `Balance Transaction` 的状态 |

`balance_transaction_status` 描述交易是否已在持卡人 QI Conta 上执行，可能处于待处理（`pending_transaction_execution`）、部分交易（`partially_transacted`）或已交易（`transacted`）状态。

:::danger 注意！
QI Tech 的 webhook 不应进行严格映射。
我们 API 返回的 webhook payload 中可能会包含额外字段。
:::

:::info Webhook 重发！
Webhook 的查询和重发请参阅文档：[Webhook 重发](/documentation/notificacoes/reenvio_de_notificacoes)
:::

---

# 模拟授权

URL: /zh-Hans/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
}
```

### 请求体字段说明

下表列出了上述请求中所有变量的描述。

| 字段 | 类型 | 描述 | 最大字符数 | 示例 |
|-----------------------|--------|----------------------------------------------------|--------------|----------------------|
| **card_key**          | string | 卡片唯一密钥（必填）| 36 | "ff3c4484-7a52-457e-b989-d9dcb87dfcd6" |
| **authorization_type**| string | 授权类型（必填）| **[枚举值](#authorization-type-enumeradores)** |
| **merchant_name**     | string | 商户名称 | 40 | "Supermarket XYZ" |
| **merchant_city**     | string | 商户城市 | 40 | "São Paulo" |
| **merchant_region**   | string | 商户所在国家 | 2 | "BR" |
| **merchant_postal_code** | string | 商户邮政编码 | 8 | "01001000" |
| **merchant_mcc**      | string | 商户类别代码（MCC）| **[枚举值](#merchant-mcc-enumeradores)** |
| **amount**            | number | 交易金额 | - | 150.75 |

### merchant_mcc 枚举值

| 枚举值 | 描述 |
|------------|--------------------------------------------|
| 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                     |

### authorization_type 枚举值

| 枚举值 | 描述 |
|-------------|----------------------------|
| purchase    | Purchase                   |
| reversal    | Reversal                   |
| withdrawal  | Withdrawal                 |

---

# 创建实体卡

URL: /zh-Hans/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
实体卡寄送所用的地址将与在 QI Tech 开立支付账户时填写的地址相同。
:::

  ### 请求体参数

| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|---------|------------------------------------------------------------------------------------------------|---------------------------------------------|
| `account_key` *         | string  | QI Tech 支付账户的识别密钥。| uuid |
| `program_key` *         | string  | 用于发行卡片的程序识别密钥。| uuid |
| `type` *                | string  | 要发行的卡片类型（PLASTIC）。| **[枚举值](#enumeradores-card_type)** |
| `card_name` *           | string  | 卡片别名，用于识别该卡片。| 15 |
| `printed_name` *        | string  | 印在卡片上的姓名（不允许使用数字和特殊字符）。| 26 |
| `contactless_enabled` * | boolean | 启用或禁用卡片的非接触式功能。| - |
| `delivery_address`      | Object  | 卡片配送地址。| **[Address 对象](#address)** |

### card_type 枚举值

| 枚举值 | 说明 |
|------------|----------------|
| plastic    | 实体卡 |
| virtual    | 虚拟卡 |

### Address

| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|---------|------------------------------------------------------------------------------------------------|---------------------------------------------|
| address*              | string | 配送地址 | 100 |
| neighborhood*| string | 配送地址的街区/社区 | 100 |
| zip_code*    | string | 配送地址的邮政编码 | 8 |
| city*        | string | 配送地址的城市 | 100 |
| state*       | string | 配送地址的州 | 2 |
| number        | number | 配送地址的门牌号 | |
| complement   | string | 配送地址的补充信息 | 100 |
| reference    | string | 配送地址的参考地标 | 100 |
| address_type*        | string | 配送类型 | **[枚举值](#enumeradores-address_type)** |

:::caution 注意！
`number` 字段为可选项。无门牌号的地址可以不填写此字段。
:::

### address_type 枚举值

| 枚举值 | 说明 |
|------------|----------------------|
| residential| 住宅地址 |
| commercial | 商业地址 |
| other      | 其他地址 |

## Response

STATUS 201

Response Body

```json
{
    "card_key": "05fd3654-1f5d-479d-ade5-64239fdf214d",
	"created_at": "2023-06-20T19:28:16Z",
    "status":"created"
}
```

### 错误

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  | 描述 |
|:---------:|:------------:|:-------------------------------|
| 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"
    }
}
```

---

# 创建虚拟卡

URL: /zh-Hans/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
}
```

  ### 请求体参数

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------------|--------|------------------------------------------------------------------------------------------------|---------------------------------------------|
| `account_key` *                 | string | QI Tech 支付账户的识别密钥。| uuid |
| `program_key` *                 | string | 用于发行卡片的程序识别密钥。| uuid |
| `type` *                        | string | 要发行的卡片类型（VIRTUAL）。| **[枚举值](#enumeradores-card_type)** |
| `card_name` *                   | string | 卡片别名，用于识别该卡片。| uuid |
| `printed_name` *                | string | 印在卡片上的姓名（不允许使用数字和特殊字符）。| uuid |
| `cvv_rotation_interval_hours` * | int    | CVV 号码更新的时间间隔（小时）。| Number |

### card_type 枚举值

| 枚举值 | 说明 |
|------------|----------------|
| plastic    | 实体卡 |
| virtual    | 虚拟卡 |

## Response

STATUS 201

Response Body

```json
{
    "card_key": "05fd3654-1f5d-479d-ade5-64239fdf214d",
	"created_at": "2023-02-20T19:28:16Z",
    "status":"created"
}
```

### 错误

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  | 描述 |
|:---------:|:------------:|:-------------------------------|
| 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"
    }
}
```

---

# 简介

URL: /zh-Hans/documentation/cards/introducao

预付卡发行 API 允许 QI Tech 合作伙伴的客户申请和发行预付卡，包括实体卡和虚拟卡。

在 QI Tech，我们为合作伙伴提供成为子发行商的机会。通过我们的 API，合作伙伴可以为其自身客户提供发行实体预付卡和虚拟预付卡的能力，从而提供完整的银行服务解决方案。

为了更好地理解我们的系统，我们将简要介绍预付卡生态系统的运作方式。请注意，与其他 API 一样，服务的开通需与我们的团队协调，且**[调用需经过身份验证](/documentation/primeiros_passos/teste_de_autenticacao)**。

### 预付卡

预付卡与 QI Tech 内的支付账户绑定。

通过该卡执行的所有交易均将从支付账户的现有余额中扣除。

若账户余额不足，交易将被拒绝。

### 支付账户

QI Tech 是巴西中央银行授权运营预付支付账户的金融机构。预付卡始终与预付支付账户绑定。

因此，无论是实体卡还是虚拟卡，创建预付卡前都必须先开立支付账户。请参阅**[此处](/documentation/contas/abertura_de_conta/abertura_de_conta_pf)**的开户 API。

### 程序（Program）

合作伙伴要发行预付卡，必须在其与 QI 的集成中关联并配置相应的程序。

程序即发行符合 VISA 卡组织规定所需的配置和规则。

以下是关于程序的一些重要信息：

* **程序类型** — 指卡的使用模式。本文档所述为预付模式。
* **卡组织** — 我们使用 VISA 卡组织发行卡片。
* **卡面设计** — 指将印在实体卡上以及虚拟卡图形界面中显示的设计。

:::caution 注意
如需在集成中配置新程序，请联系 QI Tech 的商务团队和实施团队。
:::

### 虚拟卡

QI Tech 的卡 API 提供生成虚拟卡的功能，可用于线上交易。该解决方案为持卡人提供安全性和便利性。

使用虚拟卡时，持卡人无需在网络交易中提供实体卡的详细信息。他们可以生成一张专用于特定交易的唯一虚拟卡，拥有独立的卡号和信息。这有助于降低欺诈风险，提升线上交易的可信度。

### 实体卡

QI Tech 的卡 API 提供创建实体卡的选项，为持卡人提供可用于线下交易的实体塑料卡。

申请实体卡后，持卡人将收到一张个性化的塑料卡。

实体卡为持卡人提供了一种传统且被广泛接受的支付方式，确保线下交易的便利性和实用性。此外，实体卡还可能具备额外功能，例如支持非接触式（contactless）支付技术以加速交易。

QI Tech 预付卡 API 让持卡人能够根据个人需求和偏好，灵活选择使用虚拟卡进行线上交易或使用实体卡进行线下交易。

---

# 通过授权密钥查询授权

URL: /zh-Hans/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"
        }
    ]
}
```

### 授权对象

| 字段 | 类型 | 描述 |
|---|---| ---|
| authorization_key | string | 授权的唯一标识符 |
| merchant_currency_code | string | 交易使用的货币 - ISO 4217-alpha |
| original_merchant_amount | decimal | 交易发生货币下的原始交易金额 |
| billing_currency_code | string | 持卡人账单货币 - ISO 4217-alpha |
| original_billing_amount | decimal | 持卡人账单货币下的原始交易金额 |
| merchant_amount | decimal | 所有授权请求中交易货币金额的汇总 |
| iof_amount | decimal | 当交易货币与持卡人账单货币不同时，汇兑所缴纳的 IOF 金额汇总 |
| billing_amount | decimal | 所有授权请求中持卡人账单货币金额的汇总 |
| processing_datetime | datetime UTC | 授权对象的创建时间，通常为第一次授权请求的时间 |
| captured_amount | decimal | 所有授权请求已捕获的总金额 |
| authorization_status | enumerator | **[授权状态枚举](#status-da-autorizacao)** |
| card | object |**[Card 对象](#objeto-card)**  |
| balance_transactions | list of objects |**[Balance Transaction 对象](#objeto-balance-transaction)**  |
| authorization_requests | list of objects |**[授权请求对象](#objeto-rquisicao-de-autorizacao)**  |
| authorization_events | list of objects | **[授权事件对象](#objeto-evento-autorizacao)**  |

### Card 对象

| 字段 | 类型 | 描述 |
|---| ---| ---|
| card_key | string | 卡片识别密钥 |
| account_key | string | 持卡人账户标识符 |
| type | string | 卡片类型 |
| card_name | string | 卡片字母数字标识符 |
| printed_name | string | 印在卡片上的姓名 |
| cvv_rotation_interval_hours | int | CVV 轮换间隔 |
| status | string | 卡片当前状态 |
| brand | string | 卡片所属卡组织 |
| bin | string | 卡片 BIN |
| last_four_digits | string | 卡号后四位 |

### Balance Transaction 对象

`Balance Transaction` 对象表示持卡人 QI Conta 上需要执行的任何资金变动。可以是因授权获批而产生的*借记*交易，也可以是授权取消等场景下的*贷记*交易。

| 字段 | 类型 | 描述 |
|---| ---| ---|
| balance_transaction_key | string | 交易的唯一标识符 |
| balance_transaction_type | enumerator | 贷记时为 *credit*，借记时为 *debit* |
| account_key | string | 与所用卡片关联的 QI Conta 标识符 |
| merchant_currency_code | string | 交易使用的货币 - ISO 4217-alpha |
| merchant_amount | decimal | 交易货币下的等值收费金额 |
| billing_currency_code | string | 持卡人账单货币 - ISO 4217-alpha |
| billing_amount | decimal | 持卡人账单货币下的交易金额 |
| processing_datetime | datetime | 交易的处理和创建日期。由于 QI Conta 中的实际交易可能不会发生，此值作为收费或贷记生成时的参考时间 |
| balance_transaction_status | enumerator | 描述交易是否已在持卡人 QI Conta 上执行，可能为待处理（`pending_transaction_execution`）、部分交易（`partially_transacted`）或已交易（`transacted`）|
| transacted_amount | decimal | 已在 QI Conta 上执行的借记或贷记的持卡人货币总金额 |

### 授权请求对象

详见[授权请求](/documentation/cards/autorizacao/)

### 授权事件对象

`Authorization Event` 对象表示授权上发生的事件。更详细的说明请参阅[手册](/documentation/manual_pre_pago/casos_uso/)。

| 字段 | 类型 | 描述 |
|---| ---| ---|
| merchant_currency_code | string | 交易使用的货币 - ISO 4217-alpha |
| merchant_amount | decimal | 交易货币下的等值收费金额 |
| billing_currency_code | string | 持卡人账单货币 - ISO 4217-alpha |
| billing_amount | decimal | 持卡人账单货币下的事件金额 |
| processing_datetime | datetime | 事件的处理日期 |
| authorization_event_type | enumerator | **[授权事件类型](#tipos-evento-autorizacao)** |

### 授权状态

| 状态 | 描述 |
|---|---|
| pending | 授权请求已获批准，尚无捕获或取消事件被处理 |
| unauthorized | 授权请求未获批准 |
| completed | 对该授权至少已成功捕获一个金额（可等于、小于或大于所有授权请求中批准的总金额）|
| reversed | 授权已被完全冲正，或已过期而未捕获 |

### 授权事件类型

| 类型 | 描述 |
|---|---|
| authorization | 通知一次授权请求已被响应 |
| incremental_authorization | 通知一次增量授权请求已被响应 |
| authorization_reversal | 通知一次授权取消已被处理 |
| partial_authorization_reversal | 通知一次部分授权取消已被处理 |
| authorization_expiration | 通知一次授权已过期 |
| capture | 通知一笔特定金额已为某授权完成捕获 |
| refund | 通知一次授权已被退款 |
| partial_refund | 通知一次授权已被部分退款 |

---

# 查询授权列表

URL: /zh-Hans/documentation/cards/search/buscar_autorizacoes

## Request

ENDPOINT /prepaid/card/(card_key)/authorizations
MÉTODO GET
PARÂMETROS from_date, to_date, size, page

## 查询参数

| 字段 | 类型 | 描述 |
|-----------------|--------|----------------------------------------------------------|
| `size`          | int    | 返回的记录数量，默认值为 10。|
| `page`          | int    | 查询的页码，默认值为 0。|
| `from_date`     | string | 查询的开始日期（格式：YYYY-MM-DD）。|
| `to_date`       | string | 查询的结束日期（格式：YYYY-MM-DD）。|

## 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.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"
        }
    ]
}
```

### 错误

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  | 描述 |
|:---------:|:------------:|:-------------------------------|
| 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.|

---

# 通过密钥查询卡片

URL: /zh-Hans/documentation/cards/search/buscar_cartao_by_key

## Request

ENDPOINT /prepaid/card/ CARD_KEY
MÉTODO GET

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|--------------|--------|-----------------------------------|------------|   
| `CARD_KEY` * | string | 卡片识别密钥。| 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"
        }
    ]
}
```

### 错误

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  | 描述 |
|:---------:|:------------:|:-------------------------------|
| 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.|

---

# 查询 PCI 数据

URL: /zh-Hans/documentation/cards/search/buscar_dados_pci

## Request

ENDPOINT /prepaid/card/ CARD_KEY /pci
MÉTODO GET

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|--------------|--------|-----------------------------------|------------|   
| `CARD_KEY` * | string | 卡片识别密钥。| 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"
}
```

### 错误

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  | 描述 |
|:---------:|:------------:|:-------------------------------|
| 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\}.|

---

# 通过卡片密钥查询配送信息

URL: /zh-Hans/documentation/cards/search/buscar_entrega_by_key

## Request

ENDPOINT /card/ CARD_KEY /tracking
MÉTODO GET

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|--------------|--------|-----------------------------------|------------|
| `CARD_KEY` * | string | 卡片识别密钥。| 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"
    }
  ]
}
```

### DeliveryStatus 枚举值

| 枚举值 | 说明 |
|--------------------|---------------------|
| pending            | 待处理 |
| posted             | 已寄出 |
| prepared           | 已备货 |
| in_transfer        | 转运中 |
| in_delivery_unit   | 在配送网点 |
| on_route           | 派送中 |
| attempt_failed     | 尝试失败 |
| awaiting_withdrawal| 等待自提 |
| returning          | 退回中 |
| delivered          | 已送达 |
| returned           | 已退回 |
| canceled           | 已取消 |
| failed             | 失败 |
| resend             | 重新发送 |

### 错误

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  | 描述 |
|:---------:|:------------:|:-------------------------------|
| 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.|

---

# 查询 PCI 密码

URL: /zh-Hans/documentation/cards/search/buscar_senha

## Request

ENDPOINT /prepaid/card/ CARD_KEY /pci/password
MÉTODO GET

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|--------------|--------|-----------------------------------|------------|   
| `CARD_KEY` * | string | 卡片识别密钥。| uuid |

## Response

STATUS 200

Response Body

```json
{
    "pin": "1234"
}
```

### 错误

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  | 描述 |
|:---------:|:------------:|:-------------------------------|
| 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\}.|

---

# 列出卡片

URL: /zh-Hans/documentation/cards/search/listar_cartoes

## Request

ENDPOINT /prepaid/card
MÉTODO GET
PARÂMETROS account_key, size, page

## 查询参数

| 字段 | 类型 | 描述 | 字符数 |
|-----------------|--------|----------------------------------------------------------|------------| 
| `account_key` * | string | QI Tech 支付账户的识别密钥。| uuid |
| `size`          | int    | 返回的记录数量，默认值为 10。| - |
| `page`          | int    | 查询的页码，默认值为 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"
        }
    ]
}
```

### 错误

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  | 描述 |
|:---------:|:------------:|:-------------------------------|
| 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.|

---

# 激活实体卡

URL: /zh-Hans/documentation/cards/status/ativar_cartao

每张实体卡都需要通过随卡一起发送给持卡人的激活码进行激活。

持卡人收到邮寄卡片后，需将激活码告知 QI 的合作伙伴，由合作伙伴通过此端点完成卡片激活。

:::caution 注意
出于安全原因，合作伙伴无法通过 API 查询激活码。

激活码仅在实体卡寄出时独家发送给持卡人。

在集成测试时，可在沙盒环境中通过查询卡片获取该激活码。
:::

## Request

ENDPOINT /prepaid/card/ CARD_KEY /activate
MÉTODO PATCH

### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|--------------|--------|-----------------------------------|------------|   
| `CARD_KEY` * | string | 卡片识别密钥。| uuid |

Request Body

```json
{
    "code": "253615"
}
```

  ### 请求体参数

| 字段 | 类型 | 描述 | 字符数 |
|-----------|--------|-------------------------------|------------|
| `code`  * | string | 卡片激活码。| 6 |

### 错误

STATUS 4XX

Response Body

```json
{
  "title": "Not Acceptable",
  "description": "Invalid activation code [1254].",
  "translation": "Unable to activate card",
  "code": "CARD000020"
}
```

| Code      | Status code  | 描述 |
|:---------:|:------------:|:-------------------------------|
| 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"
    }
}
```

---

# 更新状态

URL: /zh-Hans/documentation/cards/status/update_status_cartao

## Request

ENDPOINT /prepaid/card/ CARD_KEY
MÉTODO PATCH

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|--------------|--------|-----------------------------------|------------|   
| `CARD_KEY` * | string | 卡片识别密钥。| uuid |

Request Body

```json
{
    "status": "blocked"
}
```

  ### 请求体参数

| 字段 | 类型 | 描述 | 字符数 |
|-------------|--------|-------------------|-----------------------------------------------|
| `status`  * | string | 卡片状态。| **[枚举值](#enumeradores-card_status)** |

### card_status 枚举值
| 枚举值 | 说明 | 类型 |
|------------|---------------------|-----------------|
| created    | 已申请创建 | Initial |
| building   | 创建中 | Initial |
| active     | 可进行交易 | Active |
| embossing  | 生产中 | Temporary block |
| blocked    | 已封锁 | Temporary block |
| warning    | 有可疑情况 | Temporary block |
| pending    | 待处理 | Temporary block |
| lost       | 已丢失 | Terminated |
| robbed     | 被抢劫 | Terminated |
| fraud      | 欺诈 | Terminated |
| canceled   | 已取消 | Terminated |
| theft      | 被盗 | Terminated |

### 错误

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  | 描述 |
|:---------:|:------------:|:-------------------------------|
| 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"
    }
}
```

---

# 非接触式（Contactless）配置

URL: /zh-Hans/documentation/cards/update/contactless_cartao

启用或禁用非接触式（contactless）支付功能，用于线下当面支付。

要启用或禁用卡片的非接触式支付功能，卡片状态必须为**有效**或**临时封锁**类型。（有关状态类型的详细信息，请参阅[此处](../../cards/status/update_status_cartao#enumeradores-card_status)）

## Request

ENDPOINT /prepaid/card/ CARD_KEY /contactless
MÉTODO PATCH

### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|--------------|--------|-----------------------------------|------------|   
| `CARD_KEY` * | string | 卡片识别密钥。| uuid |

Request Body

```json
{
    "contactless_enabled": false
}
```

### 请求体参数

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|-----------------------------------|------------|
| `contactless_enabled`  *  | Boolean | 指示是否已启用。| true/false |

## Response

STATUS SUCCESS 200

### 错误

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"
}
```

| Code      | Status code  | 描述 |
|:---------:|:------------:|:-------------------------------|
| 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
    }
}
```

---

# 修改实体卡密码

URL: /zh-Hans/documentation/cards/update/password_cartao

每张实体卡都有一个用于授权交易的密码，必要时可以更新。

要更新卡片密码，卡片状态必须为**Active（有效）**或**Temporary block（临时封锁）**类型。（有关状态的详细信息，请参阅[此处](../../cards/status/update_status_cartao#enumeradores-card_status)）

:::caution 注意
出于安全原因，更新密码时需谨慎，因为这可能影响卡片的授权。

请制定规则以提高密码授权的安全性，例如不使用生日日期、重复数字（如：3333）等。
:::

## Request

ENDPOINT /prepaid/card/ CARD_KEY /password
MÉTODO PATCH

### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|--------------|--------|-----------------------------------|------------|   
| `CARD_KEY` * | string | 卡片识别密钥。| uuid |

Request Body

```json
{
    "pin": "2143"
}
```

  ### 请求体参数

| 字段 | 类型 | 描述 | 字符数 |
|-----------|--------|-----------------------------------------------|------------|
| `pin`  *  | string | 用于授权交易的卡片密码。| 4 |

## Response

STATUS SUCCESS 200

### 错误

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"
}
```

| Code      | Status code  | 描述 |
|:---------:|:------------:|:-------------------------------|
| 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"
    }
}
```

---

# 更新配送地址

URL: /zh-Hans/documentation/cards/update/update_delivery_address

当发现地址有误或配送三次失败时，可通过更新配送地址来进行纠正。

## Request

ENDPOINT /account/ ACCOUNT_KEY /card/ CARD_KEY /address
MÉTODO POST

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | 账户的唯一识别密钥，格式为 uuid v4 | 36 |
| `card_key`              | uuidv4 | 卡片的唯一识别密钥，格式为 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"},
    ],
}
```

### 请求体

### address 对象

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|--------|----------------------------------------------------|------------|
| `street` *                | string | 街道/路名 | 100 |
| `number`                  | string | 门牌号 | 10 |
| `neighborhood` *          | string | 街区/社区 | 100 |
| `postal_code` *           | string | 邮政编码 | 8 |
| `city` *                  | string | 城市 | 100 |
| `complement`              | string | 补充信息 | 100 |
| `reference`               | string | 参考地标 | 100 |
| `notes`                   | string array | 地址相关备注 | 100 |
| `phones`                  | object array | 联系电话 | **[phone 对象](#objeto-phone)** |
| `state` *                 | string | 州（UF）| **[state 枚举值](#enumeradores-state)** |
| `address_type` *          | string | 地址类型 | **[address_type 枚举值](#enumeradores-address_type)** |

:::caution 注意！
`number` 字段为可选项。无门牌号的地址可以不填写此字段。
:::

:::caution 注意！
最多可发送 两个 联系电话和 四条 备注。若无联系电话和/或备注，则不应发送这些字段（`phones` 和 `notes`）。
:::

### phone 对象

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------------|--------|----------------------------------------------|------------|
| `international_dial_code` *     | string | 国际区号（DDI）| 2 |
| `area_code` *                   | string | 地区区号（DDD）| 2 |
| `number` *                      | string | 电话号码 | 9 |

### address_type 枚举值

| 枚举值 | 描述 |
|--------------------|--------------------------|
| residential        | 住宅地址 |
| commercial         | 商业地址 |
| other              | 其他类型地址 |

### state 枚举值

| 枚举值 | 描述 |
|--------------------|-----------------------|
| 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                 | 例外 |

## 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"
  }
}
```

### 响应体参数

| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|--------|-------------------------------------------------------------------------------------------------|------------|
| `card_key` *            | uuidv4 | 卡片的唯一识别密钥，格式为 uuid v4 | 36 |
| `tracking_code` *       | string | 卡片配送的物流追踪码 | 14 |
| `address`               | object | `address` 类型对象，与请求中发送的内容类似 | **[address 对象](#objeto-address)** |

## 错误响应

STATUS 4xx

Response Body: Error

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title` | 描述（英文）<br/>`description` | 描述（葡文）<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. |

---

# 非接触式（Contactless）配置

URL: /zh-Hans/documentation/cartao_pos_pago/cartao/atualizar/atualizar_contactless

启用或禁用非接触式（contactless）支付功能，用于线下当面支付。

要启用或禁用卡片的非接触式支付功能，卡片状态必须为**有效**或**临时封锁**类型。（有关状态类型的详细信息，请参阅[此处](../../credit_cards/status/atualiar_status_cartao#enumeradores-card_status)）

## Request

ENDPOINT /wallet/ WALLET_KEY /card/ CARD_KEY /contactless
MÉTODO PATCH

### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|--------------|--------|-----------------------------------|------------|
| `WALLET_KEY` * | string | 钱包识别密钥。| uuid |    
| `CARD_KEY` * | string | 卡片识别密钥。| uuid |

Request Body

```json
{
    "contactless_enabled": false
}
```

### 请求体参数

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|-----------------------------------|------------|
| `contactless_enabled`  *  | Boolean | 指示是否已启用。| 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
}
```

### 错误

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"
}
```

| Code      | Status code  | 描述 |
|:---------:|:------------:|:-------------------------------|
| 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.|

---

# 更新配送地址

URL: /zh-Hans/documentation/cartao_pos_pago/cartao/atualizar/atualizar_endereco_entrega

当发现地址有误或配送三次失败时，可通过更新配送地址来进行纠正。

## Request

ENDPOINT /wallet/ WALLET_KEY /card/ CARD_KEY /address
MÉTODO PATCH

### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|--------------|--------|-----------------------------------|------------|
| `WALLET_KEY` * | string | 钱包识别密钥。| uuid |    
| `CARD_KEY` * | string | 卡片识别密钥。| 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"},
    ],
}
```

### 请求体

### address 对象

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|--------|----------------------------------------------------|------------|
| `street` *                | string | 街道/路名 | 100 |
| `number` *                | string | 门牌号 | 10 |
| `neighborhood` *          | string | 街区/社区 | 100 |
| `postal_code` *           | string | 邮政编码 | 8 |
| `city` *                  | string | 城市 | 100 |
| `complement`              | string | 补充信息 | 100 |
| `reference`               | string | 参考地标 | 100 |
| `notes`                   | string array | 地址相关备注 | 100 |
| `phones`                  | object array | 联系电话 | **[phone 对象](#objeto-phone)** |
| `state` *                 | string | 州（UF）| **[state 枚举值](#enumeradores-state)** |
| `address_type` *          | string | 地址类型 | **[address_type 枚举值](#enumeradores-address_type)** |

:::caution 注意！
最多可发送 两个 联系电话和 四条 备注。若无联系电话和/或备注，则不应发送这些字段（`phones` 和 `notes`）。
:::

### phone 对象

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------------|--------|----------------------------------------------|------------|
| `international_dial_code` *     | string | 国际区号（DDI）| 2 |
| `area_code` *                   | string | 地区区号（DDD）| 2 |
| `number` *                      | string | 电话号码 | 9 |

### address_type 枚举值

| 枚举值 | 描述 |
|--------------------|--------------------------|
| residential        | 住宅地址 |
| commercial         | 商业地址 |
| other              | 其他类型地址 |

### state 枚举值

| 枚举值 | 描述 |
|--------------------|-----------------------|
| 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                 | 例外 |

## 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"
  }
}
```

### 响应体参数

| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|--------|-------------------------------------------------------------------------------------------------|------------|
| `card_key` *            | uuidv4 | 卡片的唯一识别密钥，格式为 uuid v4 | 36 |
| `tracking_code` *       | string | 卡片配送的物流追踪码 | 14 |
| `address`               | object | `address` 类型对象，与请求中发送的内容类似 | **[address 对象](#objeto-address)** |

## 错误响应

STATUS 4xx

Response Body: Error

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title` | 描述（英文）<br/>`description` | 描述（葡文）<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. |

---

# 修改实体卡密码

URL: /zh-Hans/documentation/cartao_pos_pago/cartao/atualizar/atualizar_senha

每张实体卡都有一个用于授权交易的密码，必要时可以更新。

要更新卡片密码，卡片状态必须为**Active（有效）**或**Temporary block（临时封锁）**类型。（有关状态的详细信息，请参阅[此处](../../credit_cards/status/atualiar_status_cartao#enumeradores-card_status)）

:::caution 注意
出于安全原因，更新密码时需谨慎，因为这可能影响卡片的授权。

请制定规则以提高密码授权的安全性，例如不使用生日日期、重复数字（如：3333）等。
:::

## Request

ENDPOINT /wallet/ WALLET_KEY /card/ CARD_KEY /password
MÉTODO PATCH

### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|--------------|--------|-----------------------------------|------------| 
| `WALLET_KEY` * | string | 钱包识别密钥。| uuid |   
| `CARD_KEY` * | string | 卡片识别密钥。| uuid |

Request Body

```json
{
    "pin": "2143"
}
```

  ### 请求体参数

| 字段 | 类型 | 描述 | 字符数 |
|-----------|--------|-----------------------------------------------|------------|
| `pin`  *  | string | 用于授权交易的卡片密码。| 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
}
```

### 错误

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"
}
```

| Code      | Status code  | 描述 |
|:---------:|:------------:|:-------------------------------|
| 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.|

---

# 场景模拟

URL: /zh-Hans/documentation/cartao_pos_pago/cartao/atualizar/simulacao_de_cenarios

本页面介绍如何模拟后付费卡物流追踪状态的更新，以测试配送更新流程。这些模拟对于正式验收测试和集成测试非常有用。

:::info 说明

这些请求模拟物流追踪状态更新，并返回带有更新后追踪数据的 HTTP 状态。

:::

## 1 - 模拟物流追踪状态更新

模拟后付费卡物流追踪状态的更新，允许在配送流程的不同状态之间进行转换。更新操作会在物流历史中创建一个新事件。

ENDPOINT /mock/wallet/ WALLET_KEY /card/ CARD_KEY /tracking

MÉTODO PATCH

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|------------------------------|--------|----------------------------------------------|------------|
| `wallet_key` *               | string | UUID v4 格式的钱包唯一密钥 | 36 |
| `card_key` *                 | string | UUID v4 格式的卡片唯一密钥 | 36 |

Request Body

```json
{
  "status": "posted",
  "place": "São Paulo - SP",
  "description": "Postado - logística iniciada",
  "reason": "Processamento concluído"
}
```

### 请求体字段说明

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------------------------------|---------|------------------------------------------------------------------------------------|--------------|
| `status` *                               | string  | 新的物流状态 | **[status 枚举值](#enumeradores-status)** |
| `place` *                                | string  | 事件发生地点 | 100 |
| `description` *                          | string  | 物流事件描述 | 255 |
| `reason`                                 | string  | 事件的附加原因（可选）| 100 |

### status 枚举值

| 枚举值 | 描述 |
|-----------------------------|-----------------------------------------------------------------------------------|
| `pending`                   | 待处理 - 等待初始处理 |
| `posted`                    | 已寄出 - 物流已启动 |
| `prepared`                  | 已备货 - 卡片已准备好转运 |
| `in_transfer`               | 转运中 - 卡片在途中 |
| `in_delivery_unit`          | 在配送网点 - 卡片已到达配送分发单位 |
| `on_route`                  | 派送中 - 卡片已出发配送 |
| `attempt_failed`            | 尝试失败 - 配送尝试未成功 |
| `awaiting_withdrawal`       | 等待自提 - 卡片可供自取 |
| `returning`                 | 退回中 - 卡片正在退回处理中 |
| `delivered`                 | 已送达 - 卡片成功送达 |
| `returned`                  | 已退回 - 卡片已被退回 |
| `canceled`                  | 已取消 - 物流追踪已取消 |
| `failed`                    | 失败 - 配送流程失败 |
| `resend`                    | 重新发送 - 卡片将被重新发送 |
| `redispatch_error`          | 重新调度错误 - 重新调度卡片时出错 |
| `waiting_for_address_update`| 等待地址更新 - 等待地址确认 |

### Response

STATUS 204

Response Body

```json
{}
```

:::tip 行为说明
- 模拟操作会更新物流追踪状态并在历史记录中创建新事件
- 状态转换遵循特定顺序并进行验证：
  - 不能回退到之前的状态（特殊状态除外）
  - 不能从最终状态（`delivered`、`returned`、`canceled`、`failed`）更改状态
  - 不能将 `waiting_for_address_update` 转换为 `pending` 以外的状态
  - 不能从最终状态转换为 `waiting_for_address_update`
  - 特殊状态（`attempt_failed`、`resend`、`redispatch_error`）可在初始状态之后随时使用
- `reason` 字段为可选项，若提供则会被附加到事件描述中
:::

---

# 通过密钥查询卡片

URL: /zh-Hans/documentation/cartao_pos_pago/cartao/busca/buscar_cartao_por_chave

## Request

ENDPOINT /wallet/ WALLET_KEY /card/ CARD_KEY
MÉTODO GET

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|--------------|--------|-----------------------------------|------------| 
| `WALLET_KEY` * | string | 钱包识别密钥。| uuid |    
| `CARD_KEY` * | string | 卡片识别密钥。| 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
}
```

### 错误

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  | 描述 |
|:---------:|:------------:|:-------------------------------|
| 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.|

---

# 通过卡片密钥查询配送信息

URL: /zh-Hans/documentation/cartao_pos_pago/cartao/busca/buscar_dados_entrega_por_chave

## Request

ENDPOINT /wallet/ WALLET_KEY /card/ CARD_KEY /tracking
MÉTODO GET

### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|--------------|--------|-----------------------------------|------------|
| `WALLET_KEY` * | string | 钱包识别密钥。| uuid |    
| `CARD_KEY` * | string | 卡片识别密钥。| 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"
    }
  ]
}
```

### DeliveryStatus 枚举值

| 枚举值 | 说明 |
|--------------------|---------------------|
| pending            | 待处理 |
| posted             | 已寄出 |
| prepared           | 已备货 |
| in_transfer        | 转运中 |
| in_delivery_unit   | 在配送网点 |
| on_route           | 派送中 |
| attempt_failed     | 尝试失败 |
| awaiting_withdrawal| 等待自提 |
| returning          | 退回中 |
| delivered          | 已送达 |
| returned           | 已退回 |
| canceled           | 已取消 |
| failed             | 失败 |
| resend             | 重新发送 |

### 错误

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  | 描述 |
|:---------:|:------------:|:-------------------------------|
| 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.|

---

# 查询 PCI 数据

URL: /zh-Hans/documentation/cartao_pos_pago/cartao/busca/buscar_dados_pci

## Request

ENDPOINT /wallet/ WALLET_KEY /card/ CARD_KEY /pci
MÉTODO GET

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|--------------|--------|-----------------------------------|------------|  
| `WALLET_KEY` * | string | 钱包识别密钥。| uuid |   
| `CARD_KEY` * | string | 卡片识别密钥。| 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"
}
```

### 错误

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  | 描述 |
|:---------:|:------------:|:-------------------------------|
| 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\}.|

---

# 查询 PCI 密码

URL: /zh-Hans/documentation/cartao_pos_pago/cartao/busca/buscar_senha

## Request

ENDPOINT /wallet/ WALLET_KEY /card/ CARD_KEY /pci/password
MÉTODO GET

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|--------------|--------|-----------------------------------|------------| 
| `WALLET_KEY` * | string | 钱包识别密钥。| uuid |    
| `CARD_KEY` * | string | 卡片识别密钥。| uuid |

## Response

STATUS 200

Response Body

```json
{
    "pin": "1234"
}
```

### 错误

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  | 描述 |
|:---------:|:------------:|:-------------------------------|
| 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\}.|

---

# 激活实体卡

URL: /zh-Hans/documentation/cartao_pos_pago/cartao/status/ativar_cartao

每张实体卡都需要通过随卡一起发送给持卡人的激活码进行激活。

持卡人收到邮寄卡片后，需将激活码告知 QI 的合作伙伴，由合作伙伴通过此端点完成卡片激活。

:::caution 注意
出于安全原因，合作伙伴无法通过 API 查询激活码。

激活码仅在实体卡寄出时独家发送给持卡人。

在集成测试时，可在沙盒环境中通过查询卡片获取该激活码。
:::

## Request

ENDPOINT /wallet/ WALLET_KEY /card/ CARD_KEY /activate
MÉTODO PATCH

### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|--------------|--------|-----------------------------------|------------| 
| `WALLET_KEY` * | string | 钱包识别密钥。| uuid |  
| `CARD_KEY` * | string | 卡片识别密钥。| uuid |

Request Body

```json
{
    "code": "253615"
}
```

  ### 请求体参数

| 字段 | 类型 | 描述 | 字符数 |
|-----------|--------|-------------------------------|------------|
| `code`  * | string | 卡片激活码。| 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
}
```

### 错误

STATUS 4XX

Response Body

```json
{
  "title": "Not Acceptable",
  "description": "Invalid activation code [1254].",
  "translation": "Unable to activate card",
  "code": "CARD000020"
}
```

| Code      | Status code  | 描述 |
|:---------:|:------------:|:-------------------------------|
| 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.|

---

# 更新状态

URL: /zh-Hans/documentation/cartao_pos_pago/cartao/status/atualizar_status_cartao

## Request

ENDPOINT /wallet/ WALLET_KEY /card/ CARD_KEY
MÉTODO PATCH

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|--------------|--------|-----------------------------------|------------| 
| `WALLET_KEY` * | string | 钱包识别密钥。| uuid |   
| `CARD_KEY` * | string | 卡片识别密钥。| uuid |

Request Body

```json
{
    "status": "blocked"
}
```

  ### 请求体参数

| 字段 | 类型 | 描述 | 字符数 |
|-------------|--------|-------------------|-----------------------------------------------|
| `status`  * | string | 卡片状态。| **[枚举值](#enumeradores-card_status)** |

### card_status 枚举值
| 枚举值 | 说明 | 类型 |
|------------|---------------------|-----------------|
| created    | 已申请创建 | Initial |
| building   | 创建中 | Initial |
| active     | 可进行交易 | Active |
| embossing  | 生产中 | Temporary block |
| blocked    | 已封锁 | Temporary block |
| warning    | 有可疑情况 | Temporary block |
| pending    | 待处理 | Temporary block |
| lost       | 已丢失 | Terminated |
| robbed     | 被抢劫 | Terminated |
| fraud      | 欺诈 | Terminated |
| canceled   | 已取消 | Terminated |
| theft      | 被盗 | Terminated |

### 错误

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  | 描述 |
|:---------:|:------------:|:-------------------------------|
| 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"
    }
}
```

---

# 修改钱包额度

URL: /zh-Hans/documentation/cartao_pos_pago/faturas/carteira/alteracao_de_limite

修改钱包额度允许更改现有钱包的后付费信用额度金额。

## Request

ENDPOINT /wallet/ WALLET_KEY /wallet_limit/ WALLET_LIMIT_KEY
MÉTODO PATCH

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|------------------------------|--------|----------------------------------------------|------------|
| `wallet_key` *               | uuidv4 | UUID v4 格式的钱包唯一密钥 | 36 |
| `wallet_limit_key` *         | uuidv4 | UUID v4 格式的钱包额度唯一密钥 | 36 |

Request Body

```json
{
  "limit_amount": 10000.00
}
```

### 请求体参数

| 字段 | 类型 | 描述 | 字符数 |
|------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `limit_amount` *             | float   | 新的后付费信用额度金额 | - |

:::info 说明
- 新额度金额必须大于或等于已用额度（`used_limit`）
- 只能更新 `postpaid_credit_limit` 类型的额度
- 只有 `default` 类型的钱包可以更新其额度
- 额度更新也会同步更新卡片服务中的额度
:::

## Response

STATUS 200

Response Body：钱包额度已更新

```json
{
  "wallet_limit_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "limit_type": "postpaid_credit_limit",
  "limit_amount": 10000.00,
  "used_limit": 2500.00
}
```

### 响应体参数

| 字段 | 类型 | 描述 | 字符数 |
|----------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `wallet_limit_key` *             | uuidv4  | UUID v4 格式的已更新额度唯一识别密钥 | 36 |
| `limit_type` *                   | string  | 已更新的额度类型 | **[limit_type 枚举值](#enumeradores-limit_type)** |
| `limit_amount` *                 | float   | 更新后的新后付费信用额度金额 | - |
| `used_limit` *                   | float   | 更新时的已用额度金额 | - |

### limit_type 枚举值

| 枚举值 | 描述 |
|-------------------------|-----------------------------------------|
| postpaid_credit_limit   | 后付费信用额度 |

## 错误响应

STATUS 4xx

Response Body: Error

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title` | 描述（英文）<br/>`description` | 描述（葡文）<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                                                                                   |

---

# 通过密钥查询钱包条目

URL: /zh-Hans/documentation/cartao_pos_pago/faturas/carteira/consulta_entrada_por_chave

通过密钥查询钱包条目将返回特定条目的完整详情，包括所有相关的账单项目。

## Request

ENDPOINT /wallet/ WALLET_KEY /wallet_entry/ WALLET_ENTRY_KEY
MÉTODO GET

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|-------------------|--------|----------------------------------------------|------------|
| `wallet_key`      | uuidv4 | UUID v4 格式的钱包唯一密钥 | 36 |
| `wallet_entry_key`| uuidv4 | UUID v4 格式的条目唯一密钥 | 36 |

## Response

STATUS 200

Response Body：钱包条目详情

```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"
}
```

### 响应体参数

| 字段 | 类型 | 描述 | 字符数 |
|------------------------------|--------------|---------------------------------------|---------------------------------------------|
| `wallet_entry_key` *         | uuidv4       | uuid v4 格式的条目唯一识别密钥 | 36 |
| `wallet_entry_amount` *      | float  | 条目金额 | - |
| `wallet_entry_settlement_key` * | string    | 条目的清算密钥 | - |
| `wallet_entry_type` *        | string       | 钱包条目类型 | **[wallet_entry_type 枚举值](#enumeradores-wallet_entry_type)** |
| `wallet_entry_status` *      | string       | 钱包条目状态 | **[wallet_entry_status 枚举值](#enumeradores-wallet_entry_status)** |
| `invoice_items` *            | object array | 相关账单项目 | **[invoice_item 对象](#objeto-invoice_item)** |
| `created_at` *               | string       | 创建日期（ISO 8601 UTC 格式）| - |

### invoice_item 对象

| 字段 | 类型 | 描述 | 字符数 |
|------------------------------------|---------|-----------------------------------------------------------------------------------|------------|
| `invoice_item_key` *               | uuidv4  | uuid v4 格式的账单项目唯一识别密钥 | 36 |
| `invoice_key` *                    | uuidv4  | uuid v4 格式的账单唯一识别密钥 | 36 |
| `wallet_entry_key`                 | uuidv4  | uuid v4 格式的钱包条目唯一识别密钥 | 36 |
| `payment_instrument_entry_key`     | uuidv4  | uuid v4 格式的支付工具条目唯一识别密钥 | 36 |
| `installment_number` *             | integer | 分期期数 | - |
| `invoice_description` *            | string  | 账单项目描述 | - |
| `amount` *                         | float  | 项目金额 | - |
| `used_limit` *                     | float  | 已用额度 | - |
| `invoice_item_status` *            | string  | 账单项目状态 | **[invoice_item_status 枚举值](#enumeradores-invoice_item_status)** |
| `invoice_item_due_date` *          | string  | 项目到期日（YYYY-MM-DD 格式）| 10 |
| `created_at` *                     | string  | 创建日期（ISO 8601 UTC 格式）| - |

### wallet_entry_type 枚举值

| 枚举值 | 描述 |
|-------------------|-----------------------------------------------------------------------------------|
| revolving_credit  | 循环信用 |
| payroll_withdraw  | 工资提款 |
| payroll_overdue   | 工资逾期 |

:::info 钱包条目类型
- **`revolving_credit`**：为客户提供的信用额度
- **`payroll_withdraw`**：因提取额度而产生的债务，每月从 INSS 中扣除
- **`payroll_overdue`**：因未支付账单而产生的债务，每月也从 INSS 中扣除
:::

### wallet_entry_status 枚举值

| 枚举值 | 描述 |
|------------|-----------------------------------------|
| concluded     | 条目已完成 |

### invoice_item_status 枚举值

| 枚举值 | 描述 |
|------------|-----------------------------------------|
| concluded    | 项目已完成 |
| canceled  | 项目已取消 |

## 错误响应

STATUS 4xx

Response Body: Error

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title` | 描述（英文）<br/>`description` | 描述（葡文）<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                                |

---

# 通过密钥查询钱包

URL: /zh-Hans/documentation/cartao_pos_pago/faturas/carteira/consulta_por_chave

通过密钥查询钱包将返回特定钱包的完整详情，包括其账单配置和信用额度。

## Request

ENDPOINT /wallet/ WALLET_KEY
MÉTODO GET

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|--------|----------------------------------------------|------------|
| `wallet_key`              | uuidv4 | 钱包的唯一识别密钥 | 36 |

## Response

STATUS 200

Response Body：钱包详情

```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"
}
```

### 响应体参数

| 字段 | 类型 | 描述 | 字符数 |
|------------------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `wallet_key` *                           | string  | 钱包的唯一识别密钥 | 36 |
| `owner_person_key` *                     | string  | 钱包所有者的识别密钥 | 36 |
| `owner_document_number` *                | string  | 钱包所有者的 CPF/CNPJ | 11-14 |
| `invoice_configuration` *                | object  | 钱包的账单配置 | **[invoice_configuration 对象](#objeto-invoice_configuration)** |
| `wallet_status` *                         | string  | 钱包的当前状态 | **[wallet_status 枚举值](#enumeradores-wallet_status)** |
| `wallet_type` *                           | string  | 钱包类型 | **[wallet_type 枚举值](#enumeradores-wallet_type)** |
| `wallet_limits` *                         | array   | 钱包额度列表 | **[wallet_limits 对象](#objeto-wallet_limits)** |
| `created_at` *                            | string  | 创建日期（ISO 8601 UTC 格式）| - |

### invoice_configuration 对象

| 字段 | 类型 | 描述 | 字符数 |
|------------------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `closing_date_configuration` *           | object  | 账单结账日配置 | **[closing_date_configuration 对象](#objeto-closing_date_configuration)** |
| `due_date_configuration` *               | object  | 账单到期日配置 | **[due_date_configuration 对象](#objeto-due_date_configuration)** |
| `invoice_payment_type` *                 | string  | 账单支付类型 | **[invoice_payment_type 枚举值](#enumeradores-invoice_payment_type)** |
| `interest_base`                         | string  | 利息计算基础 | **[interest_base 枚举值](#enumeradores-interest_base)** |
| `monthly_interest_percentage`           | float  | 逾期月利率（0-100）| - |
| `fine_percentage`                       | float  | 逾期罚款比例（0-100）| - |

:::info
注意：`payroll` 类型的钱包不包含 `interest_base`、`monthly_interest_percentage` 和 `fine_percentage` 字段。
:::

### closing_date_configuration 对象

#### 固定配置（`type: "fixed"`）

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|----------------------------------------------|------------|
| `type` *                  | string  | 配置类型（必须为 "fixed"）| - |
| `fixed_day` *             | integer | 每月固定结账日（1-27）| - |

#### 基于规则的配置（`type: "rule_based"`）

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|----------------------------------------------|------------|
| `type` *                  | string  | 配置类型（必须为 "rule_based"）| - |
| `rule` *                  | object  | 日期计算规则 | **[rule 对象（closing_date_configuration）](#objeto-rule-closing_date_configuration)** |

### rule 对象（closing_date_configuration）

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|----------------------------------------------|------------|
| `day_of_week` *          | string  | 星期几 | **[day_of_week 枚举值](#enumeradores-day_of_week)** |
| `occurrence` *            | string  | 当月第几次出现 | **[occurrence 枚举值](#enumeradores-occurrence)** |
| `fallback_strategy` *     | string  | 非工作日策略 | **[fallback_strategy 枚举值](#enumeradores-fallback_strategy)** |

### due_date_configuration 对象

#### 固定配置（`type: "fixed"`）

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|----------------------------------------------|------------|
| `type` *                  | string  | 配置类型（必须为 "fixed"）| - |
| `offset_months` *         | integer | 从结账日起的月份偏移量 | - |
| `fixed_day` *             | integer | 每月固定到期日（2-27）| - |

#### 基于规则的配置（`type: "rule_based"`）

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|----------------------------------------------|------------|
| `type` *                  | string  | 配置类型（必须为 "rule_based"）| - |
| `offset_months` *         | integer | 从结账日起的月份偏移量 | - |
| `rule` *                  | object  | 日期计算规则 | **[rule 对象（due_date_configuration）](#objeto-rule-due_date_configuration)** |

### rule 对象（due_date_configuration）

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|----------------------------------------------|------------|
| `day_of_week` *          | string  | 星期几 | **[day_of_week 枚举值](#enumeradores-day_of_week)** |
| `occurrence` *            | string  | 当月第几次出现 | **[occurrence 枚举值](#enumeradores-occurrence)** |
| `fallback_strategy` *     | string  | 非工作日策略 | **[fallback_strategy 枚举值](#enumeradores-fallback_strategy)** |

### wallet_limits 对象

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|----------------------------------------------|------------|
| `limit_type` *            | string  | 额度类型 | **[limit_type 枚举值](#enumeradores-limit_type)** |
| `limit_amount` *          | float  | 总额度金额 | - |
| `used_limit` *            | float  | 已用额度金额 | - |

### wallet_status 枚举值

| 枚举值 | 描述 |
|--------------------|-----------------------------------------|
| pending_analysis   | 等待 KYC 分析的钱包 |
| active             | 已激活且可使用的钱包 |
| rejected           | 已拒绝的钱包 |

### wallet_type 枚举值

| 枚举值 | 描述 |
|-------------|------------------------------|
| default     | 标准钱包 |
| payroll     | 薪资代扣卡钱包 |

### limit_type 枚举值

| 枚举值 | 描述 |
|---------------------------|------------------------------|
| postpaid_credit_limit     | 后付费信用额度 |
| payroll_withdraw_limit    | 工资提款额度（工资/代扣）|

:::info 薪资卡 Wallet 的额度
`payroll` 类型的钱包有两种不同的额度：
- **`postpaid_credit_limit`**：用于消费和卡片交易的后付费信用额度
- **`payroll_withdraw_limit`**：工资提款（工资/代扣）的专用额度，每月自动从客户工资中扣除
:::

### day_of_week 枚举值

| 枚举值 | 描述 |
|-------------|-----------|
| monday     | 星期一 |
| tuesday    | 星期二 |
| wednesday  | 星期三 |
| thursday   | 星期四 |
| friday     | 星期五 |
| saturday   | 星期六 |
| sunday     | 星期日 |

### occurrence 枚举值

| 枚举值 | 描述 |
|-------------|-----------|
| first      | 第一次出现 |
| second     | 第二次出现 |
| third      | 第三次出现 |
| fourth     | 第四次出现 |
| last       | 最后一次出现 |

### fallback_strategy 枚举值

| 枚举值 | 描述 |
|----------------------|------------------------------|
| next_business_day    | 下一个工作日 |
| previous_business_day| 上一个工作日 |
| same_day             | 当天 |

### invoice_payment_type 枚举值

| 枚举值 | 描述 |
|-------------|----------------|
| bank_slip  | 银行票据（Boleto bancário）|

### interest_base 枚举值

| 枚举值 | 描述 |
|-----------------|------------------|
| calendar_days   | 自然日 |

### wallet_limits 对象

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|----------------------------------------------|------------|
| `wallet_limit_key` *             | uuidv4  | UUID v4 格式的已更新额度唯一识别密钥 | 36 |
| `limit_type` *            | string  | 额度类型 | **[limit_type 枚举值](#enumeradores-limit_type)** |
| `limit_amount` *          | float  | 总额度金额 | - |
| `used_limit` *            | float  | 已用额度金额 | - |

### limit_type 枚举值

| 枚举值 | 描述 |
|---------------------------|------------------------------|
| postpaid_credit_limit     | 后付费信用额度 |

## 错误响应

STATUS 4xx

Response Body: Error

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title` | 描述（英文）<br/>`description` | 描述（葡文）<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                                                                          |

---

# 创建钱包（Wallet）

URL: /zh-Hans/documentation/cartao_pos_pago/faturas/carteira/criacao_de_carteira

创建钱包（wallet）允许为个人或法人注册新的信用钱包。

:::info 什么是 Wallet
**wallet** 代表客户的账单，作为管理所有关联支付手段的集中器。重要须知：

- **一个 wallet = 一张账单**：每个钱包对应一个特定客户（由 CPF/CNPJ 标识）的账单
- **多种支付手段**：同一个 wallet 可以有不同的支付工具（卡片、PIX 等）
- **独立的工具**：创建 wallet 后，需要分别创建支付工具（信用卡、额度等）
- **集中管理**：wallet 集中管理与该客户相关的所有操作和配置
:::

## 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_control_key`    | uuidv4     | 客户使用的请求唯一识别密钥 | 36 |
| `owner`                                  | object  | 钱包所有者数据（个人或法人）| **[owner 对象](#objeto-owner)** |
| `person_key`                             | string  | UUID v4 格式的人员唯一识别密钥 | 36 |
| `invoice_configuration` *                | object  | 账单结账和到期配置 | **[invoice_configuration 对象](#objeto-invoice_configuration)** |
| `limits` *                               | object  | 钱包信用额度 | **[limits 对象](#objeto-limits)** |

:::info 条件字段
- **`owner`**：未发送 `person_key` 时为必填项
- **`person_key`**：未发送 `owner` 时为必填项
- 两个字段互斥
:::

### owner 对象

#### 个人（`person_type: "natural"`）

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|--------|----------------------------------------------|------------|
| `person_type` *           | string | 人员类型（必须为 "natural"）| - |
| `name` *                  | string | 姓名 | 100 |
| `document_number` *       | string | CPF（仅数字）| 11 |
| `birthdate` *             | string | 出生日期（YYYY-MM-DD 格式）| 10 |
| `email` *                 | string | 联系邮箱 | 254 |
| `phone` *                 | object | 联系电话 | **[phone 对象](#objeto-phone)** |
| `address` *               | object | 完整地址 | **[address 对象](#objeto-address)** |

#### 法人（`person_type: "legal"`）

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|--------|----------------------------------------------|------------|
| `person_type` *           | string | 人员类型（必须为 "legal"）| - |
| `name` *                  | string | 公司法定名称 | 100 |
| `trading_name` *          | string | 公司商业名称 | 100 |
| `document_number` *       | string | CNPJ（仅数字）| 14 |
| `foundation_date` *       | string | 成立日期（YYYY-MM-DD 格式）| 10 |
| `email` *                 | string | 联系邮箱 | 254 |
| `phone` *                 | object | 联系电话 | **[phone 对象](#objeto-phone)** |
| `address` *               | object | 完整地址 | **[address 对象](#objeto-address)** |
| `legal_representatives` * | array  | 法定代表人列表（个人）| - |

### phone 对象

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|--------|----------------------------------------------|------------|
| `country_code` *          | string | 国家代码（DDI）| 2-3 |
| `area_code` *             | string | 地区代码（DDD）| 2 |
| `number` *                | string | 电话号码 | 8-9 |

### address 对象

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|--------|----------------------------------------------|------------|
| `street` *                | string | 街道/路名 | 500 |
| `number` *                | string | 门牌号 | 10 |
| `neighborhood` *          | string | 街区/社区 | 100 |
| `postal_code` *           | string | 邮政编码（仅数字）| 8 |
| `city` *                  | string | 城市 | 100 |
| `state` *                 | string | 州（UF）| **[state 枚举值](#enumeradores-state)** |
| `complement`              | string | 地址补充信息 | 500 |

### state 枚举值

| 枚举值 | 描述 |
|-------------|----------------|
| 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          | 例外 |

### invoice_configuration 对象

| 字段 | 类型 | 描述 | 字符数 |
|------------------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `closing_date_configuration` *           | object  | 账单结账日配置 | **[closing_date_configuration 对象](#objeto-closing_date_configuration)** |
| `due_date_configuration` *               | object  | 账单到期日配置 | **[due_date_configuration 对象](#objeto-due_date_configuration)** |
| `invoice_payment_type` *                 | string  | 账单支付类型 | **[invoice_payment_type 枚举值](#enumeradores-invoice_payment_type)** |
| `interest_base` *                        | string  | 利息计算基础 | **[interest_base 枚举值](#enumeradores-interest_base)** |
| `monthly_interest_percentage` *          | float  | 逾期月利率（0-100）| - |
| `fine_percentage` *                      | float  | 逾期罚款比例（0-100）| - |

### closing_date_configuration 对象

#### 固定配置（`type: "fixed"`）

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|----------------------------------------------|------------|
| `type` *                  | string  | 配置类型（必须为 "fixed"）| - |
| `fixed_day` *             | integer | 每月固定结账日（1-27）| - |

#### 基于规则的配置（`type: "rule_based"`）

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|----------------------------------------------|------------|
| `type` *                  | string  | 配置类型（必须为 "rule_based"）| - |
| `rule` *                  | object  | 日期计算规则 | **[rule 对象（closing_date_configuration）](#objeto-closing_date_configuration)** |

### rule 对象（closing_date_configuration）

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|----------------------------------------------|------------|
| `day_of_week` *          | string  | 星期几 | **[day_of_week 枚举值](#enumeradores-day_of_week)** |
| `occurrence` *            | string  | 当月第几次出现 | **[occurrence 枚举值](#enumeradores-occurrence)** |
| `fallback_strategy` *     | string  | 非工作日策略 | **[fallback_strategy 枚举值](#enumeradores-fallback_strategy)** |

### due_date_configuration 对象

#### 固定配置（`type: "fixed"`）

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|----------------------------------------------|------------|
| `type` *                  | string  | 配置类型（必须为 "fixed"）| - |
| `offset_months` *         | integer | 从结账日起的月份偏移量 | - |
| `fixed_day` *             | integer | 每月固定到期日（2-27）| - |

#### 基于规则的配置（`type: "rule_based"`）

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|----------------------------------------------|------------|
| `type` *                  | string  | 配置类型（必须为 "rule_based"）| - |
| `offset_months` *         | integer | 从结账日起的月份偏移量 | - |
| `rule` *                  | object  | 日期计算规则 | **[rule 对象（closing_date_configuration）](#objeto-due_date_configuration)** |

### rule 对象（due_date_configuration）

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|----------------------------------------------|------------|
| `day_of_week` *          | string  | 星期几 | **[day_of_week 枚举值](#enumeradores-day_of_week)** |
| `occurrence` *            | string  | 当月第几次出现 | **[occurrence 枚举值](#enumeradores-occurrence)** |
| `fallback_strategy` *     | string  | 非工作日策略 | **[fallback_strategy 枚举值](#enumeradores-fallback_strategy)** |

:::caution 日期验证
- 到期日必须至少在结账日后 2 天
- 对于基于规则的配置，结账和到期的星期几之间必须至少相差一天（例如：周一结账，周三到期）
:::

### day_of_week 枚举值

| 枚举值 | 描述 |
|-------------|-----------|
| monday     | 星期一 |
| tuesday    | 星期二 |
| wednesday  | 星期三 |
| thursday   | 星期四 |
| friday     | 星期五 |
| saturday   | 星期六 |
| sunday     | 星期日 |

### occurrence 枚举值

| 枚举值 | 描述 |
|-------------|-----------|
| first      | 第一次出现 |
| second     | 第二次出现 |
| third      | 第三次出现 |
| fourth     | 第四次出现 |
| last       | 最后一次出现 |

### fallback_strategy 枚举值

| 枚举值 | 描述 |
|----------------------|------------------------------|
| next_business_day    | 下一个工作日 |
| previous_business_day| 上一个工作日 |
| same_day             | 当天 |

### invoice_payment_type 枚举值

| 枚举值 | 描述 |
|-------------|----------------|
| bank_slip  | 银行票据（Boleto bancário）|

### interest_base 枚举值

| 枚举值 | 描述 |
|-----------------|------------------|
| calendar_days   | 自然日 |

### limits 对象

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|----------------------------------------------|------------|
| `postpaid_credit_limit` * | float  | 后付费信用额度 | - |

## Response

### 成功 - 钱包已创建，等待分析

STATUS 202

Response Body：等待分析的钱包

```json
{
  "wallet_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "owner_person_key": null,
  "wallet_status": "pending_analysis"
}
```

:::info 说明
若返回 **HTTP Status 202** 且 `wallet_status` 字段值为 `pending_analysis`，则创建将异步处理。
之后将发送 webhook 通知钱包是否通过 KYC 分析审批或被拒绝。有关 webhook 的更多详情，请参阅 [webhook 文档](/documentation/cartao_pos_pago/faturas/webhooks/carteira)
:::

:::note 说明
对于需要 KYC 分析的情况，`owner_person_key` 字段在初始响应中将返回为 `null`。钱包的持有人仅在 KYC 流程结束且获得批准后才会在系统中创建。此时，人员密钥将通过审批 webhook 发送，请参阅 [webhook 文档](/documentation/cartao_pos_pago/faturas/webhooks/carteira)
:::

### 成功 - 钱包已创建并激活

STATUS 201

Response Body：已激活的钱包

```json
{
  "wallet_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "owner_person_key": "ecf87b4b-fa6e-49c0-a7f0-f2cad6b42d79",
  "wallet_status": "active"
}
```

### 响应体参数

| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|--------|-----------------------------------------------------------------------------------|------------|
| `wallet_key` *          | uuidv4 | uuid v4 格式的钱包唯一识别密钥 | 36 |
| `owner_person_key` *    | string | 钱包所有者的识别密钥 | 36 |
| `wallet_status` *       | string | 钱包状态 | - |

### wallet_status 枚举值

| 枚举值 | 描述 |
|--------------------|-----------------------------------------|
| pending_analysis   | 等待 KYC 分析的钱包 |
| active             | 已激活且可使用的钱包 |
| rejected           | 已拒绝的钱包 |

:::info 钱包状态
- **`pending_analysis`**：当钱包以完整所有者数据创建时返回，将进行 KYC 分析。
- **`active`**：当钱包以现有人员密钥创建时返回，可立即使用。
:::

## 错误响应

STATUS 4xx

Response Body: Error

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title` | 描述（英文）<br/>`description` | 描述（葡文）<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.                                                                                          |

---

# 列出钱包（Wallets）

URL: /zh-Hans/documentation/cartao_pos_pago/faturas/carteira/listar_carteiras

列出钱包将返回符合请求中发送的查询参数的所有钱包。

## Request

ENDPOINT /wallets
MÉTODO GET

### 查询参数

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|----------------------------------------------|------------|
| `owner_document_number`   | string  | 钱包所有者的 CPF/CNPJ | 11-14 |
| `wallet_status`                  | string  | 用于筛选的钱包状态 | **[wallet_status 枚举值](#enumeradores-wallet_status)** |
| `page`                    | integer | 分页的页码 | - |
| `page_size`               | integer | 每页项目数量 | - |

:::caution 验证
- **分页**：页码和每页大小必须为有效整数
- **每页大小**：每页最多 100 条记录
:::

### wallet_status 枚举值

| 枚举值 | 描述 |
|--------------------|-----------------------------------------|
| pending_analysis   | 等待 KYC 分析的钱包 |
| active             | 已激活且可使用的钱包 |
| rejected           | 已拒绝的钱包 |

## Response

STATUS 200

Response Body：钱包列表

```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,
  }
}
```

### 响应体参数

| 字段 | 类型 | 描述 | 字符数 |
|------------------|--------------|---------------------------------------|---------------------------------------------|
| `data` *         | object array | 钱包列表 | **[wallet 对象](#objeto-wallet)** |
| `pagination` *   | object       | 分页信息 | **[pagination 对象](#objeto-pagination)** |

### wallet 对象

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|--------|----------------------------------------------|------------|
| `wallet_key` *            | uuidv4 | 钱包的唯一识别密钥 | 36 |
| `owner_person_key` *      | string | 钱包所有者的识别密钥 | 36 |
| `owner_document_number` * | string | 钱包所有者的 CPF/CNPJ | 11 或 14 |
| `invoice_configuration` * | object | 结账和到期配置 | **[invoice_configuration 对象](#objeto-invoice_configuration)** |
| `wallet_status` *         | string | 钱包当前状态 | **[wallet_status 枚举值](#enumeradores-wallet_status)** |
| `wallet_type` *           | string | 钱包类型 | **[wallet_type 枚举值](#enumeradores-wallet_type)** |
| `created_at` *            | string | 创建日期（ISO 8601 UTC 格式）| - |

### pagination 对象

| 字段 | 类型 | 描述 | 字符数 |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `current_page` *           | integer | 当前页码 | - |
| `rows_per_page` *          | integer | 每页条数 | - |

### wallet_type 枚举值

| 枚举值 | 描述 |
|-------------|------------------------------|
| default     | 标准钱包 |
| payroll     | 薪资代扣卡钱包 |

### invoice_configuration 对象

| 字段 | 类型 | 描述 | 字符数 |
|------------------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `closing_date_configuration` *           | object  | 账单结账日配置 | **[closing_date_configuration 对象](#objeto-closing_date_configuration)** |
| `due_date_configuration` *               | object  | 账单到期日配置 | **[due_date_configuration 对象](#objeto-due_date_configuration)** |
| `invoice_payment_type` *                 | string  | 账单支付类型 | **[invoice_payment_type 枚举值](#enumeradores-invoice_payment_type)** |
| `interest_base`                         | string  | 利息计算基础 | **[interest_base 枚举值](#enumeradores-interest_base)** |
| `monthly_interest_percentage`          | float  | 逾期月利率（0-100）| - |
| `fine_percentage`                       | float  | 逾期罚款比例（0-100）| - |

:::info
注意：`payroll` 类型的钱包不包含 `interest_base`、`monthly_interest_percentage` 和 `fine_percentage` 字段。
:::

### closing_date_configuration 对象

#### 固定配置（`type: "fixed"`）

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|----------------------------------------------|------------|
| `type` *                  | string  | 配置类型（必须为 "fixed"）| - |
| `fixed_day` *             | integer | 每月固定结账日（1-27）| - |

#### 基于规则的配置（`type: "rule_based"`）

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|----------------------------------------------|------------|
| `type` *                  | string  | 配置类型（必须为 "rule_based"）| - |
| `rule` *                  | object  | 日期计算规则 | **[rule 对象（closing_date_configuration）](#objeto-closing_date_configuration)** |

### rule 对象（closing_date_configuration）

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|----------------------------------------------|------------|
| `day_of_week` *          | string  | 星期几 | **[day_of_week 枚举值](#enumeradores-day_of_week)** |
| `occurrence` *            | string  | 当月第几次出现 | **[occurrence 枚举值](#enumeradores-occurrence)** |
| `fallback_strategy` *     | string  | 非工作日策略 | **[fallback_strategy 枚举值](#enumeradores-fallback_strategy)** |

### due_date_configuration 对象

#### 固定配置（`type: "fixed"`）

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|----------------------------------------------|------------|
| `type` *                  | string  | 配置类型（必须为 "fixed"）| - |
| `offset_months` *         | integer | 从结账日起的月份偏移量 | - |
| `fixed_day` *             | integer | 每月固定到期日（2-27）| - |

#### 基于规则的配置（`type: "rule_based"`）

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|----------------------------------------------|------------|
| `type` *                  | string  | 配置类型（必须为 "rule_based"）| - |
| `offset_months` *         | integer | 从结账日起的月份偏移量 | - |
| `rule` *                  | object  | 日期计算规则 | **[rule 对象（closing_date_configuration）](#objeto-due_date_configuration)** |

### rule 对象（due_date_configuration）

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|----------------------------------------------|------------|
| `day_of_week` *          | string  | 星期几 | **[day_of_week 枚举值](#enumeradores-day_of_week)** |
| `occurrence` *            | string  | 当月第几次出现 | **[occurrence 枚举值](#enumeradores-occurrence)** |
| `fallback_strategy` *     | string  | 非工作日策略 | **[fallback_strategy 枚举值](#enumeradores-fallback_strategy)** |

### day_of_week 枚举值

| 枚举值 | 描述 |
|-------------|-----------|
| monday     | 星期一 |
| tuesday    | 星期二 |
| wednesday  | 星期三 |
| thursday   | 星期四 |
| friday     | 星期五 |
| saturday   | 星期六 |
| sunday     | 星期日 |

### occurrence 枚举值

| 枚举值 | 描述 |
|-------------|-----------|
| first      | 第一次出现 |
| second     | 第二次出现 |
| third      | 第三次出现 |
| fourth     | 第四次出现 |
| last       | 最后一次出现 |

### fallback_strategy 枚举值

| 枚举值 | 描述 |
|----------------------|------------------------------|
| next_business_day    | 下一个工作日 |
| previous_business_day| 上一个工作日 |
| same_day             | 当天 |

### invoice_payment_type 枚举值

| 枚举值 | 描述 |
|-------------|----------------|
| bank_slip  | 银行票据（Boleto bancário）|

### interest_base 枚举值

| 枚举值 | 描述 |
|-----------------|------------------|
| calendar_days   | 自然日 |

## 错误响应

STATUS 4xx

Response Body: Error

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title` | 描述（英文）<br/>`description` | 描述（葡文）<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                                                                                 |

---

# 列出钱包条目

URL: /zh-Hans/documentation/cartao_pos_pago/faturas/carteira/listar_entradas_da_carteira

列出钱包条目将返回特定钱包中符合请求查询参数的所有条目。

## Request

ENDPOINT /wallet/ WALLET_KEY /wallet_entries
MÉTODO GET

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|--------------|--------|----------------------------------------------|------------|
| `wallet_key` | uuidv4 | UUID v4 格式的钱包唯一密钥 | 36 |

### 查询参数

| 字段 | 类型 | 描述 | 字符数 |
|------------------------------|---------|----------------------------------------------|------------|
| `wallet_entry_type` *        | string  | 钱包条目类型 | **[wallet_entry_type 枚举值](#enumeradores-wallet_entry_type)** |
| `wallet_entry_status` *      | string  | 钱包条目状态 | **[wallet_entry_status 枚举值](#enumeradores-wallet_entry_status)** |
| `page`                       | integer | 分页的页码 | - |
| `page_size`                  | integer | 每页项目数量 | - |

:::caution 验证
- **分页**：页码和每页大小必须为有效整数
- **每页大小**：每页最多 100 条记录
:::

### wallet_entry_type 枚举值

| 枚举值 | 描述 |
|-------------------|-----------------------------------------------------------------------------------|
| revolving_credit  | 循环信用 |
| payroll_withdraw  | 工资提款 |
| payroll_overdue   | 工资逾期 |

:::info 钱包条目类型
- **`revolving_credit`**：为客户提供的信用额度
- **`payroll_withdraw`**：因提取额度而产生的债务，每月从 INSS 中扣除
- **`payroll_overdue`**：因未支付账单而产生的债务，每月也从 INSS 中扣除
:::

### wallet_entry_status 枚举值

| 枚举值 | 描述 |
|------------|-----------------------------------------|
| concluded     | 条目已完成 |

## Response

STATUS 200

Response Body：钱包条目列表

```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
  }
}
```

### 响应体参数

| 字段 | 类型 | 描述 | 字符数 |
|------------------|--------------|---------------------------------------|---------------------------------------------|
| `data` *         | object array | 钱包条目 | **[wallet_entry 对象](#objeto-wallet_entry)** |
| `pagination` *   | object       | 分页信息 | **[pagination 对象](#objeto-pagination)** |

### wallet_entry 对象

| 字段 | 类型 | 描述 | 字符数 |
|------------------------------|---------|-----------------------------------------------------------------------------------|------------|
| `wallet_entry_key` *         | uuidv4  | uuid v4 格式的条目唯一识别密钥 | 36 |
| `wallet_entry_amount` *      | float  | 条目金额 | - |
| `wallet_entry_settlement_key` * | string | 条目的清算密钥 | - |
| `wallet_entry_type` *        | string  | 钱包条目类型 | **[wallet_entry_type 枚举值](#enumeradores-wallet_entry_type)** |
| `wallet_entry_status` *      | string  | 钱包条目状态 | **[wallet_entry_status 枚举值](#enumeradores-wallet_entry_status)** |
| `created_at` *               | string  | 创建日期（ISO 8601 UTC 格式）| - |

### pagination 对象

| 字段 | 类型 | 描述 | 字符数 |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `current_page` *           | integer | 当前页码 | - |
| `rows_per_page` *          | integer | 每页条数 | - |

## 错误响应

STATUS 4xx

Response Body: Error

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title` | 描述（英文）<br/>`description` | 描述（葡文）<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                                         |

---

# 查询钱包票据（Boleto）

URL: /zh-Hans/documentation/cartao_pos_pago/faturas/fatura/boleto_de_pagamento_da_fatura

查询钱包票据将返回与钱包关联的银行票据信息，包括条形码和可键入行。

:::warning 注意
钱包票据**仅在第一张账单结账后才会生成**。
:::

## Request

ENDPOINT /v2/invoice/wallet/ WALLET_KEY /wallet_bank_slip
MÉTODO GET

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|---------------|--------|----------------------------------------------|------------|
| `wallet_key`  | uuidv4 | UUID v4 格式的钱包唯一密钥 | 36 |

## Response

STATUS 200

Response Body：票据详情

```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"
  }
}
```

### 响应体参数

| 字段 | 类型 | 描述 | 字符数 |
|--------------------------|--------|-----------------------------------------------------------------------------------|------------|
| `wallet_bank_slip_key` * | uuidv4 | uuid v4 格式的钱包票据唯一识别密钥 | 36 |
| `wallet_bank_slip_status` * | string | 票据状态 | **[wallet_bank_slip_status 枚举值](#enumeradores-wallet_bank_slip_status)** |
| `bank_slip_amount` *     | float  | 票据金额 | - |
| `bank_slip_due_date` *   | string | 票据到期日（YYYY-MM-DD 格式）| 10 |
| `bank_slip_data` *       | object | 包含条形码和可键入行的票据数据 | **[bank_slip_data 对象](#objeto-bank_slip_data)** |

### bank_slip_data 对象

| 字段 | 类型 | 描述 | 字符数 |
|--------------------------|--------|-----------------------------------------------------------------------------------|------------|
| `barcode` *              | string | 票据条形码 | 44 |
| `digitable_line` *       | string | 票据可键入行 | 47 |

### wallet_bank_slip_status 枚举值

| 枚举值 | 描述 |
|------------|-----------------------------------------|
| accepted   | 票据已接受，等待登记确认 |
| registered | 票据已登记，可供支付 |

## 错误响应

STATUS 4xx

Response Body: Error

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title` | 描述（英文）<br/>`description` | 描述（葡文）<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                                                                                   |

---

# 通过密钥查询账单

URL: /zh-Hans/documentation/cartao_pos_pago/faturas/fatura/consulta_por_chave

通过密钥查询账单将返回特定账单的完整详情，包括所有账单项目。

## Request

ENDPOINT /wallet/ WALLET_KEY /invoice/ INVOICE_KEY
MÉTODO GET

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|---------------|--------|----------------------------------------------|------------|
| `wallet_key`  | uuidv4 | UUID v4 格式的钱包唯一密钥 | 36 |
| `invoice_key` | uuidv4 | UUID v4 格式的账单唯一密钥 | 36 |

## Response

STATUS 200

Response Body：账单详情

```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"
}
```

### 响应体参数

| 字段 | 类型 | 描述 | 字符数 |
|------------------|--------------|---------------------------------------|---------------------------------------------|
| `invoice_key` *  | uuidv4       | uuid v4 格式的账单唯一识别密钥 | 36 |
| `due_date` *     | string       | 账单到期日（YYYY-MM-DD 格式）| 10 |
| `closing_date` * | string       | 账单结账日（YYYY-MM-DD 格式）| 10 |
| `invoice_status` * | string    | 账单状态 | **[invoice_status 枚举值](#enumeradores-invoice_status)** |
| `total_amount` * | number       | 账单总金额 | - |
| `paid_amount` *  | number       | 账单已付金额 | - |
| `invoice_items` * | object array | 账单项目 | **[invoice_item 对象](#objeto-invoice_item)** |
| `invoice_payments` *               | object array | 账单付款 | [invoice_payment 对象](#objeto-invoice_payment) |
| `invoice_payments_chargebacks` *  | object array | 账单付款退款 | [invoice_payment_chargeback 对象](#objeto-invoice_payment_chargeback) |
| `created_at` *                     | string       | 创建日期（ISO 8601 UTC 格式）| - |

### invoice_item 对象

| 字段 | 类型 | 描述 | 字符数 |
|------------------------------------|---------|-----------------------------------------------------------------------------------|------------|
| `invoice_item_key` *               | uuidv4  | uuid v4 格式的账单项目唯一识别密钥 | 36 |
| `invoice_key` *                    | uuidv4  | uuid v4 格式的账单唯一识别密钥 | 36 |
| `wallet_entry_key`                 | uuidv4  | uuid v4 格式的钱包条目唯一识别密钥 | 36 |
| `payment_instrument_entry_key`     | uuidv4  | uuid v4 格式的支付工具条目唯一识别密钥 | 36 |
| `installment_number` *             | integer | 分期期数 | - |
| `invoice_description` *            | string  | 账单项目描述 | - |
| `amount` *                         | float  | 项目金额 | - |
| `used_limit` *                     | float  | 已用额度 | - |
| `invoice_item_status` *            | string  | 账单项目状态 | **[invoice_item_status 枚举值](#enumeradores-invoice_item_status)** |
| `invoice_item_due_date` *          | string  | 项目到期日（YYYY-MM-DD 格式）| 10 |
| `created_at` *                     | string  | 创建日期（ISO 8601 UTC 格式）| - |

### invoice_payment 对象

| 字段 | 类型 | 描述 | 字符数 |
|------------------------------------|---------|-----------------------------------------------------------------------------------|------------|
| invoice_payment_key *              | uuidv4  | uuid v4 格式的账单付款唯一识别密钥 | 36 |
| total_amount                       | number  | 付款总金额 | - |
| paid_amount                        | number  | 已付金额 | - |
| invoice_payment_type *              | string  | 账单支付类型 | [invoice_payment_type 枚举值](#enumeradores-invoice_payment_type) |
| invoice_payment_status *           | string  | 账单付款状态 | [invoice_payment_status 枚举值](#enumeradores-invoice_payment_status) |

### invoice_payment_chargeback 对象

| 字段 | 类型 | 描述 | 字符数 |
|------------------------------------|---------|-----------------------------------------------------------------------------------|------------|
| invoice_item_key *                 | uuidv4  | 与退款相关的账单项目 uuid v4 格式唯一识别密钥 | 36 |
| chargeback_paid_amount             | number  | 已使用的退款金额 | - |

### invoice_status 枚举值

| 枚举值 | 描述 |
|------------|-----------------------------------------|
| opened                 | 账单已开 |
| processing_closing     | 处理结账中 |
| processing_expiration  | 处理到期中 |
| closed                 | 账单已结 |
| processing_payment        | 等待付款 |
| paid                   | 账单已付 |

:::info 说明
`processing_payment` 状态仅适用于 `payroll` 类型的钱包，在已收到可能付款金额但仍有剩余金额需通过福利支付的场景下应用。
:::

### invoice_payment_type 枚举值

| 枚举值 | 描述 |
|------------|-----------------------------------------|
| bank_slip        | 银行票据（Boleto bancário）|
| payroll_discount | 通过 INSS 折扣支付 |

:::info 说明
`payroll_discount` 类型仅存在于 `payroll` 类型的钱包，代表通过福利扣除的金额。
:::

### invoice_payment_status 枚举值

| 枚举值 | 描述 |
|------------|-----------------------------------------|
| processing_payment  | 等待付款 |
| paid             | 已付款 |

:::info 说明
- 对于 `payroll_discount` 类型的付款：付款在账单结账时以 `processing_payment` 状态创建，并向 INSS 请求折扣。当折扣付款完成后，状态变为 `paid`。
- 对于 `bank_slip` 类型的付款：当我们收到票据付款通知时，付款以 `processing_payment` 状态创建。票据结算后，状态变为 `paid`。若未收到付款通知，付款可直接以 `paid` 状态创建。
:::

### invoice_item_status 枚举值

| 枚举值 | 描述 |
|------------|-----------------------------------------|
| concluded    | 项目已完成 |
| canceled  | 项目已取消 |

## 错误响应

STATUS 4xx

Response Body: Error

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title` | 描述（英文）<br/>`description` | 描述（葡文）<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                      | CIN000080            | 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                                           |

---

# 列出账单

URL: /zh-Hans/documentation/cartao_pos_pago/faturas/fatura/listar_faturas

列出账单将返回符合请求查询参数的特定钱包的所有账单。

## Request

ENDPOINT /wallet/ WALLET_KEY /invoices
MÉTODO GET

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|--------------|--------|----------------------------------------------|------------|
| `wallet_key` | uuidv4 | UUID v4 格式的钱包唯一密钥 | 36 |

### 查询参数

| 字段 | 类型 | 描述 | 字符数 |
|------------------------------|---------|----------------------------------------------|------------|
| `invoice_status` *           | string  | 账单状态 | **[invoice_status 枚举值](#enumeradores-invoice_status)** |
| `page`                       | integer | 分页的页码 | - |
| `page_size`                  | integer | 每页项目数量 | - |

:::caution 验证
- **分页**：页码和每页大小必须为有效整数
- **每页大小**：每页最多 100 条记录
:::

### invoice_status 枚举值

| 枚举值 | 描述 |
|------------|-----------------------------------------|
| opened                 | 账单已开 |
| processing_closing     | 处理结账中 |
| processing_expiration  | 处理到期中 |
| closed                 | 账单已结 |
| processing_payment        | 等待付款 |
| paid                   | 账单已付 |

## Response

STATUS 200

Response Body：账单列表

```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
  }
}
```

### 响应体参数

| 字段 | 类型 | 描述 | 字符数 |
|------------------|--------------|---------------------------------------|---------------------------------------------|
| `data` *         | object array | 账单列表 | **[invoice 对象](#objeto-invoice)** |
| `pagination` *   | object       | 分页信息 | **[pagination 对象](#objeto-pagination)** |

### invoice 对象

| 字段 | 类型 | 描述 | 字符数 |
|------------------------------|---------|-----------------------------------------------------------------------------------|------------|
| `invoice_key` *              | uuidv4  | uuid v4 格式的账单唯一识别密钥 | 36 |
| `due_date` *                 | string  | 账单到期日（YYYY-MM-DD 格式）| 10 |
| `closing_date` *             | string  | 账单结账日（YYYY-MM-DD 格式）| 10 |
| `invoice_status` *           | string  | 账单状态 | **[invoice_status 枚举值](#enumeradores-invoice_status)** |
| `total_amount` *             | number  | 账单总金额 | - |
| `paid_amount` *              | number  | 已付金额 | - |
| `created_at` *               | string  | 创建日期（ISO 8601 UTC 格式）| - |

### pagination 对象

| 字段 | 类型 | 描述 | 字符数 |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `current_page` *           | integer | 当前页码 | - |
| `rows_per_page` *          | integer | 每页条数 | - |

## 错误响应

STATUS 4xx

Response Body: Error

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title` | 描述（英文）<br/>`description` | 描述（葡文）<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                                         |

---

# 场景模拟 - 账单结账与到期

URL: /zh-Hans/documentation/cartao_pos_pago/faturas/fatura/simulacao_de_cenarios

本页面介绍如何模拟账单结账和到期，以测试后付费卡交易流程。这些模拟对于正式验收测试和集成测试非常有用。

## 1 - 模拟账单结账

模拟未结账单的结账操作，将其状态更改为 `processing_closing` 并在结账队列中发布消息。账单将根据钱包配置进行处理。

ENDPOINT /mock/invoice/ INVOICE_KEY /close
MÉTODO PATCH

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|------------------------------|--------|----------------------------------------------|------------|
| `invoice_key` *           | string  | UUID v4 格式的账单唯一密钥 | 36 |

### Headers

### Request Body

此请求无请求体。

### Response

STATUS 204

Response Body

```json

{}

```

### 响应体参数

此响应无请求体参数。

:::tip 行为说明

- 模拟操作将账单状态更改为 `processing_closing`
- 账单状态必须为 `opened` 才能进行结账
- 系统将向客户发送状态变更通知
:::

## 2 - 模拟账单到期

模拟已结账单的到期，将其状态更改为 `processing_expiration` 并在到期队列中发布消息。账单将根据钱包配置进行处理。

ENDPOINT /mock/invoice/ INVOICE_KEY /expire
MÉTODO PATCH

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|------------------------------|--------|----------------------------------------------|------------|
| `invoice_key` *           | string  | UUID v4 格式的账单唯一密钥 | 36 |

### Request Body

此请求无请求体。

### Response

STATUS 204

Response Body

```json

{}

```

### 响应体参数

此响应无请求体参数。

:::tip 行为说明
- 模拟操作将账单状态更改为 `processing_expiration`
- 账单状态不能为 `opened`（必须已结账）
- 钱包必须至少有一张未结账单
- 钱包的下一个结账日期不能早于下一个到期日期
- 系统将向客户发送状态变更通知
:::

---

# 修改支付工具额度

URL: /zh-Hans/documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/alteracao_de_limite

修改支付工具额度允许更改现有支付工具的额度金额。

## Request

ENDPOINT /wallet/ WALLET_KEY /payment_instrument/ PAYMENT_INSTRUMENT_KEY
MÉTODO PATCH

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|------------------------------|--------|----------------------------------------------|------------|
| `wallet_key` *               | uuidv4 | UUID v4 格式的钱包唯一密钥 | 36 |
| `payment_instrument_key` *   | uuidv4 | UUID v4 格式的支付工具唯一密钥 | 36 |

Request Body

```json
{
  "limit_amount": 3000.00
}
```

### 请求体参数

| 字段 | 类型 | 描述 | 字符数 |
|------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `limit_amount` *             | float   | 支付工具的新额度金额 | - |

:::info 说明
- 新额度金额必须大于或等于已用额度（`used_limit`）
- 新额度金额不能超过钱包的后付费信用额度（`postpaid_credit_limit`）
- 只有 `postpaid_card` 类型的支付工具可以更新其额度
- 只有 `default` 类型的钱包可以更新其支付工具的额度
- 支付工具状态必须为 `active` 才能更新其额度
:::

## Response

STATUS 200

Response Body：已更新支付工具额度

```json
{
  "payment_instrument_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "limit_amount": 3000.00,
  "payment_instrument_status": "active"
}
```

### 响应体参数

| 字段 | 类型 | 描述 | 字符数 |
|----------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `payment_instrument_key` *       | uuidv4  | UUID v4 格式的已更新工具唯一识别密钥 | 36 |
| `limit_amount` *                 | float   | 更新后的工具新额度金额 | - |
| `payment_instrument_status` *    | string  | 支付工具状态 | **[payment_instrument_status 枚举值](#enumeradores-payment_instrument_status)** |

### payment_instrument_status 枚举值

| 枚举值 | 描述 |
|------------|-----------------------------------------|
| active     | 工具已激活 |
| canceled   | 工具已取消 |

## 错误响应

STATUS 4xx

Response Body: Error

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title` | 描述（英文）<br/>`description` | 描述（葡文）<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                                                                            |

---

# 取消支付工具

URL: /zh-Hans/documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/cancelamento_de_instrumento_de_pagamento

取消支付工具允许取消现有的支付工具，将其状态更改为 `canceled`，同时自动取消关联的后付费卡。

## Request

ENDPOINT /wallet/ WALLET_KEY /payment_instrument/ PAYMENT_INSTRUMENT_KEY /cancel
MÉTODO PATCH

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|------------------------------|--------|----------------------------------------------|------------|
| `wallet_key` *               | uuidv4 | UUID v4 格式的钱包唯一密钥 | 36 |
| `payment_instrument_key` *   | uuidv4 | UUID v4 格式的支付工具唯一密钥 | 36 |

:::info 说明
此请求没有请求体。取消操作仅通过路径参数执行。
:::

## Response

STATUS 200

Response Body：已取消支付工具

```json
{
  "payment_instrument_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "payment_instrument_status": "canceled"
}
```

### 响应体参数

| 字段 | 类型 | 描述 | 字符数 |
|----------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `payment_instrument_key` *       | uuidv4  | UUID v4 格式的已取消工具唯一识别密钥 | 36 |
| `payment_instrument_status` *    | string  | 取消后的工具状态 | **[payment_instrument_status 枚举值](#enumeradores-payment_instrument_status)** |

### payment_instrument_status 枚举值

| 枚举值 | 描述 |
|------------|-----------------------------------------|
| canceled   | 工具已取消 |

:::tip 行为说明
- 支付工具取消后将转为 `canceled` 状态
- 关联的后付费卡也将自动取消
- 已取消的工具无法用于新交易
:::

## 错误响应

STATUS 4xx

Response Body: Error

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

---

# 按密钥查询支付工具条目

URL: /zh-Hans/documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/consulta_entrada_por_chave

按密钥查询支付工具条目将返回特定条目的完整详情，包括所有相关发票项目。

## Request

ENDPOINT /wallet/ WALLET_KEY /payment_instrument/ PAYMENT_INSTRUMENT_KEY /payment_instrument_entry/ PAYMENT_INSTRUMENT_ENTRY_KEY
MÉTODO GET

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|--------------------------------|--------|----------------------------------------------|------------|
| `wallet_key`                   | uuidv4 | UUID v4 格式的钱包唯一密钥 | 36 |
| `payment_instrument_key`       | uuidv4 | UUID v4 格式的支付工具唯一密钥 | 36 |
| `payment_instrument_entry_key` | uuidv4 | UUID v4 格式的条目唯一密钥 | 36 |

## Response

STATUS 200

Response Body：支付工具条目详情

```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"
}
```

### 响应体参数

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------------------|--------------|---------------------------------------|---------------------------------------------|
| `payment_instrument_entry_key` *      | uuidv4       | uuid v4 格式的条目唯一识别密钥 | 36 |
| `payment_instrument_entry_amount` *   | number       | 条目金额 | - |
| `payment_instrument_entry_type` *     | string       | 支付工具条目类型 | **[payment_instrument_entry_type 枚举值](#enumeradores-payment_instrument_entry_type)** |
| `payment_instrument_entry_status` *  | string       | 工具条目状态 | **[payment_instrument_entry_status 枚举值](#enumeradores-payment_instrument_entry_status)** |
| `invoice_items` *                     | object array | 相关发票项目 | **[invoice_item 对象](#objeto-invoice_item)** |
| `payment_instrument_entry_data`      | object  | 附加数据 | **[payment_instrument_entry_data 对象](#objeto-payment_instrument_entry_data)** |
| `created_at` *                       | string  | 创建日期（ISO 8601 UTC 格式） | - |

### payment_instrument_entry_data 对象（purchase | withdraw）

| 字段 | 类型 | 描述 | 字符数 |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `merchant_name` *          | string  | 商家名称 | - |
| `merchant_country` *       | string  | 商家所在国家 | - |
| `merchant_postal_code` *   | string  | 商家邮政编码 | - |
| `merchant_city` *          | string  | 商家所在城市 | - |
| `merchant_street` *        | string  | 商家街道地址 | - |

### payment_instrument_entry_data 对象（postpaid_card_issuance）

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `postpaid_card_issuance_name` * | string  | 后付费卡发卡名称 | - |
| `payment_instrument_key` *      | string  | UUID v4 格式的支付工具唯一密钥 | 36 |
| `postpaid_card_key` *           | string  | UUID v4 格式的后付费卡唯一密钥 | 36 |

:::info 说明
此条目仅适用于代扣卡钱包卡。
:::

### payment_instrument_entry_type 枚举值

| 枚举值 | 描述 |
|-------------------------|-----------------------------------------------------------------------------------|
| purchase                | 购买 |
| withdraw                | 提款 |
| postpaid_card_issuance  | 后付费卡发卡 |

### payment_instrument_entry_status 枚举值

| 枚举值 | 描述 |
|-------------------------|-----------------------------------------|
| processing_conclusion   | 正在处理结算 |
| processing_cancellation | 正在处理取消 |
| concluded               | 条目已结算 |
| canceled                | 条目已取消 |

:::info 说明
支付工具条目可以直接从 `processing_conclusion` 转换为 `processing_cancellation` 和 `canceled`。在这种情况下，不会创建发票项目。
:::

### invoice_item 对象

| 字段 | 类型 | 描述 | 字符数 |
|------------------------------------|---------|-----------------------------------------------------------------------------------|------------|
| `invoice_item_key` *               | uuidv4  | uuid v4 格式的发票项目唯一识别密钥 | 36 |
| `invoice_key` *                    | uuidv4  | uuid v4 格式的发票唯一识别密钥 | 36 |
| `wallet_entry_key`                 | uuidv4  | uuid v4 格式的钱包条目唯一识别密钥 | 36 |
| `payment_instrument_entry_key`     | uuidv4  | uuid v4 格式的支付工具条目唯一识别密钥 | 36 |
| `installment_number` *             | integer | 分期编号 | - |
| `invoice_description` *            | string  | 发票项目描述 | - |
| `amount` *                         | number  | 项目金额 | - |
| `used_limit` *                     | number  | 已用额度 | - |
| `invoice_item_status` *            | string  | 发票项目状态 | **[invoice_item_status 枚举值](#enumeradores-invoice_item_status)** |
| `invoice_item_due_date` *          | string  | 项目到期日（YYYY-MM-DD 格式） | 10 |
| `created_at` *                     | string  | 创建日期（ISO 8601 UTC 格式） | - |

### invoice_item_status 枚举值

| 枚举值 | 描述 |
|------------|-----------------------------------------|
| concluded  | 项目已结算（所属发票未支付） |
| canceled   | 项目已取消 |

## 错误响应

STATUS 4xx

Response Body: Error

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title` | 描述（英文）<br/>`description` | 描述（葡文）<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                                                             |

---

# 创建支付工具

URL: /zh-Hans/documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/criacao_de_instrumento_de_pagamento

创建支付工具允许为现有钱包注册新的支付方式（如后付费卡）。

## Request

ENDPOINT /wallet/ WALLET_KEY /payment_instrument
MÉTODO POST

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|--------------|--------|----------------------------------------------|------------|
| `wallet_key` | uuidv4 | 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_control_key`    | uuidv4     | 客户端使用的请求唯一识别密钥 | 36 |
| `owner`                      | object  | 工具所有人信息（个人或法人） | **[owner 对象](#objeto-owner)** |
| `person_key`                 | string  | UUID v4 格式的人员唯一识别密钥 | 36 |
| `payment_instrument_type` *  | string  | 支付工具类型 | **[payment_instrument_type 枚举值](#enumeradores-payment_instrument_type)** |
| `limit_amount`               | float  | 工具信用额度（必须小于或等于钱包额度） | - |
| `postpaid_card_data`         | object  | 后付费卡的特定数据 | **[postpaid_card_data 对象](#objeto-postpaid_card_data)** |

:::info 条件字段
- **`owner`**：未发送 `person_key` 时为必填
- **`person_key`**：未发送 `owner` 时为必填
- **`postpaid_card_data`**：`payment_instrument_type` 为 "postpaid_card" 时为必填
- `owner` 和 `person_key` 字段互斥
:::

:::caution 额度验证
- `limit_amount` **非必填**
- 填写时不得超过钱包的后付费信用额度
- 未填写时，工具将使用钱包的全部额度
:::

### owner 对象

#### 个人（`person_type: "natural"`）

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|--------|----------------------------------------------|------------|
| `person_type` *           | string | 人员类型（必须为 "natural"） | - |
| `name` *                  | string | 姓名全称 | 100 |
| `document_number` *       | string | CPF（仅数字） | 11 |
| `birthdate` *             | string | 出生日期（YYYY-MM-DD 格式） | 10 |
| `email` *                 | string | 联系邮箱 | 254 |
| `phone` *                 | object | 联系电话 | **[phone 对象](#objeto-phone)** |
| `address` *               | object | 完整地址 | **[address 对象](#objeto-address)** |

#### 法人（`person_type: "legal"`）

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|--------|----------------------------------------------|------------|
| `person_type` *           | string | 人员类型（必须为 "legal"） | - |
| `name` *                  | string | 公司法定名称 | 100 |
| `trading_name` *          | string | 公司商号 | 100 |
| `document_number` *       | string | CNPJ（仅数字） | 14 |
| `foundation_date` *       | string | 成立日期（YYYY-MM-DD 格式） | 10 |
| `email` *                 | string | 联系邮箱 | 254 |
| `phone` *                 | object | 联系电话 | **[phone 对象](#objeto-phone)** |
| `address` *               | object | 完整地址 | **[address 对象](#objeto-address)** |
| `legal_representatives` * | array  | 法定代表人列表（自然人） | - |

### phone 对象

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|--------|----------------------------------------------|------------|
| `country_code` *          | string | 国家代码（DDI） | 2-3 |
| `area_code` *             | string | 区号（DDD） | 2 |
| `number` *                | string | 电话号码 | 8-9 |

### address 对象

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|--------|----------------------------------------------|------------|
| `street` *                | string | 街道/大道名称 | 500 |
| `number` *                | string | 门牌号 | 10 |
| `neighborhood` *          | string | 社区/街区 | 100 |
| `postal_code` *           | string | CEP（仅数字） | 8 |
| `city` *                  | string | 城市 | 100 |
| `state` *                 | string | 州（UF） | **[state 枚举值](#enumeradores-state)** |
| `complement`              | string | 地址补充说明 | 500 |

### state 枚举值

| 枚举值 | 描述 |
|-------------|----------------|
| 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          | 特殊情况 |

### payment_instrument_type 枚举值

| 枚举值 | 描述 |
|-----------------|------------------|
| postpaid_card   | 后付费卡 |

### postpaid_card_data 对象

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------------|---------|----------------------------------------------|------------|
| `card_type` *                   | string  | 卡片类型 | **[card_type 枚举值](#enumeradores-card_type)** |
| `card_name` *                   | string  | 卡片名称 | 1-50 |
| `printed_name` *                | string  | 卡片印刷名称 | 2-26 |
| `cvv_rotation_interval_hours`   | int  | CVV 轮换间隔（小时） | - |
| `contactless_enabled`           | boolean | 启用非接触式支付 | - |
| `delivery_address`              | object  | 卡片配送地址 | **[delivery_address 对象](#objeto-delivery_address)** |

### card_type 枚举值

| 枚举值 | 描述 |
|-------------|------------------|
| virtual     | 虚拟卡 |
| plastic     | 实体卡 |

:::info 条件字段
- **`cvv_rotation_interval_hours`**：`card_type: "virtual"` 时为必填，`card_type: "plastic"` 时不允许。
- **`delivery_address`**：`card_type: "virtual"` 时不允许；`card_type: "plastic"` 时为可选，若未填写，将使用 `owner` 的地址或已为 `person_key` 注册的地址。
- **`contactless_enabled`**：`card_type: "virtual"` 时不允许，`card_type: "plastic"` 时为必填。
:::

### delivery_address 对象

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|--------|----------------------------------------------|------------|
| `street` *                | string | 街道/大道名称 | 500 |
| `number` *                | string | 门牌号 | 10 |
| `neighborhood` *          | string | 社区/街区 | 100 |
| `postal_code` *           | string | CEP（仅数字） | 8 |
| `city` *                  | string | 城市 | 100 |
| `state` *                 | string | 州（UF） | **[state 枚举值](#enumeradores-state)** |
| `complement`              | string | 地址补充说明 | 500 |

## Response

### 成功 - 工具已创建

STATUS 201

Response Body：已创建工具

```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"
}
```

### 响应体参数

| 字段 | 类型 | 描述 | 字符数 |
|------------------------------|---------|-----------------------------------------------------------------------------------|------------|
| `request_control_key`        | uuidv4  | 客户端使用的请求唯一识别密钥 | 36 |
| `payment_instrument_key` *   | uuidv4  | uuid v4 格式的工具唯一识别密钥 | 36 |
| `postpaid_card_key` *        | uuidv4  | uuid v4 格式的后付费卡唯一识别密钥 | 36 |
| `owner_person_key` *         | uuidv4  | uuid v4 格式的所有人唯一识别密钥 | 36 |

## 错误响应

STATUS 4xx

Response Body: Error

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title` | 描述（英文）<br/>`description` | 描述（葡文）<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.                                                                                          |

---

# 列出支付工具条目

URL: /zh-Hans/documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/listar_entradas_do_instrumento_de_pagamento

列出支付工具条目将返回符合请求中所发送查询参数的特定支付工具的所有条目。

## Request

ENDPOINT /wallet/ WALLET_KEY /payment_instrument/ PAYMENT_INSTRUMENT_KEY /payment_instrument_entries
MÉTODO GET

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|--------|----------------------------------------------|------------|
| `wallet_key`              | uuidv4 | UUID v4 格式的钱包唯一密钥 | 36 |
| `payment_instrument_key`  | uuidv4 | UUID v4 格式的支付工具唯一密钥 | 36 |

### 查询参数

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------------------|---------|----------------------------------------------|------------|
| `payment_instrument_entry_type` *      | string  | 支付工具条目类型 | **[payment_instrument_entry_type 枚举值](#enumeradores-payment_instrument_entry_type)** |
| `payment_instrument_entry_status` *   | string  | 工具条目状态 | **[payment_instrument_entry_status 枚举值](#enumeradores-payment_instrument_entry_status)** |
| `page`                                | integer | 分页页码 | - |
| `page_size`                           | integer | 每页条目数量 | - |

:::caution 验证规则
- **分页**：页码和页面大小必须为有效整数
- **页面大小**：每页最多 100 条
:::

### payment_instrument_entry_type 枚举值

| 枚举值 | 描述 |
|-------------------------|-----------------------------------------------------------------------------------|
| purchase                | 购买 |
| withdraw                | 提款 |
| postpaid_card_issuance  | 后付费卡发卡 |

### payment_instrument_entry_status 枚举值

| 枚举值 | 描述 |
|-------------------------|-----------------------------------------|
| processing_conclusion   | 正在处理结算 |
| processing_cancellation | 正在处理取消 |
| concluded               | 条目已结算 |
| canceled                | 条目已取消 |

:::info 说明
支付工具条目可以直接从 `processing_conclusion` 转换为 `processing_cancellation` 和 `canceled`。在这种情况下，不会创建发票项目。
:::

## Response

STATUS 200

Response Body：支付工具条目列表

```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
  }
}
```

### 响应体参数

| 字段 | 类型 | 描述 | 字符数 |
|------------------|--------------|---------------------------------------|---------------------------------------------|
| `data` *         | object array | 支付工具条目 | **[payment_instrument_entry 对象](#objeto-payment_instrument_entry)** |
| `pagination` *   | object       | 分页信息 | **[pagination 对象](#objeto-pagination)** |

### payment_instrument_entry 对象

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------------------|---------|-----------------------------------------------------------------------------------|------------|
| `payment_instrument_entry_key` *      | uuidv4  | uuid v4 格式的条目唯一识别密钥 | 36 |
| `payment_instrument_entry_amount` *   | float  | 条目金额 | - |
| `payment_instrument_entry_type` *     | string  | 支付工具条目类型 | **[payment_instrument_entry_type 枚举值](#enumeradores-payment_instrument_entry_type)** |
| `payment_instrument_entry_status` *  | string  | 工具条目状态 | **[payment_instrument_entry_status 枚举值](#enumeradores-payment_instrument_entry_status)** |
| `payment_instrument_entry_data`      | object  | 附加数据 | **[payment_instrument_entry_data 对象](#objeto-payment_instrument_entry_data)** |
| `created_at` *                       | string  | 创建日期（ISO 8601 UTC 格式） | - |

### payment_instrument_entry_data 对象（purchase | withdraw）

| 字段 | 类型 | 描述 | 字符数 |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `merchant_name` *          | string  | 商家名称 | - |
| `merchant_country` *       | string  | 商家所在国家 | - |
| `merchant_postal_code` *   | string  | 商家邮政编码 | - |
| `merchant_city` *          | string  | 商家所在城市 | - |
| `merchant_street` *        | string  | 商家街道地址 | - |

### payment_instrument_entry_data 对象（postpaid_card_issuance）

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `postpaid_card_issuance_name` * | string  | 后付费卡发卡名称 | - |
| `payment_instrument_key` *      | string  | UUID v4 格式的支付工具唯一密钥 | 36 |
| `postpaid_card_key` *           | string  | UUID v4 格式的后付费卡唯一密钥 | 36 |

:::info 说明
此条目仅适用于代扣卡钱包卡。
:::

### pagination 对象

| 字段 | 类型 | 描述 | 字符数 |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `current_page` *           | integer | 当前页码 | - |
| `rows_per_page` *          | integer | 每页条目数 | - |

## 错误响应

STATUS 4xx

Response Body: Error

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

---

# 列出支付工具

URL: /zh-Hans/documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/listar_instrumentos_de_pagamento

列出支付工具将返回符合请求中所发送查询参数的特定钱包的所有支付工具。

## Request

ENDPOINT /wallet/ WALLET_KEY /payment_instruments
MÉTODO GET

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|--------------|--------|----------------------------------------------|------------|
| `wallet_key` | uuidv4 | UUID v4 格式的钱包唯一密钥 | 36 |

### 查询参数

| 字段 | 类型 | 描述 | 字符数 |
|------------------------------|---------|----------------------------------------------|------------|
| `owner_document_number`      | string  | 工具所有人的 CPF/CNPJ | 11-14 |
| `payment_instrument_type` *  | string  | 支付工具类型 | **[payment_instrument_type 枚举值](#enumeradores-payment_instrument_type)** |
| `payment_instrument_status` *| string  | 工具状态 | **[payment_instrument_status 枚举值](#enumeradores-payment_instrument_status)** |
| `page`                       | integer | 分页页码 | - |
| `page_size`                  | integer | 每页条目数量 | - |

:::caution 验证规则
- **分页**：页码和页面大小必须为有效整数
- **页面大小**：每页最多 100 条
:::

### payment_instrument_type 枚举值

| 枚举值 | 描述 |
|-----------------|------------------|
| postpaid_card   | 后付费卡 |

### payment_instrument_status 枚举值

| 枚举值 | 描述 |
|------------|-----------------------------------------|
| active     | 工具已激活且可用 |
| rejected   | 工具已拒绝 |
| canceled   | 工具已取消 |

## Response

STATUS 200

Response Body：支付工具列表

```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,
  }
}
```

### 响应体参数

| 字段 | 类型 | 描述 | 字符数 |
|------------------|--------------|---------------------------------------|---------------------------------------------|
| `data` *         | object array | 支付工具 | **[payment_instrument 对象](#objeto-payment_instrument)** |
| `pagination` *   | object       | 分页信息 | **[pagination 对象](#objeto-pagination)** |

### payment_instrument 对象

| 字段 | 类型 | 描述 | 字符数 |
|------------------------------|---------|-----------------------------------------------------------------------------------|------------|
| `request_control_key`        | uuidv4  | 客户端使用的请求唯一识别密钥 | 36 |
| `payment_instrument_key` *   | uuidv4  | uuid v4 格式的工具唯一识别密钥 | 36 |
| `postpaid_card_key` *        | uuidv4  | uuid v4 格式的后付费卡唯一识别密钥 | 36 |
| `owner_person_key` *         | uuidv4  | uuid v4 格式的所有人唯一识别密钥 | 36 |
| `owner_document_number` *    | string  | 工具所有人的 CPF/CNPJ | 11 或 14 |
| `payment_instrument_type` *  | string  | 支付工具类型 | **[payment_instrument_type 枚举值](#enumeradores-payment_instrument_type)** |
| `payment_instrument_status` *| string  | 工具状态 | **[payment_instrument_status 枚举值](#enumeradores-payment_instrument_status)** |
| `limit_amount` *             | float  | 工具信用额度 | - |
| `used_limit` *               | float  | 工具已用额度 | - |
| `created_at` *               | string  | 创建日期（ISO 8601 UTC 格式） | - |

### pagination 对象

| 字段 | 类型 | 描述 | 字符数 |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `current_page` *           | integer | 当前页码 | - |
| `rows_per_page` *          | integer | 每页条目数 | - |

## 错误响应

STATUS 4xx

Response Body: Error

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title` | 描述（英文）<br/>`description` | 描述（葡文）<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                                         |

---

# 场景模拟

URL: /zh-Hans/documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/simulacao_de_cenarios

本页面介绍如何模拟支付工具条目的创建和取消，以测试后付费卡交易流程。这些模拟对于集成联调和测试非常有用。

:::info 说明
这些请求模拟外部交易，并返回带有已创建或已取消条目密钥的 HTTP 状态。
:::

## 1 - 模拟创建支付工具条目

模拟创建支付工具条目（交易），例如使用后付费卡进行的购买或提款。该条目将根据分期配置自动关联到发票项目。

ENDPOINT /mock/invoice/payment_instrument/ POSTPAID_CARD_KEY /payment_instrument_entry
MÉTODO POST

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|------------------------------|--------|----------------------------------------------|------------|
| `postpaid_card_key` *           | string  | 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"
    }
}
```

### 请求体对象

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------------------------------|---------|------------------------------------------------------------------------------------|--------------|
| `request_control_key` *                  | uuidv4  | 客户端使用的请求唯一识别密钥 | 36 |
| `payment_instrument_entry_amount` *       | float   | 交易总金额 | - |
| `number_of_installments` *                | integer | 分期期数 | - |
| `installment_amount` *                    | float   | 每期金额 | - |
| `payment_instrument_entry_type` *         | string  | 支付工具条目类型 | **[payment_instrument_entry_type 枚举值](#enumeradores-payment_instrument_entry_type)** |
| `payment_instrument_entry_data` *         | object  | 交易附加数据 | **[payment_instrument_entry_data 对象](#objeto-payment_instrument_entry_data)** |

### payment_instrument_entry_type 枚举值

| 枚举值 | 描述 |
|-------------------------|-----------------------------------------------------------------------------------|
| `purchase`              | 使用卡片进行的购买 |
| `withdraw`              | 使用卡片进行的提款 |
| `postpaid_card_issuance`| 后付费卡发卡 |

### payment_instrument_entry_data 对象

| 字段 | 类型 | 描述 | 字符数 |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `merchant_name` *          | string  | 商家名称 | - |
| `merchant_country` *        | string  | 商家所在国家 | - |
| `merchant_postal_code` *    | string  | 商家邮政编码 | - |
| `merchant_city` *           | string  | 商家所在城市 | - |
| `merchant_street` *         | string  | 商家街道地址 | - |

### Response

STATUS 201

Response Body

```json
{
    "payment_instrument_entry_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6"
}
```

### 响应体参数

| 字段 | 类型 | 描述 | 字符数 |
|----------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `payment_instrument_entry_key` * | uuidv4  | UUID v4 格式的已创建条目唯一识别密钥 | 36 |

:::tip 行为说明
- 模拟将创建状态为 `active` 的支付工具条目
- 该条目将根据所提供的分期数自动关联到发票项目（invoice items）
- 发票项目将根据钱包的关账配置整理到发票（invoices）中
- 创建条目前，将验证支付工具和钱包的额度
:::

## 2 - 模拟取消支付工具条目

模拟取消现有的支付工具条目，将其状态更改为 `canceled` 并释放已用额度。

ENDPOINT /mock/invoice/payment_instrument/ POSTPAID_CARD_KEY /payment_instrument_entry/ REQUEST_CONTROL_KEY /cancel
MÉTODO PATCH

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|------------------------------|--------|----------------------------------------------|------------|
| `postpaid_card_key` *           | string  | UUID v4 格式的后付费卡唯一密钥 | 36 |
| `request_control_key` *       | uuidv4 | 创建条目时使用的原始请求唯一识别密钥 | 36 |

Request Body

```json
{
    "payment_instrument_entry_amount": 100.50
}
```

### 请求体对象

| 字段 | 类型 | 描述 | 最大字符数 |
|----------------------------------|---------|------------------------------------------------------------------------------------|--------------|
| `payment_instrument_entry_amount` * | float   | 取消金额 | - |

### Response

STATUS 200

Response Body

```json
{
    "payment_instrument_entry_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6"
}
```

### 响应体参数

| 字段 | 类型 | 描述 | 字符数 |
|----------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `payment_instrument_entry_key` * | uuidv4  | UUID v4 格式的已取消条目唯一识别密钥 | 36 |

:::tip 行为说明
- **未关账发票**：在未关账发票上取消将立即释放额度并从发票中移除金额
- **已关账发票**：在已关账发票上取消将创建退款，当在下一张发票中使用时，这些退款将显示在 `invoice_payments_chargebacks` 字段中
:::

---

# 钱包 Webhooks

URL: /zh-Hans/documentation/cartao_pos_pago/faturas/webhooks/carteira

:::danger 注意！
QI Tech 的 webhooks 不应以严格方式映射。
我们 API 返回的 webhook 载荷中可能包含额外字段。
:::

:::info 重发 Webhooks
您可以按照文档中的详细说明查询和重发 webhooks：[重发 Webhooks](/documentation/notificacoes/reenvio_de_notificacoes)。
:::

## 简介

在我们系统中创建钱包（`wallet`）后，将发送以下状态的 webhooks：

| 枚举值 | 翻译 | 描述 |
|-------------------------------|------------------------|------------------------------------------------------------|
|  active                       | 已激活 | 钱包已激活且可用 |
|  rejected                     | 已拒绝 | KYC 审核中钱包被拒绝 |

:::info 说明
我们 webhooks 的响应超时时间为 10 秒。
:::

## 示例
----

### 开户确认

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"
	}
}
```

### Webhook 字段

| 字段 | 类型 | 描述 | 字符数 |
|--------------------|---------|-----------------------------------------------------------------------------------|------------|
| wallet_key         | string  | uuid v4 格式的钱包唯一识别密钥 | 36 |
| owner_person_key   | string  | uuid v4 格式的钱包所有人唯一识别密钥 | 36 |
| wallet_status      | string  | 钱包状态 | **[wallet_status 枚举值](#enumeradores-wallet_status)** |

### wallet_status 枚举值

| 枚举值 | 描述 |
|------------|-----------------------------------------------------------------------------------|
| active     | 钱包已激活且可用 |
| rejected   | KYC 审核中钱包被拒绝 |

---

# 钱包条目 Webhooks

URL: /zh-Hans/documentation/cartao_pos_pago/faturas/webhooks/entrada_da_carteira

:::danger 注意！
QI Tech 的 webhooks 不应以严格方式映射。
我们 API 返回的 webhook 载荷中可能包含额外字段。
:::

:::info 重发 Webhooks
您可以按照文档中的详细说明查询和重发 webhooks：[重发 Webhooks](/documentation/notificacoes/reenvio_de_notificacoes)。
:::

## 简介

在我们系统中创建钱包条目（`wallet_entry`）后，将发送以下状态的 webhooks：

| 枚举值 | 翻译 | 描述 |
|-------------------------------|------------------------|------------------------------------------------------------|
|  concluded                    | 已结算 | 钱包条目已结算 |

:::info 说明
我们 webhooks 的响应超时时间为 10 秒。
:::

## 示例
----

### 创建确认

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"
	}
}
```

### Webhook 字段

| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|---------|-----------------------------------------------------------------------------------|------------|
| wallet_key              | string  | uuid v4 格式的钱包唯一识别密钥 | 36 |
| wallet_entry_key        | string  | uuid v4 格式的钱包条目唯一识别密钥 | 36 |
| wallet_entry_amount     | number  | 钱包条目金额 | - |
| wallet_entry_type       | string  | 钱包条目类型 | **[wallet_entry_type 枚举值](#enumeradores-wallet_entry_type)** |
| wallet_entry_status     | string  | 钱包条目状态 | **[wallet_entry_status 枚举值](#enumeradores-wallet_entry_status)** |

### wallet_entry_type 枚举值

| 枚举值 | 描述 |
|-------------------|-----------------------------------------------------------------------------------|
| revolving_credit  | 循环信贷 |
| payroll_withdraw  | 薪资提款 |
| payroll_overdue   | 薪资逾期 |

:::info 钱包条目类型
- **`revolving_credit`**：为客户提供的可用信贷金额
- **`payroll_withdraw`**：因提取额度而产生的债务，每月从 INSS 中扣除
- **`payroll_overdue`**：因未支付发票而产生的债务，也会每月从 INSS 中扣除
:::

### wallet_entry_status 枚举值

| 枚举值 | 描述 |
|------------|-----------------------------------------------------------------------------------|
| concluded  | 钱包条目已结算 |

---

# 支付工具条目 Webhooks

URL: /zh-Hans/documentation/cartao_pos_pago/faturas/webhooks/entrada_do_instrumento_de_pagamento

:::danger 注意！
QI Tech 的 webhooks 不应以严格方式映射。
我们 API 返回的 webhook 载荷中可能包含额外字段。
:::

:::info 重发 Webhooks
您可以按照文档中的详细说明查询和重发 webhooks：[重发 Webhooks](/documentation/notificacoes/reenvio_de_notificacoes)。
:::

## 简介

在我们系统中创建支付工具条目（`payment_instrument_entry`）后，将发送以下状态的 webhooks：

| 枚举值 | 翻译 | 描述 |
|-------------------------------|------------------------|------------------------------------------------------------|
|  processing_conclusion        | 正在处理结算 | 支付工具条目正在处理结算 |
|  processing_cancellation      | 正在处理取消 | 支付工具条目正在处理取消 |
|  concluded                    | 已结算 | 支付工具条目已结算 |
|  canceled                     | 已取消 | 支付工具条目已取消 |

:::info 说明
我们 webhooks 的响应超时时间为 10 秒。
:::

## 示例
----

### 创建确认

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"
	}
}
```

### 取消确认

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"
	}
}
```

### 正在处理激活

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"
	}
}
```

### 正在处理取消

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"
	}
}
```

### Webhook 字段

| 字段 | 类型 | 描述 | 字符数 |
|------------------------------------|---------|-----------------------------------------------------------------------------------|------------|
| payment_instrument_key             | string  | uuid v4 格式的支付工具唯一识别密钥 | 36 |
| payment_instrument_entry_key       | string  | uuid v4 格式的支付工具条目唯一识别密钥 | 36 |
| payment_instrument_entry_amount   | number  | 支付工具条目金额 | - |
| payment_instrument_entry_type     | string  | 支付工具条目类型 | **[payment_instrument_entry_type 枚举值](#enumeradores-payment_instrument_entry_type)** |
| payment_instrument_entry_status   | string  | 支付工具条目状态 | **[payment_instrument_entry_status 枚举值](#enumeradores-payment_instrument_entry_status)** |

### payment_instrument_entry_type 枚举值

| 枚举值 | 描述 |
|-------------------------|-----------------------------------------------------------------------------------|
| purchase                | 购买 |
| withdrawal              | 提款 |
| postpaid_card_issuance  | 后付费卡发卡 |

### payment_instrument_entry_status 枚举值

| 枚举值 | 描述 |
|-------------------------|-----------------------------------------------------------------------------------|
| processing_conclusion   | 支付工具条目正在处理结算 |
| processing_cancellation | 支付工具条目正在处理取消 |
| concluded               | 支付工具条目已结算 |
| canceled                | 支付工具条目已取消 |

:::info 说明
支付工具条目可以直接从 `processing_conclusion` 转换为 `processing_cancellation` 和 `canceled`。在这种情况下，不会创建发票项目。
:::

---

# 发票 Webhooks

URL: /zh-Hans/documentation/cartao_pos_pago/faturas/webhooks/fatura

:::danger 注意！
QI Tech 的 webhooks 不应以严格方式映射。
我们 API 返回的 webhook 载荷中可能包含额外字段。
:::

:::info 重发 Webhooks
您可以按照文档中的详细说明查询和重发 webhooks：[重发 Webhooks](/documentation/notificacoes/reenvio_de_notificacoes)。
:::

## 简介

在我们系统中发票（`invoice`）关账后，将发送包含发票状态变更的 webhook：

| 枚举值 | 翻译 | 描述 |
|-------------------------------|------------------------|------------------------------------------------------------|
|  processing_closing           | 正在处理关账 | 发票正在处理关账 |
|  processing_expiration        | 正在处理到期 | 发票正在处理到期 |
|  closed                       | 已关账 | 发票已关账，不再接受新条目，付款已处理 |
|  processing_payment           | 等待付款 | 发票等待付款（仅适用于有剩余应付金额的 `payroll` 类型钱包） |
|  paid                         | 已付款 | 发票已付款 |

:::info 说明
我们 webhooks 的响应超时时间为 10 秒。
:::

## 示例

### 发票关账确认

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"
	}
}
```

### 发票等待付款（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"
	}
}
```

### Webhook 字段

| 字段 | 类型 | 描述 | 字符数 |
|-----------------|---------|-----------------------------------------------------------------------------------|------------|
| invoice_key     | string  | uuid v4 格式的发票唯一识别密钥 | 36 |
| total_amount    | number  | 发票总金额 | - |
| paid_amount     | number  | 发票已付金额 | - |
| closing_date    | string  | 发票关账日期（YYYY-MM-DD 格式） | 10 |
| due_date        | string  | 发票到期日期（YYYY-MM-DD 格式） | 10 |
| invoice_status  | string  | 发票状态 | **[invoice_status 枚举值](#enumeradores-invoice_status)** |

### invoice_status 枚举值

| 枚举值 | 描述 |
|-----------------------|-----------------------------------------------------------------------------------|
| processing_closing    | 发票正在处理关账 |
| processing_expiration | 发票正在处理到期 |
| closed                | 发票已关账，不再接受新条目，付款已处理 |
| processing_payment    | 发票等待付款（仅适用于有剩余应付金额的 `payroll` 类型钱包） |
| paid                  | 发票已付款 |

---

# 发票付款 Webhooks

URL: /zh-Hans/documentation/cartao_pos_pago/faturas/webhooks/pagamento_da_fatura

:::danger 注意！
QI Tech 的 webhooks 不应以严格方式映射。
我们 API 返回的 webhook 载荷中可能包含额外字段。
:::

:::info 重发 Webhooks
您可以按照文档中的详细说明查询和重发 webhooks：[重发 Webhooks](/documentation/notificacoes/reenvio_de_notificacoes)。
:::

## 简介

在我们系统中发票付款（`invoice_payment`）状态发生变更后，将发送包含付款状态变更的 webhook：

| 枚举值 | 翻译 | 描述 |
|-------------------------------|------------------------|------------------------------------------------------------|
|  processing_payment           | 等待付款 | 发票付款等待支付 |
|  paid                         | 已付款 | 发票付款已支付 |

:::info 说明
我们 webhooks 的响应超时时间为 10 秒。
:::

## 示例

### 发票付款（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"
	}
}
```

### 发票付款（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"
	}
}
```

### Webhook 字段

| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|---------|-----------------------------------------------------------------------------------|------------|
| wallet_key              | string  | uuid v4 格式的钱包唯一识别密钥 | 36 |
| invoice_payment_key     | string  | uuid v4 格式的发票付款唯一识别密钥 | 36 |
| total_amount            | number  | 发票付款总金额 | - |
| paid_amount             | number  | 发票已付金额 | - |
| payment_date            | string  | 付款日期（YYYY-MM-DD 格式） | 10 |
| invoice_payment_type    | string  | 发票付款类型 | **[invoice_payment_type 枚举值](#enumeradores-invoice_payment_type)** |
| invoice_payment_status  | string  | 发票付款状态 | **[invoice_payment_status 枚举值](#enumeradores-invoice_payment_status)** |

### invoice_payment_type 枚举值

| 枚举值 | 描述 |
|-------------------|-----------------------------------------------------------------------------------|
| bank_slip         | 银行票据 |
| payroll_discount  | 薪资扣款 |

### invoice_payment_status 枚举值

| 枚举值 | 描述 |
|-----------------------|-----------------------------------------------------------------------------------|
| processing_payment    | 发票付款等待支付 |
| paid                  | 发票付款已支付 |

:::info 说明
- 对于 `payroll_discount` 类型的付款：发票关账时以 `processing_payment` 状态创建付款，并向 INSS 申请扣款。扣款完成后，状态变更为 `paid`。
- 对于 `bank_slip` 类型的付款：收到银行票据付款通知时，以 `processing_payment` 状态创建付款。银行票据结清时，状态变更为 `paid`。如果未收到付款通知，也可能直接以 `paid` 状态创建付款。
:::

---

# 简介

URL: /zh-Hans/documentation/cartao_pos_pago/introducao

## 后付费卡

后付费卡发行 API 为 QI Tech 合作伙伴提供了一种简单高效的方式，让其客户能够申请和发行后付费卡，包括**实体卡**和**虚拟卡**。

在 QI Tech，我们为合作伙伴提供成为子发行商的机会。通过我们的 API，他们可以为自己的客户提供发行后付费卡的能力，打造完整的银行和金融服务解决方案。

为了更好地理解我们的系统，我们将简要介绍后付费卡生态系统的运作方式。请注意，与其他所有 API 一样，服务的开通需与我们的团队协调，且**[调用需经过身份验证](/documentation/primeiros_passos/teste_de_autenticacao)**。

后付费卡与一条信用额度绑定，允许持卡人进行交易并在之后付款。与预付卡不同，后付费卡不需要预先充值账户余额。用户可以先消费后还款，额度以批准的信用额度为准。

通过后付费卡进行的交易将计入持卡人的账单，需在规定期限内还款。若未在到期日前还款，持卡人可能需承担财务费用，如利息和手续费。

## 程序（Program）

要发行后付费卡，合作伙伴需要在与 QI Tech 的集成中配置好相应的程序。程序定义了符合 VISA 等卡组织要求发行卡片所需的规则和参数。

以下是关于程序的一些重要信息：

* **程序类型** — 指卡的使用模式。本文档所述为后付费模式。
* **卡组织** — 我们使用 VISA 卡组织发行卡片。
* **卡面设计** — 指卡的设计，包括实体卡和虚拟卡图形界面中显示的设计。

:::caution 注意
如需配置新的后付费卡程序，需要联系 QI Tech 的商务团队和实施团队。
:::

## 钱包（Wallet）

要发行后付费信用卡，首先需要创建一个**钱包（wallet）**来管理客户的账单。钱包作为"账户"，存储所有卡片和账单配置。

:::info 什么是 Wallet
**wallet** 就像客户的账户，存储所有卡片和账单：

- **一个 wallet = 一张账单**：每个钱包对应一个特定客户（由 CPF/CNPJ 标识）的账单
- **多种支付手段**：同一个 wallet 可以有不同的支付工具（卡片、PIX 等）
- **独立的工具**：创建 wallet 后，需要分别创建支付工具（信用卡、额度等）
- **集中管理**：wallet 集中管理与该客户相关的所有操作和配置
:::

有关创建钱包的更多详情，请参阅**[钱包创建完整文档](/documentation/cartao_pos_pago/faturas/carteira/criacao_de_carteira)**。

## 发行流程

发行后付费信用卡遵循从为客户创建钱包（wallet）开始的逻辑顺序。该钱包作为"账户"，用于组织所有卡片和账单配置。

创建钱包后，需要创建 `postpaid_card` 类型的**支付工具（payment instrument）**。该工具负责管理使用卡片进行的所有交易和消费。创建工具时，系统将根据请求自动创建实体卡或虚拟卡。

:::info 支付工具
`postpaid_card` 类型的支付工具：
- **集中管理交易**：所有使用该卡进行的消费均与此工具关联以便管理
- **自动创建卡片**：创建工具时，系统将根据请求自动创建实体卡或虚拟卡
- **管理生命周期**：通过**[后付费卡管理端点](/documentation/cartao_pos_pago/cartao/busca/buscar_cartao_por_chave)**监控卡片状态和操作
:::

要创建支付工具，请参阅**[PaymentInstrument 创建文档](/documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/criacao_de_instrumento_de_pagamento)**。

### 额度配置

钱包拥有一个全局信用额度，定义了可用的最大上限。**也可以为各个支付工具配置独立额度**。

:::info 额度的工作方式
- **钱包额度**：定义可用信用额度的最大上限
- **工具额度**：每个工具可以配置独立额度，但不得超过钱包额度
- **实际示例**：额度为 R$ 100 的钱包可以有两个额度分别为 R$ 100 和 R$ 80 的工具，但当两个工具的使用总额达到 R$ 100 时，将无法进行更多消费
- **实时验证**：在允许新交易前，系统将同时验证工具额度和钱包额度
:::

:::info 薪资卡 Wallet 的额度
`payroll` 类型的钱包有两种不同的额度：
- **`postpaid_credit_limit`**：用于消费和卡片交易的后付费信用额度
- **`payroll_withdraw_limit`**：工资提款的专用额度（工资/福利），每月自动从客户工资中扣除

两种额度均显示在钱包的 `wallet_limits` 列表中，独立运作，使客户可以分别拥有卡片消费额度和福利提款专用额度。
:::

### 卡片管理与跟踪

配置好钱包和支付工具后，卡片（实体卡或虚拟卡）将自动创建并可立即使用。钱包集中管理所有账单信息，支持跟踪交易、付款以及利息和罚款配置。

可通过**[后付费卡管理端点](/documentation/cartao_pos_pago/cartao/busca/buscar_cartao_por_chave)**跟踪卡片的状态和生命周期，监控从创建到注销或取消的所有阶段。

## 钱包条目（Wallet Entry）

**钱包条目（wallet entries）**是记录在客户钱包中的债务。这些债务可以是不同类型：

- **循环信用（`revolving_credit`）**：为客户提供的信用额度
- **工资提款（`payroll_withdraw`）**：因提取额度而产生的债务，每月从 INSS 中扣除
- **工资逾期（`payroll_overdue`）**：因未支付账单而产生的债务，每月也从 INSS 中扣除

:::info Wallet Entries 的工作方式
- **一个条目 = 一笔债务**：每个条目是一笔特定的债务
- **转化为账单项目**：每期分期付款自动转化为账单中的一个项目
- **在账单中整理**：项目在账单中整理
- **集中管理**：所有债务均在钱包中统一管理
:::

有关钱包条目（Wallet Entry）的更多信息和查询，请参阅**[Wallet Entries 文档](/documentation/cartao_pos_pago/faturas/carteira/listar_entradas_da_carteira)**。

:::tip Wallet Entry Webhook
要实时跟踪钱包条目的状态变化，请使用**[Wallet Entry webhook](/documentation/cartao_pos_pago/faturas/webhooks/wallet_entry)**。
:::

## 支付工具条目（Payment Instrument Entry）

**支付工具条目（payment instrument entries）**是使用卡片进行的交易记录。每笔消费或提款都会生成一个条目：

- **卡片交易**：使用后付费卡进行的消费
- **卡片提款**：使用后付费卡进行的提款
- **其他操作**：与工具相关的其他交易

:::info Payment Instrument Entries 的工作方式
- **自动关联**：每个条目自动与一个 **invoice item** 关联
- **在账单中整理**：invoice items 在 **invoices** 中整理
- **自动创建账单**：创建新交易时，系统根据钱包的结账配置自动创建所需账单，以容纳交易的所有分期付款
:::

:::warning 关于取消的重要说明
- **未结账单**：未结账单中的取消操作会立即释放额度并从账单中删除相应金额
- **已结账单**：已结账单中的取消操作会创建退款，显示在 `invoice_payments_chargebacks` 字段中，并在下一张账单中使用
:::

有关支付工具条目（Payment Instrument Entry）的更多信息和查询，请参阅**[Payment Instrument Entries 文档](/documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/listar_entradas_do_instrumento_de_pagamento)**。

:::tip Payment Instrument Entry Webhook
要实时跟踪支付工具条目的状态变化，请使用**[Payment Instrument Entry webhook](/documentation/cartao_pos_pago/faturas/webhooks/payment_instruction_entry)**。
:::

## 账单（Invoice）

**账单（invoices）**根据 invoice items 的需要自动创建。它们作为容器，将相关项目分组：

- **自动创建**：系统根据钱包的结账配置自动创建
- **分期付款管理**：每期分期付款均对应账单中的一个项目
- **付款与跟踪**：支持跟踪付款、余额和账单状态

---

# Manual BaaS - 数字账户

URL: /zh-Hans/documentation/casos_de_uso/manual_baas

:::warning 注意
在开始开户流程之前，合作伙伴有责任进行 KYC 和反欺诈分析。
::: 

:::danger 注意！
QI Tech 的 Webhooks 不应以受限方式进行映射。
API 返回的 Webhook payload 中可能会新增额外字段。
:::

:::info 重新发送 Webhooks
您可以按照文档中的详细说明查询和重新发送 Webhooks：[重新发送 Webhooks](/documentation/notificacoes/reenvio_de_notificacoes)。
:::

为此，应使用 /onboarding 中描述的分析端点。

## 1 - 创建账户

### 1.1. 上传文件

开户前须先上传公司文件。以下是各类型公司所需的文件列表：

S.A. 公司：

- 公司章程。

- 公司法定代表人选举会议纪要。

- 授权书（如适用）。

- 每位法定代表人或受托人的带照片证件。

其他情况：

- 合同协议。

- 授权书（如适用）。

- 每位法定代表人或受托人的带照片证件。文件须压缩为 ".zip" 格式，并通过文件上传端点发送（）。

#### **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 重要
请保存此 **_"document_key"_**，因为在创建账户步骤中将会用到它。
::: 

### 1.2. 创建法人账户（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"：** 公司数据应在此对象中发送。

"***account_owner.company_statute***"：上传公司章程文件（".zip" 格式）时，文件上传端点返回的 "***document_key***" 应在此字段中发送。

"***account_owner.company_representatives***"：公司法定代表人的数据列表应在此对象中发送。至少应发送足以根据公司章程/合同合法代表公司的法定代表人。每位法定代表人的权限验证由合作伙伴负责。

"***account_owner.company_representatives.document_identification***"：上传代表人带照片证件（".zip" 格式）时，文件上传端点返回的 "***document_key***" 应在此字段中发送。

"***allowed_user***"：此字段应发送 "***account_owner.company_representatives***" 对象中某位法定代表人的数据。该用户将成为账户管理员，拥有账户操作权限以及添加新管理员用户的权限。无论是账户操作还是添加新用户的 SMS/邮件确认，均将发送给此人。

:::info
具有管理员权限的用户对账户拥有完全控制权（通过短信或邮件的双因素认证）。因此，该用户须根据公司合同/章程在法律上具有操作账户的权限。管理员用户的权限验证由合作伙伴负责。
:::

### 1.2.1 开户条款签署
	在开户 payload 中，须发送 `signature_contract` 字段，该字段应包含用户（账户持有人或主用户）接受开户条款时的设备扫描信息。

### signed_contract 对象 
| 字段 | 类型   | 描述        | 字符数    |
|-------|--------|------------------|---------------|
| **document_key** * | uuidv4 | **开户条款**或**托管账户合同**文件的唯一标识键。（DOCUMENT_KEY 在[文件上传](./upload_de_documentos)端点的响应中返回） | 36            |
| **signatures** *   | list   | 所发送文件的签名数据。列表中的每一项对应一位签署人。      | [signatures 对象](#objeto-signatures) |

### signatures 对象
| 字段 | 类型       | 描述         | 字符数        |
|-------|------------|-------------------|-------------------|
| **authenticity** * | object     | 证明签署人完成电子签名的数据集合。 | [authenticity 对象](#objeto-authenticity) |
| **signer** * | object     | 包含某位文件签署人数据的对象。           | [signer 对象](#objeto-signer)|
| **authentication_type** * | enumerator | 签名类型。始终为 "**opt-in**"| "**opt-in**"                   |

### authenticity 对象
| 字段 | 类型   | 描述               | 字符数 |
|-------|--------|-------------------------|------------|
| **timestamp** *            | string | 文件签署时的日期和时间。                | 27         |
| **facial_recognition_key** | uuidv4 | 账户持有人自拍照片的唯一标识键。（DOCUMENT_KEY 在[文件上传](./upload_de_documentos)端点的响应中返回） | 36         |
| **lang**                   | string | 签署时捕获的签署人地理位置经度坐标。                  | -          |
| **lat**                    | string | 签署时捕获的签署人地理位置纬度坐标。                   | -          |
| **ip_address**             | string | 签署人设备的 IP 地址。     | -          |
| **session_id**             | string | 签署时签署人的会话 ID。                | -          |

### signer 对象
| 字段                 | 类型   | 描述                                 | 字符数                        |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| **name** *            | string | 签署人姓名。                        | -                                 |
| **email** *           | string | 签署人邮箱。                       | -                                 |
| **phone** *           | object | 包含签署人电话数据的对象 | **[phone 对象](#objeto-phone)** |
| **document_number** * | string | 签署人 CPF。                         | 11                                |

### phone 对象 

| 字段 | 描述 | 示例 |  最大字符数 | 
| --- | --- | --- | --- | 
|`country_code` *| string | 电话 DDI 代码 (https://ddi.guiamais.com.br/) | 3 | 
| `area_code` *| string | 电话 DDD 代码 (https://ddd.guiamais.com.br/) | 2 |
| `number` *| string |电话号码（仅数字） |  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 重要
重要：此响应中返回的 "***key***" 是开户申请的 PROPOSAL-KEY。应将其保存，以便读取开户 Webhook。
::: 

开户申请的响应始终返回状态 "***pending_kyc_analysis***"。

系统将为该客户保留一个账号，但账户仍待 QI Tech 进行 KYC 分析。此时，账户尚未开通，无法接收或发送资金。

### 1.3. 创建个人账户（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"：** 个人账户持有人的数据应在此对象中发送。

**"account_owner.document_identification"：** 文件上传端点返回的 "document_key"。

#### 1.3.1. 身份证件的提交方式

开立个人账户时，可提交两种类型的证件（***document_identification_type***）：**cnh** 或 **rg**。

身份证件可以 "**.pdf**"、"**.png**" 和 "**.jpeg**" 格式提交。

##### 1.3.1.1. 提交 CNH 类型身份证件

如果文件以 2 个文件提交，证件正面在一个文件中，背面在另一个文件中，则应在 ***/account*** 端点（**1.2.2.**）的 ***account_owner*** 对象中填写以下字段：

Request Body

```json

		"document_identification": "\<DOCUMENT-KEY DA FRENTE DO DOCUMENTO\>",
		"document_identification_back": "\<DOCUMENT-KEY DA VERSO DO DOCUMENTO\>",
		"document_identification_type": "cnh",
```

如果文件以 1 个文件提交，同一文件中包含证件正面和背面（**证件照片或电子驾照**），则应在 ***/account*** 端点（**1.2.2.**）的 account_owner 对象中填写以下字段：
Request Body

```json
		"document_identification": "\<DOCUMENT-KEY DA FRENTE DO DOCUMENTO\>",
		"document_identification_type": "cnh",
```

##### 1.3.1.2. 提交 RG 类型身份证件 

对于 RG 类型证件，必须始终提交 2 个文件，一个包含证件正面，另一个包含证件背面。在此情况下，应在 /account 端点（1.2.2.）的 account_owner 对象中填写以下字段：

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 重要
**重要：** 此响应中返回的 "***key***" 是开户申请的 **PROPOSAL-KEY**。应将其保存，以便读取开户 Webhook。
:::

开户申请的响应始终返回状态 "***pending_kyc_analysis***"。
系统将为该客户保留一个账号，但账户仍待 QI Tech 进行 KYC 分析。此时，账户尚未开通，无法接收或发送资金。

:::info
在沙盒环境中，可使用账户 owner 的 CPF/CNPJ 第一位数字来模拟审批、拒绝和人工审核情况：

- 0 到 7 -> 人工审核

- 8 -> 自动拒绝

- 9 -> 自动审批
:::

QI Tech 完成 KYC/PLD 分析后，将发送开户 Webhook，如下所示：

        **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"
}
```

此时将返回账户的 "account_key"，账户即可投入使用。

如果账户未通过 KYC/PLD 流程，将发送账户被拒绝的 Webhook：

        **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 注意

**allowed_user** 属性仅在法人（PJ）开户 Webhook 中返回；对于个人（PF）账户，**data** 对象中仅返回 **account_info** 和 **account_owner** 属性。

:::

#### 1.3.2 开户条款签署
	在开户 payload 中，须发送 `signature_contract` 字段，该字段应包含用户（账户持有人或主用户）接受开户条款时的设备扫描信息。

### signed_contract 对象 
| 字段 | 类型   | 描述        | 字符数    |
|-------|--------|------------------|---------------|
| **document_key** * | uuidv4 | **开户条款**或**托管账户合同**文件的唯一标识键。（DOCUMENT_KEY 在[文件上传](./upload_de_documentos)端点的响应中返回） | 36            |
| **signatures** *   | list   | 所发送文件的签名数据。列表中的每一项对应一位签署人。      | [signatures 对象](#objeto-signatures) |

### signatures 对象
| 字段 | 类型       | 描述         | 字符数        |
|-------|------------|-------------------|-------------------|
| **authenticity** * | object     | 证明签署人完成电子签名的数据集合。 | [authenticity 对象](#objeto-authenticity) |
| **signer** * | object     | 包含某位文件签署人数据的对象。           | [signer 对象](#objeto-signer)|
| **authentication_type** * | enumerator | 签名类型。始终为 "**opt-in**"| "**opt-in**"                   |

### authenticity 对象
| 字段 | 类型   | 描述               | 字符数 |
|-------|--------|-------------------------|------------|
| **timestamp** *            | string | 文件签署时的日期和时间。                | 27         |
| **facial_recognition_key** | uuidv4 | 账户持有人自拍照片的唯一标识键。（DOCUMENT_KEY 在[文件上传](./upload_de_documentos)端点的响应中返回） | 36         |
| **lang**                   | string | 签署时捕获的签署人地理位置经度坐标。                  | -          |
| **lat**                    | string | 签署时捕获的签署人地理位置纬度坐标。                   | -          |
| **ip_address**             | string | 签署人设备的 IP 地址。     | -          |
| **session_id**             | string | 签署时签署人的会话 ID。                | -          |

### signer 对象
| 字段                 | 类型   | 描述                                 | 字符数                        |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| **name** *            | string | 签署人姓名。                        | -                                 |
| **email** *           | string | 签署人邮箱。                       | -                                 |
| **phone** *           | object | 包含签署人电话数据的对象 | **[phone 对象](#objeto-phone)** |
| **document_number** * | string | 签署人 CPF。                         | 11                                |

### phone 对象 

| 字段 | 描述 | 示例 |  最大字符数 | 
| --- | --- | --- | --- | 
|`country_code` *| string | 电话 DDI 代码 (https://ddi.guiamais.com.br/) | 3 | 
| `area_code` *| string | 电话 DDD 代码 (https://ddd.guiamais.com.br/) | 2 |
| `number` *| string |电话号码（仅数字） |  10 |

### 1.4. 获取账户数据

        **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
账户数据查询响应中最相关的字段为：**account_branch**、**account_digit**、**account_key**、**account_number**、**balance**、**owner_document_number**、**owner_name**、**owner_person_key**。
:::

## 2 - PIX 转账

### 2.1. 执行 PIX 转账

执行 PIX 转账需进行三次调用：

1. 创建转账请求：/baas/pix_transfer

2. 申请转账验证令牌：/baas/token_request

3. 批准转账：/baas/movement_validation

:::info
PIX 转账可使用两种不同的 payload 完成：**PIX 密钥**或**银行账户数据**。 
:::

### **2.1.1. 创建转账请求**
### 使用 PIX 密钥进行转账（CPF、CNPJ、电子邮件、手机号或随机密钥）

- 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
"**pix_key**" 可以是 **CPF**、**CNPJ**、**电子邮件**、**手机号**或**随机密钥（UUID）**，格式如下：

**CPF：** 11 位整数。

**CNPJ：** 14 位整数。

**电子邮件：** 包含至少一个"@"的文本。

**手机号：** 包含以下值的文本："+55" + "手机 DDD 区号" + "至少 8 位、最多 9 位整数的手机号"。例："+5511987654321"。

**随机密钥：** UUID。
:::

### 使用银行账户数据进行转账（手动 PIX）

- 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
}

```

使用手动 PIX 时，需要提供目标机构的 ISPB。此数据之所以必要，是因为有些支付机构可以接收 PIX，但没有银行代码。ISPB 是机构 CNPJ 的前缀。要获取参与 PIX 的各机构完整 ISPB 列表，可使用我们文档中的查询端点：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 PIX 转账/付款申请的可能状态： 

**pending_approval：** 转账待账户管理员用户（"***allowed_user***"）批准

**sent：** 转账已发送
:::

:::caution 注意
返回的 **end_to_end_id** 字段须保存，并在批准交易时提交。正是它来保障交易的唯一性。
:::

完成第一次 "***/baas/pix_transfer***" 调用后，需要申请令牌以批准交易。要批准 PIX 转账，须使用转账申请中返回的 "***pix_transfer_key***"，并申请生成一个令牌，该令牌将发送给账户管理员用户（"**allowed_user**"）以供批准。

### **2.1.2. 申请转账验证令牌：**

- 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：** 是批准转账时将使用的双因素认证方式，可通过电子邮件（"email"）或短信（"sms"）进行。
:::

:::info
**approver_document_number：** 应填写将批准 PIX 转账的管理员用户的 CPF。
:::

:::info
**agent_document_number：** 此字段可填写将接收用于交易双因素批准令牌的主用户 CPF。
:::

完成转账的最后一次调用是 "**/baas/movement_validation**"，收到的令牌须在批准 PIX 转账时提供。令牌的有效期为 **2 分钟**。

管理员用户须在合作伙伴应用中输入通过电子邮件或短信收到的令牌。

### **2.1.3. 批准转账：**

- 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
如果返回 **http error 422**，**不得**重新尝试 PIX 请求。需要通过 GET 请求 [/baas/pix/pix_transfer](/documentation/pix/pesquisar_por_transferencia_pix_de_saida) 路由来检查 PIX 转账申请的状态。
:::

### 2.2. PIX 到账 Webhook

#### **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. PIX 手续费扣收 Webhook

        **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. PIX 退款（Chargeback）

PIX 退款（Chargeback）分三个步骤完成：

- 1 - 发起 PIX Chargeback：/baas/pix_transfer
- 2 - 申请 PIX Chargeback 授权令牌：/baas/token_request
- 3 - 批准 PIX Chargeback：/baas/movement_validation

#### 2.4.1. 发起 PIX Chargeback

##### 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
_**pix_transfer_key**_ 是向 QI 账户入账的 PIX 的密钥，通过 _**account_transaction**_ 的 Webhook 返回。

_**chargeback_amount**_ 须小于或等于向 QI 账户入账的 PIX 金额。
:::

##### 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
调用中返回的 _**pix_transfer_key**_ 是待批准的 PIX Chargeback 的参考密钥。
:::

#### 2.4.2. 申请 PIX Chargeback 授权令牌

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. 批准 PIX Chargeback

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 - TED 转账

:::info
TED 转账只能在工作日 **7:00** 至 **17:00** 之间进行。
:::

### 3.1. 执行 TED 转账

通过 TED 进行转账需进行以下调用： 

1. 申请转账验证令牌：/baas/token_request

2. 批准转账：/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
	}
}
```

收到的令牌须在批准 TED 转账时提供，且 "***movement_payload***" 须与申请令牌时提供的内容相同。

        **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
"***transacted_at***" 字段采用 UTC 格式。
:::

:::info
"***transaction_key***" 将在后续申请转账凭证时使用。
:::

### 3.2. 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. 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 - PIX QR Code 付款

### 4.1. 支付静态 PIX QR Code

支付静态 PIX QR Code 需进行四次调用：

1. 解码 PIX QR Code：/baas/pix/qrcode

2. 创建转账请求：/baas/pix_transfer

3. 申请转账验证令牌：/baas/token_request

4. 批准转账：/baas/movement_validation

解码静态 PIX QR Code 所需的信息是与 QR Code 关联的 PIX 复制粘贴 URI。

:::info
**PIX 复制粘贴 URI 示例：** 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 注意
支付静态 PIX QR Code 的请求与 PIX 转账请求相同，但有以下变化：
**1** - 新增 "***end_to_end_id***" 字段。须填写静态 QR Code 解码返回的相同值；

**2** - 在 "***transaction_amount***" 字段中填写静态 QR Code 解码时 "qr_code_data.amount" 字段返回的相同值；

**3** - 将 "***pix_transfer_type***" 字段改为 "***static***"，以通过 "***/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"
}
```

完成第二次 "**/baas/pix_transfer**" 端点调用后，需要申请令牌以批准交易。要批准 PIX 转账，须使用转账申请中返回的 "**pix_transfer_key**"，并申请生成一个令牌，该令牌将发送给账户管理员用户（"***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"
    }
}
```

完成付款的最后一次调用是 "**/baas/movement_validation**"，收到的令牌须在批准 PIX 转账时提供。令牌的有效期为 2 分钟。
管理员用户须在合作伙伴应用中输入通过电子邮件或短信收到的令牌。

        **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

此响应与 PIX 转账批准响应的唯一区别，是 "***pix_transfer_type***" 字段的值，此处返回为 "***static***"。

:::

### 4.2. 支付动态 PIX QR Code

支付动态 PIX QR Code 需进行四次调用：

1. 解码 PIX QR Code：/baas/pix/qrcode

2. 创建转账请求：/baas/pix_transfer

3. 申请转账验证令牌：/baas/token_request

4. 批准转账：/baas/movement_validation。解码动态 PIX QR Code 所需的信息是与 QR Code 关联的 PIX 复制粘贴 URI。

:::info
静态 PIX QR Code 和动态 PIX QR Code 在 "***/baas/pix/qrcode***" 中的唯一区别是端点的响应。
:::

        **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 注意
支付动态 PIX QR Code 的请求与 PIX 转账请求相同，但有以下变化：

1 - 新增 "end_to_end_id" 字段。须填写动态 QR Code 解码返回的相同值。
2 - 在 "transaction_amount" 字段中填写动态 QR Code 解码时 "qr_code_data.amount" 字段返回的相同值；
3 - 将 "pix_transfer_type" 字段改为 "dynamic_term"，以通过 "/baas/pix_trasnfer" 发起付款请求。
4 - 新增 "receiver_conciliation_id" 字段。须填写动态 QR Code 解码返回的相同值。
:::

        **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"
}
```

完成第二次 "***/baas/pix_transfer***" 端点调用后，需要申请令牌以批准交易。要批准 PIX 转账，须使用转账申请中返回的 "***pix_transfer_key***"，并申请生成一个令牌，该令牌将发送给账户管理员用户（"***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"
    }
}
```
 

完成付款的最后一次调用是 "***/baas/movement_validation***"，收到的令牌须在批准 PIX 转账时提供。令牌的有效期为 2 分钟。
管理员用户须在合作伙伴应用中输入通过电子邮件或短信收到的令牌。

        **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
此响应与 PIX 转账批准响应的唯一区别，是 "***pix_transfer_type***" 字段的值，此处返回为 "***dynamic_term***"。
:::

## 5 - 管理 PIX 密钥

:::info
"***pix_key***" 可以是 **CPF**、**CNPJ**、**电子邮件**、**手机号**或**随机密钥**（UUID），格式如下：

**CPF：** 11 位整数。

**CNPJ：** 14 位整数。

**电子邮件：** 包含至少一个"@"的文本。

**手机号：** 包含以下值的文本："+55" + "手机 DDD 区号" + "至少 8 位、最多 9 位整数的手机号"。例："+5511987654321"。

**随机密钥：** UUID。
:::

### 5.1. 创建 CPF、CNPJ 或随机 PIX 密钥
要创建 CNPJ PIX 密钥或随机密钥，只需调用 "***/baas/pix/keys***" 端点，将 "***pix_key_type***" 更改为 "**cnpj**"、"**cpf**" 或 "**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"
}
```

或

Request Body

```json

{
    "account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
    "pix_key_type": "cnpj",
    "pix_key": "09080702000105"
}

```

或

**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 注意
对于创建**随机** PIX 密钥的响应，"***pix_key***" 字段将返回空值，因为这是一个由巴西中央银行生成密钥的异步过程。要获取已生成的随机密钥值，需要查询账户中已注册的密钥列表（如"**查询账户中已注册的 PIX 密钥**"条目所述），或等待 inclusion Webhook。
:::

:::info
由于验证 **CNPJ** 或 **CPF** PIX 密钥是否激活是异步过程，需要查询账户中已注册的密钥列表（如"**查询账户中已注册的 PIX 密钥**"条目所述），或等待 inclusion Webhook。
:::

**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. 创建电子邮件和手机号 PIX 密钥

要创建**电子邮件**或**手机号** PIX 密钥，须调用两个端点：

**1 - 创建密钥：** POST 请求 "**/baas/pix/keys**" 端点，将 "***pix_key_type***" 字段改为 "email" 或 "phone_number"。此时，将向 "***pix_key***" 字段中填写的电子邮件或手机号发送令牌。

**2 - 批准密钥：** PATCH 请求 "**/baas/pix/keys/\ **" 端点，填写上一步收到的令牌。

        **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",
	"request_type": "inclusion",
	"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
	"updated_at": "2022-09-02T17:41:55"
}
```

**重要：** "pix_key_request_key" 字段返回的值须在请求 URL 中用于批准 PIX 密钥创建。

### 5.3. 批准已申请的电子邮件或手机号 PIX 密钥

        **Request**

- MÉTODO PATCH
- ENDPOINT /baas/pix/keys/ PIX_KEY_REQUEST_KEY /twofa_validation

Request Body

```json
{
    "verification_code": "756816"
}
```

### 5.4. 重新发送验证码

        **Request**

- MÉTODO PATCH
- ENDPOINT /baas/pix/keys/ PIX_KEY_REQUEST_KEY /resend_twofa

**payload.json**

```json
{}
```

### 5.5. 查询账户中已注册的 PIX 密钥

        **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. 删除 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 - 生成 PIX QR Code

### 6.1. 生成静态 PIX QR Code

QR Code 从账户中已注册的有效 PIX 密钥创建。生成 QR Code 后，将返回与 QR Code 关联的 PIX 复制粘贴 URI，以及 QR Code 图片的 base64（如有请求）。

QR Code 图片也可由合作伙伴使用 PIX 复制粘贴 URI 自行生成。

生成静态 PIX QR Code 只需一个请求：

        **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
**qr_code_format** 字段可填写 "***image***"、"***payload***" 和 "***both***"。
- "***image***"：返回包含 PIX QR Code 图片 base64 的字段。
- "***payload***"：返回包含 PIX QR Code 复制粘贴 URI base64 的字段。
- "***both***"：返回以上两个字段。
:::

        **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. 生成动态 PIX QR Code

动态 QR Code 有两种类型：即时付款动态 QR Code 和到期日动态 QR Code。

#### 6.2.1. 生成带到期日的动态 PIX QR Code

这是一种功能与银行票据（boleto）非常相似的 PIX QR Code 类型，可包含到期日、滞纳金、逾期利息和提前付款折扣等信息。生成此类 PIX QR Code 只需向 "***/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：** 此字段填写预期操作。可选值：registration、edit、write_off 
- **registration：** 创建新 QR Code
- **edit：** 编辑已有 QR Code（如下方条目所述）。
- **write_off：** 注销已激活的 QR Code。

**interest_amount：** 每日逾期利息金额（巴西雷亚尔 R$）。

**fine_amount：** 逾期罚款金额（巴西雷亚尔 R$）。

**discounts：** 提前付款折扣信息。如不适用，请发送空列表（[]）。

**additional_data：** 可自定义的元标签，可在付款时向付款方展示。格式如下："\ ": "\ "。

**tag_name** 最多 100 个字符，**tag_value** 最多 320 个字符。
:::

        **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
"**base_64**"字段是与此动态 PIX QR Code 关联的 PIX 复制粘贴 URI。
:::
 

#### 6.2.2. 生成即时支付动态 PIX QR Code

这是一种类似于静态 QR Code 的 PIX QR Code 类型，但便于收款方进行对账，并且可以设置当日到期（例如，有效期仅为 5 分钟）。
要生成此类 PIX QR Code，只需向端点 ***"/baas/qrcode/dynamic"*** 发起一次请求。

        **请求（Request）**

- 方法 POST
- 端点 /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）**

- 方法 POST
- 端点 /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. 编辑动态 PIX QR Code 数据

要编辑动态 PIX QR Code 的数据，需要提供 QR Code 的 "***qr_code_key***" 并将 "***occurrence_type***" 设置为 "***edit***"。在此情况下，需要重新发送所有数据。

        **请求（Request）**

- 方法 POST
- 端点 /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）**

- 方法 POST
- 端点 /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. 注销动态 PIX QR Code

要注销动态 PIX QR Code，需要提供 QR Code 的 "***qr_code_key***" 并将 "***occurrence_type***" 设置为 "***write_off***"。

        **请求（Request）**

- 方法 POST
- 端点 /baas/qrcode/dynamic

Request Body

```json
{
    "qr_code_key": "3bd19ada-2341-41bf-9f1f-c5ce0b216723",
    "occurrence_type": "write_off"
}

```

        **响应（Response）**

- 方法 POST
- 端点 /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 - 登记、修改和支付银行票据（Boleto）

### 7.1. 查询收款钱包

要登记、修改和支付银行票据，首先需要获取与账户绑定的收款钱包代码（Requester Profile Code）。每个账户在创建时都会自动绑定一个收款钱包。

收款钱包代码遵循以下格式：

"银行编号" + "钱包代码" + "账户行号" + "不含校验位的7位账户号码"。
在 QI Tech，银行编号、钱包代码和行号默认分别为 "329"、"09" 和 "0001"。
例如："**329-09-0001-2359934**"。

如需获取各账户的收款钱包代码列表，请使用以下端点：

        **请求（Request）**

- 方法 GET
- 端点 /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 注意
银行票据的登记、修改和注销通过事件（occurrence）机制进行。每个事件发送至 QI Tech 后，再转发至票据集中处理中心。
事件可能被票据集中处理中心接受或拒绝。
关于事件接受或拒绝的结果将通过 webhook 发送给合作方。
:::

### 7.2. 登记票据
要登记一张票据，需要发送一个登记事件，具体方式如下端点所述：

        **请求（Request）**

- 方法 POST
- 端点 /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
我方银行编号（"***our_number***"）是票据在收款钱包中的 ID，应为递增 ID。
我方银行编号（"***our_number***"）由合作方生成，并在登记票据时提供。

**重要提示：** 票据应通过以下组合键定位：我方银行编号（"***our_number***"）+ 收款钱包代码（"***requester_profile_code***"）。
:::

        **响应（Response）**

- 方法 POST
- 端点 /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": []
}
```

关于票据登记的接受或拒绝结果将通过以下 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"
}
```

要将收到的 webhook 与某张票据关联，应使用我方银行编号（"***our_number***"）和收款钱包代码（"requester_profile_code"）。

一旦票据登记被集中处理中心接受，webhook 中将返回票据的 UUID 密钥（"***bank_slip_key***"）。请保存此密钥，通过它可以查询票据信息。

### 7.2. 修改票据数据

要修改票据数据，需要发送一个事件。每种可能的修改对应相应的事件类型。票据数据修改的事件列表可在我们的文档《发送票据指令》[链接]中查阅。

### 7.3. 申请票据补发

票据登记后，可申请生成票据的 ".pdf" 文件，其中包含付款所需的信息。

        **请求（Request）**

- 方法 POST
- 端点 /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
将返回票据的所有数据，".pdf" 下载链接将在 "bank_slip_file.url" 对象中提供。
:::

### 7.4. 查询票据数据

票据数据可通过两种不同方式查询。

#### 7.4.1. 通过可输入行查询

票据的可输入行（linha digitável）是一串包含票据信息的数字序列。付款用户在付款银行的网银中输入此数字序列。

:::info
可输入行示例：32990001031000000000902000000204685640000100000
:::

通过可输入行可查询票据数据：

        **请求（Request）**

- 方法 GET
- 端点 /bank_slip/payment
- 参数 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. 通过票据密钥查询

一旦票据登记被集中处理中心接受，webhook 中将返回票据的 UUID 密钥（"***bank_slip_key***"）。通过此密钥可查询票据信息：

        **请求（Request）**

- 方法 GET
- 端点 /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. 支付票据

要支付一张票据，需要进行两次调用：

1. 申请转账验证 token：/baas/token_request

2. 批准转账：/baas/movement_validation

        **请求（Request）**

- 方法 POST
- 端点 /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
发送的 Token 需在批准票据付款时提供，且 "***movement_payload***" 必须与申请 Token 时所提供的内容一致。
:::

        **请求（Request）**

- 方法 POST
- 端点 /baas/movement_validation

Request Body

```json
{
    "token": "358192",
    "movement_payload": {
        "resource_account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
        "digitable_line": "32990001031000699926165000000201993810000003500"
    }
}

```

        **响应（Response）**

- 方法 POST
- 端点 /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. 票据收款通知

当票据在其他银行被支付时，系统会实时发送该票据已被支付的通知。财务清算将于下一个工作日进行。

        **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：** 票据的支付方式，可为：

**"credit_card"：** 信用卡

**"cash"：** 现金

**"account_debit"：** 账户扣款

**"check"：** 支票
:::

:::info
**payment_origin：** 票据支付地点的来源，可为：

**"internet"：** 网上银行

**"phisical_cashier"：** 银行柜台（窗口）

**"taa"：** 自动柜员机

**"eletronic_file"：** CNAB 清算文件

**"call_center"：** 客服中心

**"dda"：** DDA（授权直接扣款）

**"corban"：** 彩票点 - 银行代理
:::

:::caution 注意
支付方式（"***payment_method***"）和支付来源（"***payment_origin***"）信息由付款方在支付票据时提供，其一致性和真实性由处理该支付的机构负责。
:::

## 8 - 资金流动、凭证与账单

:::info
本手册包含我们 Banking as a Service 产品的结构/信息，同时也可作为我们端点的文档参考。
:::

### 8.1. 资金流动
每一笔资金流动都将发送一个 "***account_transaction***" webhook。

每笔交易都有一种分类类型（**Source Sub Type**）。该分类用于对账户中的每笔流动进行归类。Source Sub Types 列表可在本手册的**附录 I** 中查阅。

账户入账将产生一个 "***data.amount***" 为正值的 webhook，"***data.origin***" 为资金来源账户，"***data.destination***" 为资金目标账户：

        **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: 其他交易

```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"
}
```

账户出账将产生一个 "***data.amount***" 为负值的 webhook，"***data.origin***" 为资金目标账户，"***data.destination***" 为资金来源账户：

        **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"
}
```
 

**source_sub_type 列表：**

| Enum                                    | 描述                                            |
|-----------------------------------------|-------------------------------------------------|
| operation_disbursement                  | 操作放款                                        |
| protest_expense                         | 抗议费用                                        |
| automatic_integrated_payment            | 集成自动支付                                    |
| tax                                     | 税费                                            |
| electronic_funds_fee                    | TED手续费                                       |
| credit_operation_fee                    | 信贷开立手续费                                  |
| internal_funds_transfer                 | 内部转账                                        |
| incoming_funds_transfer                 | 入账转账                                        |
| outgoing_funds_transfer                 | TED                                             |
| deposit                                 | 存款                                            |
| withdrawal                              | 转账                                            |
| withdrawal_reversal                     | 转账退款                                        |
| trade_funds_transfer                    | 转让付款转账                                    |
| settlement_funds_transfer               | 清算转账                                        |
| bank_slip_fee                           | 银行单据手续费                                  |
| bank_slip_settlement                    | 银行单据清算                                    |
| outgoing_funds_transfer_reversal        | TED退款                                         |
| incoming_funds_transfer_refusal         | 拒绝转账                                        |
| electronic_funds_fee_reversal           | TED手续费退款                                   |
| monthly_account_fee_reversal            | 账户维护手续费退款                              |
| bank_slip_fee_reversal                  | 银行单据手续费退款                              |
| correspondent_bank_transfer             | 银行代理转付                                    |
| credit_analysis_fee                     | 信贷分析手续费                                  |
| credit_operation_fee_reversal           | 信贷开立手续费退款                              |
| financial_investments_income            | 金融投资收益                                    |
| bank_slip_settlement_reversal           | 银行单据清算退款                                |
| bank_slip_settlement_expense_reversal   | 银行单据清算手续费退款                          |
| bank_slip_settlement_incoming_reversal  | 银行单据清算收款退款                            |
| correspondent_bank_transfer_reversal    | 银行代理转付退款                                |
| credit_analysis_fee_reversal            | 信贷分析手续费退款                              |
| doc_expense_reversal                    | DOC手续费退款                                   |
| incoming_doc_reversal                   | DOC入账退款                                     |
| operation_disbursement_reversal         | 操作放款退款                                    |
| operation_settling_reversal             | 操作付款退款                                    |
| outgoing_doc_reversal                   | DOC出账退款                                     |
| rebate_reversal                         | 回扣退款                                        |
| settlement_funds_transfer_reversal      | 清算转账退款                                    |
| tax_reversal                            | 税费退款                                        |
| trade_funds_transfer_reversal           | 转让付款转账退款                                |
| bank_slip_permanency_fee                | 票据保管手续费                                  |
| bank_slip_cancel_protest_fee            | 票据保管手续费                                  |
| bank_slip_protest_fee                   | 抗议申请手续费                                  |
| bank_slip_notary_office_fee             | 抗议公证费用                                    |
| bank_slip_registration_fee              | 登记手续费                                      |
| bank_slip_extension_fee                 | 延期手续费                                      |
| bank_slip_rebate_fee                    | 折扣手续费                                      |
| bank_slip_discount_fee                  | 贴现手续费                                      |
| bank_slip_settlement_fee                | 清算手续费                                      |
| bank_slip_write_off_term_fee            | 到期注销手续费                                  |
| bank_slip_write_off_fee                 | 注销手续费                                      |
| bank_slip_cancel_protest_write_off_fee  | 带注销的抗议中止手续费                          |
| bank_slip_notary_office_settlement_fee  | 公证处清算手续费                                |
| rebate_tax_free                         | 受托转付                                        |
| rebate_tax_free_reversal                | 受托转付退款                                    |
| incoming_funds_transfer_reversal        | 内部转账退款                                    |
| bank_slip_payment                       | 银行单据付款                                    |
| bank_slip_payment_reversal              | 银行单据付款退款                                |
| warranty_analysis_fee                   | 担保分析手续费                                  |
| bank_slip_settlement_deposit            | 银行单据清算                                    |
| bank_slip_payment_withdrawal            | 银行单据付款                                    |
| account_setup_fee                       | 开户手续费                                      |
| account_setup_fee_reversal              | 开户手续费退款                                  |
| bank_slip_payment_withdrawal_reversal   | 银行单据付款退款                                |
| incoming_anticipation_of_receivable     | -                                               |
| incoming_credit_card_settlement         | 信用卡清算                                      |
| incoming_debit_card_settlement          | 借记卡清算                                      |
| assignment_automatic_transfer           | 自动转让扣款                                    |
| assignment_automatic_transfer_reversal  | 自动转让扣款退款                                |
| pix_fee                                 | PIX手续费                                       |
| incoming_pix_transfer                   | PIX入账                                         |
| outgoing_pix_transfer                   | PIX出账                                         |
| pix_fee_reversal                        | PIX手续费退款                                   |
| incoming_pix_transfer_reversal          | PIX入账退款                                     |
| outgoing_pix_transfer_reversal          | PIX出账退款                                     |
| pix_deposit                             | PIX存款                                         |
| pix_withdrawal                          | PIX转账                                         |
| pix_withdrawal_reversal                 | PIX转账退款                                     |
| pix_chargeback_withdrawal               | PIX退款发送                                     |
| outgoing_pix_chargeback                 | PIX退款出账                                     |
| incoming_pix_chargeback                 | PIX退款收款                                     |
| pix_chargeback_deposit                  | PIX退款入账                                     |
| pix_chargeback_withdrawal_reversal      | PIX退款发送退款                                 |
| outgoing_pix_chargeback_reversal        | PIX退款出账退款                                 |
| incoming_pix_chargeback_reversal        | PIX退款收款退款                                 |
| operation_pix_disbursement              | 操作PIX放款                                     |
| operation_pix_disbursement_reversal     | 操作PIX放款退款                                 |
| receivables_inquiry_fee                 | 应收款日程查询手续费                            |
| pix_deposit_reversal                    | PIX存款退款                                     |
| internal_pix_transfer                   | PIX转账                                         |
| automatic_integrated_payment_reversal   | 集成自动支付退款                                |
| operation_dibursement_reversal          | 操作放款退款                                    |
| available_yield                         | 流动投资存款                                    |

 
### 8.2. 凭证

转账/付款的凭证数据可通过 "**transaction_key**" 查询。

        **请求（Request）**

- 方法 GET
- 端点 /transaction_receipt/TRANSACTION-KEY

        **响应（Response）** - 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）** - 内部转账或 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）** - 票据付款

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. 账单

账户账单可通过以下端点查询：

        **请求（Request）**

- 方法 GET
- 端点 /account_statement
- 参数 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 - 用户管理

可以对已开立账户的管理员用户进行添加和编辑。添加操作始终需要对被添加用户进行双因素身份验证。

### 9.1. 向已开立账户添加新用户

#### 9.1.1. 创建

首先需要创建用户。在创建时，QI Tech 将通过短信或邮件向被创建用户发送一个 token。

        **请求（Request）**

- 方法 POST
- 端点 /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
		}
	}
}
```

创建/更新新用户的双因素身份验证只能通过 "sms" 方式进行。

#### 9.1.2. 确认创建

需要提供发送的 token 以完成新用户的创建：

        **请求（Request）**

- 方法 POST
- 端点 /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）**

- 方法 POST
- 端点 /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. 创建职业关联

用户创建后，需要将其关联到持有已开立账户的企业：

        **请求（Request）**

- 方法 POST
- 端点 /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. 批准职业关联

要批准关联的添加，需要发送管理员用户收到的 token。

        **请求（Request）**

- 方法 POST
- 端点 /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）**

- 方法 POST
- 端点 /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. 更新现有用户数据

用户数据的更新始终在该用户与特定企业的关联层级上进行。因此，执行任何更新时，始终需要用户的识别密钥（"***natural_person***"）以及该用户与企业关联的密钥（"***professional_data_key***"）。

#### 9.2.1. 申请变更

首先需要申请更新用户与特定企业的关联数据。

        **请求（Request）**

- 方法 POST
- 端点 /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. 批准变更申请

要批准用户数据的变更，需要发送发送给变更目标用户的 token：

        **请求（Request）**

- 方法 POST
- 端点 /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）**

- 方法 POST
- 端点 /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 - 服务

URL: /zh-Hans/documentation/casos_de_uso/manual_baas_servico

:::danger 注意！
QI Tech 的 Webhook 不应进行严格映射。
我们 API 返回的 Webhook 载荷中可能会包含额外字段。
:::

:::info Webhook 重发
您可以按照文档中的详细说明查询和重发 Webhook：[重发 Webhook](/documentation/notificacoes/reenvio_de_notificacoes)。
:::

:::caution 注意
在开始开户流程之前，合作伙伴有责任进行 KYC 分析和欺诈预防。

为此，应使用 [/onboarding](https://docs.zaig.com.br/onboarding/#introducao) 中描述的分析接口。
:::

### 1 - 创建账户

**1.1. 文件上传：** 在开户之前，必须先上传公司文件。以下是各类型公司所需的文件清单：

对于股份公司（S.A.）：

- 公司章程。

- 公司法定代表人选举会议记录。

- 授权书（如适用）。

- 每位法定代表人或受托人的带照片证件。

对于其他情况：

- 社会合同。

- 授权书（如适用）。

- 每位法定代表人或受托人的带照片证件。

文件须压缩为".zip"文件，并通过[文件上传](/documentation/upload_de_documentos/)接口发送。

        **响应**

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
**重要提示：** 请保存此 "**document_key**"，因为在创建账户阶段将会用到它。
:::
 

**1.2.1. 创建企业账户（PJ）：**

        **请求**

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***"：公司数据须在此对象中发送。

"***account_owner.company_statute***"：上传公司社会文件".zip"时，文件上传接口返回的 "***document_key***" 须在此字段中发送。

"***account_owner.company_representatives***"：公司法定代表人数据列表须在此对象中发送。至少须发送能够依据各自章程/社会合同合法代表公司的法定代表人。每位法定代表人权限的核验由合作伙伴负责。

"***account_owner.company_representatives.document_identification***"：上传代表人带照片证件".zip"时，文件上传接口返回的 "***document_key***" 须在此字段中发送。

        **响应**

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
**重要提示：** 此响应中返回的 "***key***" 是开户申请的 **PROPOSAL-KEY**。需保存以用于读取开户 Webhook。
:::

开户请求的响应始终返回状态 "***pending_kyc_analysis***"。
系统将为该客户预留一个账号，但该账户仍待 QI Tech 进行 KYC 分析。此时，账户尚未开通，无法收发资金。

**1.2.2. 创建个人账户（PF）：**

        **请求**

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***"：账户个人持有人数据须在此对象中发送。

"***account_owner.document_identification***"：文件上传接口返回的 "***document_key***"。

        **1.2.2.1. 身份证件发送方式：** 在开立个人账户时，可发送两种类型的证件（***document_identification_type***）：cnh 或 rg。
身份证件可以".pdf"、".png"和".jpeg"格式发送。

           &nbsp**1.2.2.1.1. 发送 CNH 类型身份证件：**

如证件分两个文件发送，正面和背面分别为一个文件，则须在 **/account（1.2.2.）** 接口的 ***account_owner*** 对象中填写以下字段：

"document_identification": "\ ",
"document_identification_back": "\ ",
		"document_identification_type": "cnh",

如证件合并为 1 个文件，同时包含正面和背面（**证件照片或数字驾照**），则须在 ***/account*** 接口 **（1.2.2.）** 的 ***account_owner*** 对象中填写以下字段：

"document_identification": "\ ",
		"document_identification_type": "cnh",
           &nbsp**1.2.2.1.2. 发送 RG 类型身份证件：** 
对于 RG 类型证件，必须始终发送 2 个文件，一个包含证件正面，另一个包含证件背面。此情况下须在 ***/account*** 接口 **（1.2.2.）** 的 ***account_owner*** 对象中填写以下字段：

"document_identification": "\ ",
"document_identification_back": "\ ",
		"document_identification_type": "rg",
 

        **响应**

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
**重要提示：** 此响应中返回的 "**key**" 是开户申请的 **PROPOSAL-KEY**。需保存以用于读取开户 Webhook。
:::

开户请求的响应始终返回状态 "***pending_kyc_analysis***"。
系统将为该客户预留一个账号，但该账户仍待 QI Tech 进行 KYC 分析。此时，账户尚未开通，无法收发资金。

:::info
在沙箱环境中，可使用账户 owner 的 CPF/CNPJ 第一位数字模拟审批、拒绝和人工审核场景：

- 0 至 7 -> 自动审批

- 8 -> 自动拒绝

- 9 -> 人工审核
:::

**1.2.3.** QI Tech 完成 KYC/PLD 分析后，将发送开户 Webhook，如下所示：

        **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
此时将返回账户的 "***account_key***"，账户即可投入使用。
:::

**1.2.4.** 如账户未通过 KYC/PLD 流程，将发送账户拒绝 Webhook：

        **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. 获取账户数据：**

        **请求**

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
账户数据查询响应中最相关的字段为：
**account_branch**、**account_digit**、**account_key**、**account_number**、**balance**、**owner_document_number**、**owner_name**、**owner_person_key**。
:::

--- 

### 2 - PIX 转账
**2.1. 发起 PIX 转账：** 要发起 PIX 转账，需要进行三次调用：

1. 创建转账请求：**/baas/pix_transfer**

2. 审批转账：**/baas/pix_transfer_approval**

:::info
PIX 转账可使用两种不同的载荷发起：**PIX 密钥** 或 **银行账户数据**。
:::

**2.2. 使用 PIX 密钥进行转账（CPF、CNPJ、邮箱、手机号或随机密钥）：**

        **请求**

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
"***pix_key***" 可以是 **CPF**、**CNPJ**、**邮箱**、**手机号** 或 **随机密钥**（UUID），格式如下：

**CPF：** 11 位整数。

**CNPJ：** 14 位整数。

**邮箱：** 包含至少一个"@"的文本。

**手机号：** 包含以下值的文本："+55" + "[手机区号]" + "[最少 8 位、最多 9 位的手机号整数]"。例如："+5511987654321"。

**随机密钥：** UUID。
:::

**2.3. 使用银行账户数据进行转账（手动 PIX）：**

        **请求**

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
}
```

使用手动 PIX 时，需要提供目标机构的 ISPB。之所以使用此数据，是因为存在可接收 PIX 但没有银行代码的支付机构。ISPB 是该机构 CNPJ 的基础部分。要获取每个参与 PIX 机构的完整 ISPB 列表，可使用我们文档中的查询接口：/documentation/lista_de_instituicoes_financeiras/consulta_de_instituicoes_financeiras

 
        **响应**

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
PIX 转账/支付请求的可能状态：

**pending_approval：** 转账待请求方审批

**sent：** 转账已发送
:::

要审批 PIX 转账，需要使用转账请求（***/baas/pix_transfer***）中返回的 "***pix_transfer_key***"：

        **请求**

ENDPOINT /baas/pix_transfer_approval
MÉTODO POST

Request Body

```json
{
    "pix_transfer_key": "cea836b5-b02e-4f94-b1e2-4d575671c33d",
    "approver_document_number": "97564480084"
}
```

        **响应**

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
如返回 **http error 422**，**不得重试** PIX 请求。需通过 GET 请求 [/baas/pix/pix_transfer](/documentation/pix/pesquisar_por_transferencia_pix_de_saida) 路由来检查 PIX 转账请求的状态。
:::

--- 

### 3 - 交易明细、凭证与对账单

**3.1. 交易明细：**

每笔交易都将发送一个 "***account_transaction***" Webhook。

每笔交易都有一个分类类型（**Source Sub Type**）。该分类用于对账户中的每笔交易进行归类。Source Sub Type 列表可在本手册的**附录 I** 中查看。

**3.1.1.** 账户入账将生成一个 "***data.amount***" 为正数的 Webhook，其中 "***data.origin***" 为资金来源账户，"***data.destination***" 为资金目标账户：

        **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: 其他交易

```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.** 账户扣款将生成一个 "data.amount" 为负数的 Webhook，其中 "***data.origin***" 为资金目标账户，"***data.destination***" 为资金来源账户：

        **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"
}
```

**source_sub_type 列表：**

|枚举值|描述|
|--|--|
|operation_disbursement|		操作放款|
|protest_expense|		抗议费用|
|automatic_integrated_payment|		自动集成支付|
|tax	|	税费|
|electronic_funds_fee|		TED 手续费|
|credit_operation_fee|		信贷开立手续费|
|internal_funds_transfer|		内部转账|
|incoming_funds_transfer|		入账转账|
|outgoing_funds_transfer|		TED|
|deposit|		存款|
|withdrawal	|	转账|
|withdrawal_reversal	|	转账冲销|
|trade_funds_transfer|		让渡支付转账|
|settlement_funds_transfer|		清算转账|
|bank_slip_fee	|	票据手续费|
|bank_slip_settlement|		票据清算|
|outgoing_funds_transfer_reversal|		TED 冲销|
|incoming_funds_transfer_refusal	|	转账拒绝|
|electronic_funds_fee_reversal|	TED 手续费冲销|
|monthly_account_fee_reversal|	账户维护费冲销|
|bank_slip_fee_reversal	|票据手续费冲销|
|correspondent_bank_transfer|	银行代理转账|
|credit_analysis_fee	|信用分析手续费|
|credit_operation_fee_reversal|	信贷开立手续费冲销|
|financial_investments_income|	金融投资收益|
|bank_slip_settlement_reversal|	票据清算冲销|
|bank_slip_settlement_expense_reversal|	票据清算手续费冲销|
|bank_slip_settlement_incoming_reversal|	票据清算入账冲销|
|correspondent_bank_transfer_reversal|	银行代理转账冲销|
|credit_analysis_fee_reversal|	信用分析手续费冲销|
|doc_expense_reversal|	DOC 手续费冲销|
|incoming_doc_reversal|	DOC 入账冲销|
|operation_disbursement_reversal|	操作放款冲销|
|operation_settling_reversal|	操作还款冲销|
|outgoing_doc_reversal|	DOC 出账冲销|
|rebate_reversal	|折扣冲销|
|settlement_funds_transfer_reversal|	清算转账冲销|
|tax_reversal|	税费冲销|
|trade_funds_transfer_reversal|	让渡支付转账冲销|
|bank_slip_permanency_fee	|票据留存手续费|
|bank_slip_cancel_protest_fee	|票据留存手续费|
|bank_slip_protest_fee|	抗议申请手续费|
|bank_slip_notary_office_fee|	抗议公证费|
|bank_slip_registration_fee|	票据登记手续费|
|bank_slip_extension_fee|	票据延期手续费|
|bank_slip_rebate_fee	|票据折扣手续费|
|bank_slip_discount_fee|	票据优惠手续费|
|bank_slip_settlement_fee|	票据清算手续费|
|bank_slip_write_off_term_fee|	票据到期注销手续费|
|bank_slip_write_off_fee	|票据注销手续费|
|bank_slip_cancel_protest_write_off_fee|	暂停抗议并注销手续费|
|bank_slip_notary_office_settlement_fee|	公证清算手续费|
|rebate_tax_free	|代收代付转账|
|rebate_tax_free_reversal|	代收代付转账冲销|
|incoming_funds_transfer_reversal|	内部转账冲销|
|bank_slip_payment|	票据支付|
|bank_slip_payment_reversal|	票据支付冲销|
|warranty_analysis_fee	|担保分析手续费|
|bank_slip_settlement_deposit|	票据清算|
|bank_slip_payment_withdrawal	|票据支付|
|account_setup_fee	|开户手续费|
|account_setup_fee_reversal|	开户手续费冲销|
|bank_slip_payment_withdrawal_reversal|	票据支付冲销|
|incoming_anticipation_of_receivable|	-|
|incoming_credit_card_settlement|	信用卡清算|
|incoming_debit_card_settlement|	借记卡清算|
|assignment_automatic_transfer	|自动让渡扣款|
|assignment_automatic_transfer_reversal	|自动让渡扣款冲销|
|pix_fee|	PIX 手续费|
|incoming_pix_transfer|	PIX 入账|
|outgoing_pix_transfer|	PIX 出账|
|pix_fee_reversal|	PIX 手续费冲销|
|incoming_pix_transfer_reversal|	PIX 入账冲销|
|outgoing_pix_transfer_reversal|	PIX 出账冲销|
|pix_deposit|	PIX 存款|
|pix_withdrawal|	PIX 转账|
|pix_withdrawal_reversal	|PIX 转账冲销|
|pix_chargeback_withdrawal|	PIX 退款发送|
|outgoing_pix_chargeback	|PIX 退款出账|
|incoming_pix_chargeback|	PIX 退款接收|
|pix_chargeback_deposit|	PIX 退款入账|
|pix_chargeback_withdrawal_reversal	|PIX 退款发送冲销|
|outgoing_pix_chargeback_reversal	|PIX 退款出账冲销|
|incoming_pix_chargeback_reversal	|PIX 退款接收冲销|
|operation_pix_disbursement|	操作 PIX 放款|
|operation_pix_disbursement_reversal|	操作 PIX 放款冲销|
|receivables_inquiry_fee	|应收账款查询手续费|
|pix_deposit_reversal	|PIX 存款冲销|
|internal_pix_transfer	|PIX 转账|
|automatic_integrated_payment_reversal	|自动集成支付冲销|
|operation_dibursement_reversal|	操作放款冲销|
|available_yield|	流动投资存款|

**3.2. 凭证：** 转账/支付的凭证数据可通过 "***transaction_key***" 获取。

        **请求**

ENDPOINT /transaction_receipt/[TRANSACTION-KEY]
MÉTODO GET

Response Body - 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 - 内部转账或 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 - 票据支付

```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. 对账单：** 账户对账单可通过以下接口获取：

        **请求**

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 - TED 转账
 
:::info
TED 转账只能在工作日 **7:00** 至 **17:00** 之间进行。
:::

**4.1. 发起 TED 转账：**
要进行 TED 转账，需要进行以下调用：

        **请求**

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
}
```

        **响应**

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"
}
```

"event_datetime" 字段为 UTC 格式。

:::info
"***transaction_key***" 是转账的唯一标识键，后续可用于申请转账凭证。
:::
 

**4.2. TED 冲销：** 如目标机构退回 TED，将触发以下 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 - 注册与修改银行票据

**5.1. 查询托收钱包：** 要注册、修改和支付票据，首先需要拥有与账户绑定的托收钱包代码（Requester Profile Code）。每个账户在创建时都自动绑定一个托收钱包。

托收钱包代码遵循以下格式：
"银行编号" + "钱包代码" + "账户支行编号" + "不含校验位的 7 位账号"。

在 QI Tech 中，银行编号、钱包代码和支行编号默认分别为"329"、"09"和"0001"。
例如："**329-09-0001-2359934**"。

如需获取每个账户的托收钱包代码列表，请使用以下接口：

        **请求**

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 提示
票据的注册、修改和注销通过事件动态机制进行。每个事件发送至 QI Tech 并转发至票据中央数据库。
事件可被票据中央数据库接受或拒绝。
关于事件接受或拒绝的响应将通过 Webhook 发送给合作伙伴。
:::
 

**5.2. 注册票据：** 要注册票据，需要发送一个注册事件，如下面的接口所述：

        **请求**

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
银行编号（"***our_number***"）是票据在托收钱包中的 ID，必须为递增 ID。
银行编号（"***our_number***"）须由合作伙伴生成，并在注册票据时提供。
**重要提示：** 票据应通过以下组合键定位：银行编号（"***our_number***"）+ 托收钱包代码（"***requester_profile_code***"）。
:::

        **响应**

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.** 票据注册是否被接受或拒绝的响应将通过以下 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"
}
```

要将发送的 Webhook 与票据关联，须使用银行编号（"***our_number***"）和托收钱包代码（"***requester_profile_code***"）。

一旦票据注册被中央数据库接受，Webhook 中将返回票据的 UUID 密钥（"***bank_slip_key***"）。请保存此密钥，以便后续获取票据信息。

 

**5.4. 修改票据数据：** 要修改票据数据，需要发送一个事件。每种可能的修改都有对应的事件类型。票据数据修改的事件列表可在我们的文档中查看（/documentation/emissao_de_boleto/enviar_instrucao_de_boleto）。

 

**5.5. 申请票据副本：** 票据注册后，可申请生成包含支付信息的票据".pdf"文件。

        **请求**

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
将返回票据的所有数据，".pdf" 的下载链接将在 "***bank_slip_file.url***" 对象中提供。
:::
 

**5.5. 查询票据数据：** 票据数据可通过两种方式查询。

        **5.5.1. 通过可输入行查询：** 票据的可输入行是一串数字序列，其中包含票据信息。付款人在其网银中输入此数字序列。

:::info
可输入行示例：32990001031000000000902000000204685640000100000
:::

通过可输入行可以查询票据数据：

        **请求**

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. 通过票据密钥查询：** 一旦票据注册被中央数据库接受，Webhook 中将返回票据的 UUID 密钥（"***bank_slip_key***"）。通过此密钥可获取票据信息：

        **请求**

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. 票据收款到账通知：** 当票据在其他银行被支付时，将实时发送该票据已支付的通知。支付的资金清算将在下一个工作日进行。

        **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：**" 为票据支付方式，可能为：

"**credit_card**"：信用卡

"**cash**"：现金

"**account_debit**"：账户扣款

"**check**"：支票
:::

:::info
payment_origin：为票据支付地点来源，可能为：

"**internet**"：网上银行

"**phisical_cashier**"：银行柜台

"**taa**"：自助服务终端

"**eletronic_file**"：CNAB 清算文件

"**call_center**"：客服中心

"**dda**"：DDA（直接借记授权）

"**corban**"：彩票点 - 银行代理机构
:::

:::caution 注意
支付方式（"***payment_method***"）和支付来源（"***payment_origin***"）信息是在票据支付时提供的，其一致性和真实性由处理该笔支付的机构负责。
:::

--- 

### 6 - 生成 PIX QR Code

**6.1. 生成静态 PIX QR Code：** QR Code 由已在账户中注册的有效 PIX 密钥创建。生成 QR Code 后，将返回与 QR Code 关联的 PIX 复制粘贴 URI，以及 QR Code 图片的 base64（如已请求）。
QR Code 图片可由合作伙伴自行通过 PIX 复制粘贴 URI 生成。

生成静态 PIX QR Code 只需一个请求：

        **请求**

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
**qr_code_format** 字段可填写 "**image**"、"**payload**" 和 "**both**"。

"**image**"：返回包含 PIX QR Code 图片 base64 的字段。

"**payload**"：返回包含 PIX QR Code 复制粘贴 URI base64 的字段。

"**both**"：返回两个字段。
:::

        **响应**

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. 生成动态 PIX QR Code：** 动态 QR Code 分两种类型：带即时支付的动态 QR Code 和带到期日的动态 QR Code。

        **6.2.1. 生成带到期日的动态 PIX QR Code：** 这是一种功能非常类似于银行票据的 PIX QR Code 类型，可包含到期日、逾期罚款、逾期利息和提前付款折扣信息。生成此类 PIX QR Code 只需向 "/baas/qrcode/dynamic" 接口发送一个请求。

        **请求**

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：** 此字段填写预期操作类型，可为：registration、edit、write_off

**registration：** 创建新 QR Code

**edit：** 编辑已有 QR Code（如下方条目所述）。

**write_off：** 注销有效 QR Code。

**interest_amount：** 每日逾期利息金额（巴西雷亚尔 R$）。

**fine_amount：** 逾期罚款金额（巴西雷亚尔 R$）。

**discounts：** 提前付款折扣信息。如不适用，发送空列表（[]）。

**additional_data：** 可自定义的元标签，在支付时呈现给付款人。格式为："\ "："\ "。

**tag_name：** 最多 100 个字符，tag_value 最多 320 个字符。
:::

        **响应**

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"
}
```

"base_64" 字段是与此动态 PIX QR Code 关联的 PIX 复制粘贴 URI。

 

        **6.2.2. 生成带即时支付的动态 PIX QR Code：** 这是一种类似于静态 QR Code 的 PIX QR Code 类型，但更便于收款方进行对账，且可设置当日到期（例如，有效期仅 5 分钟）。
生成此类 PIX QR Code 只需向 "***/baas/qrcode/dynamic***" 接口发送一个请求。

        **请求**

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\>"
	}]
}
```

        **响应**

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. 编辑动态 PIX QR Code 数据：** 要编辑动态 PIX QR Code 的数据，需要提供 QR Code 的 "***qr_code_key***"，并将 "***occurrence_type***" 设为 "***edit***"。此时，需要重新发送所有数据。

        **请求**

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\>"
	}]
}
 ```

        **响应**

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. 删除动态 PIX QR Code：** 要注销动态 PIX QR Code，需要提供 QR Code 的 "***qr_code_key***"，并将 "***occurrence_type***" 设为 "***write_off***"。

        **请求**

ENDPOINT /baas/qrcode/dynamic
MÉTODO POST

Request Body

```json

{
    "qr_code_key": "3bd19ada-2341-41bf-9f1f-c5ce0b216723",
    "occurrence_type": "write_off"
}

  ```

        **响应**

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. 解码 PIX QR Code：** 要解码动态或静态 PIX QR Code，应使用以下接口：

        **请求**

ENDPOINT /baas/pix/qrcode
MÉTODO POST

Request Body

```json

{
    "qr_code_payload": "\<URI DO PIX COPIA E COLA\>"
}

```

:::info
此接口须提供 PIX 复制粘贴 URI（PIX 复制粘贴链接）。
:::

---

### 7 - 管理 PIX 密钥

:::info
"***pix_key***" 可以是 **CPF**、**CNPJ**、**邮箱**、**手机号** 或 **随机密钥**（UUID），格式如下：

**CPF：** 11 位整数。

**CNPJ：** 14 位整数。

**邮箱：** 包含至少一个"@"的文本。

**手机号：** 包含以下值的文本："+55" + "[手机区号]" + "\ "。例如："+5511987654321"。

**随机密钥：** UUID。
:::
 

        **7.1. 创建 CNPJ 和随机 PIX 密钥：** 要创建 CNPJ 或随机 PIX 密钥，只需调用 "***/baas/pix/keys***" 接口，将 "***pix_key_type***" 改为 "**cnpj**"、"**cpf**" 或 "**random_key**"。

        **请求**

ENDPOINT /baas/pix/keys
MÉTODO POST

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"
}
```

或

**payload.json**

```json

{
    "account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
    "pix_key_type": "cpf",
    "pix_key": "03882617038"
}

```

        **响应**

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 注意
在创建**随机** PIX 密钥的响应中，"***pix_key***" 字段将返回空值，因为这是一个异步流程，密钥由巴西中央银行生成。要获取已生成的随机密钥值，需要查询账户中已注册密钥列表（如"**查询账户已注册的 PIX 密钥**"条目所述），或等待包含密钥的 Webhook。
:::

:::info
由于验证 **CNPJ** 或 **CPF** PIX 密钥是否已激活是异步流程，需要查询账户中已注册密钥列表（如"**查询账户已注册的 PIX 密钥**"条目所述），或等待包含密钥的 Webhook。
:::

**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. 创建邮箱和手机号 PIX 密钥：** 要创建**邮箱**或**手机号** PIX 密钥，需要调用两个接口：

1 - 创建密钥：向 "***/baas/pix/keys***" 接口发送 POST 请求，将 "***pix_key_type***" 字段改为 "**email**" 或 "**phone_number**"。此时，将向 "pix_key" 字段中填写的邮箱或手机号发送一个验证码。

2 - 审批密钥：向 "**/baas/pix/keys/[pix_key_request_key]**" 接口发送 PATCH 请求，提供上一步收到的验证码。

        **请求**

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"
}
```
或

Request Body

```json
{
    "account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
    "pix_key_type": "phone_number",
    "pix_key": "+5511987654321"
}
```

        **响应**

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
**重要提示：** "***pix_key_request_key***" 字段返回的值须用于审批 PIX 密钥创建请求的 URL 中。
:::

 

**7.3. 审批已申请的邮箱或手机号 PIX 密钥：**

        **请求**

ENDPOINT /baas/pix/keys/ PIX_KEY_REQUEST_KEY /twofa_validation
MÉTODO PATCH

Request Body

```json
{
    "verification_code": "756816"
}
```

**7.4. 重新发送验证码：**

        **请求**

- MÉTODO PATCH
- ENDPOINT /baas/pix/keys/ PIX_KEY_REQUEST_KEY /resend_twofa

**payload.json**

```json
{}
```

**7.5. 查询账户已注册的 PIX 密钥：**

        **请求**

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. 删除 PIX 密钥：**

        **请求**

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 - PIX QR Code 支付

**8.1. 支付静态 PIX QR Code：**

要支付静态 PIX QR Code，需要进行三次调用：

解码 PIX QR Code：**/baas/pix/qrcode**

创建转账请求：**/baas/pix_transfer**

审批转账：**/baas/pix_transfer_approval**

用于解码静态 PIX QR Code 的信息是与 QR Code 关联的 PIX 复制粘贴 URI。

:::info
**PIX 复制粘贴 URI 示例：** 00020126580014br.gov.bcb.pix01360598e5d1-2cfc-4857-abf8-12d495aa0a6d52040000530398654040.225802BR5925VOVO LUCIA CONVENIENCIA L6009sao paulo610912345-78062070503***63043A5A
:::

        **请求**

ENDPOINT /baas/pix/qrcode
MÉTODO POST

Request Body

```json

{
    "qr_code_payload": "\<URI DO PIX COPIA E COLA\>"
}
```

        **响应**

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 注意
支付静态 PIX QR Code 的请求与 PIX 转账请求相同，但有以下变更：

**1 -** 新增 "***end_to_end_id***" 字段。须填写解码静态 QR Code 时返回的相同值；
**2 -** 在 "***transaction_amount***" 字段中填写解码静态 QR Code 时 "***qr_code_data.amount***" 字段返回的相同值；
**3 -** 将 "***pix_transfer_type***" 字段改为 "static"，以通过 "/baas/pix_transfer" 发起支付请求。
:::

:::info
此响应与 PIX 转账审批响应的唯一区别，是 "***pix_transfer_type***" 字段的值，此处返回的是 "***static***"。
:::
 
**8.2. 支付动态 PIX QR Code：**

要支付动态 PIX QR Code，需要进行三次调用：

解码 PIX QR Code：**/baas/pix/qrcode**

创建转账请求：**/baas/pix_transfer**

审批转账：**/baas/pix_transfer_approval**

用于解码动态 PIX QR Code 的信息是与 QR Code 关联的 PIX 复制粘贴 URI。

:::info
静态 PIX QR Code 与动态 PIX QR Code 在 "/baas/pix/qrcode" 中的唯一区别，是接口的响应内容。
:::

        **响应**

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 注意
支付动态 PIX QR Code 的请求与 PIX 转账请求相同，但有以下变更：

**1 -** 新增 "***end_to_end_id***" 字段。须填写解码动态 QR Code 时返回的相同值。
**2 -** 在 "***transaction_amount***" 字段中填写解码动态 QR Code 时 "qr_code_data.amount" 字段返回的相同值；
**3 -** 将 "***pix_transfer_type***" 字段改为 "***dynamic_term***"，以通过 "***/baas/pix_transfer***" 发起支付请求。
**4 -** 新增 "***receiver_conciliation_id***" 字段。须填写解码动态 QR Code 时返回的相同值。
:::

:::info
此响应与 PIX 转账审批响应的唯一区别，是 "***pix_transfer_type***" 字段的值，此处返回的是 "***dynamic_term***"。
::::

---

# 环境

URL: /zh-Hans/documentation/certifiqi/ambientes

我们提供生产环境和沙箱环境。

### API 与平台 URL
- 沙箱：
    - 平台：  https://sandbox.certifiqi.com.br/
    - api: [https://api.sandbox.certifiqi.com.br](https://api.sandbox.certifiqi.com.br/)
- 生产：
    - 平台： https://certifiqi.com.br/
    - api [https://api.certifiqi.com.br](https://api.sandbox.certifiqi.com.br/)

:::danger 重要提示！
不得在 QI Tech 的沙箱环境中使用真实的个人或法人数据。  
:::

---

# ZIP 文件

URL: /zh-Hans/documentation/certifiqi/arquivo_zip

每个签名事件完成后，至少会生成一个 ZIP 文件。在某些情况下，同一事件可能包含多个 ZIP 文件，因为每个文件有 **最多 500 个文档** 的限制。

要访问 ZIP 文件，请使用第 4.5 节中的 URL 查询功能。

### ZIP 包含的每份文档文件
- **CAdES**：   
  - 带有**签名信息页**的**原始 PDF**
  - 签名文件 **`.p7s`**。  
- **PAdES**：
  - **已签名的 PDF**。

---

# 自动签名

URL: /zh-Hans/documentation/certifiqi/assinatura_automatica

## 工作原理

自动签名是一项旨在加速和优化认证机构文件签名流程的功能。通过预先注册签名人，在创建事件时，认证机构会自动识别并签署文件，无需用户手动访问和执行签名流程。

## 注册

要在我们的认证机构启用自动签名，需要签署条款以生成专用于操作文件签名的私有证书。签署合同后，我们将为每位签名人生成私有证书，并在我们的认证机构中安装证书，以实现目标文件的自动签名。

要完成注册并提供条款，请发送电子邮件至 certifiqi@qitech.com.br，并提供以下信息：
- 将自动签署的文件模板
- 所有签名人的全名、电子邮件、CPF、手机号码和出生日期，用于生成私有证书。

我们的技术团队将据此完成私有证书的安装，并提供完成该流程的相关指导。

---

# 创建访问权限

URL: /zh-Hans/documentation/certifiqi/cadastro

1. 发送创建访问权限的请求至电子邮件 certifiqi@qitech.com.br，并提供以下数据：
   1. 公司 CNPJ
   2. 主管用户的全名
   3. 主管用户的 CPF
   4. 主管用户的电子邮件
2. 在 QI Tech 团队创建访问权限后，主管用户将收到一封包含 CertifiQI 平台访问链接的电子邮件，用于完成注册。
3. 首次登录平台时，主管用户可邀请其他用户以获得平台访问权限。

---

# 取消签名事件

URL: /zh-Hans/documentation/certifiqi/cancelar_batch_group_de_assinatura

此请求用于取消一个待处理的签名事件。

## Request

ENDPOINT /batch_group/batch_group_key/cancel_signature
MÉTODO PUT

### Path Params

| 字段 | 描述 |
|---|---|
| `batch_group_key` | 签名事件的唯一标识键。 |

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": []
}
```

---

# 查询签名事件

URL: /zh-Hans/documentation/certifiqi/consultar_evento

此请求返回签名事件的数据。

## Request

ENDPOINT /batch_group/batch_group_key
MÉTODO GET

### Path Params

| 字段 | 描述 |
|---|---|
| `batch_group_key` | 签名事件的唯一标识键。 |

## 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"
    ]
}

```

| 字段 | 类型 | 描述 |
|---|---|---|
| `main_related_party` | string | 负责签署事件的主要相关方名称 |
| `name` | string | 事件名称。 |
| `batch_group_key` | string | 签名事件的标识键。 |
| `signature_status` | string | 签名状态。 |
| `internal_status` | string | 事件的总体状态。 |
| `total_value` | string | 事件文件的总价值。 |
| `client_key` | string | 客户的标识键。 |
| `send_emails` | 布尔值 | 指示是否应为此事件发送签名电子邮件。 |
| `attached_document_number` | string | 转让方的 CNPJ。 |
| `batches` | 列表 | 不同类型文件及其各自相关方的列表。 |
| `webhook_url` | string | Webhook 的发送地址。 |
| `webhook_url_list` | 列表 | Webhook 的发送地址列表。 |
| `zip_file_keys_list` | 列表 | ZIP 文件的标识键。 |

### Batches 对象

| 字段 | 类型 | 描述 |
|---|---|---|
| `related_parties` | 列表 | 参与一组文件签名的相关方列表。 |
| `documents` | 列表 | 文件列表。 |
| `name` | string | Batch 名称。 |
| `signature_type` | enum | 签名类型。 |
| `document_type` | enum | 文件类型。 |

### Related Parties 对象

| 字段 | 类型 | 描述 |
|---|---|---|
| `role` | enum | 签名人所扮演的角色。 |
| `name` | string | 相关方名称。 |
| `signature_position` | 整数 | 签名位置。 |
| `signer_groups` | 列表 | 签名人组列表。 |

### Signer Groups 对象

| 字段 | 类型 | 描述 |
|---|---|---|
| `minimum_required_signers` | 整数 | 组内签名被视为完成所需的最少签名人数。 |
| `signers` | 列表 | 构成签名人组的签名人列表。 |

### Signer 对象

| 字段 | 类型 | 描述 |
|---|---|---|
| `name` | string | 签名人姓名。 |
| `document_number` | string | 签名人的 CPF。 |
| `email` | string | 签名人的电子邮件。 |
| `is_group_mandatory` | 布尔值 | 指示该签名人是否必须签名才能使其所属签名人组被视为完成。 |
| `signer_control_number` | string | 可用于控制或外部引用的自由字段。 |
| `signature_timestamp` | date | 签名日期。 |

### Documents 对象

| 字段 | 类型 | 描述 |
|---|---|---|
| `name` | string | 文件名称。 |
| `control_number` | string | 可用于控制或外部引用的自由字段。 |
| `file_size` | float | 文件大小。 |
| `url` | string | 文件 URL。 |
| `document_key` | string | 文件的标识键。 |
| `original_file_url` | string | 原始文件的 URL。 |
| `signed_file_url` | string | 带签名页的文件 URL。 |
| `file_url` | string | 签名文件的 URL。 |

---

# 查询文件 URL

URL: /zh-Hans/documentation/certifiqi/consultar_url

可通过以下请求查询已创建的签名事件的链接。

# 查询签名事件 URL
### Request

ENDPOINT /batch_group/batch_group_key/url
MÉTODO GET

### Path Params

| 字段              | 描述                                             |
|--------------------|-------------------------------------------------------|
| `batch_group_key`  | 签名事件的唯一标识键。 |

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

| 字段                 | 类型     | 描述                                                    |  
|-----------------------|----------|--------------------------------------------------------------| 
| `batch_group_key`     | string   | 签名事件的唯一标识键。        |
| `all_files_url`       | string   | 包含原始 PDF 和 p7s 的 ZIP 文件 URL。          |
| `batches`             | string   | 不同类型文件的列表。                     |
| `document_batch_key`  | string   | 文件批次的唯一标识键。          |
| `documents`           | Array    | 文件对象列表。                             |
| `document_key`        | string   | 文件的唯一标识键。                   | 
| `original_file_url`   | string   | 原始文件的 URL。                                   |
| `signed_file_url`     | string   | 带签名页的文件 URL。                   |
| `file_url`            | string   | p7s 文件的 URL。                                          |
| `expiration_datetime` | string   | URL 过期的日期和时间。 |

# 查询文件 URL
### Request

ENDPOINT /document/document_key/url
MÉTODO GET

### Path Params

| 字段          | 描述                                  |
||----------------|--------------------------------------------|
| `document_key` | 文件的唯一标识键  |

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

| 字段                 | 类型     | 描述                                                    |  
|-----------------------|----------|--------------------------------------------------------------| 
| `document_key`        | string   | 文件的唯一标识键。                   | 
| `original_file_url`   | string   | 原始文件的 URL。                                   |
| `signed_file_url`     | string   | 带签名页的文件 URL。                   |
| `file_url`            | string   | p7s 文件的 URL。                                          |
| `expiration_datetime` | string   | URL 过期的日期和时间。 |

# 查询 ZIP 文件 URL
### Request

ENDPOINT /certifier/zip_file/zip_file_key/url
MÉTODO GET

### Path Params

| 字段          | 描述                                  |
||----------------|--------------------------------------------|
| `zip_file_key` | ZIP 文件的标识键。     |

Response Body

```json
{
    "zip_file_key": "222",
    "signed_url": "https://google3.com",
    "expiration_datetime": "2024-05-01T01:00:00.000Z"
}
```

### Body Params

| 字段                 | 类型     | 描述                                                    |  
|-----------------------|----------|--------------------------------------------------------------| 
| `zip_file_key`        | string   | ZIP 文件的标识键。                       | 
| `expiration_datetime` | date     | URL 过期的日期和时间。 |
| `signed_url`          | string   | ZIP 文件的链接。   												  |

---

# 创建签名事件

URL: /zh-Hans/documentation/certifiqi/criar_batch_group

此端点用于发送签名事件，包括文件及各自的签名人，这些内容被分组在一个名为 **batch_group** 的对象中。

## 定义

### 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

| 字段 | 类型 | 描述 | 必填 |
|---|---| ---|  ---| 
| `main_related_party` |  string | 负责签署事件的主要相关方名称。 | 是 | 
| `name` | string | 签名事件名称。 | 是 |
| `total_value`| string | 事件文件的总价值。 | 是 |
| `send_emails` |  布尔值 | 指示是否应为此事件发送签名电子邮件。如果值为 **FALSE**，则在流程的任何阶段都不会发送电子邮件。 | 是 |
| `attached_document_number`  | string | 转让方的 CNPJ，当文件与特定转让方相关时使用。 | 否 |
| `batches` | 列表 | 不同类型文件及其各自相关方的列表。 | 是 |
| `webhook_url`  | string | 通知 Webhook 的发送 URL。 | 否 |
| `webhook_url_list`  | 列表 | 通知 Webhook 的发送 URL 列表。 | 否 |
| `is_asynchronous` | 布尔值   | 事件包含异步生成的文件。 | 否 |
| `send_to_fund_administrador` | 布尔值   | 签名完成后，事件应通过 SOAP 通知使用 Fromtis 软件的管理方。 | 否 |

:::info
- **webhook_url** 或 **webhook_url_list** 字段仅在需要接收 Webhook 时发送。此外，每次请求只能提供其中一个选项。
- 当事件包含异步创建的文件时，**is_asynchronous** 字段必须设置为 **True**。
:::

### Batches 对象

| 字段 | 类型 | 描述 | 必填 |
|---|---| ---|  ---|
| `related_parties` | 列表 | 参与一组文件签名的相关方列表。 | 是 |
| `documents` | 列表 | 文件列表。 | 是 |
| `name` |  string | Batch 名称。 |   是 |
| `signature_type` | enum | 签名类型。 | 是 |
| `document_type` | enum | 文件类型。 | 是 |

<details>
  <summary>签名类型枚举值 (signature_type)</summary>

**cades**: Cades  
**pades**: Pades  

</details>

<details>
  <summary>文件类型枚举值 (document_type)</summary>

**endorsement**: 背书  
**other**: 其他  
**contract**: 合同  
**term_of_assignment**: 转让条款  
**term_of_endorsement**: 背书条款  
**promissory_note**: 本票  
**rural_term_of_assignment**: 转让条款  
**term_of_fomentation**: 促进条款  
**cpr**: CPR  
**cprf**: CPRF  
**trade_bill**: 汇票  
**subscription_note**: 认购公告  
**adhesion_term**: 加入条款  
**limited_liability_term**: 有限责任条款  
**account_request_document**: 开户合同  
**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>

### Related Parties 对象

| 字段 | 类型 | 描述 | 必填 |
|---|---| ---|  ---|
| `role` | enum | 签名人所扮演的角色。 | 是 |
| `name` | string | 相关方名称。  | 是 |
| `signature_position` | 整数 | 签名位置，当各相关方之间有签名顺序时需要填写。顺序按升序排列。 | 否 |
| `signer_groups` | 列表 | 签名人组列表。 | 是 |

<details>
  <summary>相关方角色枚举值 (role)</summary>

**assignor**: 转让方  
**manager**: 经理  
**underwriter**: 承销商  
**issuer**: 发行人  
**intervening_discharger**: 介入清偿方  
**investor**: 投资者  
**debtor**: 债务人  
**secretary**: 秘书  
**intervening_consentor**: 介入同意方  
**guarantor**: 担保人  
**fund_representative**: 基金代表  
**company_representative**: 公司代表  
**solidary_debtor**: 连带债务人  
**attestant**: 见证人  
**bestowal**: 配偶赠与  
**owner**: 所有人  
**attorney**: 代理人  
**associate**: 合伙人  
**co_issuer**: 共同发行人  
**fiduciary_agent**: 受托代理人  
**guest**: 嘉宾  
**spouse**: 配偶  
**intervening_guarantor**: 介入担保人  
**fiduciary_debtor**: 信托债务人  
**bonafide_depositary**: 善意保管人  
**faithful_depositary**: 忠实保管人  
**president**: 总裁  
**endorser**: 背书人  
**fund_administrator**: 基金管理人  
**cosigner**: 保证人  
**consulting**: 顾问  
**fund_manager**: 基金经理  
**director**: 董事  

</details>

### Signer Groups 对象

| 字段 | 类型 | 描述 | 必填 |
|---|---| ---|  ---|
| `minimum_required_signers` | 整数 | 组内签名被视为完成所需的最少签名人数。 | 是 |
| `signers` | 列表 | 构成签名人组的签名人列表。  | 是 |

### Signer 对象

| 字段 | 类型 | 描述 | 必填 |
|---|---| ---|  ---|
| `name` | string | 签名人姓名。 | 是 |
| `document_number` | string | 签名人的 CPF。  | 是 |
| `email` | string | 签名人的电子邮件。  | 是 |
| `is_group_mandatory` | 布尔值 | 填写 **TRUE** 表示该签名人必须签名才能使其所属签名人组被视为完成。  | 是 |
| `signer_control_number` | string | 可用于控制或外部引用的自由字段。  | 是 |

### Documents 对象

:::info 重要
documents 字段应使用 /document 请求的响应来填充。
:::

| 字段 | 类型 | 描述 | 必填 |
|---|---| ---|  ---|
| `name` | string | 文件名称。 | 是 |
| `control_number` | string | 可用于控制或外部引用的自由字段。在涉及汇票的 Fromtis 集成中，此字段的值必须与异步生成文件端点中接收到的值保持一致。| 是 |
| `file_size` | float | 文件大小。 | 是 |
| `url` | string | 文件 URL。 | 是 |
| `document_key` | string | 文件的标识键。 | 是 |

## Response Body Params

| 字段 | 类型 | 描述 |
|---|---| ---|
| `batch_group_key` |  string | 签名事件的标识键。 |
| `signature_status` | string | 签名状态。 |
| `internal_status`| string | 事件的总体状态。 |
| `original_file_url`   | string   | 原始文件的 URL。 |
| `signed_file_url`     | string   | 带签名页的文件 URL。 |
| `file_url`            | string   | 签名文件的 URL。 |
| `signature_timestamp` | date   | 签名日期。 |
| `webhook_key` | string   | Webhook 的标识键。 |

---

# 创建签名事件以通知 Fromtis

URL: /zh-Hans/documentation/certifiqi/criar_batch_group_fromtis

CertifiQI 提供通过 SOAP 向使用 Fromtis 软件的管理方发送通知的选项。为确保通知正确发送，需要遵循一些特定步骤。如果未遵循其中任何步骤，签名事件将处于待通知状态，因为无法找到通过 Fromtis 传递的转让记录。

签名通知将在所有必要文件的签名完成后发送。

## 含汇票的事件

1. 发送文件
   1. 按照第 4.2.3 节，以异步方式发送汇票的 CNAB 文件。
   2. 以 PDF 格式发送转让条款
2. 创建事件
    1. 在请求体中将 is_asynchronous 字段设置为 True
    2. 在请求体中将 send_to_fund_administrator 字段设置为 True
    3. 在请求体中的 total_value 字段填写转让的净值
    4. 在请求体中发送与汇票对应的 document type 及其文件
    5. 在请求体中发送与转让条款对应的 document type 及其文件

## 含其他类型资产的事件

1. 发送文件
   1. 以 PDF 格式发送转让条款
2. 创建事件
    1. 在请求体中将 send_to_fund_administrator 字段设置为 True
    2. 在请求体中的 total_value 字段填写转让的净值
    3. 在请求体中发送与转让条款对应的 document type 及其文件

---

# 发送签名

URL: /zh-Hans/documentation/certifiqi/enviar_para_assinatura

## Request

此请求向签名人发送电子邮件。收件人应在创建签名事件时指定。

ENDPOINT /batch_group/batch_group_key/send_to_signature
MÉTODO PUT

### Path params

| 字段 | 类型 | 描述 |
|---|---|---|
| `batch_group_key`|  string | 签名事件的唯一标识键。 |

Response Body

```json
{}

```

---

# 结构

URL: /zh-Hans/documentation/certifiqi/estrutura

CertifiQI 具有签名事件（batch_group），它包含不同的文件及其签名人。以下将介绍一些对理解平台运作方式重要的术语。

### Related Party

代表与文件签名相关联的自然人或法人（公司）。可以包含一个或多个签名人组。

### Signer Group

构成相关方的签名人组。如果配置的任何一个组得到满足（最少签名数量或代表的价值），则该相关方将被视为已签名。为公司提供灵活的签名规则配置。

### Signer

属于某个组的签名人。可以定义其签名是否为必须，以满足组的条件。

### Document

需要签署的文件。

### Document Batch

特定类型的一组文件，需要由一个或多个相关方签署。一个签名事件可以包含多个 Batch，代表不同类别的文件。

### Batch Group

签名事件，将多个文件批次（Document Batch）分组以进行签名。

## 结构图

## 使用示例

### 图示

签名事件包含两个 Document Batch 类型的元素：一个用于汇票，另一个用于转让条款。

### Document Batch – 汇票

- 包含两份文件：汇票 1 和汇票 2。

- 与一个 Related Party 关联，代表转让方。

- 该 Related Party 有两个 Signer Group：

    - Signer Group 1：由两名签名人（Signer 1 和 Signer 2）组成。

    - Signer Group 2：由一名签名人（Signer 3）组成。

Related Party 被视为已签名，只需满足其中一个 Signer Group 即可。这可以通过两种方式实现：

    - 方式 1：Signer 1 和 Signer 2 进行签名，满足 Signer Group 1。

    - 方式 2：只有 Signer 3 签名，满足 Signer Group 2。

一旦 Related Party 通过任何一种方式得到满足，汇票的 Document Batch 将被视为已签名。

### Document Batch – 转让条款

- 包含一份文件：转让条款。
- 有两个 Related Party：
    - 转让方
    - 基金管理人
- 每个 Related Party 有一个签名人组
- 咨询方的 Related Party 有一个包含两名签名人的 Signer Group，因此需要两名签名人都签名才能完成咨询方的相关方。
- 基金管理方的 Related Party 有一个包含一名签名人的 Signer Group，因此需要该签名人签名才能完成基金管理方的相关方。

一旦各 Related Party 得到满足，转让条款的 Document Batch 将被视为已签名。

---

# 认证方式

URL: /zh-Hans/documentation/certifiqi/forma_de_autenticacao

要在我们的平台上发起请求，需要在请求的 header 中包含 API 密钥，使用 x-api-token 字段，如下例所示：

Header

```json

{"x-api-token": "\<EXAMPLE-OF-API-KEY\>"}

```

此密钥对每位客户唯一，可通过电子邮件申请，发送请求至 certifiqi@qitech.com.br。

---

# 开始

URL: /zh-Hans/documentation/certifiqi/inicio

CertifiQI 平台旨在通过符合 ICP-Brasil 标准的证书进行签名。此外，平台可在数秒内完成大量文件的签名。
更多信息请访问：

https://qitech.com.br

# 签名方式

### Cades
- 一种数字签名方式，签名文件单独存放。
- 文件格式为 p7s。

### Pades
- 一种数字签名方式，签名包含在 PDF 文件内部。
- 文件格式为 PDF。

---

# 用户权限

URL: /zh-Hans/documentation/certifiqi/permissoes

平台上的用户分为三类访问权限：主管、签名人和观察者。

### 主管：
- 可以编辑和创建事件。
- 可查看所有文件。
- 可修改用户权限。

### 签名人：
- 可在平台上签署文件。
- 可查看其作为签名人的文件。

### 观察者
- 可在平台上查看文件。

---

# CNAB 文件上传

URL: /zh-Hans/documentation/certifiqi/upload_documentos_cnab_assincrono

#  使用说明
此方法用于将 CNAB 444 的每一行以异步方式转换为 PDF 文件。

事件可以在文件生成完成之前创建。

:::warning 重要提示！
在创建事件时，`is_asynchronous` 字段必须设置为 TRUE。文件生成完成后，文件才可供签署。
:::

## Request

ENDPOINT /certifier/document/trade_bill/asynchronous
MÉTODO POST

### Request Body Params

以下数据需作为 form-data 发送到请求体中：

| 字段 | 类型 | 描述                              | 必填 |
|---|---|----------------------------------------|---|
| `file` | file | 需要发送的文件的二进制内容。 | 是 |
| `assignor_address`| string | 转让方地址                    | 是 |
| `assignor_address_number`| string | 转让方地址门牌号          | 是 |
| `assignor_city`| string | 转让方城市                      | 是 |
| `assignor_state`| string | 转让方州                      | 是 |
| `assignor_CEP`| string | 转让方邮政编码                         | 是 |
| `assignor_neighborhood `|string | 转让方社区                           | 是 |

### 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"
}
```

## 请求示例
```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"'
```

---

# PDF 文件上传

URL: /zh-Hans/documentation/certifiqi/upload_documentos_pdf

#  使用说明
此方法用于以 PDF 格式发送文件。

## Request

ENDPOINT /document
MÉTODO POST

### Request Body Params

以下数据需作为 form-data 发送到请求体中：

| 字段 | 类型 | 描述 | 必填| 
|---|---|---|---|
| `file` | file | 需要发送的文件的二进制内容。 | 是 |
| `control_number` | string | 可用于控制或外部引用的自由字段。  | 否 |
| `endorsement_page` | 布尔值 | 如果设置为 true，将在文件末尾添加背书页  | 否 |
| `endorser_name` | string | 背书页上的背书受让人姓名  | 否 |
| `endorser_document_number` | string | 背书页上的背书受让人文件号码  | 否 |
| `receiver_name`| string | 背书页上的收款人姓名 | 否 |
| `receiver_document_number`| string | 背书页上的收款人文件号码  | 否 |
| `document_identifier` |string | 背书页上的文件标识符 | 否 |     
| `document_type` |string | 背书页上的文件类型 | 否 |     

## 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."
}
```

## 请求示例
```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"'
```

## 添加背书页

要在发送的 PDF 末尾添加黑色背书页，需要填写以下字段：

- endorsement_page 设置为 True
- endorser_name
- endorser_document_number
- receiver_name
- receiver_document_number
- document_identifier
- document_type

填写这些字段后，背书的附加文本将按以下格式呈现：

机构 endorser_name ，CNPJ 号为 endorser_document_number ，
将本 document_type 编号 document_identifier 背书给
receiver_name ，CNPJ 号为 receiver_document_number ，依据适用法律，
特别是 2004 年 8 月 2 日第 10.931 号法律第 29 条第 1 款的规定，以将完整所有权转让给
上述指定机构。本背书以电子方式进行，双方自此同意并承认其电子签名的有效性，依据
2001 年 8 月 24 日第 2.200 号临时措施第 10 条第 2 款，或取代该措施的规范。

---

# Webhook

URL: /zh-Hans/documentation/certifiqi/webhook

所有签名事件的通知将发送到事件创建时注册的地址。在所有 Webhook 调用中，payload 将包含 batch_group、batches、related_parties、signer_groups 和 signer 的数据。

通知将在以下阶段之一完成时发送：相关方签名、开始创建 ZIP 文件或签名事件完成。

## 相关方已签名通知

在此情况下，相关方、签名人组和签名人的 **signature_status** 字段值将为 **signed**。而 **internal_status** 字段值将为 **pending**。

### 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": []
}

```

## 事件完成

事件完成时，首先会发送一个 Webhook 通知所有相关方已完成签名。此时，**internal_status** 字段值将为 **waiting_zip_files_creation**。已签名文件的链接将立即可用。

在前述 Webhook 之后，将发送一个新的 Webhook 通知事件完全完成。此时，**internal_status** 字段值将为 **finished**，事件将附带 ZIP 文件，可通过 **zip_file_keys_list** 中的键进行查询。ZIP 文件包含所有文件和签名文件。

要了解如何查询 ZIP 文件，请参阅第 4.5 节"查询 URL"。

### 等待 ZIP 生成的 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": 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": []
}

```

### 事件完成的 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": "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"
  ]
}

```

---

# 创建债权转让

URL: /zh-Hans/documentation/cessoes/criacao_de_cessao_0eaeffec-ee95-4cb1-a266-bcb52f23237d

债权转让 API 允许客户直接创建和查询债权转让。可以使用债权转让配置密钥（UUID4）创建债权转让，并通过特定端点查询债权转让的一般信息。

:::caution 注意
此服务仅对已注册债权转让配置的合作伙伴开放，请咨询我们的支持团队了解详情。
:::

## 创建债权转让

要创建债权转让，需要使用客户的配置密钥（**assignment_configuration_key**）、参与本次债权转让的信贷操作密钥集合（**credit_operation_keys**）以及**daily_assignment_interest_rate**（即每日债权转让利率，该利率与相关合同采用相同的天数基准）向端点发起 POST 请求。

### Request

ENDPOINT /v2/assignment/assignment_configuration/[assignment_configuration_key]/assignment
MÉTODO POST

### Params

| 字段                          | 描述                                                 |
| ------------------------------ | --------------------------------------------------------- |
| `assignment_configuration_key` | 客户债权转让配置的标识密钥 |

Request Body

```json
{
  "credit_operation_keys": ["key1", "key2", "key3"],
  "daily_assignment_interest_rate": 0.0003
}
```

:::caution 注意
如果在 Request 中未为特定合同提供 **daily_assignment_interest_rate**，则将使用客户债权转让配置中注册的转让利率。
:::

### 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"
  }
]
```

## 查询债权转让
要查询特定债权转让，客户可以使用债权转让标识密钥（**assignment_key**）向端点发起 GET 请求。

### Request

ENDPOINT /v2/assignment/[assignment_key] MÉTODO GET

### Params

| 字段            | 描述                      |
| ---------------- | ------------------------------ |
| `assignment_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"
}
```

## 查询债权转让项目
要查询债权转让中的合同，请使用相同的 **assignment_key** 向端点发起 GET 请求。

### Request

ENDPOINT /v2/assignment/[assignment_key]/assignment_items MÉTODO GET

### Params

| 字段            | 描述                      |
| ---------------- | ------------------------------ |
| `assignment_key` | 债权转让标识密钥 |

### Response

返回结果为债权转让中每份合同的信息列表（状态码 200），已分页：

### 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
    }
}
```

---

# 托管账户开户（个人）

URL: /zh-Hans/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

| 字段 | 类型 | 描述 | 字符 |
|---|---| ---|---|
| `account_owner` * | object  | 账户所有人对象 | **[account_owner 对象](#objeto-account_owner)** |
| `destination_list` | object  | 目标账户列表，即允许转入资金的账户列表。 | **[destination_list 对象](#objeto-destination_list)** |
| `signed_contract` *| object | 包含合同签名信息的对象。 | **[signed_contract 对象](#objeto-signed_contract)** |

### account_owner 对象

| 字段 | 类型 | 描述 | 字符 |
|---| ---| ---| ---|
| `address` | string | 客户地址。 | **[address 对象](#objeto-address)** |
| `birth_date` * | string | 人员出生日期（格式"YYYY-MM-DD"） | |
| `document_identification` * | string | 带照片的身份证件 PDF 的 DOCUMENT_KEY（RG 或 CNH）（预先上传） | |
| `email` * | string | 客户电子邮件。 | |
| `individual_document_number` | string | 人员 CPF（仅数字）。限制为 11 个字符。 | |
| `is_pep` * | string | 声明该人员是否为 PEP（http://www.portaldatransparencia.gov.br/download-de-dados/pep）。 | |
| `mother_name` * | string | 个人（PF）情况下的客户母亲姓名。 | 100 |
| `name` * | string | 法人（PJ）情况下的公司名称，或个人（PF）情况下的人员姓名。 | 100 |
| `nationality` * | string | 客户国籍。 | 50 |
| `person_type` * | string | 标识发送对象为个人或法人的标识符。 | |
| `phone` | string | 包含电话数据的对象 | **[phone 对象](#objeto-phone)** |
| `proof_of_residence` | string | 已发送地址的居住证明 PDF 的 DOCUMENT_KEY（预先上传）。 | |

### address 对象

该对象存在于个人（PF）和法人（PJ）对象中，是一个简单的地址表示对象。

| 字段 | 描述 | 示例 | 最大字符数 |
|---|---|---|---|
| `street` * | string | 地址街道 | 100 |
| `state` * | string | 地址所在州（两个大写字母） | 2 |
| `city` * | string | 地址城市 | 100 |
| `neighborhood` * | string | 地址社区 | 100 |
| `number` * | string | 门牌号 | 10 |
| `postal_code` * | string | 地址邮政编码（http://www.buscacep.correios.com.br/sistemas/buscacep/）（仅数字） | 8 |
| `complement` * | string | 地址补充信息（自由文本） | 100 |

### signed_contract 对象
| 字段 | 类型 | 描述 | 字符 |
|---|---|---|---|
| **document_key** * | uuidv4 | **开户条款**或**托管账户合同**文件的唯一标识密钥。（DOCUMENT_KEY 由[文档上传](./upload_de_documentos)端点的响应返回） | 36 |
| **signatures** * | list | 已发送文件的签名数据。列表中的每一项对应文件的一个签名人。 | [signatures 对象](#objeto-signatures) |

### signatures 对象
| 字段 | 类型 | 描述 | 字符 |
|---|---|---|---|
| **authenticity** * | object | 证明签名人完成电子签名的一组数据。 | [authenticity 对象](#objeto-authenticity) |
| **signer** * | object | 包含文件某一签名人数据的对象。 | [signer 对象](#objeto-signer) |
| **authentication_type** * | enumerator | 签名类型。始终为"**opt-in**" | "**opt-in**" |

### authenticity 对象
| 字段 | 类型 | 描述 | 字符 |
|---|---|---|---|
| **timestamp** * | string | 文件签名时的日期和时间。 | 27 |
| **facial_recognition_key** | uuidv4 | 账户持有人自拍照的唯一标识密钥。（DOCUMENT_KEY 由[文档上传](./upload_de_documentos)端点的响应返回） | 36 |
| **lang** | string | 签名时获取的签名人地理位置经度坐标。 | - |
| **lat** | string | 签名时获取的签名人地理位置纬度坐标。 | - |
| **ip_address** | string | 签名人设备的 IP 地址。 | - |
| **session_id** | string | 签名时签名人的会话 ID。 | - |

### signer 对象
| 字段 | 类型 | 描述 | 字符 |
|---|---|---|---|
| **name** * | string | 签名人姓名。 | - |
| **email** * | string | 签名人电子邮件。 | - |
| **phone** * | object | 包含签名人电话数据的对象 | **[phone 对象](#objeto-phone)** |
| **document_number** * | string | 签名人 CPF。 | 11 |

### phone 对象

| 字段 | 描述 | 示例 | 最大字符数 |
| --- | --- | --- | --- |
| `country_code` * | string | 电话国际区号（https://ddi.guiamais.com.br/） | 3 |
| `area_code` * | string | 电话区域号（https://ddd.guiamais.com.br/） | 2 |
| `number` * | string | 电话号码（仅数字） | 10 |

### destination_list 对象

| 字段 | 描述 | 示例 | 最大字符数 |
| --- | --- | --- | --- |
| `account_branch` * | string | 银行支行号 | 3 |
| `account_digit` * | string | 账户校验位（如有） | 2 |
| `account_number` * | string | 账户号码 | 10 |
| `document_number` * | string | 人员 CPF 或 CNPJ（仅数字） | 10 |
| `financial_institutions_code_number` * | string | 金融机构 COMPE 代码（https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf）（3 位数字）。 | 3 |
| `name` * | string | 个人姓名或法人公司名称。 | 10 |
| `ted_account_type` * | enum | 目标账户类型。 | **[枚举值](#enumeradores-ted_account_type)** |

### ted_account_type 枚举值

| 枚举值 | 翻译 |
|---|---|
| checking_account | 支票账户 |
| deposit_account | 存款账户 |
| guaranteed_account | 担保账户 |
| investment_account | 投资账户 |
| payment_account | 支付账户 |
| saving_account | 储蓄账户 |

## 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\"}"
}

```

---

# 托管账户开户（法人）

URL: /zh-Hans/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

| 字段 | 类型 | 描述 | 字符 |
|---|---| ---| ---|
| `account_manager` * | object | 负责账户操作的人员对象。 | **[address 对象](#objeto-address)** |
| `account_owner` * | object | 账户所有人对象。 | **[account_owner 对象](#objeto-account_owner)** |
| `allowed_user` * | object | 拥有账户查询访问权限的人员对象。 | **[allowed_user 对象](#objeto-allowed_user)** |
| `destination_list` * | object | 目标账户列表，即允许转入资金的账户列表。 | **[destination_list 对象](#objeto-destination_list)** |
| `signed_contract` * | object | 包含合同签名信息的对象。 | **[signed_contract 对象](#objeto-signed_contract)** |

### account_manager 对象

| 字段 | 类型 | 描述 | 字符 |
|---|---| ---| ---|
| `address` * | object | 客户地址。 | **[address 对象](#objeto-address)** |
| `cnae_code` * | string | 国家经济活动分类代码 | 14 |
| `company_document_number` | object | CNPJ | 14 |
| `company_statute` * | string | 公司章程 PDF 的 DOCUMENT_KEY（预先上传）。 | uuid 密钥 |
| `directors_election_minute` * | string | 公司法定代表人会议纪要 PDF 的 DOCUMENT_KEY（预先上传）。 | uuid 密钥 |
| `email` * | string | 公司机构电子邮件。 | |
| `foundation_date` * | date | 公司成立日期（格式"YYYY-MM-DD"）。 | |
| `name` * | string | 公司名称。 | |
| `person_type` * | string | 标识发送对象为法人的标识符。法人（PJ）对象必须始终包含值"legal"。 | |
| `phone` | string | 包含电话数据的对象 | **[phone 对象](#objeto-phone)** |
| `trading_name` * | string | 公司商号名称 | |

### company_representatives 对象

| 字段 | 类型 | 描述 | 字符 |
|---|---| ---| ---|
| `person_type` * | string | 标识发送对象为个人的标识符。个人（PF）对象必须始终包含值"natural"。 | 11 |
| `name` * | string | 法人情况下的公司名称，或个人情况下的人员姓名。限制为 100 个字符。 | 11 |
| `mother_name` * | string | 人员母亲姓名。 | 11 |
| `birth_date` * | string | 人员出生日期（格式"YYYY-MM-DD"） | 11 |
| `nationality` * | string | 客户国籍。限制为 50 个字符。 | 11 |
| `is_pep` * | string | 声明该人员是否为 PEP（http://www.portaldatransparencia.gov.br/download-de-dados/pep）。 | 11 |
| `final_beneficiary` | boolean | 声明该人是否为公司的最终受益人。 | - |
| `individual_document_number` | string | 人员 CPF（仅数字）。 | 11 |
| `document_identification` * | string | 带照片的身份证件 PDF 的 DOCUMENT_KEY（RG 或 CNH）（预先上传） | UUID |
| `proof_of_residence` * | UUID | 居住证明 PDF 的 DOCUMENT_KEY（预先上传） | UUID |
| `email` * | string | 人员电子邮件。 | 11 |
| `address` | string | 人员地址对象。 | 11 |

### address 对象

该对象存在于个人（PF）和法人（PJ）对象中，是一个简单的地址表示对象。

| 字段 | 描述 | 示例 | 最大字符数 |
|---|---|---|---|
| `street` * | string | 地址街道 | 10 |
| `state` * | string | 地址所在州（两个大写字母） | 2 |
| `city` * | string | 地址城市 | 10 |
| `neighborhood` * | string | 地址社区 | 10 |
| `number` * | string | 门牌号 | 10 |
| `postal_code` * | string | 地址邮政编码（http://www.buscacep.correios.com.br/sistemas/buscacep/）（仅数字） | 8 |
| `complement` * | string | 地址补充信息（自由文本） | 100 |

### account_owner 对象

| 字段 | 类型 | 描述 | 字符 |
|---|---|---|---|
| `address` * | object | 账户持有人地址对象 | **[address 对象](#objeto-address)** |
| `cnae_code` * | string | 国家经济活动分类代码 | 9 |
| `company_document_number` * | string | CNPJ | 14 |
| `company_statute` * | string | 公司章程 PDF 的 DOCUMENT_KEY（预先上传）。 | 36 |
| `company_type` | enum | 公司类型 | **[company_type 枚举值](#enumeradores-company_type)** |
| `company_representatives` * | list | 公司法定代表人列表 | **[company_representatives 对象](#objeto-company_representatives)** |
| `email` * | string | 公司机构电子邮件。 | 254 |
| `foundation_date` * | string | 公司成立日期（格式"YYYY-MM-DD"）。 | 10 |
| `name` * | string | 公司名称。 | 100 |
| `person_type` * | enum | 标识发送对象为法人的标识符。法人（PJ）对象必须始终包含值"legal"。 | **[person_type 枚举值](#enumeradores-person_type)** |
| `phone` * | object | 账户持有人电话。 | **[phone 对象](#objeto-phone)** |
| `trading_name` * | string | 商号名称。 | 200 |

### allowed_user 对象

| 字段 | 描述 | 示例 | 最大字符数 |
|---|---|---|---|
| `email` * | string | 账户用户的电子邮件。 | 10 |
| `individual_document_number` * | string | 账户用户的 CPF（仅数字）。 | 10 |
| `name` * | string | 账户用户的姓名。 | 10 |
| `person_type` * | string | 标识发送对象为个人的标识符。必须始终包含值"natural"。 | 10 |
| `phone` | string | 用户电话对象。 | **[phone 对象](#objeto-phone)** |

### destination_list 对象

| 字段 | 描述 | 示例 | 最大字符数 |
| --- | --- | --- | --- |
| `account_branch` * | string | 银行支行号。 | 3 |
| `account_digit` * | string | 账户校验位（如有）。 | 3 |
| `account_number` * | string | 账户号码。 | 3 |
| `document_number` * | string | CPF 或 CNPJ（仅数字）。 | 3 |
| `financial_institutions_code_number` * | string | 金融机构 COMPE 代码（https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf） | 3 |
| `name` * | string | 个人姓名或法人公司名称。 | |
| `ted_account_type` * | enum | 目标账户类型。 | **[枚举值](#enumeradores-ted_account_type)** |

### signed_contract 对象
| 字段 | 类型 | 描述 | 字符 |
|---|---|---|---|
| **document_key** * | uuidv4 | **开户条款**或**托管账户合同**文件的唯一标识密钥。（DOCUMENT_KEY 由[文档上传](./upload_de_documentos)端点的响应返回） | 36 |
| **signatures** * | list | 已发送文件的签名数据。列表中的每一项对应文件的一个签名人。 | [signatures 对象](#objeto-signatures) |

### signatures 对象
| 字段 | 类型 | 描述 | 字符 |
|---|---|---|---|
| **authenticity** * | object | 证明签名人完成电子签名的一组数据。 | [authenticity 对象](#objeto-authenticity) |
| **signer** * | object | 包含文件某一签名人数据的对象。 | [signer 对象](#objeto-signer) |
| **authentication_type** * | enumerator | 签名类型。始终为"**opt-in**" | "**opt-in**" |

### authenticity 对象
| 字段 | 类型 | 描述 | 字符 |
|---|---|---|---|
| **timestamp** * | string | 文件签名时的日期和时间。 | 27 |
| **facial_recognition_key** | uuidv4 | 账户持有人自拍照的唯一标识密钥。（DOCUMENT_KEY 由[文档上传](./upload_de_documentos)端点的响应返回） | 36 |
| **lang** | string | 签名时获取的签名人地理位置经度坐标。 | - |
| **lat** | string | 签名时获取的签名人地理位置纬度坐标。 | - |
| **ip_address** | string | 签名人设备的 IP 地址。 | - |
| **session_id** | string | 签名时签名人的会话 ID。 | - |

### signer 对象
| 字段 | 类型 | 描述 | 字符 |
|---|---|---|---|
| **name** * | string | 签名人姓名。 | - |
| **email** * | string | 签名人电子邮件。 | - |
| **phone** * | object | 包含签名人电话数据的对象 | **[phone 对象](#objeto-phone)** |
| **document_number** * | string | 签名人 CPF。 | 11 |

### phone 对象

| 字段 | 描述 | 示例 | 最大字符数 |
| --- | --- | --- | --- |
| `country_code` * | string | 电话国际区号（https://ddi.guiamais.com.br/） | 3 |
| `area_code` * | string | 电话区域号（https://ddd.guiamais.com.br/） | 2 |
| `number` * | string | 电话号码（仅数字） | 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\"}"
}

```

---

# 简介

URL: /zh-Hans/documentation/contas/abertura_de_conta_escrow/introducao

自由活动账户是指客户可以全额或部分提取并使用余额的任何银行账户。

开户
与债务发行一样，开户申请只需一次调用即可完成（注意文件必须提前上传）。

收到开户申请后，QI Tech 负责执行合规审查并开立账户。实际操作流程如下：

1 - 提交开户申请（通过请求发送）

2 - 合规验证（通过 webhook 通知结果）

3 - 账户开立（通过 webhook 通知结果）

---

# 个人账户开户

URL: /zh-Hans/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 复制粘贴示例载荷
开始测试之前，`document_identification` 字段中的 document_key 必须替换为上传账户持有人文件时返回的密钥。
:::

:::info CPF/CNPJ 模拟
为模拟审批、拒绝和人工审查情况，可使用账户 owner 的 CPF/CNPJ 首位数字：

0 至 7 -> 人工审查

8 -> 自动拒绝

9 -> 自动审批
:::

### 请求体参数

| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---|---|
| `account_owner` | object  | 账户持有人对象 | **[account_owner 对象](#objeto-account_owner)** |
| `signed_contract` *| object | 包含合同签署信息的对象 | **[signed_contract 对象](#objeto-signed_contract)** |

### account_owner 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `address` | string | 客户地址 | **[address 对象](#objeto-address)** |
| `birth_date` * | string | 出生日期（"YYYY-MM-DD" 格式） | |
| `document_identification` * | string | 带照片身份证件（身份证或驾照）PDF 的 DOCUMENT_KEY（提前上传） | |
| `document_identification_back` * | string | 带照片身份证件背面（身份证或驾照）PDF 的 DOCUMENT_KEY（提前上传） | |
| `document_identification_type` * | string | 提前上传的证件类型（身份证或驾照） | |
| `email` * | string | 客户电子邮箱 | |
| `individual_document_number` | string | CPF（仅数字，限 11 位） | |
| `is_pep` * | string | 声明该人是否为政治公众人物（PEP） | |
| `mother_name` * | string | 个人账户情况下的客户母亲姓名 | 100 |
| `name` * | string | 法人账户情况下的公司名称，或个人账户情况下的个人姓名 | 100 |
| `nationality` * | string | 客户国籍 | 50 |
| `person_type` * | string | 标识所发送对象为个人还是法人 | |
| `phone` | string | 电话数据对象 | **[phone 对象](#objeto-phone)** |
| `proof_of_residence` | string | 所提供地址的居住证明 PDF 的 DOCUMENT_KEY（提前上传） | |

### address 对象

此对象在个人和法人对象中均存在，是用于表示地址的简单对象。

| 字段 | 描述 | 示例 | 最大字符数 |
|---|---|---|---|
| `street` *| string | 街道名称 | 100 |
| `state` *| string | 州（两位大写字母） | 2 |
| `city` *| string | 城市 | 100 |
| `neighborhood` *| string | 社区/街区 | 100 |
| `number` *| string | 门牌号 | 10 |
| `postal_code` *| string | CEP（仅数字） | 8 |
| `complement` *| string | 地址补充说明（自由文本） | 100 |

### signed_contract 对象
| 字段 | 类型 | 描述 | 字符数 |
|-------|--------|------------------|---------------|
| **document_key** * | uuidv4 | **开户条款**或**托管账户合同**文件的唯一识别密钥（DOCUMENT_KEY 在[上传文件](./upload_de_documentos)端点的响应中返回） | 36 |
| **signatures** * | list | 已发送文件的签名数据，列表中的每个项目对应一位签署人 | [signatures 对象](#objeto-signatures) |

### signatures 对象
| 字段 | 类型 | 描述 | 字符数 |
|-------|------------|-------------------|-------------------|
| **authenticity** * | object | 证明签署人完成电子签名的一组数据 | [authenticity 对象](#objeto-authenticity) |
| **signer** * | object | 包含文件某位签署人数据的对象 | [signer 对象](#objeto-signer) |
| **authentication_type** * | enumerator | 签署类型，始终为 "**opt-in**" | "**opt-in**" |

### authenticity 对象
| 字段 | 类型 | 描述 | 字符数 |
|-------|--------|-------------------------|------------|
| **timestamp** * | string | 文件签署时的日期和时间 | 27 |
| **facial_recognition_key** | uuidv4 | 账户持有人自拍照片的唯一识别密钥（DOCUMENT_KEY 在[上传文件](./upload_de_documentos)端点的响应中返回） | 36 |
| **lang** | string | 签署时捕获的签署人地理定位经度坐标 | - |
| **lat** | string | 签署时捕获的签署人地理定位纬度坐标 | - |
| **ip_address** | string | 签署人设备的 IP 地址 | - |
| **session_id** | string | 签署时签署人的会话 ID | - |

### signer 对象
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| **name** * | string | 签署人姓名 | - |
| **email** * | string | 签署人电子邮箱 | - |
| **phone** * | object | 签署人电话数据对象 | **[phone 对象](#objeto-phone)** |
| **document_number** * | string | 签署人 CPF | 11 |

### phone 对象

| 字段 | 描述 | 示例 | 最大字符数 |
| --- | --- | --- | --- |
|`country_code` *| string | 电话 DDI 代码 | 3 |
| `area_code` *| string | 电话 DDD 代码 | 2 |
| `number` *| string | 电话号码（仅数字） | 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\"}"
}

```

---

# 法人账户开户

URL: /zh-Hans/documentation/contas/abertura_de_conta/abertura_de_conta_pj

## 双因素认证（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"
            }
        ]
    }
}
```

## 法人账户开户

### 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 复制粘贴示例载荷
开始测试之前，`company_statute` 和 `document_identification` 字段中的 document_keys（UUID）必须替换为上传账户持有人文件时返回的密钥。
:::

:::info CPF/CNPJ 模拟
为模拟审批、拒绝和人工审查情况，可使用账户 owner 的 CPF/CNPJ 首位数字：

0 至 7 -> 人工审查

8 -> 自动拒绝

9 -> 自动审批
:::

### 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\"}"
}
```

### 请求体参数

| 字段 | 类型 | 描述 | 字符数 |
|-----------------------|--------|------------------------------------------------------------------------------|-------------------------------------------------------|
| **account_owner** * | object | 账户持有人对象 | **[account_owner 对象](#objeto-account_owner)** |
| **allowed_user** * | object | 关联到账户的用户 | **[allowed_user 对象](#objeto-allowed_user)** |
| **account_manager** | object | 将通过 API 进行账户操作的集成合作伙伴数据 | **[account_manager 对象](#objeto-account_manager)** |
| `signed_contract` * | object | 包含合同签署信息的对象 | **[signed_contract 对象](#objeto-signed_contract)** |

### account_owner 对象

| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|
| **address** * | object | 账户持有人地址对象 | **[address 对象](#objeto-address)** |
| **cnae_code** * | string | 国家经济活动分类代码（CNAE） | 9 |
| **company_document_number** * | string | CNPJ | 14 |
| **company_statute** * | string | 公司章程 PDF 的 DOCUMENT_KEY（提前上传） | 36 |
| **company_type** | enum | 公司类型 | **[company_type 枚举值](#enumeradores-company_type)** |
| **company_representatives** * | list | 公司法定代表人列表 | **[company_representatives 对象](#objeto-company_representatives)** |
| **email** * | string | 公司机构电子邮箱 | 254 |
| **foundation_date** * | string | 公司成立日期（"YYYY-MM-DD" 格式） | 10 |
| **name** * | string | 公司法定名称 | 100 |
| **person_type** * | enum | 标识所发送对象为法人，法人对象必须始终为 "legal" | **[person_type 枚举值](#enumeradores-person_type)** |
| **phone** * | object | 账户持有人电话 | **[phone 对象](#objeto-phone)** |
| **trading_name** * | string | 公司商号 | 200 |

### allowed_user 对象

| 字段 | 类型 | 描述 | 字符数 |
|----------------------------------|--------|--------------------------------------------------------------------------------------------------|------------------------------------------------------------|
| **email** * | string | 账户用户电子邮箱 | 254 |
| **individual_document_number** * | string | 账户用户 CPF（仅数字） | 11 |
| **name** * | string | 账户用户姓名 | 100 |
| **person_type** * | enum | 标识所发送对象为个人，必须始终为 "natural" | **[person_type 枚举值](#enumeradores-person_type)** |
| **phone** | object | 用户电话 | **[phone 对象](#objeto-phone)** |

### account_manager 对象

| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------|
| **address** * | object | 集成合作伙伴地址对象 | **[address 对象](#objeto-address)** |
| **cnae_code** * | string | 国家经济活动分类代码（CNAE） | 9 |
| **company_document_number** * | string | CNPJ | 14 |
| **company_statute** * | string | 公司章程 PDF 的 DOCUMENT_KEY（提前上传） | 36 |
| **company_type** | enum | 公司类型 | **[company_type 枚举值](#enumeradores-company_type)** |
| **company_representatives** * | list | 公司法定代表人列表 | **[company_representatives 对象](#objeto-company_representatives)** |
| **email** * | string | 公司机构电子邮箱 | 254 |
| **foundation_date** * | string | 公司成立日期（"YYYY-MM-DD" 格式） | 10 |
| **name** * | string | 公司法定名称 | 100 |
| **person_type** * | enum | 标识所发送对象为法人，法人对象必须始终为 "legal" | **[person_type 枚举值](#enumeradores-person_type)** |
| **phone** * | object | 集成合作伙伴电话 | **[phone 对象](#objeto-phone)** |
| **trading_name** * | string | 公司商号 | 200 |

### company_representatives 对象

| 字段 | 类型 | 描述 | 字符数 |
|------------------------------------|---------|--------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
| **name** * | string | 公司代表姓名 | 100 |
| **address** * | object | 公司代表地址对象 | **[address 对象](#objeto-address)** |
| **email** * | string | 公司代表电子邮箱 | 254 |
| **birth_date** * | string | 公司代表出生日期（"YYYY-MM-DD" 格式） | 10 |
| **individual_document_number** * | string | 公司代表 CPF（仅数字） | 11 |
| **document_identification** | string | 带照片身份证件（身份证或驾照）PDF 的 DOCUMENT_KEY（提前上传） | 36 |
| **document_identification_number** | string | 带照片身份证件号码（身份证或驾照） | 16 |
| **is_pep** * | boolean | 声明该人是否为政治公众人物（PEP） | - |
| **final_beneficiary** | boolean | 声明该人是否为公司的最终受益人。 | - |
| **marital_status** | enum | 公司代表婚姻状况 | **[marital_status 枚举值](#enumeradores-marital_status)** |
| **mother_name** * | string | 公司代表母亲姓名 | 100 |
| **nationality** | string | 公司代表国籍 | 50 |
| **person_type** * | enum | 标识所发送对象为个人 | **[person_type 枚举值](#enumeradores-person_type)** |
| **phone** * | object | 公司代表电话数据对象 | **[phone 对象](#objeto-phone)** |

### address 对象

此对象在个人和法人对象中均存在，是用于表示地址的简单对象。

| 字段 | 描述 | 示例 | 字符数 |
|--------------------|-----------|-------------------------------------------------------------------------------------------|------------|
| **street** * | string | 街道名称 | 500 |
| **state** * | enum | 州（两位大写字母） | 2 |
| **city** * | string | 城市 | 255 |
| **neighborhood** * | string | 社区/街区 | 500 |
| **number** * | string | 门牌号 | 10 |
| **postal_code** * | string | CEP（仅数字） | 8 |
| **complement** | string | 地址补充说明（自由文本） | 500 |

### signed_contract 对象
| 字段 | 类型 | 描述 | 字符数 |
|-------|--------|------------------|---------------|
| **document_key** * | uuidv4 | **开户条款**或**托管账户合同**文件的唯一识别密钥（DOCUMENT_KEY 在[上传文件](./upload_de_documentos)端点的响应中返回） | 36 |
| **signatures** * | list | 已发送文件的签名数据，列表中的每个项目对应一位签署人 | [signatures 对象](#objeto-signatures) |

### signatures 对象
| 字段 | 类型 | 描述 | 字符数 |
|-------|------------|-------------------|-------------------|
| **authenticity** * | object | 证明签署人完成电子签名的一组数据 | [authenticity 对象](#objeto-authenticity) |
| **signer** * | object | 包含文件某位签署人数据的对象 | [signer 对象](#objeto-signer) |
| **authentication_type** * | enumerator | 签署类型，始终为 "**opt-in**" | "**opt-in**" |

### authenticity 对象
| 字段 | 类型 | 描述 | 字符数 |
|-------|--------|-------------------------|------------|
| **timestamp** * | string | 文件签署时的日期和时间 | 27 |
| **facial_recognition_key** | uuidv4 | 账户持有人自拍照片的唯一识别密钥（DOCUMENT_KEY 在[上传文件](./upload_de_documentos)端点的响应中返回） | 36 |
| **lang** | string | 签署时捕获的签署人地理定位经度坐标 | - |
| **lat** | string | 签署时捕获的签署人地理定位纬度坐标 | - |
| **ip_address** | string | 签署人设备的 IP 地址 | - |
| **session_id** | string | 签署时签署人的会话 ID | - |

### signer 对象
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| **name** * | string | 签署人姓名 | - |
| **email** * | string | 签署人电子邮箱 | - |
| **phone** * | object | 签署人电话数据对象 | **[phone 对象](#objeto-phone)** |
| **document_number** * | string | 签署人 CPF | 11 |

### phone 对象

| 字段 | 描述 | 示例 | 最大字符数 |
| --- | --- | --- | --- |
|`country_code` *| string | 电话 DDI 代码 | 3 |
| `area_code` *| string | 电话 DDD 代码 | 2 |
| `number` *| string | 电话号码（仅数字） | 10 |

### person_type 枚举值
| 枚举值 | 描述 |
|-------------|-------------------|
| **natural** | 个人 |
| **legal** | 法人 |

### document_identification_type 枚举值
| 枚举值 | 描述 |
|---------|----------------------------------------|
| **rg** | RG - 身份证 |
| **cnh** | CNH - 驾照 |

### company_type 枚举值
| 枚举值 | 描述 |
|----------------------------|--------------------------------------------------------------------------|
| **ltda** | 有限责任公司 |
| **sa** | 股份公司 |
| **micro_enterprise** | 微型企业 |
| **freelancer** | 自由职业者 |
| **sa_opened** | 上市股份公司 |
| **sa_closed** | 非上市股份公司 |
| **se_ltda** | 有限责任企业公司 |
| **se_cn** | 普通合伙企业公司 |
| **se_cs** | 有限合伙企业公司 |
| **se_ca** | 股份有限合伙企业公司 |
| **scp** | 参与账户合伙公司 |
| **ei** | 个体工商户 |
| **ese** | 外国公司在巴西的分支机构 |
| **eeab** | 阿根廷-巴西双边公司在巴西的分支机构 |
| **ssp** | 简单合伙公司 |
| **ss_ltda** | 有限简单合伙公司 |
| **ss_cn** | 普通合伙简单公司 |
| **ss_cs** | 有限合伙简单公司 |
| **eireli_ne** | 个人有限责任公司（商业性质） |
| **eireli_ns** | 个人有限责任公司（简单性质） |
| **eireli** | 个人责任公司 |
| **mei** | 个体微型企业主 |
| **me** | 微型企业 |
| **cop** | 合作社 |
| **private_association** | 私人协会 |

### marital_status 枚举值
| 枚举值 | 描述 |
|--------------|---------------|
| **single** | 未婚 |
| **married** | 已婚 |
| **widower** | 丧偶 |
| **divorced** | 离婚 |
| **separated** | 分居 |

---

# 自由活动账户草稿 - 法人

URL: /zh-Hans/documentation/contas/abertura_de_conta/draft_checking_legal_person

Draft Checking Legal Person 流程允许分两步创建账户开户申请：

1. **POST**：以**最大灵活性**创建草稿（draft）——从最少数据到完整数据均可接受
2. **PATCH**：将草稿提交处理，**验证所有必填字段的完整性**

**重要**：此流程正在为与 **Monte Bravo** 的集成做准备。POST 和 PATCH 之间的字段划分将在与 Monte Bravo 确认每个流程节点可用数据后进行调整。

## 创建法人账户草稿

### Request

ENDPOINT /v2/account_request/draft_checking_legal_person
MÉTODO POST

### 描述

此端点为法人（Legal Person）创建账户开户**草稿**。POST 接受**从最少数据到完整数据**，提供最大灵活性。

### 灵活性策略

- **最少数据**：CNPJ + 名称 + 人员类型
- **部分数据**：根据可用情况添加字段
- **完整数据**：一次性发送全部（较少见）

### 示例 1：最小载荷（仅必填项）

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"
  }
}
```

**行为**：如果再次使用相同的 `request_control_key`，将返回 409（Conflict）错误，而不是创建新草稿。

### 示例 2：完整载荷（一次性发送全部数据）

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 注意
`account_request_key` 字段必须保存，并将用于通过 PATCH 提交草稿。
:::

### 请求体参数

| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|--------|------------------------------------------------------------------------------|---------------------------------------------------------------------|
| `request_control_key` | string | 用于保证幂等性的 UUID（36 字符） | 36 |
| `reserved_account_key` | string | 预留账户的 UUID（36 字符） | 36 |
| `account_owner` * | object | 账户持有人信息（法人） | **[account_owner 对象（POST）](#objeto-account_owner-post)** |

### account_owner 对象（POST）

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `company_document_number` * | string | 公司 CNPJ（14 位，仅数字） | 14 |
| `name` * | string | 公司法定名称 | 100 |
| `person_type` * | enum | 人员类型（始终为 "legal"） | **[person_type 枚举值](#enumeradores-person_type)** |
| `email` | string | 公司电子邮箱（有效邮箱格式） | 254 |
| `phone` | object | 公司电话 | **[phone 对象](#objeto-phone)** |
| `trading_name` | string | 公司商号 | 200 |
| `company_type` | enum | 公司组织形式 | **[company_type 枚举值](#enumeradores-company_type)** |
| `foundation_date` | string | 成立日期（格式：YYYY-MM-DD） | 10 |
| `cnae_code` | string | CNAE 活动代码 | 9 |
| `company_statute` | string | 公司章程 UUID（UUID 格式） | 36 |
| `monthly_revenue` | number | 月营业额 | - |
| `address` | object | 公司完整地址 | **[address 对象](#objeto-address)** |
| `company_representatives` | array | 法定代表人列表（发送时至少 1 人） | **[company_representatives 对象](#objeto-company_representatives)** |

:::info POST 中的必填字段
POST 中只有 3 个字段为必填：
- `company_document_number`
- `name`
- `person_type`

其余所有字段均为可选，可根据可用情况发送。
:::

:::warning 代表人验证
如果在 POST 中发送 `company_representatives`，必须**至少包含 1 个项目**（`minItems: 1`）。每位代表必须填写所有必填字段（见 PATCH 部分）。每位代表内的 `documents` 字段在 **POST 中为可选**。
:::

---

## 提交法人账户草稿

### Request

ENDPOINT /v2/account_request/{account_request_key}/draft_checking_legal_person
MÉTODO PATCH

### 描述

此端点**提交草稿**进行处理。PATCH **验证完整性**——所有必填字段必须存在于 PATCH 载荷中。

**⚠️ 重要**：PATCH 会用所发送的载荷**完全覆盖** `account_owner` 的数据。这意味着：
- 您必须在 PATCH 载荷中发送**所有**必填字段，即使这些字段已在 POST 中发送过
- 仅在 POST 中发送的数据如果不在 PATCH 中重新发送将**丢失**
- 此行为是**完全替换**，不是合并/部分更新
- 每个 `company_representative` 中的 `documents` 字段为**必填**，必须至少包含一种有效证件类型（身份证、驾照、RNE、CRNM、护照或数字 CIN）

提交成功后，状态从 `draft` 变更为 `pending_bacen_validation`，并启动 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 Bacen Protege+ 流程
提交成功后，状态变更为 `pending_bacen_validation`。系统在进行 KYC 分析前会先向 Bacen Protege+ 进行预验证。Bacen 批准后，状态将自动更新为 `pending_kyc_analysis`。
:::

### 请求体参数

| 字段 | 类型 | 描述 | 字符数 |
|-----------------------|--------|------------------------------------------------------------------------------|---------------------------------------------------------------------|
| `additional_documents` | array | 附加文件 UUID 列表（UUID 数组） | - |
| `account_owner` * | object | 账户持有人完整信息（法人） | **[account_owner 对象（PATCH）](#objeto-account_owner-patch)** |

### account_owner 对象（PATCH）

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `company_document_number` * | string | CNPJ（14 位，仅数字，格式：`^[0-9]{14}$`） | 14 |
| `name` * | string | 公司法定名称 | 100 |
| `person_type` * | enum | 始终为 `"legal"` | **[person_type 枚举值](#enumeradores-person_type)** |
| `email` * | string | 公司电子邮箱（有效邮箱格式） | 254 |
| `phone` * | object | 公司电话 | **[phone 对象](#objeto-phone)** |
| `trading_name` * | string | 公司商号 | 200 |
| `company_type` * | enum | 公司组织形式 | **[company_type 枚举值](#enumeradores-company_type)** |
| `foundation_date` * | string | 成立日期（格式：YYYY-MM-DD） | 10 |
| `cnae_code` * | string | CNAE 活动代码 | 9 |
| `company_statute` * | string | 公司章程 UUID（UUID 格式） | 36 |
| `monthly_revenue` * | number | 月营业额 | - |
| `address` * | object | 公司完整地址 | **[address 对象](#objeto-address)** |
| `company_representatives` * | array | 法定代表人列表（至少 1 人为必填） | **[company_representatives 对象](#objeto-company_representatives)** |

:::warning PATCH 中的必填字段
所有标注 `*` 的字段在 PATCH 中均为**必填**。JSON schema 在处理提交之前会验证所有字段的完整性。
:::

### phone 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `country_code` * | string | 国家代码（1-3 位数字，格式：`^[0-9]{1,3}$`） | 1-3 |
| `area_code` * | string | DDD（1-3 位数字，格式：`^[0-9]{1,3}$`） | 1-3 |
| `number` * | string | 电话号码（1-10 位数字，格式：`^[0-9]{1,10}$`） | 1-10 |
| `type` | enum | 电话类型（可选：`"residential"`、`"commercial"`、`"mobile"`、`"fax"`） | - |

### address 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `street` * | string | 街道/地址 | 1-500 |
| `neighborhood` * | string | 社区/街区 | 0-100 |
| `number` * | string | 门牌号 | 1-10 |
| `postal_code` * | string | CEP（8 位数字，格式：`^\d{8}$`） | 8 |
| `city` * | string | 城市 | 1-100 |
| `state` * | enum | 州（两位大写字母） | **[state 枚举值](#enumeradores-state)** |
| `complement` | string | 补充说明（可选，最多 500 字符） | 0-500 |

### company_representatives 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `name` * | string | 全名 | 100 |
| `address` * | object | 完整地址（与公司 address 结构相同） | **[address 对象](#objeto-address)** |
| `email` * | string | 电子邮箱（有效邮箱格式） | 5-200 |
| `birth_date` * | string | 出生日期（格式：YYYY-MM-DD） | 10 |
| `individual_document_number` * | string | CPF（11 位，仅数字，格式：`^[0-9]{11}$`） | 11 |
| `is_pep` * | boolean | 是否为政治公众人物（PEP） | - |
| `final_beneficiary` | boolean | 声明该人是否为公司的最终受益人。 | - |
| `mother_name` * | string | 母亲姓名 | 100 |
| `nationality` * | string | 国籍 | 50 |
| `person_type` * | enum | 始终为 `"natural"` | **[person_type 枚举值](#enumeradores-person_type)** |
| `phone` * | object | 电话（与公司 phone 结构相同） | **[phone 对象](#objeto-phone)** |
| `documents` * | object | 反欺诈证件（PATCH 中为必填） | **[documents 对象](#objeto-documents)** |
| `face` | string | 人脸照片 UUID（36 字符） | 36 |
| `document_identification` | string | 身份证件 UUID（UUID 格式） | 36 |
| `document_identification_number` | string | 身份证件号码 | 16 |
| `marital_status` | enum | 婚姻状况 | **[marital_status 枚举值](#enumeradores-marital_status)** |
| `gender` | enum | 性别 | **[gender 枚举值](#enumeradores-gender)** |
| `representative_relationship` | enum | 与公司的关系 | **[representative_relationship 枚举值](#enumeradores-representative_relationship)** |

### documents 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `rg` | object | 身份证正反面 OCR 上传密钥 | **[rg 对象](#objeto-rg)** |
| `cnh` | object | 驾照 OCR 上传密钥 | **[cnh 对象](#objeto-cnh)** |
| `cnh_digital` | object | 数字驾照 OCR 上传密钥 | **[cnh_digital 对象](#objeto-cnh_digital)** |
| `national_registry_of_foreigners` | object | 外国人登记（RNE）正反面 OCR 上传密钥 | **[national_registry_of_foreigners 对象](#objeto-national_registry_of_foreigners)** |
| `national_migration_registry` | object | 外国人移民登记（CRNM）正反面 OCR 上传密钥 | **[national_migration_registry 对象](#objeto-national_migration_registry)** |
| `passport` | object | 护照 OCR 上传密钥 | **[passport 对象](#objeto-passport)** |
| `cin_digital` | object | 数字国家身份证（CIN）OCR 上传密钥 | **[cin_digital 对象](#objeto-cin_digital)** |

### rg 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `ocr_front_key` * | uuidv4 | 身份证正面图片 OCR 上传密钥 | 36 |
| `ocr_back_key` * | uuidv4 | 身份证背面图片 OCR 上传密钥 | 36 |

或

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `ocr_key` * | uuidv4 | 身份证图片 OCR 上传密钥 | 36 |

### cnh 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `ocr_front_key` * | uuidv4 | 驾照正面图片 OCR 上传密钥 | 36 |
| `ocr_back_key` * | uuidv4 | 驾照背面图片 OCR 上传密钥 | 36 |

或

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `ocr_key` * | uuidv4 | 驾照图片 OCR 上传密钥 | 36 |

### cnh_digital 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `ocr_key` * | uuidv4 | 数字驾照图片 OCR 上传密钥 | 36 |

### national_registry_of_foreigners 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `ocr_front_key` * | uuidv4 | RNE 正面图片 OCR 上传密钥 | 36 |
| `ocr_back_key` * | uuidv4 | RNE 背面图片 OCR 上传密钥 | 36 |

或

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `ocr_key` * | uuidv4 | RNE 图片 OCR 上传密钥 | 36 |

### national_migration_registry 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `ocr_front_key` * | uuidv4 | CRNM 正面图片 OCR 上传密钥 | 36 |
| `ocr_back_key` * | uuidv4 | CRNM 背面图片 OCR 上传密钥 | 36 |

或

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `ocr_key` * | uuidv4 | CRNM 图片 OCR 上传密钥 | 36 |

### passport 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `ocr_key` * | uuidv4 | 护照图片 OCR 上传密钥 | 36 |

### cin_digital 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `ocr_key` * | uuidv4 | 数字国家身份证图片 OCR 上传密钥 | 36 |

:::info 说明
证件图片上传的 OCR 密钥（`ocr_key` 或 `ocr_front_key` 和 `ocr_back_key`）由反欺诈图片上传的响应提供。`face_recognition_key` 在人脸识别响应中返回。
:::

### 响应体参数

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `account_request_key` * | string | 创建申请的识别密钥 | - |
| `account_request_status` * | string | 申请状态（提交后变更为 `pending_bacen_validation`） | - |
| `account_info` * | object | 包含账户信息的对象 | **[account_info 对象](#objeto-account_info)** |

### account_info 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `account_branch` * | string | 分行号 | 4 |
| `account_digit` * | string | 账户验证位 | 1 |
| `account_number` * | string | 账户号码 | - |

### 错误响应

STATUS 4xx

Response Body: Error

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title` | 描述（英文）<br/>`description` | 描述（葡文）<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 |

---

## POST 和 PATCH 的区别

| 方面 | POST（创建草稿） | PATCH（提交草稿） |
|---------|-------------------|------------------------|
| **目的** | 以灵活方式创建草稿 | 验证完整性并提交至 Bacen |
| **必填字段** | 仅 CNPJ + 名称 + 类型 | 所有字段 + 1 位带 **documents** 的完整代表人 |
| **documents** | 每位代表人可选 | 每位代表人**必填**（含 OCR 证件对象） |
| **代表人** | 可选 | 必填（至少 1 人） |
| **验证** | 最低限度（仅 3 个字段） | 完整（所有必填字段） |
| **初始状态** | N/A | `draft`（必须处于此状态） |
| **最终状态** | `draft` | `pending_bacen_validation` |
| **Bacen 验证** | 否 | 是 |
| **KYC 分析** | 否 | 是（Bacen 之后） |
| **幂等性** | 是（通过 `request_control_key`） | 否 |

---

## 使用场景

### 场景 1：客户最初只有基本数据
```
POST → {CNPJ, 名称, 类型}  [状态：draft]
...客户收集更多数据...
PATCH → {所有字段 + 每位代表人的 documents} [状态：pending_bacen_validation]
```

### 场景 2：客户一次性拥有所有数据
```
POST → {所有字段}  [状态：draft]
PATCH → {所有字段} [状态：pending_bacen_validation]
```

### 场景 3：客户逐步发送部分数据
```
POST → {CNPJ, 名称, 类型, 邮箱}  [状态：draft]
...客户收集更多数据...
PATCH → {所有字段，包括带 documents 的代表人} [状态：pending_bacen_validation]
```
---

## 枚举值

### person_type 枚举值

| 枚举值 | 描述 |
|------|-----------|
| `natural` | 个人 |
| `legal` | 法人 |

### company_type 枚举值

| 枚举值 | 描述 |
|------|-----------|
| `ltda` | 有限责任公司 |
| `sa` | 股份公司 |
| `micro_enterprise` | 微型企业 |
| `freelancer` | 自由职业者 |
| `sa_opened` | 上市股份公司 |
| `sa_closed` | 非上市股份公司 |
| `se_ltda` | 有限责任企业公司 |
| `se_cn` | 普通合伙企业公司 |
| `se_cs` | 有限合伙企业公司 |
| `se_ca` | 股份有限合伙企业公司 |
| `scp` | 参与账户合伙公司 |
| `ei` | 个体工商户 |
| `ese` | 外国公司在巴西的分支机构 |
| `eeab` | 阿根廷-巴西双边公司在巴西的分支机构 |
| `ssp` | 简单合伙公司 |
| `ss_ltda` | 有限简单合伙公司 |
| `ss_cn` | 普通合伙简单公司 |
| `ss_cs` | 有限合伙简单公司 |
| `eireli_ne` | 个人有限责任公司（商业性质） |
| `eireli_ns` | 个人有限责任公司（简单性质） |
| `eireli` | 个人责任公司 |
| `mei` | 个体微型企业主 |
| `me` | 微型企业 |
| `cop` | 合作社 |
| `private_association` | 私人协会 |

### state 枚举值

| 枚举值 | 描述 |
|------|-----------|
| `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` | 境外 |

### marital_status 枚举值

| 枚举值 | 描述 |
|------|-----------|
| `single` | 未婚 |
| `married` | 已婚 |
| `widower` | 丧偶 |
| `divorced` | 离婚 |
| `separated` | 分居 |

### gender 枚举值

| 枚举值 | 描述 |
|------|-----------|
| `male` | 男性 |
| `female` | 女性 |

### representative_relationship 枚举值

| 枚举值 | 描述 |
|------|-----------|
| `ceo` | CEO / 总裁 |
| `analyst` | 分析师 |
| `partner` | 合伙人 |
| `director` | 董事 |
| `attorney` | 代理人 |
| `signer` | 签署人 |

---

## 完整流程

1. **POST** `/v2/account_request/draft_checking_legal_person`
   - 使用可用数据创建草稿
   - 状态：`draft`
   - 返回：`account_request_key`

2. **（可选）** 收集附加数据

3. **PATCH** `/v2/account_request/{account_request_key}/draft_checking_legal_person`
   - 验证所有字段的完整性
   - 提交至 Bacen Protege+
   - 状态：`pending_bacen_validation`

4. **Bacen Protege+ 验证**（异步）
   - 状态：`pending_kyc_analysis`（批准后）

5. **KYC 分析法人**
   - 状态：`approved`（一切正常时）

6. **账户创建完成并可使用**

---

---

# fluxo_de_abertura_de_conta

URL: /zh-Hans/documentation/contas/abertura_de_conta/fluxo_de_abertura_de_conta

### 自由活动账户

自由活动账户是指客户可以全额或部分提取并使用余额的任何银行账户。

开户
与债务发行一样，开户申请只需一次调用即可完成（注意文件必须提前上传）。

收到开户申请后，QI Tech 负责执行合规审查并开立账户。实际操作流程如下：

1 - 提交开户申请（通过请求发送）
2 - 合规验证（通过 webhook 通知结果）
3 - 账户开立（通过 webhook 通知结果）

---

# 简介

URL: /zh-Hans/documentation/contas/abertura_de_conta/introducao

我们在集成中能够提供的功能之一是通过 API 管理账户，以及向 QI Tech 账户或其他金融机构的账户进行转账。不仅如此，我们还提供通过 API 进行账户**开户**的功能，无论是为您自己还是为第三方。

与其他 API 一样，服务的启用需要与我们的团队沟通，所有调用均经过身份验证。

在以下子章节中，我们将了解如何在 QI Tech 内部开立和管理支付账户。

---

# 开户 Webhooks

URL: /zh-Hans/documentation/contas/abertura_de_conta/webhooks_contas

开户申请的响应可能根据合作伙伴的集成配置返回 "pending_kyc_analysis" 状态。

在这种情况下，账户开户批准或拒绝的结果将通过 webhook 以异步方式返回。

账户号码将在申请开户时保留，但此时**账户尚未开立**。只有在 QI Tech 完成 KYC 分析后，账户才会正式开立。

## 法人账户

#  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"
}
```

## 个人账户

# 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"
}
```

---

# 开具银行关系证明函

URL: /zh-Hans/documentation/contas/carta_bancaria

银行关系证明函（"Declaração de Relacionamento"）是由 QI SCD 数字签名的 PDF 文件，用于证明客户与本机构之间有效的银行关系，并包含账户信息。开具完成后，已签名的文件会通过电子邮件发送至请求中指定的收件人。

## Request

ENDPOINT /account/ ACCOUNT_KEY /ownership_letter
MÉTODO POST

### Path parameters

| 字段 | 类型 | 描述 |
|---|------|--------------------------------|
| `ACCOUNT_KEY` | UUID | 需要开具证明函的账户密钥 |

### Body parameters

| 字段 | 类型 | 描述 | 最大字符数 |
|---|---|---|---|
| `emails` * | string 数组 | 接收已签名 PDF 的电子邮件列表。至少 1 个地址。 | - |

Request Body

```json
{
  "emails": ["contact@customer.com", "finance@customer.com"]
}
```

## 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": ["contact@customer.com", "finance@customer.com"]
  },
  "created_at": "2026-05-28T19:50:47",
  "updated_at": "2026-05-28T19:50:47"
}
```

### Response Body parameters

| 字段 | 类型 | 描述 | 最大字符数 |
|---|---|---|---|
| `document_key` | UUID | 文档在 QI 内部的唯一标识符。 | 36 |
| `account_key` | UUID | 来源账户的密钥。 | 36 |
| `document_type` | string | 文档类型。此接口固定为 `ownership_letter`。 | - |
| `document_status` | string | 文档当前状态。参见 [document_status 枚举值](#document_status-枚举值)。 | - |
| `external_identifier_key` | string | 签名批次的外部标识符。 | 300 |
| `file_url` | string | 文档当前 URL。处于 `pending` 时指向签名跟踪页面；变为 `sent` 后指向已签名 PDF。 | - |
| `payload` | object | 请求体的回显。 | - |
| `created_at` | datetime Zulu | 文档创建时间。 | 20 |
| `updated_at` | datetime Zulu | 文档最后更新时间。 | 20 |

### document_status 枚举值

| 枚举值 | 描述 |
|---|---|
| **pending** | 文档已创建，正在等待签名完成。 |
| **sent** | 文档已签名，电子邮件已发送给收件人。 |

## 获取已签名文档链接

签名完成后（状态为 `sent`），使用此接口获取由 CertifIQI 按需生成的、用于下载已签名 PDF 的**带时效链接**。当文档仍处于 `pending` 时——即尚未收到签名 webhook——该 URL 尚不存在，接口将返回错误。

### Request

ENDPOINT /account/ ACCOUNT_KEY /document/ DOCUMENT_KEY /url
方法 GET

### Path parameters

| 字段 | 类型 | 描述 |
|---|------|-----------|
| `ACCOUNT_KEY` | UUID | 文档所属账户的密钥。 |
| `DOCUMENT_KEY` | UUID | 开具信函时返回的文档标识符（`document_key`）。 |

## 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

| 字段 | 类型 | 描述 | 最大字符数 |
|---|---|---|---|
| `document_key` | UUID | QI 内部文档标识符。 | 36 |
| `document_type` | string | 文档类型。银行信函为 `ownership_letter`。 | - |
| `document_status` | string | 文档当前状态。仅当为 `sent` 时才返回 URL。 | - |
| `url` | string | 用于下载已签名 PDF 的**带时效链接**。按需生成，短时间后过期。 | - |

### 可能的错误

| 状态 | 描述 |
|---|---|
| 404 | 未找到对应标识符的账户或文档。 |
| 409 | 文档仍在签名中（`pending`）；已签名 URL 尚不可用。 |

---

# 开具审计询证函

URL: /zh-Hans/documentation/contas/carta_circularizacao

审计询证函（"circularização"）是由 QI SCD 数字签名的审计文件，用于在指定基准日确认客户名下账户的余额。文件列出与路径中账户属于同一证件号码且在同一 requester 下的**全部**账户。开具完成后，已签名的 PDF 会通过电子邮件发送至请求中指定的收件人（通常是审计师）。

## Request

ENDPOINT /account/ ACCOUNT_KEY /circularization_letter
MÉTODO POST

### Path parameters

| 字段 | 类型 | 描述 |
|---|------|-----------|
| `ACCOUNT_KEY` | UUID | 客户名下任一账户的密钥。仅用于识别证件号码和 requester；询证函会列出该证件号码在同一 requester 下的**全部**账户。 |

### Body parameters

| 字段 | 类型 | 描述 | 最大字符数 |
|---|---|---|---|
| `emails` * | string 数组 | 接收已签名 PDF 的电子邮件列表。至少 1 个地址。通常为申请询证的审计师邮箱。 | - |
| `reference_date` * | string (YYYY-MM-DD) | 余额计算的基准日。询证函将以该日的期末余额为准声明每个账户的余额。 | 10 |
| `recipient_name` | string | 收件公司/机构名称，用于文档的称谓行（"致 `{recipient_name}` 全体" ）。如未填写，默认为"敬启者，"。 | - |

Request Body

```json
{
  "emails": ["audit@audit-firm.com"],
  "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": ["audit@audit-firm.com"],
    "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

| 字段 | 类型 | 描述 | 最大字符数 |
|---|---|---|---|
| `document_key` | UUID | 文档在 QI 内部的唯一标识符。 | 36 |
| `account_key` | UUID | 来源账户的密钥。 | 36 |
| `document_type` | string | 文档类型。此接口固定为 `circularization_letter`。 | - |
| `document_status` | string | 文档当前状态。参见 [document_status 枚举值](#document_status-枚举值)。 | - |
| `external_identifier_key` | string | 签名批次的外部标识符。 | 300 |
| `file_url` | string | 文档当前 URL。处于 `pending` 时指向签名跟踪页面；变为 `sent` 后指向已签名 PDF。 | - |
| `payload` | object | 请求体的回显。 | - |
| `created_at` | datetime Zulu | 文档创建时间。 | 20 |
| `updated_at` | datetime Zulu | 文档最后更新时间。 | 20 |

### document_status 枚举值

| 枚举值 | 描述 |
|---|---|
| **pending** | 文档已创建，正在等待签名完成。 |
| **sent** | 文档已签名，电子邮件已发送给收件人。 |

## 获取已签名文档链接

签名完成后（状态为 `sent`），使用此接口获取由 CertifIQI 按需生成的、用于下载已签名 PDF 的**带时效链接**。当文档仍处于 `pending` 时——即尚未收到签名 webhook——该 URL 尚不存在，接口将返回错误。

### Request

ENDPOINT /account/ ACCOUNT_KEY /document/ DOCUMENT_KEY /url
方法 GET

### Path parameters

| 字段 | 类型 | 描述 |
|---|------|-----------|
| `ACCOUNT_KEY` | UUID | 文档所属账户的密钥。 |
| `DOCUMENT_KEY` | UUID | 开具信函时返回的文档标识符（`document_key`）。 |

## 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

| 字段 | 类型 | 描述 | 最大字符数 |
|---|---|---|---|
| `document_key` | UUID | QI 内部文档标识符。 | 36 |
| `document_type` | string | 文档类型。询证函为 `circularization_letter`。 | - |
| `document_status` | string | 文档当前状态。仅当为 `sent` 时才返回 URL。 | - |
| `url` | string | 用于下载已签名 PDF 的**带时效链接**。按需生成，短时间后过期。 | - |

### 可能的错误

| 状态 | 描述 |
|---|---|
| 404 | 未找到对应标识符的账户或文档。 |
| 409 | 文档仍在签名中（`pending`）；已签名 URL 尚不可用。 |

---

# 查询费率

URL: /zh-Hans/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"
         },
         "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"
         }
      }
   }
}
```

### 计费配置数据

| 字段 | 类型 | 描述 |
|---| ---| ---|
| `bank_slip` | object | **[银行票据](#bank_slip)** |
| `ted` | object | **[TED](#ted)** |
| `pix` | object | **[Pix](#pix)** |
| `account` | object | **[账户](#account)** |
| `prepaid_card` | object | **[预付卡](#prepaid_card)** |
| `qr_code` | object | **[QR 码](#qr_code)** |

### 银行票据（BankSlip）

| 字段 | 类型 | 描述 | 参考 |
|---|---|---|---|
| `registration` | object | 登记费 | **[标准费率对象](#objeto-padrão-fees)** |
| `permanence` | object | 已登记票据保留费 | **[标准费率对象](#objeto-padrão-fees)** |
| `protest_removal` | object | 撤销抗议/移除负面记录费 | **[标准费率对象](#objeto-padrão-fees)** |
| `protest_request` | object | 抗议申请/添加负面记录费 | **[标准费率对象](#objeto-padrão-fees)** |
| `protest_costs` | object | 抗议费用，此字段的 **expense_type 必须为 'percentage'** | **[标准费率对象](#objeto-padrão-fees)** |
| `expiration_date_change` | object | 更改到期日费 | **[标准费率对象](#objeto-padrão-fees)** |
| `rebate_inclusion` | object | 添加折扣费 | **[标准费率对象](#objeto-padrão-fees)** |
| `discount_inclusion` | object | 添加优惠费 | **[标准费率对象](#objeto-padrão-fees)** |
| `notary_office_payment` | object | 公证处付款票据撤销费 | **[标准费率对象](#objeto-padrão-fees)** |
| `expiration_write_off` | object | 逾期撤销票据费 | **[标准费率对象](#objeto-padrão-fees)** |
| `write_off` | object | 按请求撤销票据费 | **[标准费率对象](#objeto-padrão-fees)** |
| `protest_write_off` | object | 撤销抗议票据费 | **[标准费率对象](#objeto-padrão-fees)** |
| `protest_removal_and_write_off` | object | 撤销票据 SUST/RET/公证处费 | **[标准费率对象](#objeto-padrão-fees)** |
| `payment` | object | 结算费 | **[标准费率对象](#objeto-padrão-fees)** |
| `payment_qr_code` | object | QR 码结算费 | **[标准费率对象](#objeto-padrão-fees)** |
| `fine_or_interest_inclusion` | object | 添加罚款和利息费 | **[标准费率对象](#objeto-padrão-fees)** |
| `bank_slip_fine_alteration` | object | 修改罚款费 | **[标准费率对象](#objeto-padrão-fees)** |
| `bank_slip_interest_alteration` | object | 修改利息费 | **[标准费率对象](#objeto-padrão-fees)** |
| `bank_slip_discount_alteration` | object | 修改折扣费 | **[标准费率对象](#objeto-padrão-fees)** |
| `bank_slip_instant_registration` | object | 即时银行票据登记费 | **[标准费率对象](#objeto-padrão-fees)** |

### TED

| 字段 | 类型 | 描述 | 参考 |
|---|---|---|---|
| `outgoing_ted` | object | TED 发送费 | **[标准费率对象](#objeto-padrão-fees)** |
| `incoming_ted` | object | TED 接收费 | **[标准费率对象](#objeto-padrão-fees)** |

### Pix

| 字段 | 类型 | 描述 | 参考 |
|---|---|---|---|
| `incoming_pix` | object | PIX 接收费 | **[标准费率对象](#objeto-padrão-fees)** |
| `outgoing_pix` | object | PIX 发送费 | **[标准费率对象](#objeto-padrão-fees)** |

### 账户（Account）

| 字段 | 类型 | 描述 | 参考 |
|---|---|---|---|
| `incoming_funds` | object | 资金进账费 | **[标准费率对象](#objeto-padrão-fees)** |
| `account_maintenance` | object | 账户维护费 | **[标准费率对象](#objeto-padrão-fees)** |
| `account_creation` | object | 开户费 | **[标准费率对象](#objeto-padrão-fees)** |

### QR 码（QrCode）

| 字段 | 类型 | 描述 | 参考 |
|---|---|---|---|
| `dynamic_qr_code_expiration` | object | 未结清动态 QR 码到期费 | **[标准费率对象](#objeto-padrão-fees)** |

### 预付卡（PrepaidCard）

| 字段 | 类型 | 描述 | 参考 |
|---|---|---|---|
| `prepaid_fisical_card_creation` | object | 实体卡创建费 | **[标准费率对象](#objeto-padrão-fees)** |
| `prepaid_virtual_card_creation` | object | 虚拟卡创建费 | **[标准费率对象](#objeto-padrão-fees)** |
| `card_withdrawal_fee` | object | 取款费 | **[标准费率对象](#objeto-padrão-fees)** |
| `international_card_withdrawal_fee` | object | 国际取款费 | **[标准费率对象](#objeto-padrão-fees)** |

### 标准费率对象（fees）

| 字段 | 类型 | 描述 | 参考 |
|---|---|---|---|
| `amount` | number | 费率金额，可以是绝对值（fixed_amount）或百分比（percentage），限两位小数 | |
| `expense_type` | enum | 收费方式 | **[expense_type 枚举值](#enumerador-expense-type)** |
| `billing_account_key` | string | 包含收费账户引用的 id（uuid） | |

# 枚举值

### expense_type 枚举值
| 枚举值 | 描述 |
|-----------------------|---------------------------------------------------------------------------|
| **percentage** | 百分比金额 |
| **fixed_amount** | 绝对金额 |

STATUS 4XX

**Response Body: Error**

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

| HTTP 代码 | QI 代码<br/>`code` | 标题<br/>`title` | 描述（英文）<br/>`Description` | 描述（葡文）<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. |

---

# 查询账户

URL: /zh-Hans/documentation/contas/consultar_conta

## Request

ENDPOINT /account/ ACCOUNT_KEY
MÉTODO GET

### Path Params

| 字段           | 类型 | 描述               |
|---------------|------|--------------------|
| `ACCOUNT_KEY` | UUID | 需要查询的账户密钥  |

## 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

| 字段                      | 类型          | 描述                           | 最大字符数                                                            |
|---------------------------|---------------|--------------------------------|-----------------------------------------------------------------------|
| `account_key`             | uuid          | 账户唯一标识符。               | 36                                                                    |
| `account_branch`          | string        | 机构号，不含检验位。           | 4                                                                     |
| `account_digit`           | string        | 账户检验位。                   | 1                                                                     |
| `account_number`          | string        | 账户号，不含检验位。           | 20                                                                    |
| `account_type`            | string        | 账户类型定义。                 | 20                                                                    |
| `account_status`          | string        | 账户状态。                     | [account_status 枚举值](#enumeradores-account_status)                 |
| `owner_document_number`   | string        | CPF 或 CNPJ 号码。             | 14                                                                    |
| `owner_name`              | string        | 账户所有人姓名。               | 120                                                                   |
| `balance`                 | double        | 账户余额。                     | 120                                                                   |
| `blocked_balance`         | double        | 账户冻结余额。                 | 120                                                                   |
| `owner_person_key`        | string        | 账户所有人唯一标识符。         | 36                                                                    |
| `account_documents`       | ARRAY         | 账户唯一标识符数组。           | -                                                                     |
| `created_at`              | datetime Zulu | 请求创建日期。                 | 20                                                                    |

### account_status 枚举值
| 枚举值    | 描述       |
|-----------|------------|
| `opened`  | 账户已开立 |
| `closed`  | 账户已关闭 |
| `blocked` | 账户已冻结 |

STATUS 404

Response Body: 用户无凭证

```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: 用户无凭证

```json
{
    "title": "Permission Validator Error",
    "description": "Selected agent do not own this item.",
    "translation": "O agente selecionado não é dono do item.",
    "code": "QIT000005"
}
```

---

# 列出账户

URL: /zh-Hans/documentation/contas/consultar_contas

## Request

ENDPOINT /account
MÉTODO GET

## 查询参数
| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---| ---|
| `owner_document_number` | string | 账户持有人证件号码 | - |
| `account_number` | string | 账户号码 | - |

## 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\"}"
}

```

---

# 查询开户请求详情

URL: /zh-Hans/documentation/contas/consultar_detalhes_pedido_conta

用于查询开户请求的完整详情，包括提案状态、相关方、附件文档、事件和配置等信息。

:::info 信息
此接口仅支持 **checking**（活期账户）和 **escrow**（托管账户）类型的账户。
:::

## Request

ENDPOINT /v2/account_request/ ACCOUNT_REQUEST_KEY /full
MÉTODO GET

### Path Params

| 字段 | 类型 | 描述 |
|---|------|-----------|
| `ACCOUNT_REQUEST_KEY` | UUID | 要查询的开户请求唯一密钥 |

## 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": "请求者姓名",
    "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": "账户持有人姓名",
        "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": "账户开立成功",
            "created_at": "2023-05-15T20:00:00"
        }
    ],
    "destinations": [
        {
            "account_branch": "0001",
            "account_number": "5960389",
            "account_digit": "7",
            "document_number": "30987145223",
            "name": "目标账户名称",
            "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": "身份证明文件",
            "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": "补充信息",
                "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": "巴西",
            "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 参数

| 字段 | 类型 | 描述 |
|---|------|-----------|
| `proposal_key` | string | 开户请求唯一密钥 |
| `contract_number` | string | 合同编号 |
| `requester_key` | string | 请求者密钥 |
| `requester_name` | string | 请求者姓名 |
| `requester_document_number` | string | 请求者 CPF 或 CNPJ |
| `request_control_key` | string | 请求控制密钥 |
| `created_account_key` | string | 已创建账户密钥 |
| `reserved_related_account` | object | 预留关联账户数据（可为 `null`） |
| `proposal_status` | object | 当前提案状态 |
| `account_type` | object | 账户类型 |
| `document_key` | string | 文档密钥 |
| `document_template_key` | string | 文档模板密钥 |
| `is_simplified` | boolean | 是否为简化账户 |
| `created_at` | datetime | 请求创建日期 |
| `signed_contract` | object | 已签署合同数据（可为 `null`） |
| `additional_documents` | array | 附加文档（可为 `null`） |
| `events` | array | 请求事件列表 |
| `rejection_reason` | string | 拒绝原因，仅在被拒绝时出现 |
| `destinations` | array | 已配置的目标账户列表 |
| `attached_documents` | array | 附件文档列表 |
| `related_parties` | array | 相关方列表 |
| `credit_operations` | array | 信贷操作列表 |
| `automatic_transfer_config` | object | 自动转账配置 |
| `billing_configuration_data` | object | 计费配置（可为 `null`） |
| `account_owner_data` | object | 账户所有人数据（可为 `null`） |

### proposal_status / account_type 对象

| 字段 | 类型 | 描述 |
|---|------|-----------|
| `enumerator` | string | 枚举值 |
| `translation_path` | string | 翻译路径 |
| `created_at` | datetime | 创建日期 |

### proposal_status 枚举值

| 枚举值 | 描述 |
|------------|-----------|
| `pending` | 待处理 |
| `pending_kyc_analysis` | 待 KYC 审核 |
| `account_opened` | 账户已开立 |
| `rejected` | 已拒绝 |
| `cancelled` | 已取消 |

### account_type 枚举值

| 枚举值 | 描述 |
|------------|-----------|
| `checking` | 活期账户 |
| `escrow` | 托管账户 |

### events 对象

| 字段 | 类型 | 描述 |
|---|------|-----------|
| `old_status` | object | 旧状态（与 proposal_status 格式相同） |
| `new_status` | object | 新状态（与 proposal_status 格式相同） |
| `rejection_reason` | string | 拒绝原因（可为 `null`） |
| `event_description` | string | 事件描述 |
| `created_at` | datetime | 事件日期 |

### destinations / reserved_related_account 对象

| 字段 | 类型 | 描述 |
|---|------|-----------|
| `account_branch` | string | 机构号 |
| `account_number` | string | 账户号 |
| `account_digit` | string | 检验位 |
| `document_number` | string | CPF 或 CNPJ |
| `name` | string | 账户持有人姓名 |
| `financial_institutions_code_number` | string | 金融机构代码 |
| `financial_institutions` | object | 金融机构数据 |
| `ted_account_type` | object | TED 账户类型 |
| `is_activated` | boolean | 目标账户是否激活 |
| `updated_at` | datetime | 更新日期 |
| `created_at` | datetime | 创建日期 |

### attached_documents 对象

| 字段 | 类型 | 描述 |
|---|------|-----------|
| `document_key` | string | 文档唯一密钥 |
| `document_type` | object | 文档类型（枚举格式） |
| `description` | string | 文档描述 |
| `document_url` | string | 文档 URL |
| `is_activated` | boolean | 文档是否激活 |
| `updated_at` | datetime | 更新日期 |
| `created_at` | datetime | 创建日期 |

### related_parties 对象

| 字段 | 类型 | 描述 |
|---|------|-----------|
| `person_key` | string | 人员唯一密钥 |
| `person_type` | object | 人员类型（枚举格式） |
| `individual_document_number` | string | CPF |
| `company_document_number` | string | CNPJ |
| `name` | string | 姓名 |
| `mother_name` | string | 母亲姓名 |
| `is_pep` | boolean | 是否为政治敏感人士 |
| `final_beneficiary` | boolean | 是否为最终受益人 |
| `is_signer` | boolean | 是否为签署人 |
| `is_activated` | boolean | 是否激活 |
| `address` | object | 地址 |
| `phone` | object | 电话 |
| `nationality` | string | 国籍 |
| `email` | string | 电子邮件 |
| `birth_date` | string | 出生日期 |
| `role_type` | object | 角色类型（枚举格式） |
| `updated_at` | datetime | 更新日期 |
| `created_at` | datetime | 创建日期 |

## 错误

STATUS 404

Response Body: 未找到开户请求

```json
{
    "title": "Proposal Not Found",
    "description": "Proposal not found.",
    "translation": "Proposta não encontrada.",
    "code": "ACR000003"
}
```

STATUS 400

Response Body: 不支持的账户类型

```json
{
    "title": "Temporarily unavailable",
    "description": "Temporarily unavailable",
    "translation": "Temporariamente indisponível",
    "code": "ACR000068"
}
```

STATUS 403

Response Body: 用户无凭证

```json
{
    "title": "Permission Validator Error",
    "description": "Selected agent do not own this item.",
    "translation": "O agente selecionado não é dono do item.",
    "code": "QIT000005"
}
```

---

# 账户注销

URL: /zh-Hans/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 **注意！**

**"url"** 字段中返回的账户注销凭证 PDF 必须提供给客户查看。

:::

### 路径参数

| 字段 | 类型 | 描述 |
|---|---| ---|
| `account_key` * | string | 账户密钥 |

## 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\"}"
}

```

### 错误码

| 代码 | 状态码 | 描述 |
|---|---|---|
| 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 注意！
QI Tech 的 webhooks 不应以严格方式映射。
我们 API 返回的 webhook 载荷中可能包含额外字段。
:::

:::info 重发 Webhooks
您可以按照文档中的详细说明查询和重发 webhooks：[重发 Webhooks](/documentation/notificacoes/reenvio_de_notificacoes)。
:::

以下描述了账户注销时触发的 webhook。

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"
  }
}
```

---

# 费率对账单

URL: /zh-Hans/documentation/contas/extrato_de_tarifas

返回所选周期内向特定收费账户收取的费率列表。

## Request

ENDPOINT /billing/requester_configuration/billing_account/ BILLING_ACCOUNT_KEY /invoices
MÉTODO GET

### Path Params

| 字段 | 类型 | 描述 |
|---|---| ---|
| `BILLING_ACCOUNT_KEY` | string | 将列出其费率的收费账户 id（uuid）。 |

## Query Params

| 字段 | 类型 | 描述 |
|---|---| ---|
| `start_date` | string | 周期的起始日期，格式为 `yyyy-mm-dd`。可选。 |
| `end_date` | string | 周期的结束日期，格式为 `yyyy-mm-dd`。可选。 |
| `status` | string | 按费率状态筛选。可选。 **[状态枚举值](#状态枚举值)** |
| `billing_type` | string | 按费率类型筛选。可多次提供以组合多种类型。可选。 |
| `page` | integer | 页码。默认 `1`。 |
| `page_size` | integer | 每页费率数量。默认 `20`，最大 `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

| 字段 | 类型 | 描述 |
|---|---| ---|
| `data` | array | 收取的费率列表。 **[Data](#data)** |
| `page` | integer | 返回的页码。 |
| `page_size` | integer | 每页费率数量。 |
| `has_next_page` | boolean | 表示是否还有更多结果页。 |

### Data

| 字段 | 类型 | 描述 |
|---|---| ---|
| `invoice_key` | string | 费率 id（uuid）。 |
| `reference_date` | string | 费率的参考日期，格式为 `yyyy-mm-dd`。 |
| `billing_type` | string | 费率类型（枚举值）。 |
| `billing_type_description` | string | 费率类型的描述。 |
| `status` | string | 费率状态。 **[状态枚举值](#状态枚举值)** |
| `total_amount` | number | 费率的总金额。 |
| `paid_amount` | number | 费率已付金额。 |
| `amount_owed` | number | 费率未结清金额。已核销费率（`written_off`）返回 `0`。 |

# 枚举值

### 状态枚举值

| 枚举值 | 描述 |
|---|---|
| **open** | 未结清费率。 |
| **pending** | 等待付款的费率。 |
| **paid** | 已结清费率。 |
| **written_off** | 已核销费率。 |

STATUS 4XX

**Response Body: Error**

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

| HTTP 代码 | QI 代码<br/>`code` | 标题<br/>`title`          | 描述（英文）<br/>`description`                        | 描述（葡文）<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.                                         |

---

# 费率管理

URL: /zh-Hans/documentation/contas/gestao_de_tarifas

## Request

ENDPOINT /account/ ACCOUNT_KEY /billing_configuration
MÉTODO PUT

:::danger 费率定义与转让
每项费率的最大值和最小值必须与 QI Tech 商务团队协商确定。

向合作伙伴转让的金额（对应每项收取的费率）也必须与 QI Tech 商务团队协商确定。
:::

:::danger 一般注意事项：
对于此端点，"Request Body" 必须严格按照要求填写，因为所有字段均为必填项。
:::

**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"
         },
         "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"
         }
      }
   }
}

```

### 请求体参数

| 字段 | 类型 | 描述 |
|---|---| ---|
| `billing_configuration_data` | object | **[计费配置数据](#billing_configuration_data)** |

### 计费配置数据

| 字段 | 类型 | 描述 |
|---| ---| ---|
| `bank_slip` | object | **[银行票据](#bank_slip)** |
| `ted` | object | **[TED](#ted)** |
| `pix_transfer` | object | **[Pix](#pix)** |
| `account` | object | **[账户](#account)** |
| `prepaid_card` | object | **[预付卡](#prepaid_card)** |
| `qr_code` | object | **[QR 码](#qr_code)** |
| `automatic_pix` | object | **[自动 PIX](#automatic_pix)** |

### 银行票据（BankSlip）

| 字段 | 类型 | 描述 | 参考 |
|---|---|---|---|
| `registration` | object | 登记费 | **[标准费率对象](#objeto-padrão-fees)** |
| `permanence` | object | 已登记票据保留费 | **[标准费率对象](#objeto-padrão-fees)** |
| `protest_removal` | object | 撤销抗议/移除负面记录费 | **[标准费率对象](#objeto-padrão-fees)** |
| `protest_request` | object | 抗议申请/添加负面记录费 | **[标准费率对象](#objeto-padrão-fees)** |
| `protest_costs` | object | 抗议费用，此字段的 **expense_type 必须为 'percentage'** | **[标准费率对象](#objeto-padrão-fees)** |
| `expiration_date_change` | object | 更改到期日费 | **[标准费率对象](#objeto-padrão-fees)** |
| `rebate_inclusion` | object | 添加折扣费 | **[标准费率对象](#objeto-padrão-fees)** |
| `discount_inclusion` | object | 添加优惠费 | **[标准费率对象](#objeto-padrão-fees)** |
| `notary_office_payment` | object | 公证处付款票据撤销费 | **[标准费率对象](#objeto-padrão-fees)** |
| `expiration_write_off` | object | 逾期撤销票据费 | **[标准费率对象](#objeto-padrão-fees)** |
| `write_off` | object | 按请求撤销票据费 | **[标准费率对象](#objeto-padrão-fees)** |
| `protest_write_off` | object | 撤销抗议票据费 | **[标准费率对象](#objeto-padrão-fees)** |
| `protest_removal_and_write_off` | object | 撤销票据 SUST/RET/公证处费 | **[标准费率对象](#objeto-padrão-fees)** |
| `payment` | object | 结算费 | **[标准费率对象](#objeto-padrão-fees)** |
| `payment_qr_code` | object | QR 码结算费 | **[标准费率对象](#objeto-padrão-fees)** |
| `fine_or_interest_inclusion` | object | 添加罚款和利息费 | **[标准费率对象](#objeto-padrão-fees)** |
| `bank_slip_fine_alteration` | object | 修改罚款费 | **[标准费率对象](#objeto-padrão-fees)** |
| `bank_slip_interest_alteration` | object | 修改利息费 | **[标准费率对象](#objeto-padrão-fees)** |
| `bank_slip_discount_alteration` | object | 修改折扣费 | **[标准费率对象](#objeto-padrão-fees)** |
| `bank_slip_instant_registration` | object | 即时银行票据登记费 | **[标准费率对象](#objeto-padrão-fees)** |

### TED

| 字段 | 类型 | 描述 | 参考 |
|---|---|---|---|
| `outgoing_ted` | object | TED 发送费 | **[标准费率对象](#objeto-padrão-fees)** |
| `incoming_ted` | object | TED 接收费 | **[标准费率对象](#objeto-padrão-fees)** |

### Pix

| 字段 | 类型 | 描述 | 参考 |
|---|---|---|---|
| `incoming_pix` | object | PIX 接收费 | **[标准费率对象](#objeto-padrão-fees)** |
| `outgoing_pix` | object | PIX 发送费 | **[标准费率对象](#objeto-padrão-fees)** |

### 账户（Account）

| 字段 | 类型 | 描述 | 参考 |
|---|---|---|---|
| `incoming_funds` | object | 资金进账费 | **[标准费率对象](#objeto-padrão-fees)** |
| `account_maintenance` | object | 账户维护费 | **[标准费率对象](#objeto-padrão-fees)** |
| `account_creation` | object | 开户费 | **[标准费率对象](#objeto-padrão-fees)** |

### QR 码（QrCode）

| 字段 | 类型 | 描述 | 参考 |
|---|---|---|---|
| `dynamic_qr_code_expiration` | object | 未结清动态 QR 码到期费 | **[标准费率对象](#objeto-padrão-fees)** |

### 预付卡（PrepaidCard）

| 字段 | 类型 | 描述 | 参考 |
|---|---|---|---|
| `prepaid_fisical_card_creation` | object | 实体卡创建费 | **[标准费率对象](#objeto-padrão-fees)** |
| `prepaid_virtual_card_creation` | object | 虚拟卡创建费 | **[标准费率对象](#objeto-padrão-fees)** |
| `card_withdrawal_fee` | object | 取款费 | **[标准费率对象](#objeto-padrão-fees)** |
| `international_card_withdrawal_fee` | object | 国际取款费 | **[标准费率对象](#objeto-padrão-fees)** |

### 自动 PIX（Pix Automático）

| 字段 | 类型 | 描述 | 参考 |
|---|---|---|---|
| `active_recurrence` | object | PIX 有效循环费 | **[标准费率对象](#objeto-padrão-fees)** |
| `recurrence_settlement` | object | PIX 循环结算费 | **[标准费率对象](#objeto-padrão-fees)** |

### 标准费率对象（fees）

| 字段 | 类型 | 描述 | 参考 |
|---|---|---|---|
| `amount` | number | 费率金额，可以是绝对值（fixed_amount）或百分比（percentage），限两位小数 | |
| `expense_type` | enum | 收费方式 | **[expense_type 枚举值](#enumerador-expense-type)** |
| `billing_account_key` | string | 包含收费账户引用的 id（uuid） | |

# 枚举值

### expense_type 枚举值
| 枚举值 | 描述 |
|-----------------------|---------------------------------------------------------------------------|
| **percentage** | 百分比金额 |
| **fixed_amount** | 绝对金额 |

## Response

STATUS 200

**Response Body**

```json
{
   "account_key": "3a4fe5f9-3133-4ce3-9988-9ff8827bcaa5",
   "billing_configuration_data":{
      "bank_slip":{...},
      "ted":{...},
      "pix":{...},
      "account": {...},
      "qr_code": {...},
      "prepaid_card": {...},
      "automatic_pix": {...}
   }
}
```

STATUS 400

**Response Body**

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

```

---

# 收益报告

URL: /zh-Hans/documentation/contas/informe_rendimentos

## Request

ENDPOINT /account/ ACCOUNT_KEY /income_report/ REFERENCE_YEAR
MÉTODO POST

Request Body - 个人账户持有人（PF）

```json
{
  "partner_logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAHgAAAAiCAYAAACUc"
}
```

| 字段 | 描述 | 示例 |
|---|---|---|
| `partner_logo` | 合作伙伴标志，将显示在收益报告页眉左侧（如提供）。若未提供，则仅在右上角显示 QI 标志。图像需以 HTML data:image/png;格式,base64 编码格式提供 | data:image/png;base64,iVBORw0... |

### Path Params
| 字段 | 类型 | 描述 |
|---|---|---|
| `REFERENCE_YEAR` | number | 报告参考年份 |
| `ACCOUNT_KEY` | UUID | 要查询收益报告的账户密钥 |

## Response
将返回一个 blob（base64），需将其转换为收益报告的 PDF。

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+CmVuZG9iago..."
}
```

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\"}"
}

```

---

# 查询账户冻结记录

URL: /zh-Hans/documentation/contas/ordens_de_bloqueio

## Request

ENDPOINT /account/ ACCOUNT_KEY /account_block_records
MÉTODO GET

### 路径参数

| 字段 | 类型 | 描述 |
|---|------|--------------------------------|
| `ACCOUNT_KEY` | UUID | 要查询详情的账户密钥 |

### 查询参数

| 字段 | 类型 | 描述 | 字符数 |
|----------------------------|------------|-------------------------------------------------------|-----------------------------------------------------------------------------|
| `block_order_statuses` * | enumerator | 冻结指令状态 | [block_order_statuses 枚举值](#enumeradores-block_order_statuses) |

### block_order_statuses 枚举值

| 枚举值 | 描述 |
|--------------|------------------------------|
| **pending** | 冻结指令待处理 |
| **open** | 冻结指令已开放 |
| **concluded** | 冻结指令已完成 |

## 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"
      }
    }
  ]
}
```

### 响应体参数

| 字段 | 类型 | 描述 | 最大字符数 |
|--------------------------------|-----------------|----------------------------------------------------|-----------------|
| `account_blocked_amount`       | float          | 账户冻结金额 | - |
| `block_order`                  | object          | 冻结指令详情 | **[block_order 对象](#objeto-block_order)** |

### block_order 对象

| 字段 | 类型 | 描述 | 最大字符数 |
|--------------------------------|-----------------|----------------------------------------------------|-----------------|
| `block_order_protocol`      | string          | 冻结指令协议编号 | - |
| `block_order_sequence`      | string          | 冻结指令序列号 | - |
| `case_number`               | string          | 案件编号 | - |
| `court_code`                | string          | 法院代码 | - |
| `defendant_document_number` | string          | 被告证件号码 | 14 |
| `institution_document_number` | string or null| 机构证件号码（如适用） | - |
| `lawsuit_author_name`       | string          | 诉讼作者姓名 | - |
| `lawsuit_type`              | enumerator      | 诉讼类型 | **[lawsuit_type 枚举值](#enumeradores-lawsuit_type)** |
| `protocol_datetime`         | string   | 协议日期和时间 | 20 |
| `requested_amount`          | float          | 申请金额 | - |
| `requester_judge`           | string          | 申请法官姓名 | - |

### lawsuit_type 枚举值

| 枚举值 | 描述 |
|-------------|------------------------|
| `labor`     | 劳动纠纷 |
| `civil`     | 民事诉讼 |
| `criminal`  | 刑事诉讼 |
| `tax`       | 税务纠纷 |
| `family`    | 家事纠纷 |

STATUS 404

Response Body：账户未找到

```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：用户无权限

```json
{
    "title": "Permission Validator Error",
    "description": "Selected agent do not own this item.",
    "translation": "O agente selecionado não é dono do item.",
    "code": "QIT000005"
}
```

---

# 场景模拟

URL: /zh-Hans/documentation/contas/simulacao

模拟客户账户冻结和解冻的分步说明。

## 1 - 模拟账户冻结

### Request

ENDPOINT /mock/account/ ACCOUNT_KEY /block
MÉTODO PATCH

Request Body

```json
{
  "account_block_reason": "\<Motivo do bloqueio da conta\>"
}
```

### 请求体参数

| 字段 | 类型 | 描述 | 示例 |
|----------------------|--------|------------------------------------|----------------------------------------|
| `account_block_reason` | string | 账户冻结原因 | "judicially_suspended" |

:::info
可用的冻结原因可以在[账户冻结 Webhook](../movimentacao_de_contas/webhook_movimentacoes#webhook-de-bloqueio-de-conta) 部分查阅。
:::

## 2 - 模拟账户解冻

### Request

ENDPOINT /mock/account/ ACCOUNT_KEY /unblock
MÉTODO PATCH

Request Body

```json
{
}
```

---

# 为 Escrow 账户创建目标账户

URL: /zh-Hans/documentation/d88ff174-100d-4b55-80b7-86e11f508400

此端点允许为 Escrow 账户创建目标账户

## Request

### 请求端点

ENDPOINT /account/ ACCOUNT_KEY /destination
MÉTODO POST

### 请求路径参数

| 字段              | 类型    | 描述                      | 字符数 |
|-------------------|---------|---------------------------|--------|
| `account_key` *   | uuid4   | 账户的唯一识别密钥。      | 36     |

Request Body: 添加目标账户

```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

| 字段                                         | 类型   | 描述                          |
|----------------------------------------------|--------|-------------------------------|
| `name` *                                     | string | 收款方姓名                    |    
| `ted_account_type` *                         | enum   | 目标账户类型。                |
| `account_branch`  *                          | string | 目标账户机构号。              |
| `account_digit` *                            | string | 目标账户检验位。              |
| `account_number` *                           | string | 目标账户号。                  |
| `financial_institutions_code_number` *       | string | 目标账户所在银行代码。        |

## Response

### 成功响应

STATUS 201

Response Body:

```json
{}
```

### 错误响应

STATUS 4XX

Response Body

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

| HTTP 状态码 | QI 代码   | 标题                                           | 英文描述                                               | 葡语描述                                                     |
|-------------|-----------|------------------------------------------------|--------------------------------------------------------|--------------------------------------------------------------|
| 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               |

---

# 在 DDA 中注册账户

URL: /zh-Hans/documentation/dda/cadastro_dda

要启用接收以 QI 账户持有人作为付款方的银行票据信息，需要在 DDA 中注册该账户。

加入条款签名的凭证必须在请求中发送。

## 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

| 字段         | 类型   | 描述                                               | 字符数 |
| ------------- | ------ | ------------------------------------------------------- | ---------- |
| `account_key` | string | 要在 DDA 中注册的账户标识键 | 36         |

### Body Params

| 字段                | 类型   | 描述                                  | 字符数 |
| -------------------- | ------ | ------------------------------------------ | ---------- |
| `authorization_term` | object | 付款方签署的授权数据 | -          |

## 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"
}
```

| 字段                   | 类型   | 描述                                                | 字符数 |
| ----------------------- | ------ | -------------------------------------------------------- | ---------- |
| `account_key`           | string | 在 DDA 中注册的账户的 account_key。                  | 36         |
| `dda_account_status`    | enum   | [账户状态枚举值。](#enumeradores-status) | -          |
| `account_number`        | string | 账户号码。                                         | 20         |
| `account_digit`         | string | 账户验证位。                                         | 1          |
| `owner_document_number` | string | 账户持有人的文件号码。                              | 14         |
| `owner_person_key`      | string | 账户持有人的 person key。                             | 36         |
| `requester_key`         | string | 开户方的 requester key。                     | 36         |
| `created_at`            | string | 在 DDA 中创建和激活的日期。                       | 24         |

### 状态枚举值

| 枚举值  | 描述                           |
| ----------- | ----------------------------------- |
| `active`    | DDA 中的活跃账户。                 |
| `cancelled` | 与 DDA 的关系已终止。 |

---

# 从 DDA 中移除账户

URL: /zh-Hans/documentation/dda/cancelamento_dda

从 DDA 中移除账户后，将不再接收以该账户持有人作为付款方的银行票据注册通知。

:::info 信息
如果账户持有人还拥有其他由集成合作伙伴开设且在 DDA 中注册的账户，通知将继续发送。

要停止通知，需要移除在 DDA 中注册的持有人的所有账户。
:::

取消注册条款签名的凭证必须在请求中发送。

## 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

| 字段         | 类型   | 描述                                         | 字符数 |
| ------------- | ------ | ------------------------------------------------- | ---------- |
| `account_key` | string | 在 DDA 中注册的账户标识键 | 36         |

### Body Params

| 字段                | 类型   | 描述                                  | 字符数 |
| -------------------- | ------ | ------------------------------------------ | ---------- |
| `authorization_term` | object | 付款方签署的授权数据 | -          |

## 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"
}
```

| 字段                   | 类型   | 描述                                                | 字符数 |
| ----------------------- | ------ | -------------------------------------------------------- | ---------- |
| `account_key`           | string | 在 DDA 中注册的账户的 account_key。                  | 36         |
| `dda_account_status`    | enum   | [账户状态枚举值。](#enumeradores-status) | -          |
| `account_number`        | string | 账户号码。                                         | 20         |
| `account_digit`         | string | 账户验证位。                                         | 1          |
| `owner_document_number` | string | 账户持有人的文件号码。                              | 14         |
| `owner_person_key`      | string | 账户持有人的 person key。                             | 36         |
| `requester_key`         | string | 开户方的 requester key。                     | 36         |
| `created_at`            | string | 在 DDA 中创建和激活的日期。                       | 24         |

### 状态枚举值

| 枚举值  | 描述                           |
| ----------- | ----------------------------------- |
| `active`    | DDA 中的活跃账户。                 |
| `cancelled` | 与 DDA 的关系已终止。 |

---

# 查询 DDA 中注册的账户

URL: /zh-Hans/documentation/dda/consultar_dados_conta

查询请求方在 DDA 中的活跃账户。
## Request

ENDPOINT /account/ ACCOUNT_KEY /dda
MÉTODO GET

### Path Params

| 字段         | 类型   | 描述                                         | 字符数 |
| ------------- | ------ | ------------------------------------------------- | ---------- |
| `account_key` | string | 在 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"
}
```

| 字段                   | 类型   | 描述                                                | 字符数 |
| ----------------------- | ------ | -------------------------------------------------------- | ---------- |
| `account_key`           | string | 在 DDA 中注册的账户的 account_key。                  | 36         |
| `dda_account_status`    | enum   | [账户状态枚举值。](#enumeradores-status) | -          |
| `account_number`        | string | 账户号码。                                         | 20         |
| `account_digit`         | string | 账户验证位。                                         | 1          |
| `owner_document_number` | string | 账户持有人的文件号码。                              | 14         |
| `owner_person_key`      | string | 账户持有人的 person key。                             | 36         |
| `requester_key`         | string | 开户方的 requester key。                     | 36         |
| `created_at`            | string | 在 DDA 中创建和激活的日期。                       | 24         |

### 状态枚举值

| 枚举值  | 描述                           |
| ----------- | ----------------------------------- |
| `active`    | DDA 中的活跃账户。                 |
| `cancelled` | 与 DDA 的关系已终止。 |

---

# Erros retornados na api

URL: /zh-Hans/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"
}

```

---

# 介绍

URL: /zh-Hans/documentation/dda/introducao

授权直接扣款（DDA）API 使 QI Tech 账户能够接收以该账户持有人作为付款方的所有银行票据的信息。

:::danger 一般说明：
- 对于此 API，在 DDA 中注册的**账户**必须是 QI 账户。
- 条款的公示和接受是合作伙伴（集成商）的责任。
:::

---

# 列出 DDA 中注册的账户

URL: /zh-Hans/documentation/dda/lista_contas_cadastradas

## Request

ENDPOINT /dda/accounts
MÉTODO GET

### QUERY PARAMS

| 字段         | 描述                              |
| ------------- | -------------------------------------- |
| `page_number` | 当前查询的页码 |
| `page_size`   | 每页结果数量    |

## 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
  }
}

```

| 字段                   | 类型   | 描述                                                | 字符数 |
| ----------------------- | ------ | -------------------------------------------------------- | ---------- |
| `account_key`           | string | 在 DDA 中注册的账户的 account_key。                  | 36         |
| `dda_account_status`    | enum   | [账户状态枚举值。](#enumeradores-status) | -          |
| `account_number`        | string | 账户号码。                                         | 20         |
| `account_digit`         | string | 账户验证位。                                         | 1          |
| `owner_document_number` | string | 账户持有人的文件号码。                              | 14         |
| `owner_person_key`      | string | 账户持有人的 person key。                             | 36         |
| `requester_key`         | string | 开户方的 requester key。                     | 36         |
| `created_at`            | string | 在 DDA 中创建和激活的日期。                       | 24         |

### 状态枚举值

| 枚举值  | 描述                           |
| ----------- | ----------------------------------- |
| `active`    | DDA 中的活跃账户。                 |
| `cancelled` | 与 DDA 的关系已终止。 |

---

# 带过滤条件的 DDA 银行票据通知列表

URL: /zh-Hans/documentation/dda/lista_notificacoes_de_boletos

允许列出在 DDA 中注册账户的银行票据，支持按状态和时间范围过滤的方法。

## Request
ENDPOINT /account/ ACCOUNT_KEY /dda/bank_slips
MÉTODO GET

### Path Params

| 字段         | 类型   | 描述                                         | 字符数 |
| ------------- | ------ | ------------------------------------------------- | ---------- |
| `account_key` | string | 在 DDA 中注册的账户标识键 | 36         |

### QUERY PARAMS

| 字段         | 描述                              |
| ------------- | -------------------------------------- |
| `status`      | 银行票据状态                    |
| `start_date`  | 列表开始日期。            |
| `end_date`    | 列表结束日期。               |
| `page_number` | 当前查询的页码 |
| `page_size`   | 每页结果数量    |

## 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

| 字段                     | 类型    | 描述                                                                           | 字符数 |
| ------------------------- | ------- | ----------------------------------------------------------------------------------- | ---------- |
| `barcode`                 | string  | 银行票据条形码。                                                         | 44         |
| `digitable_line`          | string  | 银行票据可输入行。                                                          | 47         |
| `status`                  | enum    | [银行票据状态枚举值。](#enumeradores-status)                        | -          |
| `nominal_amount`          | float   | 银行票据票面金额。                                                            | -          |
| `total_amount`            | float   | 银行票据计算后金额。                                                          | -          |
| `total_payment_amount`    | float   | 银行票据支付金额。                                                       | -          |
| `partial_payment_allowed` | boolean | 是否接受部分付款的指标。                                           | -          |
| `paid_fine`               | float   | 支付银行票据时实际发生的罚款总额，从总金额计算。 | -          |
| `paid_interest`           | float   | 支付银行票据时实际发生的利息总额，从总金额计算。 | -          |
| `discount_amount`         | float   | 支付银行票据时的折扣总额，从总金额计算。       | -          |
| `expiration`              | string  | 银行票据到期日期。                                                       | 10         |
| `max_payment_date`        | string  | 银行票据最终支付日期。                                                 | 10         |
| `payer`                   | object  | [银行票据付款人对象。](#objeto-payer)                                          | -          |
| `beneficiary`             | object  | [银行票据受益人对象。](#objeto-beneficiary)                               | -          |
| `guarantor`               | object  | [银行票据担保人对象。](#objeto-guarantor)                              | -          |
| `rebate_amount`           | float   | 折扣金额。                                                                    | -          |
| `interest`                | list    | [利息对象列表。](#objeto-interest)                                      | -          |
| `fine`                    | list    | [罚款对象列表。](#objeto-fine)                                              | -          |
| `discounts`               | list    | [折扣对象列表。](#objeto-discount)                                      | -          |
| `calculations`            | list    | 银行票据计算组列表。                                                   | -          |
| `calculation_model`       | string  | 银行票据当前金额的计算方法。                                         | 2          |

### 状态枚举值

| 枚举值       | 描述                              |
| ---------------- | -------------------------------------- |
| `registered`     | 已注册的银行票据条形码。 |
| `paid`           | 已支付的银行票据。                           |
| `partially_paid` | 部分支付的银行票据。              |
| `written_off`    | 已注销的银行票据。                        |

### Payer 对象

| 字段             | 类型   | 描述                  | 字符数 |
| ----------------- | ------ | -------------------------- | ---------- |
| `name`            | string | 付款人姓名。           | -          |
| `person_type`     | string | 付款人的人员类型。 | 7          |
| `document_number` | string | 付款人的文件号码。      | 14         |

### Beneficiary 对象

| 字段             | 类型   | 描述                        | 字符数 |
| ----------------- | ------ | -------------------------------- | ---------- |
| `name`            | string | 受益人姓名。            | -          |
| `person_type`     | string | 受益人的人员类型。  | 7          |
| `document_number` | string | 受益人的文件号码。       | 14         |
| `bank_code`       | string | 受益人银行代码。 | 3          |
| `bank_ispb`       | string | 受益人银行的 ISPB。   | 8          |

### guarantor 对象

| 字段             | 类型   | 描述                           | 字符数 |
| ----------------- | ------ | ----------------------------------- | ---------- |
| `name`            | string | 担保人姓名。           | -          |
| `person_type`     | string | 担保人的人员类型。 | 7          |
| `document_number` | string | 担保人的文件号码。      | 14         |

### interest 对象

| 字段                         | 类型   | 描述                | 字符数 |
| ----------------------------- | ------ | ------------------------ | ---------- |
| `interest_billing_start_date` | string | 利息开始日期。 | 10         |
| `interest_amount_type`        | string | 利息类型。           | -          |
| `interest_amount`             | string | 利息金额。          | -          |

### fine 对象

| 字段                     | 类型   | 描述                | 字符数 |
| ------------------------- | ------ | ------------------------ | ---------- |
| `fine_billing_start_date` | string | 罚款开始日期。 | 10         |
| `fine_amount_type`        | string | 罚款类型。           | -          |
| `fine_amount`             | string | 罚款金额。          | -          |

### discount 对象

| 字段                 | 类型   | 描述                | 字符数 |
| --------------------- | ------ | ------------------------ | ---------- |
| `discount_limit_date` | string | 折扣截止日期。 | 10         |
| `discount_type`       | string | 折扣类型。        | -          |
| `discount_amount`     | string | 折扣金额。       | -          |

---

# 获取 DDA 注册的接受和取消条款

URL: /zh-Hans/documentation/dda/recuperacao_termo

DDA（授权直接扣款）的接受条款和取消条款是规范客户授权使用其银行账户直接扣款服务的文件，以及如需取消该授权的程序。

DDA 接受条款是客户正式同意并授权其账单和发票从其银行账户自动扣款的文件。该条款规定了客户和金融机构的权利与责任，以及 DDA 的使用条件。通常包含以下信息：客户和金融机构的身份信息、直接扣款授权、已授权付款的标识、有效期、客户的权利与责任，以及金融机构的权利与责任。

DDA 加入取消条款是允许客户撤销之前授权并申请取消直接扣款服务的文件。该条款通常需要客户签名并通知金融机构以停止自动扣款。重要的是遵循银行规定的取消程序，其中可能包括书面申请、填写特定表格或通过电子方式通知。

两份条款的目的都是为客户的金融交易提供透明度和安全性，为直接扣款服务提供法律基础。接受条款正式确认初始授权并设定服务条款和条件，而取消条款允许客户在不再需要使用该自动付款方式时终止 DDA 加入。

:::info 信息
如果账户在取消后重新激活 DDA，取消条款将不会在后续查询中返回。
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /term/ TYPE
MÉTODO GET

### Path Params

| 字段         | 类型   | 描述                                                  | 字符数 |
| ------------- | ------ | ---------------------------------------------------------- | ---------- |
| `account_key` | string | 在 DDA 中注册的账户标识键          | 36         |
| `type`        | enum   | [条款类型枚举值。](#enumeradores-tipo-de-termo) | -          |

### 条款类型枚举值

| 枚举值     | 描述                      |
| -------------- | ------------------------------ |
| `agreement`    | DDA 签名                 |
| `cancellation` | 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...."
			}
		}
	}
}
```

| 字段                | 类型   | 描述                                  | 字符数 |
| -------------------- | ------ | ------------------------------------------ | ---------- |
| `authorization_term` | object | 付款方签署的授权数据 | -          |

---

# 模拟银行票据注册和修改场景

URL: /zh-Hans/documentation/dda/simulacoes

要生成以账户持有人作为付款方的银行票据注册通知模拟，集成合作伙伴可以使用以下端点：

:::info 信息
要接收测试 Webhook，端点中指定的账户必须是请求方的有效账户且在 DDA 中处于活跃状态。
:::

## 注册银行票据请求

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"
}
```

| 字段                       | 类型    | 描述                                                    | 字符数 |
| --------------------------- | ------- | ------------------------------------------------------------ | ---------- |
| `status` *                  | enum    | [银行票据状态枚举值。](#enumeradores-status) | -          |
| `amount` *                  | float   | 银行票据票面金额。                                     | -          |
| `partial_payment_allowed` * | boolean | 是否接受部分付款的指标。                    | -          |
| `expiration` *              | string  | 银行票据到期日期。                                | 10         |
| `max_payment_date` *        | string  | 银行票据最终支付日期。                          | 10         |
| `beneficiary` *             | object  | [银行票据受益人对象。](#objeto-beneficiary)        | -          |
| `guarantor`                 | object  | [银行票据担保人对象。](#objeto-guarantor)       | -          |
| `rebate_amount`             | float   | 折扣金额。                                             | -          |
| `interest`                  | list    | [利息对象列表。](#objeto-interest)               | -          |
| `fine`                      | list    | [罚款对象列表。](#objeto-fine)                       | -          |
| `discounts`                 | list    | [折扣对象列表。](#objeto-discount)               | -          |
| `calculations`              | list    | 银行票据计算组列表。                            | -          |
| `calculation_model` *       | string  | 银行票据当前金额的计算方法。                  | 2          |

### 状态枚举值

| 枚举值       | 描述                              |
| ---------------- | -------------------------------------- |
| `registered`     | 已注册的银行票据条形码。 |
| `paid`           | 已支付的银行票据。                           |
| `partially_paid` | 部分支付的银行票据。              |
| `written_off`    | 已注销的银行票据。                        |

### Beneficiary 对象

| 字段               | 类型   | 描述                        | 字符数 |
| ------------------- | ------ | -------------------------------- | ---------- |
| `name` *            | string | 受益人姓名。            | -          |
| `person_type` *     | string | 受益人的人员类型。  | 7          |
| `document_number` * | string | 受益人的文件号码。       | 14         |
| `bank_code` *       | string | 受益人银行代码。 | 3          |
| `bank_ispb` *       | string | 受益人银行的 ISPB。   | 8          |

### guarantor 对象

| 字段               | 类型   | 描述                           | 字符数 |
| ------------------- | ------ | ----------------------------------- | ---------- |
| `name` *            | string | 担保人姓名。           | -          |
| `person_type` *     | string | 担保人的人员类型。 | 7          |
| `document_number` * | string | 担保人的文件号码。      | 14         |

### interest 对象

| 字段                           | 类型   | 描述                | 字符数 |
| ------------------------------- | ------ | ------------------------ | ---------- |
| `interest_billing_start_date` * | string | 利息开始日期。 | 10         |
| `interest_amount_type` *        | string | 利息类型。           | -          |
| `interest_amount` *             | string | 利息金额。          | -          |

### fine 对象

| 字段                       | 类型   | 描述                | 字符数 |
| --------------------------- | ------ | ------------------------ | ---------- |
| `fine_billing_start_date` * | string | 罚款开始日期。 | 10         |
| `fine_amount_type` *        | string | 罚款类型。           | -          |
| `fine_amount` *             | string | 罚款金额。          | -          |

### discount 对象

| 字段                   | 类型   | 描述                | 字符数 |
| ----------------------- | ------ | ------------------------ | ---------- |
| `discount_limit_date` * | string | 折扣截止日期。 | 10         |
| `discount_type` *       | string | 折扣类型。        | -          |
| `discount_amount` *     | string | 折扣金额。       | -          |

## Response

STATUS 200

```json
{}
```

## 修改银行票据请求

只有银行票据的某些字段可以修改，如下面的请求所示。受益人、付款人和部分付款接受等字段不接受修改。

:::info 信息
对象列表字段在不希望修改时不应传递。如果传递空列表或列表中传递任何其他值，所有对象都将被替换。
:::

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"
}
```

| 字段               | 类型   | 描述                                                    | 字符数 |
| ------------------- | ------ | ------------------------------------------------------------ | ---------- |
| `status` *          | enum   | [银行票据状态枚举值。](#enumeradores-status) | -          |
| `amount`            | float  | 银行票据票面金额。                                     | -          |
| `expiration`        | string | 银行票据到期日期。                                | 10         |
| `max_payment_date`  | string | 银行票据最终支付日期。                          | 10         |
| `guarantor`         | object | [银行票据担保人对象。](#objeto-guarantor)      | -          |
| `rebate_amount`     | float  | 折扣金额。                                             | -          |
| `interest`          | list   | [利息对象列表。](#objeto-interest)              | -          |
| `fine`              | list   | [罚款对象列表。](#objeto-fine)                      | -          |
| `discounts`         | list   | [折扣对象列表。](#objeto-discount)              | -          |
| `calculations`      | list   | 银行票据计算组列表。                            | -          |
| `calculation_model` | string | 银行票据当前金额的计算方法。                  | 2          |

## Response

STATUS 200

```json
{}
```

## 因支付注销银行票据请求

ENDPOINT /mock/account/ ACCOUNT-KEY /dda/bank_slip/ BARECODE
MÉTODO PATCH

Request Body

```json
{
  "status": "paid",
  "paid_amount": 1200,
}
```

| 字段           | 类型  | 描述                                                    | 字符数 |
| --------------- | ----- | ------------------------------------------------------------ | ---------- |
| `status` *      | enum  | [银行票据状态枚举值。](#enumeradores-status) | -          |
| `paid_amount` * | float | 银行票据已支付金额。                                        | -          |

## Response

STATUS 200

```json
{}
```

## 因取消注销银行票据请求

ENDPOINT /mock/account/ ACCOUNT-KEY /dda/bank_slip/ BARECODE
MÉTODO PATCH

Request Body

```json
{
  "status": "written_off",
}
```

| 字段      | 类型 | 描述                                                    | 字符数 |
| ---------- | ---- | ------------------------------------------------------------ | ---------- |
| `status` * | enum | [银行票据状态枚举值。](#enumeradores-status) | -          |

## Response

STATUS 200

```json
{}
```

---

# Webhook 格式

URL: /zh-Hans/documentation/dda/webhooks

:::danger 注意！
QI Tech 的 Webhook 不应以严格方式映射。
我们 API 返回的 Webhook payload 中可能会添加额外字段。
:::

:::info 重新发送 Webhook
您可以按照文档中的详细说明查询和重新发送 Webhook：[重新发送 Webhook](/documentation/notificacoes/reenvio_de_notificacoes)。
:::

DDA 中有两种类型的事件，通过 Webhook 中的 webhook_type 属性加以区分。

## 银行票据捕获 Webhook

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

| 字段                     | 类型    | 描述                                                    | 字符数 |
| ------------------------- | ------- | ------------------------------------------------------------ | ---------- |
| `barcode`                 | string  | 银行票据条形码。                                                         | 44         |
| `digitable_line`          | string  | 银行票据可输入行。                                                          | 47         |
| `status`                  | enum    | [银行票据状态枚举值。](#enumeradores-status) | -          |
| `nominal_amount`          | float   | 银行票据票面金额。                                                            | -          |
| `total_amount`            | float   | 银行票据计算后金额。                                                          | -          |
| `total_payment_amount`    | float   | 银行票据支付金额。                                                | -          |
| `partial_payment_allowed` | boolean | 是否接受部分付款的指标。                                           | -          |
| `expiration`              | string  | 银行票据到期日期。                                                       | 10         |
| `max_payment_date`        | string  | 银行票据最终支付日期。                                                 | 10         |
| `payer`                   | object  | [银行票据付款人对象。](#objeto-payer)                                          | -          |
| `beneficiary`             | object  | [银行票据受益人对象。](#objeto-beneficiary)                               | -          |
| `guarantor`               | object  | [银行票据担保人对象。](#objeto-guarantor)                              | -          |
| `rebate_amount`           | float   | 折扣金额。                                                                    | -          |
| `interest`                | list    | [利息对象列表。](#objeto-interest)                                      | -          |
| `fine`                    | list    | [罚款对象列表。](#objeto-fine)                                              | -          |
| `discounts`               | list    | [折扣对象列表。](#objeto-discount)                                      | -          |
| `calculations`            | list    | 银行票据计算组列表。                                                   | -          |
| `calculation_model`       | string  | 银行票据当前金额的计算方法。                                         | 2          |

### 状态枚举值

| 枚举值       | 描述                              |
| ---------------- | -------------------------------------- |
| `registered`     | 已注册的银行票据条形码。 |
| `paid`           | 已支付的银行票据。                           |
| `partially_paid` | 部分支付的银行票据。              |
| `written_off`    | 已注销的银行票据。                        |

### Payer 对象

| 字段             | 类型   | 描述                  | 字符数 |
| ----------------- | ------ | -------------------------- | ---------- |
| `name`            | string | 付款人姓名。           | -          |
| `person_type`     | string | 付款人的人员类型。 | 7          |
| `document_number` | string | 付款人的文件号码。      | 14         |

### Beneficiary 对象

| 字段             | 类型   | 描述                        | 字符数 |
| ----------------- | ------ | -------------------------------- | ---------- |
| `name`            | string | 受益人姓名。            | -          |
| `person_type`     | string | 受益人的人员类型。  | 7          |
| `document_number` | string | 受益人的文件号码。       | 14         |
| `bank_code`       | string | 受益人银行代码。 | 3          |
| `bank_ispb`       | string | 受益人银行的 ISPB。   | 8          |

### guarantor 对象

| 字段             | 类型   | 描述                           | 字符数 |
| ----------------- | ------ | ----------------------------------- | ---------- |
| `name`            | string | 担保人姓名。           | -          |
| `person_type`     | string | 担保人的人员类型。 | 7          |
| `document_number` | string | 担保人的文件号码。      | 14         |

### interest 对象

| 字段                         | 类型   | 描述                | 字符数 |
| ----------------------------- | ------ | ------------------------ | ---------- |
| `interest_billing_start_date` | string | 利息开始日期。 | 10         |
| `interest_amount_type`        | string | 利息类型。           | -          |
| `interest_amount`             | string | 利息金额。          | -          |

### fine 对象

| 字段                     | 类型   | 描述                | 字符数 |
| ------------------------- | ------ | ------------------------ | ---------- |
| `fine_billing_start_date` | string | 罚款开始日期。 | 10         |
| `fine_amount_type`        | string | 罚款类型。           | -          |
| `fine_amount`             | string | 罚款金额。          | -          |

### discount 对象

| 字段                 | 类型   | 描述                | 字符数 |
| --------------------- | ------ | ------------------------ | ---------- |
| `discount_limit_date` | string | 折扣截止日期。 | 10         |
| `discount_type`       | string | 折扣类型。        | -          |
| `discount_amount`     | string | 折扣金额。       | -          |

## 银行票据修改 Webhook

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

| 字段                     | 类型    | 描述                                                                           | 字符数 |
| ------------------------- | ------- | ----------------------------------------------------------------------------------- | ---------- |
| `barcode`                 | string  | 银行票据条形码。                                                         | 44         |
| `digitable_line`          | string  | 银行票据可输入行。                                                          | 47         |
| `status`                  | enum    | [银行票据状态枚举值。](#enumeradores-status)                        | -          |
| `nominal_amount`          | float   | 银行票据票面金额。                                                            | -          |
| `total_amount`            | float   | 银行票据计算后金额。                                                          | -          |
| `total_payment_amount`    | float   | 银行票据支付金额。                                                       | -          |
| `partial_payment_allowed` | boolean | 是否接受部分付款的指标。                                           | -          |
| `paid_fine`               | float   | 支付银行票据时实际发生的罚款总额，从总金额计算。 | -          |
| `paid_interest`           | float   | 支付银行票据时实际发生的利息总额，从总金额计算。 | -          |
| `discount_amount`         | float   | 支付银行票据时的折扣总额，从总金额计算。       | -          |
| `expiration`              | string  | 银行票据到期日期。                                                       | 10         |
| `max_payment_date`        | string  | 银行票据最终支付日期。                                                 | 10         |
| `payer`                   | object  | [银行票据付款人对象。](#objeto-payer)                                          | -          |
| `beneficiary`             | object  | [银行票据受益人对象。](#objeto-beneficiary)                               | -          |
| `guarantor`               | object  | [银行票据担保人对象。](#objeto-guarantor)                              | -          |
| `rebate_amount`           | float   | 折扣金额。                                                                    | -          |
| `interest`                | list    | [利息对象列表。](#objeto-interest)                                      | -          |
| `fine`                    | list    | [罚款对象列表。](#objeto-fine)                                              | -          |
| `discounts`               | list    | [折扣对象列表。](#objeto-discount)                                      | -          |
| `calculations`            | list    | 银行票据计算组列表。                                                   | -          |
| `calculation_model`       | string  | 银行票据当前金额的计算方法。                                         | 2          |

---

# acg1

URL: /zh-Hans/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

| 字段 | 类型 | 描述 |
|---|---| ---|
| `person_type`  | enum | 被查询人员的类型。 |
| `name`  | string | 被查询方的姓名。 |
| `document_number`  | string | 被查询方的 CPF 或 CNPJ。 |
| `signatures`  | array of objects | 包含签署方对象的列表。 |

## 枚举值

### marital_status 枚举值

| 枚举值 | 翻译 | 
|---|---|
|  natural  |  自然人 |
|  legal  |  法人 |

## Response

状态: 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"
}

```

状态: 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"
}

```

状态: 400

**body.json**

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

```

## Webhooks

提交查询申请后，其余流程由 QI Tech 负责。届时将发送一个 Webhook，呈现两种不同的模型：

- 如果查询成功找到，将收到 **"status"** 字段值为 **"completed"** 的 Webhook，此时 **"data"** 对象将包含查询的其余信息。

- 如果在被查询期间未在数据库中找到相关文件，将收到 **"status"** 字段值为 **"not_found"** 的 Webhook，表示查询未返回任何信息。

## 成功示例

Webhook 中的 **"data"** 对象包含以下字段：

**"valueless_months"**：无活动的月份数量。  
**"card_schemes"**：构成已清算总额的支付安排。  
**"value"**：卡片清算的总金额。

```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"
}
```

## 查询未找到的情况

```json
{
   "status": "not_found",
   "webhook_type": "historic_card_settlement",
   "event_datetime": "2022-05-18T20:57:00",
   "key": "38934f1b-204f-4fc4-844d-5ad562ff36f6"
}
```

---

# introducao

URL: /zh-Hans/documentation/documentacoes ocultas/agc1/introducao

卡片结算历史记录是一个新的查询系统，它提供特定客户在特定时间段内已清算的卡片应收账款支付信息。

这些数据由中央银行通过一个名为 ACG1 的系统提供给金融机构。要访问这些数据，QI Tech 需要被查询方的授权。一旦签名完成，您将收到与查询日期前12个月相关的所有信息。

包括：

- 该期间已清算支付的总聚合金额。

- 构成该总额的支付安排类型。

- 无任何支付记录的月份数量；

:::danger 注意！

与其他 API 一样，服务开通需与我们的团队协商，且调用需要认证。
:::

## 查询流程

要执行卡片结算历史记录查询，QI Tech 需要向中央银行发送一份文件，以正式提出查询申请。该文件在我们的内部流程中根据发送到端点 16.1 的载荷生成。

查询流程包括：

- 通过请求提交查询申请；
- 接收包含查询结果的 Webhook；

---

# 权限（通用）：

URL: /zh-Hans/documentation/documentacoes ocultas/perfis_de_acesso

#### 观察者

无法在平台上执行任何操作，只能查看可用数据。

- 导出报告；
- 下载凭证；
- 导出对账单。

#### 操作员

拥有"观察者"的所有权限，并额外具备以下权限：

- 注册操作；
- 登记票据（boleto）；
- 下达票据指令；
- 提交 escrow 账户开设申请；
- 提交 TED、PIX 和票据支付申请；
- 申请 SCR 查询；

#### 管理员

拥有操作员的所有权限，并额外具备以下权限：

- 审批支付（TED、PIX 和票据）；
- 管理门户访问权限和添加集成密钥；
- 注册 Webhook。

---

# cancelamento_de_solicitacao.md

URL: /zh-Hans/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

| 字段 | 类型 | 描述 |
|---|---| ---|
| `key`  | enum | 申请密钥（SCR_KEY）。 |
| `requester_person_key`  | string | 申请方密钥。 |

## Response

状态: 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"
}

```

状态: 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: /zh-Hans/documentation/documentacoes ocultas/scr/consultar_solicitacao

## Request

为了简化流程，如果客户希望对之前已查询过的人员使用新的基准日期重新查询，我们提供 /scr/redo 操作。使用此操作的优势在于：如果该人员的授权文件仍然有效，则无需创建新的签名文件¹，查询将立即创建。本请求的 header 和 body 签名格式在此处详细描述。

- ENDPOINT /scr/ SCR_KEY
- MÉTODO GET

### Path Params

| 字段 | 类型 | 描述 |
|---|---| ---|
| `scr_key`  | string | SCR 查询申请的密钥。 |

## Response

状态: 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"
}

```

状态: 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: /zh-Hans/documentation/documentacoes ocultas/scr/consultar_solicitacoes

## Request

为了简化流程，如果客户希望对之前已查询过的人员使用新的基准日期重新查询，我们提供 /scr/redo 操作。使用此操作的优势在于：如果该人员的授权文件仍然有效，则无需创建新的签名文件¹，查询将立即创建。本请求的 header 和 body 签名格式在此处详细描述。

- ENDPOINT /scr
- MÉTODO GET

## QUERY PARAMS

| 字段 | 类型 | 描述 |
|---|---| ---|
| `origin_key`  | string | 操作标识密钥。返回与该操作相关的所有查询。 |
| `subject_person_type`  | enum | 被查询人员类型过滤器。 |
| `subject_document_number`  | string | CPF 或 CNPJ 过滤器，不接受部分匹配。 |
| `created_at_start_date`  | string | 创建日期范围起始过滤器（格式：YYYY-MM-DD）。 |
| `created_at_end_date`  | string | 创建日期范围结束过滤器（格式：YYYY-MM-DD）。 |
| `consulted_at_start_date`  | string | 查询日期范围起始过滤器（格式：YYYY-MM-DD）。 |
| `consulted_at_end_date`  | datetime | 查询日期范围结束过滤器（格式：YYYY-MM-DD）。 |
| `scr_status`  | enum | 查询状态过滤器。 |
| `page`  | integer | 当前查询的页码。 |
| `page_size`  | integer | 每页结果数量。 |

## 枚举值

### person_type 枚举值

| 枚举值 | 翻译 | 
|---|---|
|  natural  |  自然人 |
|  legal  |  法人 |

### scr_status 枚举值

| 枚举值 | 翻译 | 
|---|---|
|  created  |  已创建 |
|  pending_signature  |  待签名 |
|  signed  |  已签名 |
|  rejected  |  已拒绝 |
|  consulted  |  已查询 |
|  error  |  出错 |
|  canceled  |  已取消 |

## Response

状态: 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
    }
}

```

状态: 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: /zh-Hans/documentation/documentacoes ocultas/scr/introducao

我们集成中可提供的功能之一是通过 API 查询自然人或法人的 SCR（信用信息系统）数据。只需通过请求发送一次查询申请，QI Tech 将负责向被查询方发送授权请求，在授权后执行查询，并通过 Webhook 将结果发送给申请方。

此外，对于 PJ（法人）查询，可以在单次申请中查询公司及其代表人，为每个证件编号生成独立查询。

与其他 API 一样，服务开通需与我们的团队协商，且调用需要认证。

以下子章节将介绍如何执行 SCR 查询。

## SCR 查询流程

SCR 查询流程包括：

- 提交查询申请（通过请求发起）
- 被查询方或其代表签署查询授权（通过邮件发送）
- 执行查询（通过 Webhook 通知结果）

---

# refazer_consulta

URL: /zh-Hans/documentation/documentacoes ocultas/scr/refazer_consulta

## Request

为了简化流程，如果客户希望对之前已查询过的人员使用新的基准日期重新查询，我们提供 /scr/redo 操作。使用此操作的优势在于：如果该人员的授权文件仍然有效，则无需创建新的签名文件¹，查询将立即创建。本请求的 header 和 body 签名格式在此处详细描述。

- 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

| 字段 | 类型 | 描述 |
|---|---| ---|
| `report_start_date`  | enum | 查询开始日期（格式"YYYY-MM"）。 |
| `report_end_date`  | string | 查询结束日期（格式"YYYY-MM"）。 |
| `origin_key`  | string | 将用于重新查询的原始 SCR 密钥（SRC_KEY）。 |

## Response

状态: 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"
}

```

状态: 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: /zh-Hans/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

| 字段 | 类型 | 描述 |
|---|---| ---|
| `person_type`  | enum | 被查询人员的类型。 |
| `name`  | string | 被查询方的姓名。 |
| `document_number`  | string | 被查询方的 CPF 或 CNPJ。 |
| `check_representatives`  | boolean | 决定是否查询公司代表人的字段（布尔值"true"或"false"，若省略则视为 false）。 |
| `report_start_date`  | string | 查询开始日期（格式"YYYY-MM"）。QI Tech 可查询的最早日期为 2019-02。 |
| `report_end_date`  | string | 查询结束日期（格式"YYYY-MM"）。 |
| `signatures`  | array of objects | 包含签署方对象的列表。 |

## 枚举值

### person_type 枚举值

| 枚举值 | 翻译 | 
|---|---|
|  natural  |  自然人 |
|  legal  |  法人 |

## Response

状态: 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
}

```

状态: 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"
}

```

状态: 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: /zh-Hans/documentation/documentacoes ocultas/scr/webhook

成功提交 SCR 查询申请后，其余流程由 QI Tech 负责。操作结果通过 Webhook 跟踪，遵循预先设定的流程。标准为：成功时发送包含查询数据的 Webhook；失败时发送通知申请被拒绝的 Webhook。此外，客户在签约时可以选择查询数据仅以 PDF 格式交付，还是以完整格式交付——完整格式除了 PDF 外，还以 JSON 格式返回所有查询数据。此时客户还会收到单个 SCR 查询的密钥 **SCR_KEY**。

## 成功示例

仅 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,
}
```

完整查询：

```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
}
```

含代表人的查询：

```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
}
```

## 失败示例

```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,
}
```

---

# 更新信贷合同受让方

URL: /zh-Hans/documentation/emissao_de_divida/atualizar_cessionario_047911bb-d3fb-48fe-88fd-aebdeb7e11ad

    ### 重要说明：

    更新受让方时，需满足以下要求：
    - 信贷操作不得已取消；
    - 信贷操作不得正处于转让流程中；
    - 信贷操作不得已被转让；
    - 必须存在与新买方的转让配置。

## 请求

ENDPOINT /debt/ DEBT-KEY /purchaser
MÉTODO PATCH

**请求体**

```json
{
  "purchaser_document_number": "01234567890001"
}
```

### 路径参数

| 字段 | 类型 | 描述 |
|---|---|---|
| `debt_key` * | string | 操作的 debt_key。 |

## 响应

STATUS 201

**响应体**

```json
{}
```

STATUS 400

**响应体**

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Credit Operation is already in assignment process for changing the purchaser.\", \"translation\": \"A operação de crédito está em processo de cessão e não pode ter seu comprador alterado.\", \"extra_fields\": {}, \"code\": \"COP000376\"}"
}
```

---

# 更新信贷合同关联方信息

URL: /zh-Hans/documentation/emissao_de_divida/atualizar_dados_da_parte_relacionada

## 请求

ENDPOINT /debt/ DEBT-KEY /related_party/ RELATED-PARTY-KEY
MÉTODO PATCH

### 个人
**请求体**

```json
{
  "name": "Teste teste",
  "email": "teste@teste.com",
  "address": {
    "street": "Rua teste",
    "neighborhood": "Bairro teste",
    "number": "123",
    "postal_code": "09725540",
    "city": "São Caetano do sul",
    "state": "SP"
  },
  "phone": {
    "country_code": "55",
    "area_code": "11",
    "number": "41234123"
  },
  "mother_name": "Mãe 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"
}
```

### 法人
**请求体**

```json
{
	"name": "Teste teste",
	"email": "teste@teste.com",
	"address": {
		"street": "Rua teste",
		"neighborhood": "Bairro teste",
		"number": "123",
		"postal_code": "09725540",
		"city": "São 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
}
```

### 路径参数

| 字段 | 类型 | 描述 |
|---|---|---|
| `debt_key` * | string | 操作的 debt_key。 |
| `related_party_key` * | string | 需要发送文件的关联方的密钥。 |

## 响应

STATUS 201

**响应体**

```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

**响应体**

```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ão permite atualizar a parte relacionada.\", \"extra_fields\": {}, \"code\": \"COP000328\"}"
}
```

---

# 授权放款

URL: /zh-Hans/documentation/emissao_de_divida/autorizar_desembolso

## 请求

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

**请求体**

```json
{
   "allow_disbursement": true
}

```

### 路径参数

| 字段 | 类型 | 描述 |
|---|---| ---|
| `debt_key` *（必填）* | string | 已发行债务的 ID。 |

### 请求体参数

| 字段 | 类型 | 描述 |
|---|---| ---|
| `allow_disbursement` | string | 放款授权指示。 |

## 响应

STATUS 201

**响应体**

```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,
  "is_allowed_to_disburse": true,
  "credit_operation_status": {
    "translation_path": "co.CreditOperationStatus.waiting_disbursement",
    "translation_ptbr": "Aguardando Desembolso",
    "enumerator": "waiting_disbursement"
  }
}

```

STATUS 400

**响应体**

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

---

# 放款前取消债务

URL: /zh-Hans/documentation/emissao_de_divida/cancelamento/cancelar_divida_antes_de_desembolsar

## 请求

ENDPOINT /debt/ DEBT-KEY /cancel
MÉTODO PATCH

## 响应

STATUS 200

响应体

```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

响应体

```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"
}
```

### 路径参数

| 字段 | 类型 | 描述 |
|---|---| ---|
| `debt_key` * | string | 创建信贷操作时返回的债务密钥。 |

---

# 永久取消

URL: /zh-Hans/documentation/emissao_de_divida/cancelamento/cancelar_permanentemente

## 请求

ENDPOINT /debt/ debt_key /cancel_permanently
MÉTODO POST

## 响应

STATUS 200

响应体

```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": [],
      "urls": []
    },
    "contract_fee_amount": 50000,
    "contract_fees": [
      {
        "fee_amount": 50000,
        "fee_type": "tac"
      }
    ],
    "external_contract_fee_amount": 0,
    "external_contract_fees": [],
    "installments": [],
    "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

响应体

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

```

---

# 放款后七天内取消债务

URL: /zh-Hans/documentation/emissao_de_divida/cancelamento/desistencia/cancelamento_de_divida_em_ate_sete_dias_apos_o_desembolso

## 请求

ENDPOINT /debt/reversal
MÉTODO POST

请求体

```json
{
    "contract_number": "0000049343/TW"
}

```

## 响应

STATUS 200

响应体

```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

响应体

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

```

## 字段定义
| 字段 | 类型 | 描述 | 最大字符数 |
|-------------------|--------|--------------------------------|--------------|
| `contract_number` * | string | 信贷合同编号。 | |

---

# 查询退款 pix qr code

URL: /zh-Hans/documentation/emissao_de_divida/cancelamento/desistencia/consulta_de_pix_qr_code_de_devolucao

返回为处于取消流程中的信贷业务先前生成的退款 pix qr code。请在 `/debt/reversal` 创建退款后使用此接口,重新获取 qr code 数据(例如,用于再次向付款人展示)。

## 请求

ENDPOINT /credit_operation/{credit_operation_key}/pix_qrcode
MÉTODO GET

:::info
此请求没有请求体。必须将 `credit_operation_key` 作为 URL 中的路径参数传入。
:::

## 响应

STATUS 200

响应体

```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

响应体 — 未找到信贷业务

```json
{
  "data": "{\"title\": \"Not Found\", \"description\": \"Credit Operation not found\", \"translation\": \"Operação não encontrada\", \"extra_fields\": {}, \"code\": \"COP000027\"}"
}
```

响应体 — 未找到退款

```json
{
  "data": "{\"title\": \"Not Found\", \"description\": \"Reversal not found.\", \"translation\": \"Estorno não encontrado.\", \"extra_fields\": {}, \"code\": \"COP000205\"}"
}
```

## 字段定义

### 路径参数

| 字段 | 类型 | 描述 |
|------|------|------|
| `credit_operation_key` * | string (uuid) | 为其生成退款 pix qr code 的信贷业务的唯一标识。 |

### 响应字段

| 字段 | 类型 | 描述 |
|------|------|------|
| `amount` | string | 退款 pix qr code 的金额(单位:雷亚尔)。 |
| `copy_paste_pix` | string | 用于支付的 pix 复制粘贴码。 |
| `debt_key` | string (uuid) | 与退款关联的信贷业务(债务)标识。 |
| `expiration_date` | string (date) | pix qr code 的过期日期,格式为 `YYYY-MM-DD`。 |
| `payer_document_number` | string | 付款人的 CPF/CNPJ。 |
| `payer_name` | string | 付款人姓名。 |
| `qr_code_key` | string (uuid) | 已发行 pix qr code 的唯一标识。 |
| `reversal_key` | string (uuid) | 与该 pix qr code 关联的退款的唯一标识。 |
| `status` | string | pix qr code 的当前状态(例如 `waiting_payment`)。 |

---

# 简介

URL: /zh-Hans/documentation/emissao_de_divida/cancelamento/desistencia/introducao

鉴于《消费者保护法典》允许通过数字方式获取信贷的借款人在 7 天内取消债务，QI Tech 开发了专门的功能来满足这些情况。

## 运作方式

在 QI Tech 系统中，有两种方式可在 7 天内取消债务：

### 1 - 通过退还放款收到的金额

如果在放款日期后 7 天内识别到对操作已放款总金额的退还，无论是通过 PIX 冲销还是向放款源账户的新转账，系统将自动取消操作，原因为：'disbursed_amount_refunded'。

### 2 - 通过取消 API

通过端点 [POST /debt/reversal](cancelamento_de_divida_em_ate_sete_dias_apos_o_desembolso) ，可以生成 QR Code，一旦借款人付款，操作即被取消。

在两种情况下，一旦资金到达 QI Tech，操作即被取消，如果合同转让已经发生，则金额将冲销给受让方。

此端点可在放款后 7 天内使用，QR Code 的有效期设定为生成后 14 天——此期限后将无法再取消合同。

## 要求

为使此端点正常运行，需要联系 QI Tech 支持团队以解锁端点并配置受让方账户以冲销资金。

---

# 简介

URL: /zh-Hans/documentation/emissao_de_divida/cancelamento/introducao

通过 QI Tech 系统可执行两种类型的债务取消。

## 放款前取消债务

QI Tech 提供的放款前信贷操作取消服务，仅需向我们的 API 发出一个请求即可。

## 放款后七天内取消债务

QI Tech 提供的放款后七天内信贷操作取消服务，仅需向我们的 API 发出一个请求即可。

提交请求后，将返回 PIX QR Code。支付后，操作将被取消，所有冲销将自动执行。

## Webhook

付款确认后，我们的服务会执行所有冲销，并向客户发送 webhook，示例如下：

```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 **七天后取消操作时需注意的主要事项：**

- 冲销申请必须在放款日期后的 8 个工作日内提出。

- 通过 QR Code 付款必须在放款日期后的 15 个工作日内完成。

- 信贷操作的当前状态不能是"未结"以外的状态。

- 不得有任何分期已付款。

- 当所有冲销成功执行后，系统每天运行一次例程，收集适当金额并发送给基金。

:::

---

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

URL: /zh-Hans/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> |

---

# 配置放款日期

URL: /zh-Hans/documentation/emissao_de_divida/configurar_data_de_desembolso

## 请求

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 **注意！**

 如果选择以多日期方式发行债务，则在合同签署后，必须通过此端点设置放款日期。

:::

### 路径参数

| 字段 | 类型 | 描述 |
|---|---| ---|
| `debt_key` * | string | 创建信贷操作时返回的债务密钥。 |

### 请求体参数

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `disbursement_date` * | date | 操作的放款日期。 | 10 | 
| `disbursement_bank_account` | object | **[放款银行账户对象](#objeto-disbursement_bank_accounts)** - 操作放款的银行账户信息。 | | 

### 放款银行账户对象

放款银行信息可与放款日期一起更改，默认情况下，放款将转入债务人名下的账户。

| 字段 | 类型 | 描述 | 最大字符数 | 
|-----------------------|--------|----------------------------------------------------------------------------------------------------|--------------|
| name | string | 账户持有人姓名 | 50 |
| document_number | string | 账户持有人 CPF | 11 |
| bank_code * | string | 金融机构的 COMPE 代码（https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf） | 3 |
| branch_number * | string | 支行号码（请勿填写支行验证位！） | 4 |
| account_number * | string | 账号（不含验证位！） | 10 |
| account_digit * | string | 账户验证位（字母处填写零） | 1 |
| account_type | enum | [账户类型枚举值](#enumerador-account-type) 账户类型 | 1 |

## 响应

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\"}"
}
```

---

# 债务查询

URL: /zh-Hans/documentation/emissao_de_divida/consulta_de_divida

## 请求

ENDPOINT /debt
MÉTODO GET

## 查询参数
| 字段 | 类型 | 描述 | 字符数 |
|---|---|-------------------------------------------------------------------------| ---|
| `key` | string | 创建信贷操作时返回的债务密钥。 | - |
| `requester_identifier_key` | string | 创建债务时发送的 UUID4 密钥。 | - |
| `contract_number` | string | 债务发行时返回的 CCB 编号。 | - |
| `issuer_document_number` | string | 发行人的证件号码。 | - |
| `issuer_name` | string | 债务发行人姓名。 | - |
| `page_size` | string | 每页显示的结果数量。 | - |
| `status` | string | 操作状态。 | - |
| `page` | string | 当前查询的页码。 | - |
| `total_due_balance` | boolean | 当设置为 `true` 时，响应中将包含 `balance_due` 字段（操作的未偿总余额）。默认情况下（`false` 或不传），**不**返回 `balance_due`。 | - |

:::tip 未偿余额（`balance_due`）
`balance_due` 字段表示操作的未偿总余额，**仅当查询时携带 `total_due_balance=true` 参数才会返回**。否则响应不包含未偿余额。

请求示例：

```bash
GET /debt?contract_number=ABC1234&total_due_balance=true
```
:::

## 响应

STATUS 200

响应体：无参数查询

```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
  }
}

```

响应体：带参数查询

```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": [],
        "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
      }
    ],
    "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": [],
        "birth_date": "1997-10-19",
        "email": "wxr@ff.com",
        "income": 0.01,
        "individual_document_number": "92147661180",
        "is_pep": false,
        "marital_status": {
          "enumerator": "single",
          "translation_path": "co.MaritalStatus.single"
        },
        "name": "Wxy  Wsx",
        "nationality": "nationality",
        "person_type": "natural",
        "related_party_key": "203b2ada-ff3e-44a6-a843-f244aa1afbc9",
        "role_type": {
          "enumerator": "issuer",
          "translation_path": "co.RoleType.issuer"
        }
      }
    ],
    "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

响应体

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

```

## 查询参数
| 字段 | 类型 | 描述 | 字符数 |
|---|---|-------------------------------------------------------------------------| ---|
| `key` | string | 创建信贷操作时返回的债务密钥。 | - |
| `requester_identifier_key` | string | 创建债务时发送的 UUID4 密钥。 | - |
| `contract_number` | string | 债务发行时返回的 CCB 编号。 | - |
| `issuer_document_number` | string | 发行人的证件号码。 | - |
| `issuer_name` | string | 债务发行人姓名。 | - |
| `page_size` | string | 每页显示的结果数量。 | - |
| `status` | string | 操作状态。 | - |
| `page` | string | 当前查询的页码。 | - |
| `total_due_balance` | boolean | 当设置为 `true` 时，响应中将包含 `balance_due` 字段（操作的未偿总余额）。默认情况下，**不**返回 `balance_due`。 | - |

---

# 按合同编号查询债务

URL: /zh-Hans/documentation/emissao_de_divida/consulta_por_contract_number

## 请求

ENDPOINT /v2/credit_operation/contract_number/ CONTRACT-NUMBER
MÉTODO GET

## ⚠️ 重要说明

如果合同编号中包含斜杠（`/`），需要将斜杠**编码**为 `%2F`。

### 实际示例
**原始输入：**
```
contract_number = 02159312/FGP
```

**应发送为：**
```
02159312%2FFGP
```

### Python 编码示例：
```python
import urllib.parse

contract_number = "02159312/FGP"
encoded_contract_number = urllib.parse.quote(contract_number)
print(encoded_contract_number)  # 02159312%2FFGP
```

:::

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|   
| `contract_number` * | string | 信贷合同编号。 | string |

## 响应

STATUS 200

响应体

```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
    }
  ],
  "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": []
}
```

STATUS 400

响应体

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

---

# 按信贷操作密钥查询债务

URL: /zh-Hans/documentation/emissao_de_divida/consulta_por_credit_operation_key

## 请求

ENDPOINT /v2/credit_operation/ CREDIT-OPERATION-KEY
MÉTODO GET

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|   
| `credit_operation_key` * | string | 信贷操作的密钥。 | UUID |

## 响应

STATUS 200

响应体

```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": [],
  "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": []
}
```

STATUS 400

响应体

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

---

# 按请求标识符密钥查询债务

URL: /zh-Hans/documentation/emissao_de_divida/consulta_por_requester_identifier_key

## 请求

ENDPOINT /v2/credit_operation/requester_identifier_key/ REQUESTER-IDENTIFIER-KEY
MÉTODO GET

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|   
| `requester_identifier_key` * | string | 创建债务时发送的 UUID4 密钥。 | UUID |

## 响应

STATUS 200

响应体

```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": [],
  "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": []
}
```

STATUS 400

响应体

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

---

# 操作放款

URL: /zh-Hans/documentation/emissao_de_divida/desembolso_da_operacao

操作放款是指释放信贷合同资金，在 QI Tech 中，放款方式遵循信贷产品的配置，如放款配置中所详述。

:::info 信息
默认情况下，操作通过 PIX 向操作中提供的账户放款，但可选择以下五种方式：

**1- 带账户信息的 PIX**；

**2- 带密钥的 PIX**；

**3- TED**；

**4- PIX QR Code**；

**5- Boleto**；

这些方式具有特定字段，在合同发行的"disbursement_bank_accounts"键中有详细说明。
:::

QI Tech 的放款例程每分钟运行一次，检查是否满足针对该特定合同所配置产品的所有要求，并更改其状态。

## 放款要求

- **放款日期**

信贷操作合同仅在设定为"disbursement_date"的日期放款。

- **信贷合同已发行并签署**

操作的信贷合同必须已发行并签署。

- **担保已设立**

对于需要担保的操作，必须先设立担保才能继续放款。

- **放款审批**

如果"放款审批"配置处于激活状态，则合同只有在 API 审批调用之后才会放款。

- **有首付款的操作需已付款**

如果所创建的操作包含首付款参数，则只有在 QI Tech 系统中完成付款和财务清算后才能放款。

- **限额对齐**

必须有可用的信用额度，操作才能被放款。

---

# 个人债务发行

URL: /zh-Hans/documentation/emissao_de_divida/emissao/emissao_de_divida_pf

使用债务发行 API，可以为自然人申请发行债务。无需提前注册借款人，只需在申请时提供注册数据即可。

:::danger 注意！

QI Tech 提供新客户入驻和反欺诈解决方案。

如需报价，请联系我们的商务团队：

comercial@qitech.com.br 或 (11) 3522-1301
:::

债务 API 设计为只需执行一次请求即可完成，需在提前上传文件（[文档上传](../../upload_de_documentos)）之后执行。
请求头和请求体的签名格式详情请参见[此处](../../primeiros_passos/teste_de_autenticacao)。

## 请求

ENDPOINT /debt
MÉTODO POST

请求体

```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 注意
`credit_agent` 对象代表信贷代理（有时称为"pastinha"），负责该债务的来源开发。对于代扣工资贷款的发行，该字段为必填项。
:::

## 响应

此次债务请求的响应将返回还款计划以及 **DEBT-KEY**，即债务在 QI SCD 中的标识符。

STATUS 200

响应体

```json
{
    "webhook_type": "debt",
    "key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
    "status": "waiting_signature",
    "event_datetime": "2025-03-27 22:46:10",
    "data": {}
}
```

## 定义

### 请求体对象
| 字段 | 类型 | 描述 | 最大字符数 | 
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **borrower** * | object | **[Borrower 对象](#objeto-borrower)** - 信贷操作的债务人 | - | 
| **disbursement_bank_account** * | object | **[Disbursement Bank Account 对象](#objeto-disbursement_bank_accounts)** - 操作放款的银行账户数据 | - |
| **financial** * | object | **[Financial 对象](#objeto-financial)** - 操作放款的银行账户数据，标识所发送的对象为自然人。borrower PF 时必须始终包含 "natural" 值 | - |
| **purchaser_document_number** * | string | 信贷操作受让人（买方）的 CNPJ | - |

### Borrower 对象
| 字段 | 类型 | 描述 | 最大字符数 | 
|----------------------------------|---------|---------------------------------------------------------------------------------------|--------------|
| **name** * | string | 债务人姓名 | 100 |
| **email** | string | 债务人电子邮件 | 254 |
| **phone** | object | **[Phone 对象](#objeto-phone)** - 债务人联系电话 | - | 
| **is_pep** * | boolean | PEP 指示器（http://www.portaldatransparencia.gov.br/download-de-dados/pep） | - |
| **address** * | object | **[Address 对象](#objeto-address)** - 债务人地址 | - | 
| **role_type** * | enum | 默认值：_issuer_ | - |
| **birth_date** * | date | 债务人出生日期（格式 "YYYY-MM-DD"） | - |
| **mother_name** * | string | 债务人母亲姓名 | 100 |
| **nationality** | string | 债务人国籍 | 50 |
| **person_type** * | string | 自然人标识 - 默认值：_natural_ | - |
| **individual_document_number** * | string | 债务人 CPF（仅数字） | 11 |
| **document_identification** * | string | 带照片的债务人身份证明文件 PDF 的 **DOCUMENT_KEY**（身份证或驾驶证） | - |
| **document_identification_back** | string | 带照片的身份证明文件背面 PDF 的 DOCUMENT_KEY（身份证或驾驶证）（预先上传）。 | 11 |
| **wedding_certificate** | string | 结婚证 PDF 的 DOCUMENT_KEY（预先上传）。若 marital_status 为 "single"，该字段值应为 NULL。 | 11 |
| **proof_of_residence** * | string | 所提供地址的居住证明 PDF 的 DOCUMENT_KEY（预先上传）。 | 11 |

### Address 对象
| 字段 | 类型 | 描述 | 最大字符数 | 
|--------------------|--------|--------------------------------------------------------------------------|--------------| 
| **city** * | string | 地址所在城市 | 100 |
| **state** * | string | 地址所在州（两位大写字母） | 2 |
| **number** * | string | 门牌号 | 10 |
| **street** * | string | 街道名称 | 100 |
| **complement** * | string | 地址补充信息（自由文本） | 100 |
| **postal_code** * | string | 邮政编码（http://www.buscacep.correios.com.br/sistemas/buscacep/） | 8 |
| **neighborhood** * | string | 社区/街区名称 | 100 |

### Phone 对象
| 字段 | 描述 | 示例 | 最大字符数 | 
|--------------------|-----------|-------------------------------------------------------|--------------| 
| **number** * | string | 电话号码 | 10 |
| **area_code** * | string | 区号（https://ddd.guiamais.com.br/） | 2 |
| **country_code** * | string | 国家代码（https://ddi.guiamais.com.br/） | 3 |

### Disbursement Bank Account 对象

债务发行必须包含放款的银行账户信息，默认情况下为债务人名下的账户。

| 字段 | 类型 | 描述 | 最大字符数 | 
|-----------------------|--------|----------------------------------------------------------------------------------------------------|--------------|
| name | string | 账户持有人姓名 | 50 |
| document_number | string | 账户持有人 CPF | 11 |
| bank_code * | string | 金融机构的 COMPE 代码（https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf） | 3 |
| branch_number * | string | 支行号码（请勿填写支行验证位！） | 4 |
| account_number * | string | 账号（不含验证位！） | 10 |
| account_digit * | string | 账户验证位（字母处填写零） | 1 |
| account_type | enum | [账户类型枚举值](#enumerador-account-type) 账户类型 | 1 |

### Financial 对象

Financial 对象描述信贷操作的财务信息。

| 字段 | 类型 | 描述 | 最大字符数 |
|----------------------------|--------|---------------------------------------------------------------------------------------------------------------|--------------|
| **amout** | float | 信贷操作的发行/名义金额 | - |
| **interest_type** | object | **[利率类型枚举值](#enumerador-interest-type)** - 摊销方法和利率计算方式 | - |
| **credit_operation_type** | object | **[信贷操作类型枚举值](#enumerador-credit-operation-type)** - 信贷合同类型 | - |
| **annual_interest_rate** | float | 以年化小数表示的固定利率 | - |
| **disbursement_date** | date | 操作放款日期 | - |
| **interest_grace_period** | int | 利息宽限期（月） | - |
| **principal_grace_period** | int | 本金宽限期 | - |
| **number_of_installments** | int | 信贷操作的分期数 | - |
| **fine_configuration** | object | **[Fine Configuration 对象](#objeto-fine-configuration)** - 逾期利息和罚款配置 | - |

### Fine Configuration 对象

Fine Configuration 对象中填写信贷操作的逾期罚款和利息金额。

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------------|-------|--------------------------------------------------------------------------------------|--------------|
| **contract_fine_rate** | float | 逾期罚款百分比 | - |
| **interest_base** | enum | **[利率基准枚举值](#enumerador-interest-base)** - 利率计算基准 | - |
| **monthly_rate** | float | 月逾期利率 | - |

### Rebates 对象
| 字段 | 类型 | 描述 | 最大字符数 | 
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **fee_type** * | enum | 费用类型。 | - | 
| **amount_type** * | object | 收取金额的类型。 | - |
| **amount** * | object | 费用金额。若费用类型为百分比，则值应在 0 到 100 之间。 | - |

### 响应体
| 字段 | 类型 | 描述 | 最大字符数 |
|----------------------------|--------|----------------------------------------------------------------|--------------|
| **data[n].data** | object | **[Data 对象](#objeto-data)** | - |
| **data[n].event_datetime** | date | 信贷操作生成时刻 | - |
| **data[n].key** | string | **DEBT-KEY** - QI 内信贷操作的唯一密钥 | - |
| **data[n].status** | string | **[债务可能的状态](../status_de_uma_divida)** | - |
| **data[n].type** | string | _debt_ | - |

# 枚举值

### _Person Type_ 枚举值
| 枚举值 | 描述 |
|------------------------|-----------------------|
| **legal** | 法人 |
| **natural** | 自然人 |

### _Amount Type_ 枚举值
| 枚举值 | 描述 |
|------------------------|-----------------------|
| **tac** | 向借款人收取的费用。 |
| **spread** | 向基金收取并加入操作转让价格的费用。 |

### _Account Type_ 枚举值
| 枚举值 | 描述 |
|------------------------|-----------------------|
| **checking_account** | 活期账户 |
| **deposit_account** | 存款账户 |
| **guaranteed_account** | 担保账户 |
| **investment_account** | 投资账户 |
| **payment_account** | 支付账户 |
| **saving_account** | 储蓄账户 |
| **salary_account** | 工资账户 |

### _Interest Type_ 枚举值
| 枚举值 | 描述 |
|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **pre_price_days** | Price 摊销法（等额分期），按日计算固定利率 |
| **pre_price** | Price 摊销法（等额分期），按固定周期（30天）计算固定利率 |
| **pre_sac** | SAC 摊销法（等额本金），按日计算固定利率 |
| **post_sac** | SAC 摊销法（等额本金），按日计算基于固定利率加浮动指数（cdi、ipca 或 igpm）的利率 |
| **post_price** | Price 摊销法（等额分期），按固定周期（30天）计算基于固定利率加浮动指数（cdi、ipca 或 igpm）的利率 |
| **post_price_days** | Price 摊销法（等额分期），按日计算基于固定利率加浮动指数（cdi、ipca 或 igpm）的利率 |

### _Credit Operation Type_ 枚举值
| 枚举值 | 描述 |
|---------------|--------------------------------|
| **ccb** | 银行信贷凭证 |
| **cce** | 出口信贷凭证 |
| **cci** | 房地产信贷凭证 |
| **nce** | 出口信贷票据 |

### _Interest Base_ 枚举值
| 枚举值 | 描述 |
|-----------------------|---------------------------------------------------------------------------|
| **workdays** | 以工作日为基准计算利率，按 252 天/年计算 |
| **calendar_days** | 以自然日为基准计算利率，按 360 天/年计算 |
| **calendar_days_365** | 以自然日为基准计算利率，按 365 天/年计算 |

### _Fee Type_ 枚举值
每种费用类型必须提前由 QI Tech 启用和配置

| 枚举值 | 描述 |
|-----------------------|----------------------------------------------------------------------------|
| **tac** | 开户费 |
| **spread** | 信贷操作收购金额中收取的溢价 |
| **warranty_analysis** | 担保分析费 |
| **ted_fee** | TED 费用 |
| **spread_ted_fee** | 信贷操作收购金额中收取的 TED 费用溢价 |

---

# 企业债务发行

URL: /zh-Hans/documentation/emissao_de_divida/emissao/emissao_de_divida_pj

使用债务发行 API，可以为法人申请发行债务。无需提前注册借款人，只需在申请时提供注册数据即可。

:::danger 注意！

QI Tech 提供新客户入驻和反欺诈解决方案。

[在此查看该服务 API 的文档。](https://www.zaig.com.br/en/devcenter.html)

如需报价，请联系我们的商务团队：

comercial@qitech.com.br 或 (11) 3522-1301
:::

债务 API 设计为只需执行一次请求即可完成，需在提前上传文件（[文档上传](../../upload_de_documentos)）之后执行。
请求头和请求体的签名格式详情请参见[此处](../../primeiros_passos/teste_de_autenticacao)。

## 请求

ENDPOINT /debt
MÉTODO POST

请求体

```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,
                "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"
}

```

## 响应

此次债务请求的响应将返回还款计划以及 **DEBT-KEY**，即债务在 QI SCD 中的标识符。

STATUS 200

响应体

```json
{
  "data": {},
  "event_datetime": "2023-05-04 12:28:35",
  "key": "feceb7fe-1305-45eb-899d-c87d36bcc534",
  "status": "waiting_signature",
  "webhook_type": "debt"
}

```

### 请求体对象
| 字段 | 类型 | 描述 | 最大字符数 | 
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **borrower** * | object | **[Borrower 对象](#objeto-borrower)** - 信贷操作的债务人 | - |
| **guarantor** | object | **[Guarantor 对象](#objeto-borrower)** - 信贷操作的担保人 | - |  
| **disbursement_bank_account** * | object | **[Disbursement Bank Account 对象](#objeto-disbursement_bank_accounts)** - 操作放款的银行账户数据 | - |
| **financial** * | object | **[Financial 对象](#objeto-financial)** - 操作放款的银行账户数据，标识所发送的对象为自然人。borrower PF 时必须始终包含 "natural" 值 | - |
| **purchaser_document_number** * | string | 信贷操作受让人（买方）的 CNPJ | - |

### Borrower 对象  
| 字段 | 类型 | 描述 | 最大字符数 | 
|----------------------------------|---------|---------------------------------------------------------------------------------------|--------------|
| **name** * | string | 公司法定名称 | 100 |
| **trading_name** * | string | 商业名称 | |
| **email** * | string | 公司机构电子邮件 | 254 |
| **phone** * | object | **[Phone 对象](#objeto-phone)** - 公司电话 | - | 
| **is_pep** * | boolean | PEP 指示器（http://www.portaldatransparencia.gov.br/download-de-dados/pep） | - |
| **address** * | object | **[Address 对象](#objeto-address)** - 债务人地址 | - | 
| **role_type** * | enum | 默认值：_issuer_ | - |
| **person_type** * | string | 法人标识 - 默认值：_legal_ | - |
| **company_document_number** * | string | CNPJ（仅数字） | - |
| **cnae_code** * | string | 国家经济活动分类代码 | |
| **company_representatives** * | array of objects | 公司法定代表人列表 | **[Company Representatives 对象](#objeto-company_representatives)** |
| **company_type** * | enum | 公司类型："ltda"、"sa"、"micro_enterprise" 或 "freelancer" | - |
| **company_statute** * | string | 公司章程 PDF 的 `document_key` | |
| **directors_election_minute** | string | 公司董事选举会议记录 PDF 的 `document_key`（仅对 company_type 为 "sa" 的公司必填） | |
| **foundation_date** * | date | 公司成立日期（格式 "YYYY-MM-DD"） | |

如上所示，"borrower" 字段和 "guarantors" 字段均可由 PF 对象或 PJ 对象填充。PJ 对象是 QI Tech 中法人实体的描述。

### Company Representatives 对象

| 字段 | 描述 | 示例 | 最大字符数 | 
|---|---|---|---| 
| **person_type** * | string | 标识所发送对象为自然人或法人。 | natural |
| **name** * | string | 法人操作时为公司法定名称，自然人操作时为个人姓名。限 100 个字符。 | |
| **mother_name** * | string | 自然人时为客户母亲姓名。限 100 个字符。 | |
| **birth_date** * | string | 人员出生日期（格式 "YYYY-MM-DD"） | - |
| **profession** * | string | 客户职业。限 64 个字符。 | 64 |
| **nationality** * | string | 客户国籍。 | 50 |
| **marital_status** * | string | 客户婚姻状况。 | |
| **property_system** * | string | 财产分隔制度（仅 marital_status 为 "married" 时必填）。 | **[property_system 枚举值](#enumeradores-property_system)** |
| **wedding_certificate** * | string | 结婚证 PDF 的 DOCUMENT_KEY（预先上传）。若 marital_status 为 "single"，该字段值应为 NULL。 | |
| **spouse** * | string | **[Spouse 对象](#objeto-spouse)**（仅当 "compulsory_separation_of_goods" 为 "total_communion_of_goods"、"partial_communion_of_goods"、"final_participation_of_acquisitions" 或 "compulsory_separation_of_goods" 时必填）。若 marital_status 为 "single"，该字段值应为 NULL。 | **[Spouse 对象](#objeto-spouse)** |
| **is_pep** * | boolean | 声明该人是否为 PEP（http://www.portaldatransparencia.gov.br/download-de-dados/pep）。 | true/false |
| **final_beneficiary** | boolean | 声明该人是否为公司的最终受益人。 | true/false |
| **individual_document_number** * | string | 人员 CPF（仅数字）。 | 10 |
| **document_identification** * | string | 带照片的身份证明文件 PDF 的 DOCUMENT_KEY（身份证或驾驶证）（预先上传） | |
| **document_identification_back** | string | 带照片的身份证明文件背面 PDF 的 DOCUMENT_KEY（身份证或驾驶证）（预先上传）。 | |
| **document_identification_type** * | string | 所提交身份证明文件的类型。 | |
| **document_identification_number** * | string | "document_identification" 中提交的身份证明文件号码。 | 16 |
| **email** * | string | 客户电子邮件。 | 254 | 
| **phone** * | object | 客户电话 | **[Phone 对象](#objeto-phone)** | - |
| **address** | object | 客户地址。 | **[Address 对象](#objeto-address)** | |
| **proof_of_residence** | string | 所提供地址的居住证明 PDF 的 DOCUMENT_KEY（预先上传）。 | - |

### Spouse 对象
| 字段 | 描述 | 示例 | 最大字符数 | 
|---|---|---|---| 
| **person_type** * | string | 标识所发送对象为自然人或法人。 | natural |
| **name** * | string | 法人操作时为公司法定名称，自然人操作时为个人姓名。限 100 个字符。 | |
| **mother_name** * | string | 自然人时为客户母亲姓名。限 100 个字符。 | |
| **birth_date** * | string | 人员出生日期（格式 "YYYY-MM-DD"） | - |
| **profession** * | string | 客户职业。限 64 个字符。 | 64 |
| **is_pep** * | boolean | 声明该人是否为 PEP（http://www.portaldatransparencia.gov.br/download-de-dados/pep）。 | true/false |
| **individual_document_number** * | string | 人员 CPF（仅数字）。 | 10 |
| **document_identification_number** * | string | "document_identification" 中提交的身份证明文件号码。 | 16 |
| **email** * | string | 客户电子邮件。 | 254 | 
| **phone** * | object | 客户电话 | **[phone 对象](#objeto-phone)** | - |
| **address** | object | 客户地址。 | **[address 对象](#objeto-address)** | |

### Address 对象

| 字段 | 类型 | 描述 | 最大字符数 | 
|--------------------|--------|--------------------------------------------------------------------------|--------------| 
| **city** * | string | 地址所在城市 | 100 |
| **state** * | string | 地址所在州（两位大写字母） | 2 |
| **number** * | string | 门牌号 | 10 |
| **street** * | string | 街道名称 | 100 |
| **complement** * | string | 地址补充信息（自由文本） | 100 |
| **postal_code** * | string | 邮政编码（http://www.buscacep.correios.com.br/sistemas/buscacep/） | 8 |
| **neighborhood** * | string | 社区/街区名称 | 100 |

### Phone 对象

| 字段 | 描述 | 示例 | 最大字符数 | 
|--------------------|-----------|-------------------------------------------------------|--------------| 
| **number** * | string | 电话号码 | 10 |
| **area_code** * | string | 区号（https://ddd.guiamais.com.br/） | 2 |
| **country_code** * | string | 国家代码（https://ddi.guiamais.com.br/） | 3 |

### Disbursement Bank Account 对象

债务发行必须包含放款的银行账户信息，默认情况下为债务人名下的账户。

| 字段 | 类型 | 描述 | 最大字符数 | 
|-----------------------|--------|----------------------------------------------------------------------------------------------------|--------------|
| name | string | 账户持有人姓名 | 50 |
| document_number | string | 账户持有人 CPF | 11 |
| bank_code * | string | 金融机构的 COMPE 代码（https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf） | 3 |
| branch_number * | string | 支行号码（请勿填写支行验证位！） | 4 |
| account_number * | string | 账号（不含验证位！） | 10 |
| account_digit * | string | 账户验证位（字母处填写零） | 1 |
| account_type | enum | [账户类型枚举值](#enumerador-account-type) 账户类型 | 1 |

### Financial 对象

Financial 对象描述发行的财务信息。其中定义了利率、宽限期和债务金额等。Financial 对象包含以下字段，但需注意某些字段是可选且互斥的（若其中一个可用，则不应发送另一个）。

| 字段 | 类型 | 描述 | 最大字符数 |
|----------------------------|--------|---------------------------------------------------------------------------------------------------------------|--------------|
| **amout** | float | 信贷操作的发行/名义金额 | - |
| **interest_type** | object | **[利率类型枚举值](#enumerador-interest-type)** - 摊销方法和利率计算方式 | - |
| **credit_operation_type** | object | **[信贷操作类型枚举值](#enumerador-credit-operation-type)** - 信贷合同类型 | - |
| **annual_interest_rate** | float | 以年化小数表示的固定利率 | - |
| **disbursement_date** | date | 操作放款日期 | - |
| **interest_grace_period** | int | 利息宽限期（月） | - |
| **principal_grace_period** | int | 本金宽限期 | - |
| **number_of_installments** | int | 信贷操作的分期数 | - |
| **fine_configuration** | object | **[Fine Configuration 对象](#objeto-fine-configuration)** - 逾期利息和罚款配置 | - |

### Fine Configuration 对象

Fine Configuration 对象中填写信贷操作的逾期罚款和利息金额。

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------------|-------|--------------------------------------------------------------------------------------|--------------|
| **contract_fine_rate** | float | 逾期罚款百分比 | - |
| **interest_base** | enum | **[利率基准枚举值](#enumerador-interest-base)** - 利率计算基准 | - |
| **monthly_rate** | float | 月逾期利率 | - |

### Rebates 对象
| 字段 | 类型 | 描述 | 最大字符数 | 
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **fee_type** * | enum | 费用类型。 | - | 
| **amount_type** * | object | 收取金额的类型。 | - |
| **amount** * | object | 费用金额。若费用类型为百分比，则值应在 0 到 100 之间。 | - |

### 响应体
| 字段 | 类型 | 描述 | 最大字符数 |
|----------------------------|--------|----------------------------------------------------------------|--------------|
| **data[n].data** | object | **[Data 对象](#objeto-data)** | - |
| **data[n].event_datetime** | date | 信贷操作生成时刻 | - |
| **data[n].key** | string | **DEBT-KEY** - QI 内信贷操作的唯一密钥 | - |
| **data[n].status** | string | **[债务可能的状态](../status_de_uma_divida)** | - |
| **data[n].type** | string | _debt_ | - |

# 枚举值

### _Person Type_ 枚举值
| 枚举值 | 描述 |
|------------------------|-----------------------|
| **legal** | 法人 |
| **natural** | 自然人 |

### _Amount Type_ 枚举值
| 枚举值 | 描述 |
|------------------------|-----------------------|
| **tac** | 向借款人收取的费用。 |
| **spread** | 向基金收取并加入操作转让价格的费用。 |

### _Account Type_ 枚举值
| 枚举值 | 描述 |
|------------------------|-----------------------|
| **checking_account** | 活期账户 |
| **deposit_account** | 存款账户 |
| **guaranteed_account** | 担保账户 |
| **investment_account** | 投资账户 |
| **payment_account** | 支付账户 |
| **saving_account** | 储蓄账户 |
| **salary_account** | 工资账户 |

### _Interest Type_ 枚举值
| 枚举值 | 描述 |
|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **pre_price_days** | Price 摊销法（等额分期），按日计算固定利率 |
| **pre_price** | Price 摊销法（等额分期），按固定周期（30天）计算固定利率 |
| **pre_sac** | SAC 摊销法（等额本金），按日计算固定利率 |
| **post_sac** | SAC 摊销法（等额本金），按日计算基于固定利率加浮动指数（cdi、ipca 或 igpm）的利率 |
| **post_price** | Price 摊销法（等额分期），按固定周期（30天）计算基于固定利率加浮动指数（cdi、ipca 或 igpm）的利率 |
| **post_price_days** | Price 摊销法（等额分期），按日计算基于固定利率加浮动指数（cdi、ipca 或 igpm）的利率 |

### _Credit Operation Type_ 枚举值
| 枚举值 | 描述 |
|------------|--------------------------------|
| **ccb** | 银行信贷凭证 |
| **cce** | 出口信贷凭证 |
| **cci** | 房地产信贷凭证 |
| **nce** | 出口信贷票据 |
| **ncom** | 商业票据 |

### _Interest Base_ 枚举值
| 枚举值 | 描述 |
|-----------------------|---------------------------------------------------------------------------|
| **workdays** | 以工作日为基准计算利率，按 252 天/年计算 |
| **calendar_days** | 以自然日为基准计算利率，按 360 天/年计算 |
| **calendar_days_365** | 以自然日为基准计算利率，按 365 天/年计算 |

### _Fee Type_ 枚举值
每种费用类型必须提前由 QI Tech 启用和配置

| 枚举值 | 描述 |
|-----------------------|----------------------------------------------------------------------------|
| **tac** | 开户费 |
| **spread** | 信贷操作收购金额中收取的溢价 |
| **warranty_analysis** | 担保分析费 |
| **ted_fee** | TED 费用 |
| **spread_ted_fee** | 信贷操作收购金额中收取的 TED 费用溢价 |

---

# 放款 Payload 示例

URL: /zh-Hans/documentation/emissao_de_divida/emissao/exemplo_payloads_desembolso

### 放款到 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
	}]
  ...
}
```

--- 

### 使用手动 PIX 放款

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 PIX 密钥类型
"pix_key" 可以是 CPF、CNPJ、电子邮件、手机号或随机密钥（UUID），格式如下：

CPF：11位整数。

CNPJ：14位整数。

电子邮件：包含至少一个"@"的文本。

手机号：包含以下格式的文本："+55" + "手机区号" + "8至9位整数手机号"。例如："+5511987654321"。

随机密钥：UUID。
:::

---

### 使用 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"
		}]
		...
}
```
---

### 使用 PIX QR Code 放款

ENDPOINT /debt
MÉTODO POST

```json title='Request Body'

{
	"disbursement_bank_accounts": [{
			"qr_code_key": "b76e436e-4767-4b16-91e6-9bfc794f2510"
		}]
		...
}
```

---

### 使用 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
		}]
		...
}
```

---

### 通过支付 Boleto 放款

ENDPOINT /debt
MÉTODO POST

```json title='Request Body'

{
	"disbursement_bank_accounts": [{
		"digitable_line": "836400000169072200500006763953020230059001020193",
		"amount_receivable": 1607.22
	}]
		...
}
```

---

# 替代签署方式

URL: /zh-Hans/documentation/emissao_de_divida/formalizacao/assinatura_de_contrato

要使用替代签署方式，需要将证明文件压缩为 .zip 文件，并通过 QI TECH 的 /upload 端点发送，这样返回的 document_key 即可在此端点中用作合同签署方式。

替代签署方式示例：

- 录音电话；

- 信用分析；

## 请求

ENDPOINT /debt/ DEBT-KEY /signed
MÉTODO POST

**请求体**

```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"
        }
    ]
}
```

## 路径参数

| 字段 | 类型 | 描述 | 字符数 | 
|---|---|---|---|
| `debt_key` * | string | 创建信贷操作时返回的债务密钥。 | - |

## 请求体参数

| 字段 | 类型 | 描述 | 字符数 | 
|---|---|---|---|
| `type` * | string | 将要发送的签署类型。 | - |
| `signatures` * | array of objects | 包含签署证明对象的列表——在签署类型为"data-signature"时发送。 | **[signatures 对象](#objeto-signatures)** |
| `path-pdf-signed` * | string | 已签署 PDF 的 URL——在签署类型为"pdf-signature"时发送。 | - |

### signatures 对象

| 字段 | 类型 | 描述 | 字符数 | 
|---|---|---|---|
| `signed_object` | object | 包含正在签署文件的对象。 | **[signed_object 对象](#objeto-signed_object)** |
| `authenticity` | object | 包含认证数据的对象。 | **[authenticity 对象](#objeto-authenticity)** |
| `signer` | object | 包含签署人数据的对象。 | **[signer 对象](#objeto-signer)** |
| `authentication_type` * | string | 签署类型。 | - |

### signed_object 对象

| 字段 | 类型 | 描述 | 字符数 | 
|---|---|---|---|
| `raw_text` | string | 包含将要签署的合同数据的连续文本（opt-in 类型认证必填）。 | - |
| `document_key` | string | 通过 API 1.1 发送的已签署文件的 DOCUMENT_KEY（仅当未发送"raw_text"字段时必填）。 | - |
| `document_md5` | string | 通过 API 1.1 发送的已签署文件的 DOCUMENT_MD5（仅当未发送"raw_text"字段时必填）。 | - |

### authenticity 对象

| 字段 | 类型 | 描述 | 字符数 | 
|---|---|---|---|
| `timestamp` * | string | 签署日期。 | - |
| `document_key` * | string | 发送签署证据文件后由 API 1.1 返回的 DOCUMENT_KEY。 | - |
| `document_md5` * | string | 发送签署证据文件后由 API 1.1 返回的 DOCUMENT_MD5。 | - |
 
### signer 对象

| 字段 | 类型 | 描述 | 字符数 | 
|---|---|---|---|
| `name` * | string | 签署人姓名。 | - |
| `email` * | string | 签署人电子邮件。 | - |
| `phone` | string | 签署人电话对象。 | **[phone 对象](#objeto-phone)** |
| `document_number` * | string | 签署人证件号码。 | - |

### phone 对象

| 字段 | 类型 | 描述 | 字符数 | 
|---|---|---|---|
| `country_code` * | string | 电话国家代码（https://ddi.guiamais.com.br/） | 3 | 
| `area_code` * | string | 电话区号（https://ddd.guiamais.com.br/） | 2 |
| `number` * | string | 电话号码（仅数字） | 10 |

## 响应

STATUS 200

**响应体**

```json
{
  "data": {},
  "event_datetime": "2022-11-07 15:24:47",
  "key": "\<DEBT-KEY\>",
  "status": "signature_received",
  "webhook_type": "debt"
}

```

STATUS 400

**响应体**

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

```

---

# 通过 OPT-IN 签署合同

URL: /zh-Hans/documentation/emissao_de_divida/formalizacao/assinatura_opt_in

## 请求

ENDPOINT /debt/ DEBT-KEY /signed
MÉTODO POST

**请求体**

```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"
        }
    ]
}
```

## 路径参数

| 字段 | 类型 | 描述 | 字符数 | 
|---|---|---|---|
| `debt_key` * | string | 创建信贷操作时返回的债务密钥。 | - |

## 请求体参数

| 字段 | 类型 | 描述 | 字符数 | 
|---|---|---|---|
| `type` * | string | 将要发送的签署类型。 | - |
| `signatures` * | array of objects | 包含签署证明对象的列表——在签署类型为"data-signature"时发送。 | **[signatures 对象](#objeto-signatures)** |

### signatures 对象

| 字段 | 类型 | 描述 | 字符数 | 
|---|---|---|---|
| `signed_object` | object | 包含正在签署文件的对象。 | **[signed_object 对象](#objeto-signed_object)** |
| `authenticity` | object | 包含认证数据的对象。 | **[authenticity 对象](#objeto-authenticity)** |
| `signer` | object | 包含签署人数据的对象。 | **[signer 对象](#objeto-signer)** |
| `authentication_type` * | string | 签署类型。 | - |

### signed_object 对象

| 字段 | 类型 | 描述 | 字符数 | 
|---|---|---|---|
| `raw_text` * | string | 包含将要签署的合同数据的连续文本。 | - |

### authenticity 对象

| 字段 | 类型 | 描述 | 字符数 | 
|---|---|---|---|
| `timestamp` * | string | 签署日期。 | - |
| `ip_address` | string | 对于"opt-in"认证类型为必填字段，表示收集接受时的 IP 地址。 | - |
| `session_id` | string | 签署时客户的会话标识 ID——必须可查询，会话证据须保存至少 5 年（"opt-in"认证类型必填）。 | - |
| `geolocation` | object | 可选地理位置字段。 | - |
 
### signer 对象

| 字段 | 类型 | 描述 | 字符数 | 
|---|---|---|---|
| `name` * | string | 签署人姓名。 | - |
| `email` * | string | 签署人电子邮件。 | - |
| `phone` | string | 签署人电话对象。 | **[phone 对象](#objeto-phone)** |
| `document_number` * | string | 签署人证件号码。 | - |

### phone 对象

| 字段 | 类型 | 描述 | 字符数 | 
|---|---|---|---|
| `country_code` * | string | 电话国家代码（https://ddi.guiamais.com.br/） | 3 | 
| `area_code` * | string | 电话区号（https://ddd.guiamais.com.br/） | 2 |
| `number` * | string | 电话号码（仅数字） | 10 |

## 响应

STATUS 200

**响应体**

```json
{
  "data": {},
  "event_datetime": "2022-11-07 15:24:47",
  "key": "\<DEBT-KEY\>",
  "status": "signature_received",
  "webhook_type": "debt"
}

```

STATUS 400

**响应体**

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

```

---

# 发送已签署 PDF

URL: /zh-Hans/documentation/emissao_de_divida/formalizacao/assinatura_pdf

## 请求

ENDPOINT /debt/ DEBT-KEY /signed
MÉTODO POST

**请求体**

```json
{
    "type": "pdf-signature",
    "path-pdf-signed": "https://www.google.com/"
}
```

## 路径参数

| 字段 | 类型 | 描述 | 字符数 | 
|---|---|---|---|
| `debt_key` * | string | 创建信贷操作时返回的债务密钥。 | - |

## 请求体参数

| 字段 | 类型 | 描述 | 字符数 | 
|---|---|---|---|
| `type` * | string | 将要发送的签署类型。 | - |
| `path-pdf-signed` * | string | 已签署 PDF 的 URL——在签署类型为"pdf-signature"时发送。 | - |

## 响应

STATUS 200

**响应体**

```json
{
  "data": {},
  "event_datetime": "2022-11-07 15:24:47",
  "key": "\<DEBT-KEY\>",
  "status": "signature_received",
  "webhook_type": "debt"
}

```

STATUS 400

**响应体**

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

```

---

# 通过自拍签署合同

URL: /zh-Hans/documentation/emissao_de_divida/formalizacao/assinatura_selfie

通过自拍认证适用于使用 QI Tech 信用分析服务的合作方，自拍认证经过验证后会生成证明 ID。

通过 QI Tech 信用分析端点生成的此 ID 可用作合同签署方式。

## 请求

ENDPOINT /debt/ DEBT-KEY /signed
MÉTODO POST

**请求体**

```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"
        }
    ]
}
```

## 路径参数

| 字段 | 类型 | 描述 | 字符数 | 
|---|---|---|---|
| `debt_key` * | string | 创建信贷操作时返回的债务密钥。 | - |

## 请求体参数

| 字段 | 类型 | 描述 | 字符数 | 
|---|---|---|---|
| `type` * | string | 将要发送的签署类型。 | - |
| `signatures` * | array of objects | 包含签署证明对象的列表——在签署类型为"data-signature"时发送。 | **[signatures 对象](#objeto-signatures)** |

### signatures 对象

| 字段 | 类型 | 描述 | 字符数 | 
|---|---|---|---|
| `signed_object` | object | 包含正在签署文件的对象。 | **[signed_object 对象](#objeto-signed_object)** |
| `authenticity` | object | 包含认证数据的对象。 | **[authenticity 对象](#objeto-authenticity)** |
| `signer` | object | 包含签署人数据的对象。 | **[signer 对象](#objeto-signer)** |
| `authentication_type` * | string | 签署类型。 | - |

### signed_object 对象

| 字段 | 类型 | 描述 | 字符数 | 
|---|---|---|---|
| `raw_text` | string | 包含将要签署的合同数据的连续文本（opt-in 类型认证必填）。 | - |
| `document_key` | string | 通过 API 1.1 发送的已签署文件的 DOCUMENT_KEY（仅当未发送"raw_text"字段时必填）。 | - |
| `document_md5` | string | 通过 API 1.1 发送的已签署文件的 DOCUMENT_MD5（仅当未发送"raw_text"字段时必填）。 | - |

### authenticity 对象

| 字段 | 类型 | 描述 | 字符数 | 
|---|---|---|---|
| `timestamp` * | string | 签署日期。 | - |
| `facial_recognition_key` * | string | 必须包含 QI Tech 人脸识别 API 返回的 facial_recognition_key——此字段仅适用于"selfie"认证类型，且排除其他证明文件的强制要求。 | - |
 
### signer 对象

| 字段 | 类型 | 描述 | 字符数 | 
|---|---|---|---|
| `name` * | string | 签署人姓名。 | - |
| `email` * | string | 签署人电子邮件。 | - |
| `phone` | string | 签署人电话对象。 | **[phone 对象](#objeto-phone)** |
| `document_number` * | string | 签署人证件号码。 | - |

### phone 对象

| 字段 | 类型 | 描述 | 字符数 | 
|---|---|---|---|
| `country_code` * | string | 电话国家代码（https://ddi.guiamais.com.br/） | 3 | 
| `area_code` * | string | 电话区号（https://ddd.guiamais.com.br/） | 2 |
| `number` * | string | 电话号码（仅数字） | 10 |

## 响应

STATUS 200

**响应体**

```json
{
  "data": {},
  "event_datetime": "2022-11-07 15:24:47",
  "key": "\<DEBT-KEY\>",
  "status": "signature_received",
  "webhook_type": "debt"
}

```

STATUS 400

**响应体**

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

```

---

# 合同签署

URL: /zh-Hans/documentation/emissao_de_divida/formalizacao/introducao_formalizacao

默认情况下，QI Tech 通过 QI Sign 收集签名，合同在发行时发送给签署人。不过，合作方也可以独立收集签名，然后将已签署的文件或签署证据发送给 QI Tech 以继续操作。

:::caution **注意**

如需由合作方收集签名后通过 API 发送已签署文件，必须向 QI Tech 支持团队申请配置此流程。
:::

签署流程可以通过以下 2 种方式进行：

1 - 通过 QI Tech 平台收集签名；

2 - 合作方独立收集签名，然后将已签署合同发送给 QI Tech——此方式既支持发送已签署 PDF，也支持发送签名哈希；

调用流程因所选方式不同而有所变化，可遵循以下调用流程：

## 流程 1
向 QI Tech 支持团队申请配置签名流程 1 后，完成债务发行所需的唯一调用是根据操作的信贷借款人进行第 3 组调用。

QI Tech 将发行预配置的信贷合同并发送以进行签署——可通过 API 5.1 或发送的回调跟踪操作进度。

文件签署通过 QI Sign 平台完成，可在合同发行后的 7 天内通过电子邮件、WhatsApp 或短信完成。

由于签署的异步性，当借款人签署合同后，系统将通过 webhook 向发起方触发事件。

## 流程 2
向 QI Tech 支持团队申请配置签名流程 2 后，需要执行一系列调用。

第一个调用必须是第 3 组 API（根据操作的信贷借款人）以生成合同 PDF，最后一个调用是 API 4.1 以提交已签署合同；

如果通过认证机构签署文件，需要在 API 4.1 中发送带有已签署 PDF 的 URL；

如果是通过前端 opt-in 方式签署，则在 API 4.1 中发送的是客户接受证据。

QI Tech 将随后进行放款流程——可通过 API 5.1 或发送的 webhook 跟踪操作进度。

## 支持的签署类型

### **pdf-signature**
此类型表示通过 "/debt" 生成的 PDF 将被签署，已签署 PDF 的链接将通过 API 4.1 作为认证方式发送。

### **data-signature**
此类型表示通过 "/debt" 生成的 PDF 将通过附在最后一页的哈希值进行签署。

数据认证有 3 种类型：

#### **Opt-in**
通过 opt-in 签署意味着客户将通过前端接受合同。

为使此签署有效，必须强制发送某些数据。

#### **Zip**
通过 zip 签署包括发送证明文件，如录音电话。

#### **Selfie**
通过自拍认证适用于使用 QI Tech CaaS 服务的合作方，自拍认证经过验证后会生成证明 ID。

---

# 为分期付款生成 Boleto 或 PIX

URL: /zh-Hans/documentation/emissao_de_divida/gerar_boleto_ou_pix_para_uma_parcela

允许为信贷操作的特定分期生成银行 Boleto 或 PIX 付款码。

:::caution 付款方式替换
如果该分期已有有效的 Boleto/PIX 用于付款，该 Boleto/PIX 将被停用并由新的付款方式替换。
:::

## 端点

### 请求

ENDPOINT /debt/ DEBT-KEY /installment/ INSTALLMENT-KEY / PAYMENT-TYPE
MÉTODO POST
路径参数
| 参数 | 类型 | 描述 |
|-----------|------|-----------|
| DEBT-KEY | string | 债务的标识密钥 |
| INSTALLMENT-KEY | string | 分期的标识密钥 |
| PAYMENT-TYPE | string | 所需付款类型：bankslip（Boleto）或 pix（PIX QR Code） |
请求体
```json
{}
```
响应
响应体
```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"
}
```
响应体对象
| 字段 | 类型 | 描述 |
|-------|------|-----------|
| installment_key | string | UUID 格式的分期唯一标识符 |
| due_date | string | 分期到期日，格式为 YYYY-MM-DD |
| business_due_date | string | 分期工作日到期日，格式为 YYYY-MM-DD |
| pre_fixed_amount | number | 利息金额 |
| principal_amortization_amount | number | 待摊还的本金金额 |
| total_amount | number | 分期总金额（利息 + 本金） |
| bank_slip_key | string | 银行 Boleto 的标识密钥 |
| qr_code_key | string | PIX QR Code 的标识密钥 |
| qr_code_url | string | PIX QR Code 付款 URL |
| digitable_line | string | 银行 Boleto 的可输入行 |

---

# 简介

URL: /zh-Hans/documentation/emissao_de_divida/introducao

本节将介绍信贷合同的发行、正式化、放款及取消所需的步骤。

## 1. 提交债务发行所需文件

要发行债务，需满足某些监管标准。其中之一是发行信贷的金融机构对债务人的身份识别。为满足这一要求，至少需要提交以下文件：

- **个人债务人**：附有照片的官方证件（身份证或驾驶证）；
- **法人债务人**：公司章程/社会合同、选举会议记录（股份公司情况下）、代表人附照片的官方证件以及授权书（如存在代理人）；

发送文件时，请使用我们的[文件上传端点](../upload_de_documentos)。

:::danger 注意！

QI Tech 提供入职、OCR 文件验证和反欺诈解决方案。

[点击此处查看该服务的 API 文档。](/documentation/caas/onboarding/natural_person)

如需报价，请联系我们的商务团队：

comercial@qitech.com.br 或 (11) 2339-4763
:::

## 2. 债务模拟

QI Tech 为客户提供了在实际发行前[模拟信贷操作金额](simulacao_de_divida_novo)的功能。模拟遵循与债务发行请求相同的模式，但无需提供债务人的注册信息和放款账户信息。此外，我们还支持通过单次请求进行多次模拟。

## 3. 债务发行
确定信贷操作草案后，QI Tech 支持团队将在平台上配置合同参数，之后可通过债务发行端点生成 PDF，具体情况如下：
- [个人债务发行。](emissao/emissao_de_divida_pf)
- [法人债务发行。](emissao/emissao_de_divida_pj)

## 4. 签署信贷合同
签署流程因可用产品而异。
如需了解签署配置，[请点击此处](formalizacao/introducao_formalizacao)。

## 5. 向债务人放款
放款是自动进行的，可通过两种方式配置。
如需了解放款配置，[请点击此处](emissao/exemplo_payloads_desembolso)。

---
## 转让流程
完成上述所有步骤后，进入债务转让流程，该流程 100% 由 QI Tech 主导。

如需了解放款的更多详情，[请点击此处](desembolso_da_operacao)。

---

# 银行代理人监控

URL: /zh-Hans/documentation/emissao_de_divida/mcb

## 1. 查询信贷代理人：

### 请求

ENDPOINT /mcb/credit_agent/[CPF-DO-AGENTE]
MÉTODO GET

#### 查询参数

| 枚举值 | 描述 |
|------------------------------|------------------------------------------------------------------|
| **include_history** | 在查询中返回代理人评分历史所需的参数 |

### 响应

ENDPOINT /mcb/credit_agent/[CPF-DO-AGENTE]
MÉTODO GET
HTTP STATUS 200

响应体

```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"
        }
    ]
}
```

### 响应体详情

| 字段 | 类型 | 描述 |
|---| ---| ---|
| `document_number` | string | 信贷代理人的 CPF。 |
| `credit_agent_status` | string | 信贷代理人状态。 |
| `block_reason` | string | 信贷代理人被封锁的原因。 |
| `current_score` | number | 代理人当前评分。 |
| `total_score` | number | 代理人累积评分。 |
| `score_expiration_date` | string | 代理人评分到期日期。 |
| `suspension_start_date` | string | 代理人暂停开始日期。 |
| `suspension_end_date` | string | 代理人暂停结束日期。 |
| `credit_agent_history` | list | 代理人更新历史记录。 |
| `reference_date` | string | 更新的参考日期。 |

#### credit_agent_status 枚举值

| 枚举值 | 描述 |
|------------------------------|------------------------------------------------------|
| **active** | 代理人处于活跃状态 |
| **blocked** | 代理人被封锁，无法发起操作 |

#### block_reason 枚举值

| 枚举值 | 描述 |
|------------------------------|------------------------------------------------------|
| **limit_score_reached** | 达到了 Núclea 通报的评分上限。 |
| **expired_certificate** | 因证书过期而被封锁。 |
| **rdr_identity_fraud** | 因在 RDR 投诉系统中发现身份欺诈而被封锁。 |
| **fraud_report** | 因在 MCB 中被两家以上金融机构举报欺诈而被封锁。 |
| **operation_irregularity** | 因操作违规而被封锁。 |
| **other** | 其他封锁原因。 |

## 2. 查询信贷代理人在 CRCP 的认证：

### 请求

ENDPOINT /mcb/credit_agent/[CPF-DO-AGENTE]/certificate
MÉTODO GET

STATUS 200

响应体

```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

响应体

```json
{
	"title": "Not Found",
	"description": "Credit agent not found.",
	"translation": "Agente de crédito não encontrado.",
	"code": "MCB000004"
}
```

### 响应体详情

| 字段 | 类型 | 描述 |
|---| ---| ---|
| `document_number` | string | 信贷代理人的 CPF。 |
| `name` | string | 认证代理人姓名。 |
| `certificate_list` | list | 与信贷代理人关联的证书列表。 |
| `certifier_name` | string | 认证机构名称。 |
| `certifier_code` | string | 证书类型代码。 |
| `title` | string | 证书标题。 |
| `certificate_number` | string | 证书编号。 |
| `exam_date` | string | 认证考试日期。 |
| `expiration_date` | string | 证书到期日期。 |
| `certificate_status` | string | 查询时证书的状态。 |

#### certificate_status 枚举值

| 枚举值 | 描述 |
|------------------------------|------------------------------------------------------|
| **active** | 证书处于有效状态 |
| **excluded** | 证书已被认证机构注销 |

---

# Metadata

URL: /zh-Hans/documentation/emissao_de_divida/metadata

允许通过自定义键值对查询信贷操作的对象。

## 1. 创建 Metadata

### 请求体对象
| 字段 | 类型 | 描述 | 最大字符数 | 
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **metadata_key** * | string | Metadata 键 | 100 |
| **metadata_value** * | string | Metadata 值 | 100 |

### 请求

ENDPOINT /credit_operation/[CREDIT-OPERATION-KEY]/metadata
MÉTODO POST

请求体

```json
{
    "metadata_key": "key",
    "metadata_value": "value"
}
```

## 2. 删除 Metadata

### 请求

ENDPOINT /credit_operation/[CREDIT-OPERATION-KEY]/metadata
MÉTODO DELETE

请求体

```json
{
    "metadata_key": "key",
    "metadata_value": "value"
  }
```

## 3. 通过 Metadata 查询信贷操作

:::caution 
通过 metadata 查询时，必须同时提供"metadata_key"和"metadata_value"两个字段。
:::

### 请求

ENDPOINT /credit_operations
MÉTODO GET
<div className='badge
badge--primary'>PARAMETERS page, page_size, metadata_key, metadata_value, credit_operation_status

### 响应

响应体
```json
{
    "data": [
        {
            "credit_operation_key": "cc217253-e89f-4d14-bf89-fb29afaa2895",
            "contract_number": "0000000007/WO",
            "credit_operation_status": "waiting_signature",
            "installments": [],
            "disbursement_options": [],
            "related_parties": []
        }
    ],
    "pagination": {
        "current_page": 1,
        "next_page": 2,
        "rows_per_page": 10,
        "total_pages": 1,
        "total_rows": 1,
        "contain_last_page": true
    }
}

```

---

# 请勿打扰

URL: /zh-Hans/documentation/emissao_de_divida/nao_me_perturbe

"请勿打扰"（Não Me Perturbe）是由电信运营商创建的平台，允许消费者注册其电话号码以拒绝接受电话营销。在信贷背景下，其使用已被纳入由 Febraban、ABBC 和 CNF 等机构推动的信贷自律指导方针，旨在加强消费者保护，遏制信贷营销中的侵权行为。

作为遵守"请勿打扰"规定的金融机构，我们实施了预检机制，确保不会向已在屏蔽名单中注册的电话号码发起主动呼叫。通过此 API，可以在尝试联系信贷借款人之前，查询特定号码是否已注册在"请勿打扰"数据库中。

此核查对于确保遵循商业行为最佳实践、尊重消费者隐私至关重要。

:::caution 注意
必须在拨打给借款人的电话之前进行查询。
:::

## 使用方法

要进行查询，需要将借款人的电话号码发送到以下端点。

ENDPOINT /do_not_disturb?phone_number=11999999999
MÉTODO GET

:::caution 注意
电话号码必须以区号 + 号码的格式发送，例如：11999999999。
:::

### 响应

STATUS 200 - 号码在"请勿打扰"名单中 已找到
STATUS 404 - 号码在"请勿打扰"名单中 未找到

:::caution 注意
如果号码在"请勿打扰"名单中 已找到 ，则不得进行呼叫。
:::

---

# 简介

URL: /zh-Hans/documentation/emissao_de_divida/reapresentacao_de_conta_bancaria

本页将帮助您在放款失败后重新提交银行账户信息

### 1 - 更新银行账户

首先，您需要更新借款人的银行账户信息

#### 请求

ENDPOINT /debt/DEBT/disbursement_bank_accounts
MÉTODO PUT

请求体

**使用银行账户信息**

```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
		}]
}
```

**使用 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 - 更新放款日期

然后，您需要更新放款日期

#### 请求

ENDPOINT /debt/DEBT/disbursement_option
MÉTODO PATCH

请求体

**更新放款日期**

```json
{
    "disbursement_date": "2025-11-28",
    "status": "active"
}
```

---

# 重新发送信贷合同关联方文件

URL: /zh-Hans/documentation/emissao_de_divida/reenviar_documentos_das_partes_relacionadas

## 请求

ENDPOINT /debt/ DEBT-KEY /related_party/ RELATED-PARTY-KEY /attached_document
MÉTODO POST

**请求体**

```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"
}

```

### 路径参数

| 字段 | 类型 | 描述 |
|---|---|---|
| `debt_key` * | string | 操作的 debt_key。 |
| `related_party_key` * | string | 需要发送文件的关联方的密钥。 |

### 请求体参数

| 字段 | 类型 | 描述 | 字符数 | 
|---|---| ---| ---|
| `document_identification` | string | person_type 为"natural"时的身份证或驾驶证正面。 | uuid 密钥 | 
| `document_identification_back` | string | person_type 为"natural"时的身份证或驾驶证背面。 | uuid 密钥 | 
| `wedding_certificate` | string | person_type 为"natural"时的结婚证。 | uuid 密钥 | 
| `proof_of_residence` | string | person_type 为"natural"时的居住证明。 | uuid 密钥 | 
| `company_statute` | string | person_type 为"legal"时的公司章程。 | uuid 密钥 | 
| `insurance_agreement` | string | 信贷操作保险合同证据。 | uuid 密钥 | 

## 响应

STATUS 201

**响应体**

```json
"
{}
"
```

STATUS 400

**响应体**

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

---

# 放款后操作

URL: /zh-Hans/documentation/emissao_de_divida/reprocessar_acao_pos_desembolso

## 1. 放款后操作执行成功或失败的 Webhooks

:::info 提示
*action_key* 是放款后操作的标识密钥。

:::

### 成功

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": {}
        }
    ],
    "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": {}
        }
    ],
    "webhook_type": "debt_actions",
    "event_datetime": "2024-07-04 10:03:33"
}
```

  

### 放款后操作错误

如果放款后操作付款发生错误，合作方将通过以下 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"
}
```

### 放款后操作 TED 冲销

如果放款后操作中执行的 TED 被目标金融机构退回，合作方将通过以下 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. 更改操作数据后重新处理放款后操作

如果放款后操作付款发生错误/冲销，可通过以下端点重试：

### 路径参数

| 字段 | 类型 | 描述 |
|---|---| ---|
| `action_key` * | string | 创建信贷操作时返回的操作密钥。 | 

### 请求

ENDPOINT /baas/action/ ACTION-KEY
MÉTODO PATCH

请求体

**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
}
```
  
  
**Boleto 可输入行**

```json
{
    "digitable_line": "10495419967200010004900031456924592920008041111"
}
```

**PIX 复制粘贴**

```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. 不更改数据重新处理放款后操作

### 请求

ENDPOINT /baas/action/action_retry/ ACTION-KEY
MÉTODO PATCH

:::info 信息
两个端点的响应相同。
:::

### 响应

STATUS 200

响应体

```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

响应体

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

```

STATUS 402

响应体

```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\"}"
}

```

---

# 重新计算信贷合同

URL: /zh-Hans/documentation/emissao_de_divida/reprocessar_contrato

此端点可用于通过调整分期金额来重新计算信贷操作。

## 请求

ENDPOINT /debt/ DEBT-KEY /recalculate_operation
MÉTODO POST

**请求体**

```json
{
    "financial": {
        "installment_face_value": 250,
        "disbursement_date": "2025-01-20"
    }
}
```

### 路径参数

| 字段 | 类型 | 描述 |
|---|---| ---|
| `debt_key` * | string | 创建信贷操作时返回的债务密钥。 |

### 请求体参数

| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---| ---| 
| `financial` * | string | 包含放款日期的简化 financial 对象。 | [financial 对象](#objeto-financial) |

### financial 对象

| 字段 | 类型 | 描述 | 字符数 | 
|---|---|---|---|
| `installment_face_value` | float | 分期金额 | 10 |

## 响应

STATUS 200

**响应体**

```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": [],
      "urls": []
    },
    "contract_fee_amount": 50000,
    "contract_fees": [],
    "external_contract_fee_amount": 0,
    "external_contract_fees": [],
    "installments": [],
    "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

**响应体**

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

```

---

# 更改放款数据

URL: /zh-Hans/documentation/emissao_de_divida/reprocessar_multiplas_datas/trocar_conta

## 请求

ENDPOINT /debt/ DEBT-KEY /disbursement_bank_accounts
MÉTODO PUT

### 路径参数

| 字段 | 类型 | 描述 |
|---|---| ---|
| `debt_key` *（必填）* | string | 已发行债务的 ID。 |

**请求体**

```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
	}]
}
```

### 请求体参数

债务发行必须包含放款的银行账户信息，默认情况下为债务人名下的账户。

| 字段 | 类型 | 描述 | 最大字符数 | 
|-----------------------|--------|----------------------------------------------------------------------------------------------------|--------------|
| name * | string | 账户持有人姓名 | 50 |
| document_number * | string | 账户持有人 CPF | 11 |
| bank_code * | string | 金融机构的 COMPE 代码（https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf） | 3 |
| branch_number * | string | 支行号码（请勿填写支行验证位！） | 4 |
| account_number * | string | 账号（不含验证位！） | 10 |
| account_digit * | string | 账户验证位（字母处填写零） | 1 |
| account_type | enum | [账户类型枚举值](#enumerador-account-type) 账户类型 | 1 |

## 响应

STATUS 200

**响应体**

```json
{}
```

STATUS 400

**响应体**

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

---

# 更改放款日期

URL: /zh-Hans/documentation/emissao_de_divida/reprocessar_multiplas_datas/trocar_data

## 请求

ENDPOINT /debt/ DEBT-KEY /disbursement_option
MÉTODO PATCH

### 路径参数

| 字段 | 类型 | 描述 |
|---|---| ---|
| `debt_key` *（必填）* | string | 已发行债务的 ID。 |

**请求体**

```json
{
    "disbursement_date": "2023-06-30",
    "status": "active"
}
```

### 请求体参数

| 字段 | 类型 | 描述 |
|---|---| ---|
| `disbursement_date` | string | 操作的放款日期。 |
| `status` | string | 表示日期是否应被配置或删除。 |

## 响应

STATUS 200

**响应体**

```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": []
		},
		"contract_fee_amount": 0.5,
		"contract_fees": [],
		"disbursed_issue_amount": 4530.98,
		"installments": [],
		"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

**响应体**

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

---

# 保险

URL: /zh-Hans/documentation/emissao_de_divida/seguro

QI Tech 为客户提供在信贷操作中附加保险的可能性，本文将帮助您了解如何在我们的 API 中使用该产品并深入了解该新产品。

:::caution 注意
该产品仅对已注册的合作方开放，请咨询我们的商务团队了解更多详情。
:::

## 如何使用

要订购保险或模拟含保险的债务，应在回扣列表中添加类型为 "insurance_premium_qi" 的回扣，无需声明任何金额，因为金额将根据提案的发行金额和所订购的保险产品计算。

:::caution 注意
不能将 tac 或 **insurance_premium** 类型的回扣与 **insurance_premium_qi** 一起使用。
:::

回扣对象

```json
{
  "rebates": [
    {
      "fee_type": "insurance_premium_qi",
      "description": "insurance_premium_plus"
    }
  ]
}
```

## 债务模拟

### 请求

下面的示例描述了一次包含保险报价的债务模拟请求。

ENDPOINT /fgts_simulation
MÉTODO POST

请求体

```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"
      }
    ]
  }
}
```

### 响应

STATUS 200

响应体

```json
{
    "type": "debt",
    "key": "a445c71c-d752-4159-82bf-097d8125b66c",
    "status": "finished",
    "event_datetime": "2024-10-03 00:26:26",
    "data": {}
}
```

:::danger 警告
可以在模拟阶段验证保险收费的资格。\
为此，必须提供出生日期（**birth_date**）、债务人的 CPF（**document_number**）以及回扣 "**insurance_premium_qi**"。\
如果 CPF 符合资格，将返回成功响应；如果不符合资格，模拟请求将返回错误。
:::

:::danger 警告
提交出生日期（**birth_date**）**在含保险的模拟中不是必填项**。但在债务发行时，若订购了该产品，则该字段为必填项。
:::

## 查询 CPF 的保险资格

持有 **CPF** 数据后，可以查询该 CPF 的资格。

### 请求

ENDPOINT /debts/borrower/[document_number]/insurance_premium_eligibility?birth_date=1994-06-11&issue_amount=150
METHOD GET

### 参数

| 字段 | 描述 |
|-------------------|-----------------------------------------|
| `document_number` | 债务人的 CPF 号码 |
| `birth_date` | 出生日期 |
| `issue_amount` | 信贷操作的发行金额 |

### 响应

STATUS 200

响应体

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

### 描述
| 字段 | 类型 |
|------------------------------|--------|
| `elegible` | boolean |

:::caution 注意
对于返回 **"elegible": false** 的 CPF，含 **insurance_premium_qi** 的模拟和债务发行都将不可能执行。
:::

## 创建债务

要创建含保险的债务，需要借款人的一些必填数据，如**地址、电话、电子邮件和出生日期**。如果省略其中任何数据，债务将无法发行。

### 请求

ENDPOINT /debt
MÉTODO POST

请求体

```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"
}
```

### 响应

STATUS 201

响应体

```json
{
  "webhook_type": "debt",
  "key": "7a9bb512-7b38-4dbc-a109-1bc122b67a4a",
  "status": "waiting_signature",
  "event_datetime": "2023-03-03 18:06:18",
  "data": {}
}
```

## Webhooks

### 保险已发行

保险将在操作放款后发行，当保险发行完成时，将发送以下包含保险数据的 webhook。

:::caution 注意
收到保险票据已发行的 webhook 时，必须将生成的票据文件传送给信贷借款人。
:::

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"
}
```

### 保险已取消

当信贷借款人希望放弃信贷操作且操作被撤销、超过某个承保限额（导致不符合保险资格），或借款人仅放弃保险时，保险可被取消。

:::caution 注意
保险票据只能在信贷操作放款后 7 个自然日内全额取消；如果在此之后取消，退还金额将按保险期限比例计算。
:::

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"
}
```

### 取消原因

| cancel_reason | 描述 |
|-------------------------------|----------------------------------------|
| `reversed_operation` | 操作已撤销，保险已取消 |
| `cover_limit_amount_exceeded` | 仅保险被取消。某个承保限额被超过，无法发行保险 |
| `insurance_premium_cancel` | 仅保险被取消。借款人直接与保险公司取消 |

## 保险查询

### 请求

ENDPOINT /debt/[debt_key]/insurance_premiums
METHOD GET

### 响应

STATUS 200

响应体

```json
{
  "data": [],
  "pagination": {
    "current_page": 0,
    "next_page": 0,
    "rows_per_page": 1
  }
}
```

### 请求

ENDPOINT /debt/[DEBT-KEY]/insurance_premium/[INSURANCE-PREMIUM-KEY]
METHOD GET

### 响应

STATUS 200

响应体

```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,
  "covers": [],
  "policy_number": "1098200000008",
  "prize_number": "3907",
  "insurance_premium_net_amount": 1145.63,
  "iof_amount": 4.37
}
```

## 查询票据文件

:::caution 注意
文件链接有效期为 15 分钟。
:::

### 请求

ENDPOINT /document/[DOCUMENT-KEY]/url
METHOD GET

### 响应

STATUS 200

响应体

```json
{
    "document_key": "a11dc0fe-51ed-41aa-bb40-bca80d6e515b",
    "signed_document_url": null,
    "document_url": "https://storage.googleapis.com/dev-doc-api-private/documents/...",
    "expiration_datetime": "2023-03-03T19:08:53.000Z"
}
```

---

# 债务模拟（旧版）

URL: /zh-Hans/documentation/emissao_de_divida/simulacao_de_divida_antigo

QI Tech 为客户提供在实际发行前模拟信贷操作金额的功能。模拟遵循与债务发行请求相同的模式，但无需提供债务人的注册信息和放款账户数据。

## 请求

以下示例描述了一次债务模拟请求。

ENDPOINT /debt_simulation
MÉTODO POST

请求体

**到期日和分期金额**

```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"
                }
            }
        ]
    }
}
```

**利率和分期日期**
```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"
    ]
  }
}
```

## 响应

STATUS 200

响应体

```json
{
    "type": "debt",
    "key": "bf84379c-d4cf-4f16-a63c-865c129e6fce",
    "status": "finished",
    "event_datetime": "2025-03-27 22:28:37",
    "data": {}
}

```

## 定义

### 请求体

### Borrower 对象
| 字段 | 类型 | 描述 | 枚举值 |
|---|---|---|---|
| **person_type** | object | 操作债务人的法律性质 | natural 或 legal |

### Financial 对象
| 字段 | 类型 | 描述 | 最大字符数 |
|---|--- |---|---|
| **amout** | float | 信贷操作的发行/名义金额 | - |
| **interest_type** | object | **[利率类型枚举值](#enumerador-interest-type)** - 摊销方法和利率计算方式 | - |
| **credit_operation_type** | object | **[信贷操作类型枚举值](#enumerador-credit-operation-type)** - 信贷合同类型 | - |
| **annual_interest_rate** | float | 以年化小数表示的固定利率 | - |
| **disbursement_date** | date | 操作放款日期 | - |
| **interest_grace_period** | int | 利息宽限期（月） | - |
| **principal_grace_period** | int | 本金宽限期 | - |
| **number_of_installments** | int | 信贷操作的分期数 | - |
| **fine_configuration** | object | **[fine_configuration 对象](#objeto-fine-configuration)** - 逾期利息和罚款配置 | - |

### Fine Configuration 对象
| 字段 | 类型 | 描述 | 最大字符数 |
|---|---|---|---|
| **contract_fine_rate** | float | 以小数表示的逾期罚款百分比 | - |
| **interest_base** | enum | **[利率基准枚举值](#enumerador-interest-base)** - 利率计算基准 | - |
| **monthly_rate** | float | 以小数表示的月逾期利率 | - |

### 响应体
| 字段 | 类型 | 描述 | 最大字符数 |
|----------------------------|--------|---------------------------------|--------------|
| **data.data** | object | **[Data 对象](#objeto-data)** | - |
| **data.event_datetime** | date | 模拟生成时刻 | - |
| **data.key** | string | 模拟的唯一密钥 | - |
| **data.status** | string | _finished_ | - |
| **data.type** | string | _debt_ | - |

### Data 对象
| 字段 | 类型 | 描述 | 最大字符数 |
|-----------------------------------------|--------|-------------------------------------------------------------------------------------------------------------------------------|--------------|
| **annual_cet** | float | 以年化小数表示的总有效成本 | - |
| **assignment_amount** | float | 信贷操作的收购金额 | - |
| **cet** | float | 以月度小数表示的总有效成本 | - |
| **contract_fee_amount** | float | QI Tech 在操作中收取的费用 | - |
| **contract_fees** | object | **[Contract Fees 对象](#objeto-contract-fees)** - QI Tech 在操作中收取的费用列表 | - |
| **credit_operation_type** | enum | **[信贷操作类型枚举值](#enumerador-credit-operation-type)** - 信贷合同类型 | - |
| **disbursed_issue_amount** | float | 信贷操作的放款金额 | - |
| **disbursement_date** | date | 操作放款日期 | - |
| **disbursement_options** | list | 操作的放款选项列表（操作的财务金额可能因放款日期而有所不同） | - |
| **external_contract_fee_amount** | float | QI Tech 向合作方回扣的操作费用金额 | - |
| **external_contract_fees** | list | **[Contract Fees 对象](#objeto-contract-fees)** - QI Tech 向合作方回扣的操作费用列表 | - |
| **final_disbursement_amount** | float | 实际放款给债务人的金额 | - |
| **installments** | list | **[Installments 对象](#objeto-installments)** - 操作分期 | - |
| **interest_grace_period** | int | 利息宽限期（月） | - |
| **interest_payment_month_period** | int | 分期利率收取频率（月） | - |
| **interest_type** | enum | **[利率类型枚举值](#enumerador-interest-type)** - 摊销方法和利率计算方式 | - |
| **iof_amount** | float | IOF 总金额（基础 IOF 和附加 IOF 之和） | - |
| **issue_amount** | float | 信贷操作的发行/名义金额 | - |
| **issue_date** | date | 操作合同发行日期 | - |
| **net_external_contract_fee_amount** | float | QI Tech 向合作方回扣的操作净费用金额 | - |
| **operation_type** | enum | **[操作类型枚举值](#enumerador-operation-type)** | - |
| **post_fixed_interest_base** | enum | **[利率基准枚举值](#enumerador-interest-base)** - 利率计算基准 | - |
| **post_fixed_interest_rate** | object | **[Interest Rate 对象](#objeto-interest-rate)** - 合同浮动利率指数 | - |
| **prefixed_interest_rate** | object | **[Interest Rate 对象](#objeto-interest-rate)** - 合同名义固定利率 | - |
| **principal_amortization_month_period** | int | 分期本金收取频率（月） | - |
| **principal_grace_period** | int | 本金宽限期（月） | - |
| **requester_key** | string | 合作方在 QI 内的唯一标识密钥 | - |
| **total_pre_fixed_amount** | float | 债务人在信贷操作中支付的利息总额 | - |

### Contract Fees 对象
| 字段 | 类型 | 描述 | 最大字符数 |
|-----------------|-------|-----------------------------------------------------------------------------------------------------|--------------|
| **amount** | float | 费用金额（以百分比或绝对值表示，取决于 _amount_type_ 字段的值） | - |
| **amount_type** | enum | **[amount_type 枚举值](#enumerador-amount-type)** - 费用金额单位 | - |
| **fee_amount** | float | 操作中收取的绝对费用金额 | - |
| **fee_type** | enum | **[费用类型枚举值](#enumerador-fee-type)** - 操作中收取的费用类型 | - |

### Installments 对象
| 字段 | 类型 | 描述 | 最大字符数 |
|-----------------------------------|---------|--------------------------------------------------------------------------------|--------------|
| **business_due_date** | date | 分期在工作日的到期日 | - |
| **calendar_days** | int | 分期之间的自然日数 | - |
| **due_date** | date | 分期的自然日到期日 | - |
| **due_principal** | float | 分期到期日付款前的剩余本金 | - |
| **has_interest** | boolean | _true_ - 分期计息指示器 | - |
| **installment_number** | int | 分期编号 | - |
| **post_fixed_amount** | float | 分期支付的浮动利息金额 | - |
| **pre_fixed_amount** | float | 分期支付的固定利息金额 | - |
| **principal_amortization_amount** | float | 分期支付的摊销金额 | - |
| **tax_amount** | float | 分期的基础 IOF | - |
| **total_amount** | float | 分期总金额 | - |
| **workdays** | int | 分期之间的工作日数 | - |

### Interest Rate 对象
| 字段 | 描述 | 最大字符数 |
|-------------------|---------------------------------------------------------------------------------------|--------------|
| **annual_rate** | 以年化小数表示的固定/浮动利率 | - |
| **daily_rate** | 以日度小数表示的固定/浮动利率 | - |
| **interest_base** | **[利率基准枚举值](#enumerador-interest-base)** - 利率计算基准 | - |
| **monthly_rate** | 以月度小数表示的固定/浮动利率 | - |

# 枚举值

### _Person Type_ 枚举值
| 枚举值 | 描述 |
|------------------------|-----------------------|
| **legal** | 法人 |
| **natural** | 自然人 |

### _Account Type_ 枚举值
| 枚举值 | 描述 |
|------------------------|-----------------------|
| **checking_account** | 活期账户 |
| **deposit_account** | 存款账户 |
| **guaranteed_account** | 担保账户 |
| **investment_account** | 投资账户 |
| **payment_account** | 支付账户 |
| **saving_account** | 储蓄账户 |
| **salary_account** | 工资账户 |

### _Amount Type_ 枚举值
| 枚举值 | 描述 |
|------------------------|-----------------------|
| **absolute** | 绝对值 |
| **percentage** | 百分比值 |

### _Interest Type_ 枚举值
| 枚举值 | 描述 |
|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **pre_price_days** | Price 摊销法（等额分期），按日计算固定利率 |
| **pre_price** | Price 摊销法（等额分期），按固定周期（30天）计算固定利率 |
| **pre_sac** | SAC 摊销法（等额本金），按日计算固定利率 |
| **post_sac** | SAC 摊销法（等额本金），按日计算基于固定利率加浮动指数（cdi、ipca 或 igpm）的利率 |
| **post_price** | Price 摊销法（等额分期），按固定周期（30天）计算基于固定利率加浮动指数（cdi、ipca 或 igpm）的利率 |
| **post_price_days** | Price 摊销法（等额分期），按日计算基于固定利率加浮动指数（cdi、ipca 或 igpm）的利率 |

### _Credit Operation Type_ 枚举值
| 枚举值 | 描述 |
|---------------|--------------------------------|
| **ccb** | 银行信贷凭证 |
| **cce** | 出口信贷凭证 |
| **cci** | 房地产信贷凭证 |
| **nce** | 出口信贷票据 |

### _Interest Base_ 枚举值
| 枚举值 | 描述 |
|-----------------------|---------------------------------------------------------------------------|
| **workdays** | 以工作日为基准计算利率，按 252 天/年计算 |
| **calendar_days** | 以自然日为基准计算利率，按 360 天/年计算 |
| **calendar_days_365** | 以自然日为基准计算利率，按 365 天/年计算 |

### _Fee Type_ 枚举值
每种费用类型必须提前由 QI Tech 启用和配置

| 枚举值 | 描述 |
|-----------------------|----------------------------------------------------------------------------|
| **tac** | 开户费 |
| **spread** | 信贷操作收购金额中收取的溢价 |
| **warranty_analysis** | 担保分析费 |
| **ted_fee** | TED 费用 |
| **spread_ted_fee** | 信贷操作收购金额中收取的 TED 费用溢价 |

---

# 债务模拟（新版）

URL: /zh-Hans/documentation/emissao_de_divida/simulacao_de_divida_novo

QI Tech 为客户提供在实际发行前模拟信贷操作金额的功能。模拟遵循与债务发行请求相同的模式，但无需提供债务人的注册信息和放款账户数据。

## 请求

以下示例描述了一次债务模拟请求。

ENDPOINT /v2/credit_operation/simulation
MÉTODO POST

请求体

**到期日和分期金额**

```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
}
```

**放款金额和分期**

 ```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
      }
    ]
  }
 ```

## 响应

STATUS 200

响应体

```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": [],
  "first_due_date": "2024-09-25",
  "installments": [],
  "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
}

```

## 定义

### 请求体

### Payload
| 字段 | 类型 | 描述 | 最大字符数 |
|---|--- |---|---|
| **credit_operation_type** | enum | **[信贷操作类型枚举值](#enumerador-credit-operation-type)** - 信贷合同类型 | - |
| **disbursed_issue_amount** | float | 信贷操作的发行/名义金额 | - |
| **disbursement_date** | date | 操作放款日期 | - |
| **first_due_date** | date | 第一期分期到期日 | - |
| **force_installments_on_workdays** | boolean | _true_ - 分期安排在工作日的指示器 | - |
| **interest_type** | enum | **[利率类型枚举值](#enumerador-interest-type)** - 摊销方法和利率计算方式 | - |
| **issuer_person_type** | enum | **[Person Type 枚举值](#enumerador-person-type)** | - |
| **monthly_interest_rate** | float | 合同的月固定利率 | - |
| **number_of_installments** | int | 信贷操作的分期数 | - |
| **principal_amortization_month_period** | int | 本金摊销月数 | - |
| **installments** | list | **[Installments 对象](#objeto-installments)** - 操作分期 | - |

### 响应体

### Payload
| 字段 | 类型 | 描述 | 最大字符数 |
|-----------------------------------------|--------|-------------------------------------------------------------------------------------------------------------------------------|--------------|
| **annual_cet** | float | 以年化小数表示的总有效成本 | - |
| **assignment_amount** | float | 信贷操作的收购金额 | - |
| **cet** | float | 以月度小数表示的总有效成本 | - |
| **fees** | object | **[Fees 对象](#objeto-fees)** - QI Tech 在操作中收取的费用列表 | - |
| **disbursed_amount** | float | 信贷操作的放款金额 | - |
| **disbursement_date** | date | 操作放款日期 | - |
| **installments** | list | **[Installments Response 对象](#objeto-installments-response)** - 操作分期 | - |
| **interest_type** | enum | **[利率类型枚举值](#enumerador-interest-type)** - 摊销方法和利率计算方式 | - |
| **additional_iof** | float | 附加 IOF 金额 | - |
| **base_iof** | float | 基础 IOF 金额 | - |
| **total_iof** | float | 总 IOF 金额 | - |
| **issue_amount** | float | 信贷操作的发行/名义金额 | - |
| **tax_configuration** | object | **[Tax Configuration 对象](#objeto-tax-configuration)** - 税率值 | - |
| **first_due_date** | date | 第一期分期到期日 | - |
| **prefixed_interest_rate** | object | **[Interest Rate 对象](#objeto-interest-rate)** - 合同名义固定利率 | - |

### Fees 对象
| 字段 | 类型 | 描述 | 最大字符数 |
|-----------------|-------|-----------------------------------------------------------------------------------------------------|--------------|
| **amount** | float | 费用金额（以百分比或绝对值表示，取决于 _amount_type_ 字段的值） | - |
| **amount_type** | enum | **[amount_type 枚举值](#enumerador-amount-type)** - 费用金额单位 | - |
| **fee_amount** | float | 操作中收取的绝对费用金额 | - |
| **fee_type** | enum | **[费用类型枚举值](#enumerador-fee-type)** - 操作中收取的费用类型 | - |
| **type** | enum | **[来源类型枚举值](#enumerador-origin-type)** - 操作中收取的费用来源 | - |

### Installments Request 对象
| 字段 | 类型 | 描述 | 最大字符数 |
|-----------------------------------|---------|--------------------------------------------------------------------------------|--------------|
| **due_date** | date | 分期的自然日到期日 | - |
| **total_amount** | float | 分期总金额 | - |

### Installments Response 对象
| 字段 | 类型 | 描述 | 最大字符数 |
|-----------------------------------|---------|--------------------------------------------------------------------------------|--------------|
| **calendar_days** | int | 分期之间的自然日数 | - |
| **due_date** | date | 分期的自然日到期日 | - |
| **due_principal** | float | 分期到期日付款前的剩余本金 | - |
| **has_interest** | boolean | _true_ - 分期计息指示器 | - |
| **installment_number** | int | 分期编号 | - |
| **prefixed_amount** | float | 分期支付的固定利息金额 | - |
| **principal_amortization_amount** | float | 分期支付的摊销金额 | - |
| **tax_amount** | float | 分期的基础 IOF | - |
| **amount** | float | 分期总金额 | - |
| **due_interest** | float | 分期到期日付款前的剩余利息 | - |
| **period** | float | 分期周期 | - |
| **period_workdays** | float | 分期工作日周期 | - |
| **period_to_disbursement** | float | 到放款的周期 | - |
| **period_workdays_to_disbursement** | float | 到放款的工作日周期 | - |
| **calendar_days_to_disbursement** | int | 到放款的自然日数 | - |
| **workdays** | int | 分期之间的工作日数 | - |
| **workdays_to_disbursement** | int | 到放款的工作日数 | - |

### Interest Rate 对象
| 字段 | 描述 | 最大字符数 |
|-------------------|---------------------------------------------------------------------------------------|--------------|
| **annual_rate** | 以年化小数表示的固定/浮动利率 | - |
| **daily_rate** | 以日度小数表示的固定/浮动利率 | - |
| **interest_base** | **[利率基准枚举值](#enumerador-interest-base)** - 利率计算基准 | - |
| **monthly_rate** | 以月度小数表示的固定/浮动利率 | - |

### Tax Configuration 对象
| 字段 | 描述 | 最大字符数 |
|-----------------------|---------------------------------------------------------------------------------------|--------------|
| **base_rate** | 基础税率值 | - |
| **additional_rate** | 附加税率值 | - |

# 枚举值

### _Person Type_ 枚举值
| 枚举值 | 描述 |
|------------------------|-----------------------|
| **legal** | 法人 |
| **natural** | 自然人 |

### _Account Type_ 枚举值
| 枚举值 | 描述 |
|------------------------|-----------------------|
| **checking_account** | 活期账户 |
| **deposit_account** | 存款账户 |
| **guaranteed_account** | 担保账户 |
| **investment_account** | 投资账户 |
| **payment_account** | 支付账户 |
| **saving_account** | 储蓄账户 |
| **salary_account** | 工资账户 |

### _Amount Type_ 枚举值
| 枚举值 | 描述 |
|------------------------|-----------------------|
| **absolute** | 绝对值 |
| **percentage** | 百分比值 |

### _Interest Type_ 枚举值
| 枚举值 | 描述 |
|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **pre_price_days** | Price 摊销法（等额分期），按日计算固定利率 |
| **pre_price** | Price 摊销法（等额分期），按固定周期（30天）计算固定利率 |
| **pre_sac** | SAC 摊销法（等额本金），按日计算固定利率 |
| **post_sac** | SAC 摊销法（等额本金），按日计算基于固定利率加浮动指数（cdi、ipca 或 igpm）的利率 |
| **post_price** | Price 摊销法（等额分期），按固定周期（30天）计算基于固定利率加浮动指数（cdi、ipca 或 igpm）的利率 |
| **post_price_days** | Price 摊销法（等额分期），按日计算基于固定利率加浮动指数（cdi、ipca 或 igpm）的利率 |

### _Credit Operation Type_ 枚举值
| 枚举值 | 描述 |
|---------------|--------------------------------|
| **ccb** | 银行信贷凭证 |
| **cce** | 出口信贷凭证 |
| **cci** | 房地产信贷凭证 |
| **nce** | 出口信贷票据 |

### _Interest Base_ 枚举值
| 枚举值 | 描述 |
|-----------------------|---------------------------------------------------------------------------|
| **workdays** | 以工作日为基准计算利率，按 252 天/年计算 |
| **calendar_days** | 以自然日为基准计算利率，按 360 天/年计算 |
| **calendar_days_365** | 以自然日为基准计算利率，按 365 天/年计算 |

### _Fee Type_ 枚举值
每种费用类型必须提前由 QI Tech 启用和配置

| 枚举值 | 描述 |
|-----------------------|----------------------------------------------------------------------------|
| **tac** | 开户费 |
| **spread** | 信贷操作收购金额中收取的溢价 |
| **warranty_analysis** | 担保分析费 |
| **ted_fee** | TED 费用 |
| **spread_ted_fee** | 信贷操作收购金额中收取的 TED 费用溢价 |

### _Origin Type_ 枚举值
每种费用类型必须提前由 QI Tech 启用和配置

| 枚举值 | 描述 |
|-----------------------|----------------------------------------------------------------------------|
| **internal** | 内部来源费用 |
| **external** | 外部来源费用 |

---

# 在沙盒中模拟错误

URL: /zh-Hans/documentation/emissao_de_divida/simulando_erros

本页将帮助您在沙盒环境中模拟错误。

# 用于模拟放款错误的数据

使用以下银行数据，您可以模拟操作放款失败，以用于重新提交银行账户数据。

```json
account_digit: 0
account_number: 11581339
bank_code: 001
branch_number: 2874
document_number: 根据借款人文件调整
Nome: 根据借款人姓名调整
```

# 使用 QI Sign 签署时模拟错误的数据

在借款人文件的 开头 使用以下数字，您可以模拟 QI Sign 签署流程中的错误。

文件开头数字：
```json
0: 签署时检测到欺诈
8: 人脸活体验证失败
9: 人脸验证未达到最低允许分数
```

---

# 债务的可能状态

URL: /zh-Hans/documentation/emissao_de_divida/status_de_uma_divida

## 状态机
发行信贷合同后，可通过 QI Tech 平台的 Webhook 跟踪合同状态。

合同所经历的状态如下所述：

**waiting_signature**

合同发行后，首先处于"等待签署"状态，该状态持续到签署流程完成为止。

**signature_finished**

这是一个过渡状态，在收到最后一个签名后，合同会短暂进入"signature_finished"状态，此时 webhook 触发，随即转入下一状态。

**signed** 

签署完成后，合同状态变为"已签署"。

**issued**

这是一个过渡状态，在合同的放款日期当天，合同进入"issued"状态，等待放款后转入下一状态。

**disbursed**

这是一个过渡状态，放款完成后，合同会短暂进入"disbursed"状态，此时 webhook 触发，随即转入下一状态。

**opened**

放款后，合同状态变为"未结"——如果 QI Tech 不是该操作的催收代理，这将是最终状态。

**settled**

当 QI Tech 是信贷操作的催收代理时，合同将持续跟踪直至结清。最后一期还款完成后，状态变为"settled"，并触发 Webhook。

**canceled**

该状态表示操作流程中发生了某些错误，例如向债务人放款失败，或合同未在规定时间内完成签署。

**canceled_permanently**

当合同附有担保/背书时，这将是最终状态，表示担保/背书已释放，合同已被永久取消。

---

# 错误目录

URL: /zh-Hans/documentation/erros/catalogo_de_erros

QI Tech 所有 API 均以标准格式返回错误：

```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"
}
```

## 全局错误 (GDF)

平台所有 API 的通用错误。

| HTTP 状态码 | 错误代码 | 标题 | 描述 | 解决方案 |
|-|-|-|-|-|
| 400 | GDF000003 | Bad Request | No API Client Key received | 在请求中包含带有您 API 密钥的 `API-CLIENT-KEY` 请求头。 |
| 401 | GDF000014 | QI Unauthenticated | Failed while decoding the authentication token | 请验证 JWT token 是否正确使用您的 EC512 私钥进行签名。参阅[认证测试](/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2)。 |
| 404 | GDF000018 | Not Found | No ClientIntegration found for api_client_key | 请验证发送的 `API-CLIENT-KEY` 是否与 QI Tech 面板中注册的密钥一致。 |

## 发行人同质化错误 (ISS)

| HTTP 状态码 | 错误代码 | 标题 | 描述 |
|-|-|-|-|
| 400 | ISS000003 | Bad Request | 发行人已存在于数据库中。 |
| 404 | ISS000004 | Not Found | 发行人代表未找到。 |
| 404 | ISS000005 | Not Found | 银行账户未找到。 |
| 404 | ISS000006 | Not Found | 发行人文件未找到。 |
| 404 | ISS000007 | Not Found | 发行人代表的文件未找到。 |
| 404 | ISS000008 | Not Found | 发行人联系信息未找到。 |
| 404 | ISS000009 | Not Found | 发行人未找到。 |
| 404 | ISS000010 | Not Found | 签署人群组未找到。 |
| 400 | ISS000011 | Bad Request | 发行人必须处于 in_filling 状态才能执行此操作。 |
| 400 | ISS000012 | Bad Request | 不允许删除主账户，请先设置新的主账户。 |
| 400 | ISS000013 | Bad Request | 不允许删除主要联系方式，请先设置新的主要联系方式。 |
| 400 | ISS000014 | Bad Request | 发行人至少需要有一条联系信息。 |
| 400 | ISS000015 | Bad Request | 发行人数据访问权限已授予。 |
| 400 | ISS000016 | Bad Request | 向发行人发送消息失败，请重试。 |
| 400 | ISS000017 | Bad Request | 链接无效。 |
| 400 | ISS000018 | Bad Request | 提交的文件无效或质量过低。 |

## 投资人同质化错误 (INV)

| HTTP 状态码 | 错误代码 | 标题 | 描述 |
|-|-|-|-|
| 400 | INV000003 | Bad Request | 投资人已存在于数据库中。 |
| 404 | INV000004 | Not Found | 投资人代表未找到。 |
| 404 | INV000005 | Not Found | 银行账户未找到。 |
| 404 | INV000006 | Not Found | 投资人文件未找到。 |
| 404 | INV000007 | Not Found | 投资人代表的文件未找到。 |
| 404 | INV000008 | Not Found | 投资人联系信息未找到。 |
| 404 | INV000009 | Not Found | 投资人未找到。 |
| 404 | INV000010 | Not Found | 签署人群组未找到。 |
| 400 | INV000011 | Bad Request | 投资人必须处于 in_filling 状态才能执行此操作。 |
| 400 | INV000012 | Bad Request | 不允许删除主账户，请先设置新的主账户。 |
| 400 | INV000013 | Bad Request | 不允许删除主要联系方式，请先设置新的主要联系方式。 |
| 400 | INV000014 | Bad Request | 投资人至少需要有一条联系信息。 |
| 400 | INV000015 | Bad Request | 投资人数据访问权限已授予。 |
| 400 | INV000016 | Bad Request | 向投资人发送消息失败，请重试。 |
| 400 | INV000017 | Bad Request | 链接无效。 |
| 400 | INV000018 | Bad Request | 提交的文件无效或质量过低。 |

## 商业票据发行错误 (COM)

| HTTP 状态码 | 错误代码 | 标题 | 描述 |
|-|-|-|-|
| 400 | COM000001 | Bad Request | 提供的文件无效。 |
| 400 | COM000002 | Bad Request | 使用此端点前需先配置 Tenant。 |
| 409 | COM000003 | Conflict | 此 Tenant 的配置已存在。 |
| 400 | COM000004 | Bad Request | 指定密钥的投资人不被允许，请检查注册信息。 |
| 400 | COM000005 | Bad Request | 指定密钥的发行人不被允许，请检查注册信息。 |
| 400 | COM000006 | Bad Request | 多投资人操作不可用。 |
| 404 | COM000007 | Not Found | 操作未找到。 |
| 403 | COM000008 | Forbidden | 操作不属于该 Tenant。 |
| 400 | COM000010 | Bad Request | 操作不在 in_filling 状态时无法更新。 |

## 认购错误 (INT)

| HTTP 状态码 | 错误代码 | 标题 | 描述 |
|-|-|-|-|
| 400 | INT000001 | Bad Request | 认购类型无效。 |
| 404 | INT000002 | Not Found | 认购未找到。 |
| 400 | INT000003 | Bad Request | 认购不在 in_filling 状态时无法更新。 |
| 400 | INT000004 | Bad Request | 支付类型无效。 |

---

# Amortização Extraordinária

URL: /zh-Hans/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 cinco tipos suportados ficam no campo `amortization_type`:

- `equal_amount` (valores proporcionais) — distribui proporcionalmente o valor informado entre as parcelas vencidas primeiro e depois entre as futuras.
- `first_installments` (primeiras parcelas) — aplica o valor sequencialmente às N primeiras parcelas 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.

Apenas `early_amortization` permite pagamento parcial — os outros quatro 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: /zh-Hans/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: /zh-Hans/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**

Existem dois modos de criação. **Modo 1 — Targeted** exige `installment_list` (array de `installment_number`, inteiros ≥ 1) e é usado com os tipos `early_amortization`, `present_amount` e `matured_installments`. **Modo 2 — Acquittance** não recebe `installment_list` e é usado com os tipos `equal_amount` e `first_installments`. Os números enviados em `installment_list` são resolvidos pelo serviço contra `installment_number` da `security` correspondente.

Exemplo — Modo 1 (`early_amortization`):

```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 — Modo 2 (`equal_amount`):

```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"
}
```

### **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`.                                                                  |
| `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) | Condicional  | Lista de `installment_number` (não UUIDs) das parcelas-alvo, com `minItems: 1`. Obrigatório para `present_amount`, `matured_installments` e `early_amortization`. Omita para `equal_amount` e `first_installments` para usar distribuição por acquittance (Modo 2). 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         | Não          | Utilizado apenas com `first_installments`, quando `installment_list` não é informado.                                                                                                                       |

---

## **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 (quando aplicável).                      |
| `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 cinco valores suportados.                                     |
| EVC100002  | 400  | `installment_list` é obrigatório (e não vazio) para `present_amount`, `matured_installments` ou `early_amortization`. |
| EVC100003  | 400  | `number_of_installments` é obrigatório para `first_installments` quando `installment_list` não é enviado. |
| 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.                |

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)

---

# 模拟特别摊销现值

URL: /zh-Hans/documentation/escrituracao/amortizacao-extraordinaria/endpoints/simular-valor-presente

本端点用于模拟 `present_amount` 类型的特别摊销，但不会创建任何事件——它是纯计算，没有任何副作用。服务会根据 `installment_list` 中指定的分期，计算并返回将要创建的特别事件的总 `amount`（现值），以及每个分期对应的 `event_conciliation`（`extraordinary` 类型）的现值——集成方无需在自己一侧计算现值。

请求中不发送 `amortization_type`：由于这是现值模拟，类型始终为 `present_amount`。`amount` 也不发送——它是计算的结果。`reference_date` 由调用方提供，是服务用于判定逾期分期并按比例（pro-rata）折算现值的唯一时间参考；在模拟中，`due_date` 被视为等于 `reference_date`。

响应即为可直接使用的创建请求体：只需移除仅作展示用途的 `event_conciliation_list` 字段，再将其作为[创建特别摊销](./criar-amortizacao)的请求体发送，即可执行所模拟的摊销。

---

## **Request**
ENDPOINT /event_conciliation/extraordinary_event/present_value_simulation
METHOD 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**

| 字段               | 类型                     | 必填 | 说明                                                                                                                                                                             |
|--------------------|--------------------------|------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `security_key`     | string (UUID)            | 是   | 将被模拟摊销的资产（`security`）的唯一键。                                                                                                                                       |
| `investment_key`   | string (UUID)            | 是   | 目标投资的键。用作现值计算的比例基础。                                                                                                                                           |
| `reference_date`   | string (date)            | 是   | `YYYY-MM-DD` 格式的参考日期。**由调用方提供**——服务将其作为"今天"来判定逾期分期并应用现值的按比例折算。在模拟中也用作 `due_date`。                                              |
| `installment_list` | array of integers (≥ 1)  | 是   | 目标分期的 `installment_number` 列表（不是 UUID），`minItems: 1`。服务会将每个编号与 `security` 的 `installment_number` 进行匹配；不存在的编号返回 `EVC000007`。                  |

与创建不同，`amortization_type`、`amount` 和 `due_date` **不需要发送**：类型始终为 `present_amount`，`amount` 由服务计算，`due_date` 被视为等于 `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**

| 字段                      | 类型              | 说明                                                                                                                               |
|---------------------------|-------------------|-----------------------------------------------------------------------------------------------------------------------------------|
| `security_key`            | string (UUID)     | 资产键——回显所发送的值。                                                                                                           |
| `investment_key`          | string (UUID)     | 目标投资键——回显所发送的值。                                                                                                       |
| `amortization_type`       | string            | 始终为 `present_amount`——由服务填充，用于组成创建请求体。                                                                          |
| `amount`                  | number            | 为特别事件计算出的总现值（等于 `event_conciliation_list` 中各 `amount` 之和）。                                                    |
| `reference_date`          | string (date)     | 参考日期——回显所发送的值。                                                                                                         |
| `due_date`                | string (date)     | 目标结算日期——等于所发送的 `reference_date`。                                                                                      |
| `installment_list`        | array of integers | 目标分期——回显所发送的值。                                                                                                         |
| `event_conciliation_list` | array             | 将要生成的各分期 `event_conciliation`（`extraordinary` 类型）的现值。**仅供展示——不属于创建请求体。** **[Object event_conciliation_list](#object-event_conciliation_list)**。 |

:::info
`event_conciliation_list` 字段**仅用于展示**每个分期的现值模拟结果——**不得**包含在特别事件的创建请求体中。要执行所模拟的摊销，请移除 `event_conciliation_list` 后，将响应作为[创建特别摊销](./criar-amortizacao)的请求体发送。
:::

### **Object event_conciliation_list**

| 字段                 | 类型    | 说明                                                                                          |
|----------------------|---------|------------------------------------------------------------------------------------------------|
| `installment_number` | integer | 此对账事件所对应分期的编号（`installment_number`）。                                          |
| `amount`             | number  | 为该分期的 `event_conciliation`（`extraordinary` 类型）计算出的现值。                          |

---

## **Errors**

| 代码       | HTTP | 含义                                                                                                                     |
|------------|------|---------------------------------------------------------------------------------------------------------------------------|
| EVC100002  | 400  | `installment_list` 为必填且不能为空。                                                                                    |
| EVC100004  | 400  | 某个所提供的分期不属于目标 `security`。                                                                                  |
| EVC000007  | 404  | `installment_list` 中的某个整数与 `security` 的任何 `installment_number` 都不匹配（`InstallmentNumberNotFound`）。       |
| QIT000001  | 400  | Schema 校验失败——例如 `installment_list` 的某项不是 ≥ 1 的整数。                                                         |
| EVC100008  | 400  | 该分期已存在待处理的特别摊销——请先取消，再进行模拟/创建。                                                                 |
| EVC100013  | 424  | 依赖服务暂时不可用（Failed Dependency）。为暂时性问题——恢复后请重试。                                                    |

`EVC100005`（`amount` 不足）不适用于模拟——`amount` 由服务计算，无需发送。

完整的错误处理请参阅[错误目录](/documentation/escrituracao/catalogo-erros/catalogo-erros)。

---

## **See also**

- [创建特别摊销](./criar-amortizacao)
- [查询特别摊销](./consultar-amortizacao)
- [概念](../conceito)
- [集成指南](../../roteiro-integracao/roteiro-integracao-padrao)
- [业务规则](../regras-de-negocio)
- [示例](../exemplos)

---

# Exemplos — Amortização Extraordinária

URL: /zh-Hans/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.

## 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.
- **`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: /zh-Hans/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: /zh-Hans/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`) parte desse campo.

## Tipos de amortização

Os 5 tipos suportados e como cada um se combina com os modos de criação:

| Tipo                   | Modo                   | `installment_list`     | Regra de distribuição                                              | Permite pagamento parcial |
|------------------------|------------------------|------------------------|--------------------------------------------------------------------|---------------------------|
| `equal_amount`         | Modo 2 (Acquittance)   | Não envia              | Proporcional, vencidas primeiro e depois futuras                   | Não                        |
| `first_installments`   | Modo 2 (Acquittance)   | Não envia              | Sequencial nas N primeiras parcelas                                | Não                        |
| `present_amount`       | Modo 1 (Targeted)      | Envia                  | Explícita por parcela; desconto ordena juros → multa → principal    | Não                        |
| `matured_installments` | Modo 1 (Targeted)      | Envia                  | Apenas parcelas já vencidas                                        | Não                        |
| `early_amortization`   | Modo 1 (Targeted)      | Envia (exatamente 1)   | Uma única parcela futura com suporte a pagamento parcial           | **Sim**                    |

**Modo 1 — Targeted** (com `installment_list` — array de `installment_number` inteiros): usa o endpoint PV per-installment — uma chamada por parcela selecionada. O serviço resolve cada `installment_number` para a parcela correspondente da `security`. **Modo 2 — Acquittance** (sem `installment_list`): usa o endpoint PV bulk — uma única chamada devolve o PV de todas as parcelas.

## Amortização antecipada (`early_amortization`)

`early_amortization` é o único tipo que permite pagamento parcial. 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`.

## 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)

---

# 错误目录

URL: /zh-Hans/documentation/escrituracao/catalogo-erros/catalogo-erros

## 错误格式

所有书写集成 API 返回的错误均按以下说明进行格式化：

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"
}
```

---

## 发行人资质审核流程中可能出现的错误表

| HTTP 代码 | 错误代码 | 标题 | 描述 (eng) | 翻译 (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.                                          |

## 投资人资质审核流程中可能出现的错误表

| HTTP 代码 | 错误代码 | 标题 | 描述 (eng) | 翻译 (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.                                          |

## 商业票据发行流程中可能出现的错误表

| HTTP 代码 | 错误代码 | 标题 | 描述 (eng) | 翻译 (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.      |

## 份额整合流程中可能出现的错误表

| HTTP 代码 | 错误代码 | 标题 | 描述 (eng) | 翻译 (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. |

---

# Webhook 配置

URL: /zh-Hans/documentation/escrituracao/configuracao-webhooks

Webhook 配置 API 允许管理 webhook 端点，以实时接收书写事件通知。每个 tenant 可以拥有多个 webhook 配置，从而将事件发送到不同的目的地。

---

## 数据模型

### 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"
}
```

---

## 创建 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

| 字段 | 类型 | 描述 |
| ---------------------- | ------ | --------------------------------------------------------- |
| `tenant_key`*         | string | tenant 的 UUID（UUID v4）。                               |
| `url`*                | string | 接收 webhook 的目标 URL。                                |
| `hmac_signature_key`* | string | 用于 webhook HMAC 签名的密钥。                           |
| `headers`             | object | 请求中要包含的自定义 headers。                           |

---

### 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

| 字段 | 类型 | 描述 |
| ---------------------- | ------ | --------------------------------------------------------- |
| `configuration_key`   | string | webhook 配置的唯一键（UUID v4）。                       |
| `tenant_key`          | string | tenant 的 UUID。                                          |
| `url`                 | string | 已配置的目标 URL。                                       |
| `headers`             | object | 已配置的自定义 headers。                                 |
| `hmac_signature_key`  | string | HMAC 签名的密钥。                                        |

---

## 列出 Webhook 配置 (GET)

### Request

ENDPOINT /outgoing_webhook/webhook_configuration
MÉTODO GET

### Query Params

| 字段 | 类型 | 描述 |
| ------------ | ------- | ---------------------------------------------- |
| `tenant_key`* | string | 用于筛选配置的 tenant UUID。                  |
| `page`       | integer | 页码（默认：1）。                              |
| `page_size`  | integer | 每页条目数（默认：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

| 字段 | 类型 | 描述 |
| ---------------------- | ------- | --------------------------------------------------------- |
| `data`                | array   | webhook 配置列表。                                       |
| `pagination`          | object  | **[pagination 对象](#objeto-pagination)**。             |

---

## 通过键获取 Webhook 配置 (GET)

### Request

ENDPOINT /outgoing_webhook/webhook_configuration/ CONFIGURATION-KEY
MÉTODO GET

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
| ------------------- | ------ | ------------------------------------------------ | ---------- |
| `CONFIGURATION-KEY` | string | 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

| 字段 | 类型 | 描述 |
| ---------------------- | ------- | --------------------------------------------------------- |
| `configuration_key`   | string  | webhook 配置的唯一键（UUID v4）。                       |
| `tenant_key`          | string  | tenant 的 UUID。                                          |
| `url`                 | string  | 已配置的目标 URL。                                       |
| `headers`             | object  | 已配置的自定义 headers。                                 |
| `hmac_signature_key`  | string  | HMAC 签名的密钥。                                        |

---

## 更新 Webhook 配置 (PUT)

### Request

ENDPOINT /outgoing_webhook/webhook_configuration/ CONFIGURATION-KEY
MÉTODO PUT

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
| ------------------- | ------ | ------------------------------------------------ | ---------- |
| `CONFIGURATION-KEY` | string | 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

| 字段 | 类型 | 描述 |
| --------------------- | ------ | --------------------------------------------------------- |
| `url`                | string | 接收 webhook 的新目标 URL。                              |
| `headers`            | object | 请求中要包含的新自定义 headers。                         |
| `hmac_signature_key` | string | webhook HMAC 签名的新密钥。                              |

---

### 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

| 字段 | 类型 | 描述 |
| ---------------------- | ------- | --------------------------------------------------------- |
| `configuration_key`   | string  | webhook 配置的唯一键（UUID v4）。                       |
| `tenant_key`          | string  | tenant 的 UUID。                                          |
| `url`                 | string  | 已配置的目标 URL。                                       |
| `headers`             | object  | 已配置的自定义 headers。                                 |
| `hmac_signature_key`  | string  | HMAC 签名的密钥。                                        |

---

## 删除 Webhook 配置 (DELETE)

### Request

ENDPOINT /outgoing_webhook/webhook_configuration/ CONFIGURATION-KEY
MÉTODO DELETE

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
| ------------------- | ------ | ------------------------------------------------ | ---------- |
| `CONFIGURATION-KEY` | string | webhook 配置的唯一键（UUID v4）。                 | 36         |

---

### Response

STATUS 200

Response Body

```json
{}
```

---

# 登记基础资产（Lastro）

URL: /zh-Hans/documentation/escrituracao/emissao-cr/cadastro-lastro

此端点用于登记CR操作的 **基础资产**（lastro）。基础资产代表为证券化提供支撑的债权。资产文件以 base64 提交，其结构化数据随请求一并发送。

:::info
基础资产在 **操作创建后** 通过单独的请求提交。同一操作可登记多个基础资产。
:::

---

## **Request**

ENDPOINT /cr/operation/ OPERATION-KEY /underlying_asset
MÉTODO POST

### Path Params

| 字段            | 类型   | 描述                          | 字符数 |
|-----------------|--------|-------------------------------|--------|
| `OPERATION-KEY` * | string | 操作的唯一键（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

| 字段                      | 类型   | 描述                       | 最大字符数                                                           |
|---------------------------|--------|----------------------------|----------------------------------------------------------------------|
| `underlying_asset_type` * | string | 基础资产类型。             | **[underlying_asset_type 枚举](#underlying_asset_type-枚举)**        |
| `underlying_asset_base64` * | string | base64 格式的基础资产文件。 | -                                                                  |
| `underlying_asset_data` * | object | 基础资产数据（自由结构）。 | -                                                                    |

### underlying_asset_type 枚举

| 枚举值     | 描述   |
|------------|--------|
| `contract` | 合同。 |

## **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

| 字段                      | 类型   | 描述               |
|---------------------------|--------|--------------------|
| `underlying_asset_key` *  | string | 所登记基础资产的唯一键。 |
| `underlying_asset_type` * | string | 基础资产类型。     |
| `underlying_asset_data` * | object | 基础资产数据。     |

---

---

# 登记CR操作

URL: /zh-Hans/documentation/escrituracao/emissao-cr/cadastro-operacao

此端点通过单个请求创建完整的CR操作。

:::info
`financial` 对象为 **必填**，且必须以已计算好的形式提交，因为此端点不执行财务模拟。发行人及其银行账户必须事先登记。
:::

---

## **Request**

ENDPOINT /cr/create_operation
MÉTODO POST

请求体既可以是仅含 **必填字段的负载**（包含财务对象），也可以是同时包含关联方的 **完整负载**。两种变体见下文。

必填字段负载

```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
            }
        ]
    }
}
```

完整负载（含关联方）

```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**

| 字段                | 类型    | 描述                                       | 最大字符数                 |
| ------------------- | ------- | ------------------------------------------ | -------------------------- |
| `tenant_key` *      | string  | tenant 的唯一键。                          | -                          |
| `issuer_key` *      | string  | 发行人的唯一键（须事先登记）。             | -                          |
| `issue_number` *    | integer | 发行编号。                                 | -                          |
| `issue_series` *    | integer | 发行系列。                                 | -                          |
| `issue_date` *      | string  | 操作发行日期（格式："YYYY-MM-DD"）。       | -                          |
| `signature_method`  | string  | 操作中使用的签名方式。可选；省略时默认为 `certifiqi`。 | **[signature_method 枚举](#signature_method-枚举)** |
| `investors` *       | array   | 相关投资人列表。                           | **investors 对象**         |
| `financial` *       | object  | 操作的已计算财务数据。                     | **financial 对象**         |
| `contract_number`   | string  | 合同编号。                                 | -                          |
| `related_party_list` | array  | 操作的关联方（担保人、债务人等）。         | **related_party 对象**     |

### investors 对象

| 字段                        | 类型   | 描述                                       |
| --------------------------- | ------ | ------------------------------------------ |
| `investor_key` *            | string | 投资人的唯一键（须事先登记）。             |
| `bank_account` *            | object | 投资人的银行账户（**bank_account 对象**）。 |
| `subscription_percentage`   | number | 认购比例。                                 |
| `subscription_quantity`     | number | 认购数量。                                 |

### bank_account 对象

| 字段                                  | 类型   | 描述                                            |
| ------------------------------------- | ------ | ----------------------------------------------- |
| `account_number` *                    | string | 银行账户号码。                                  |
| `account_digit` *                     | string | 银行账户校验位。                                |
| `account_branch` *                    | string | 银行账户支行。                                  |
| `financial_institution_code_number`   | string | 金融机构代码。                                  |
| `financial_institution_ispb` *        | string | 金融机构 ISPB 代码。                            |
| `account_type` *                      | string | 账户类型（`checking`、`savings`、`salary`、`payment`）。 |

### financial 对象

| 字段                        | 类型    | 描述                                       |
| --------------------------- | ------- | ------------------------------------------ |
| `financial_base_date` *     | string  | 财务基准日期（格式："YYYY-MM-DD"）。       |
| `interest_type` *           | string  | 利率类型。                                 |
| `issue_amount`              | number  | 发行总金额。                               |
| `issue_quantity`            | integer | 发行单位数量。                             |
| `unit_price`                | number  | 每单位发行价格。                           |
| `released_amount`           | number  | 释放的净金额。                             |
| `cet` / `annual_cet`        | number  | 有效总成本（月度与年度），百分比。         |
| `number_of_installments` *  | integer | 期数。                                     |
| `prefixed_interest_rate` *  | object  | 固定利率。                                 |
| `fine_delay_rate`           | object  | 滞纳金利率。                               |
| `contract_fine_rate`        | number  | 合同罚款百分比。                           |
| `fees`                      | array   | 费用列表。                                 |
| `installments`              | array   | 已计算的期次列表。                         |

### related_party 对象

`related_party_list` 中的每一项代表参与该操作的一方。

| 字段              | 类型    | 描述                                            |
| ----------------- | ------- | ----------------------------------------------- |
| `person_type` *   | string  | 人员类型（`natural` 自然人，`legal` 法人）。   |
| `name` *          | string  | 关联方名称。                                    |
| `document_number` * | string | CPF（自然人）或 CNPJ（法人）。                  |
| `role_type` *     | string  | 关联方在操作中的角色。**[role_type 枚举](#role_type-枚举)** |
| `street` *        | string  | 街道。                                          |
| `number` *        | string  | 门牌号。                                        |
| `neighborhood`    | string  | 街区。                                          |
| `postal_code` *   | string  | 邮政编码（格式："00000-000"）。                 |
| `city` *          | string  | 城市。                                          |
| `state` *         | string  | 州/省（2 个字母）。                             |
| `complement`      | string  | 地址补充信息。                                  |
| `is_pep`          | boolean | （自然人）是否为政治公众人物。                  |
| `marital_status`  | string  | （自然人）婚姻状况。                            |
| `property_system` | string  | （自然人）财产制度。                            |
| `birthdate`       | string  | （自然人）出生日期。                            |
| `mother_name`     | string  | （自然人）母亲姓名。                            |
| `occupation`      | string  | （自然人）职业。                                |
| `trading_name`    | string  | （法人）商号。                                  |
| `cnae_code`       | string  | （法人）CNAE 代码（格式："00.00-0-00"）。       |
| `company_type`    | string  | （法人）公司类型。                              |
| `foundation_date` | string  | （法人）成立日期。                              |

:::warning 注意
必填字段因 `person_type` 而异：
- **自然人（`natural`）**：除通用字段外，`is_pep` 为必填。
- **法人（`legal`）**：除通用字段外，`trading_name`、`cnae_code`、`company_type` 和 `foundation_date` 为必填。
:::

### role_type 枚举

| 枚举值 | 描述 |
|--------|------|
| `issuer` | 发行人。 |
| `investor` | 投资人。 |
| `cosigner` | 共同债务人。 |
| `fiduciary_debtor` | 信托债务人。 |
| `solidary_debtor` | 连带债务人。 |
| `guarantor` | 担保人。 |
| `bonafide_depositary` | 善意保管人。 |
| `intervening_guarantor` | 介入担保人。 |
| `intervening_consentor` | 介入同意人。 |
| `intervening_discharger` | 介入清偿人。 |
| `assignor` | 转让人。 |
| `endorser` | 背书人。 |
| `consulting` | 咨询方。 |
| `fund_administrator` | 基金管理人。 |
| `fund_representative` | 基金代表。 |
| `company_representative` | 公司代表。 |
| `attestant` | 见证人。 |
| `debtor` | 债务人。 |
| `bestowal` | 授予人。 |
| `manager` | 管理人。 |

:::tip
担保和基础资产在操作创建后通过 **单独的端点** 提交。请参阅本节的 **登记基础资产** 页面。
:::

### signature_method 枚举

| 枚举值 | 描述 |
|--------|------|
| `certifiqi` | 默认值。操作将发送至签名服务；创建签名信封，客户端将收到签名 URL（`signature_url`）。 |
| `qi_sign` | 操作将发送至签名服务；创建签名信封，客户端将收到签名 URL（`signature_url`）。此外还支持查询操作的签署人。 |

## **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": { ... }
}
```

响应返回所创建操作的完整 JSON，包括 `operation_key`、投资人与关联方列表，以及已计算的财务对象。

---

# 提交文件

URL: /zh-Hans/documentation/escrituracao/emissao-cr/envio-documento

此端点用于 **上传文件** 并返回标识该文件的 `document_key`。当其他操作端点需要先前已上传文件的键时，该 `document_key` 用于引用这些文件。

---

## **Request**

ENDPOINT /cr/upload
MÉTODO POST

Request Body

```json
{
    "document_base64": "string_b64"
}
```

### **Request Body Params**

| 字段              | 类型   | 描述                       | 必需 |
|-------------------|--------|----------------------------|------|
| `document_base64` * | string | base64 编码的文件内容。    | 是   |
| `document_name`   | string | 文件名称。                 | -    |

## **Response**

STATUS 201

Response Body

```json
{
    "document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b"
}
```

### **Response Body Params**

| 字段           | 类型   | 描述                          | 最大字符数 |
|----------------|--------|-------------------------------|------------|
| `document_key` * | string | 所上传文件的唯一键（UUID v4）。 | 36         |

---

---

# 提交操作的外部文件

URL: /zh-Hans/documentation/escrituracao/emissao-cr/envio-documento-externo

此端点允许将在外部签署的文件提交至书写系统，提交的 base64 将由书写方进行分析和批准。

:::warning 警告
此端点仅应用于使用 **client_side** 签名类型的操作，或用于提交 SA 或合作社类型公司的批准会议纪要。对于通过 QI Sign 或 Certifiqi 的流程，合同以正常方式生成。
:::

---

## 提交已签署文件 (POST)

### Request

ENDPOINT /cr/operation/ OPERATION-KEY /upload_signed_document
MÉTODO POST

### Path Params

| 字段            | 类型   | 描述                          | 字符数 |
|-----------------|--------|-------------------------------|--------|
| `OPERATION-KEY` | string | 操作的唯一键（UUID v4）。      | 36     |

---

### Request Body

Request Body

```json
{
    "contract_base64": "image_b64",
    "contract_type": "securitization_term"
}
```

### Request Body Params

| 字段                | 类型   | 描述               | 最大字符数                                                  |
|---------------------|--------|--------------------|------------------------------------------------------------|
| `contract_type` *   | string | 已签署文件的类型。 | **[contract_type 枚举](#contract_type-枚举)**              |
| `contract_base64` * | string | base64 格式的已签署文件。 | -                                                    |

### contract_type 枚举

| 枚举值              | 描述                                       |
|---------------------|--------------------------------------------|
| `securitization_term` | CR 证券化条款。 |
| `adhesion_term` | CR 加入条款。 |
| `sa_minute` | **SA** 公司CR发行批准会议纪要。 |
| `ltda_minute` | **LTDA** 公司CR发行批准会议纪要。 |
| `cop_minute` | **合作社** CR发行批准会议纪要。 |

### Response

响应体为更新后的完整操作 JSON。

---

---

# 登记基础资产（Lastro）

URL: /zh-Hans/documentation/escrituracao/emissao-cra/cadastro-lastro

此端点用于登记CRA操作的 **基础资产**（lastro）。基础资产代表为证券化提供支撑的债权。资产文件以 base64 提交，其结构化数据随请求一并发送。

:::info
基础资产在 **操作创建后** 通过单独的请求提交。同一操作可登记多个基础资产。
:::

---

## **Request**

ENDPOINT /cra/operation/ OPERATION-KEY /underlying_asset
MÉTODO POST

### Path Params

| 字段            | 类型   | 描述                          | 字符数 |
|-----------------|--------|-------------------------------|--------|
| `OPERATION-KEY` * | string | 操作的唯一键（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

| 字段                      | 类型   | 描述                       | 最大字符数                                                           |
|---------------------------|--------|----------------------------|----------------------------------------------------------------------|
| `underlying_asset_type` * | string | 基础资产类型。             | **[underlying_asset_type 枚举](#underlying_asset_type-枚举)**        |
| `underlying_asset_base64` * | string | base64 格式的基础资产文件。 | -                                                                  |
| `underlying_asset_data` * | object | 基础资产数据（自由结构）。 | -                                                                    |

### underlying_asset_type 枚举

| 枚举值     | 描述   |
|------------|--------|
| `contract` | 合同。 |

## **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

| 字段                      | 类型   | 描述               |
|---------------------------|--------|--------------------|
| `underlying_asset_key` *  | string | 所登记基础资产的唯一键。 |
| `underlying_asset_type` * | string | 基础资产类型。     |
| `underlying_asset_data` * | object | 基础资产数据。     |

---

---

# 登记CRA操作

URL: /zh-Hans/documentation/escrituracao/emissao-cra/cadastro-operacao

此端点通过单个请求创建完整的CRA操作。

:::info
`financial` 对象为 **必填**，且必须以已计算好的形式提交，因为此端点不执行财务模拟。发行人及其银行账户必须事先登记。
:::

---

## **Request**

ENDPOINT /cra/create_operation
MÉTODO POST

请求体既可以是仅含 **必填字段的负载**（包含财务对象），也可以是同时包含关联方的 **完整负载**。两种变体见下文。

必填字段负载

```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
            }
        ]
    }
}
```

完整负载（含关联方）

```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**

| 字段                | 类型    | 描述                                       | 最大字符数                 |
| ------------------- | ------- | ------------------------------------------ | -------------------------- |
| `tenant_key` *      | string  | tenant 的唯一键。                          | -                          |
| `issuer_key` *      | string  | 发行人的唯一键（须事先登记）。             | -                          |
| `issue_number` *    | integer | 发行编号。                                 | -                          |
| `issue_series` *    | integer | 发行系列。                                 | -                          |
| `issue_date` *      | string  | 操作发行日期（格式："YYYY-MM-DD"）。       | -                          |
| `signature_method`  | string  | 操作中使用的签名方式。可选；省略时默认为 `certifiqi`。 | **[signature_method 枚举](#signature_method-枚举)** |
| `investors` *       | array   | 相关投资人列表。                           | **investors 对象**         |
| `financial` *       | object  | 操作的已计算财务数据。                     | **financial 对象**         |
| `contract_number`   | string  | 合同编号。                                 | -                          |
| `related_party_list` | array  | 操作的关联方（担保人、债务人等）。         | **related_party 对象**     |

### investors 对象

| 字段                        | 类型   | 描述                                       |
| --------------------------- | ------ | ------------------------------------------ |
| `investor_key` *            | string | 投资人的唯一键（须事先登记）。             |
| `bank_account` *            | object | 投资人的银行账户（**bank_account 对象**）。 |
| `subscription_percentage`   | number | 认购比例。                                 |
| `subscription_quantity`     | number | 认购数量。                                 |

### bank_account 对象

| 字段                                  | 类型   | 描述                                            |
| ------------------------------------- | ------ | ----------------------------------------------- |
| `account_number` *                    | string | 银行账户号码。                                  |
| `account_digit` *                     | string | 银行账户校验位。                                |
| `account_branch` *                    | string | 银行账户支行。                                  |
| `financial_institution_code_number`   | string | 金融机构代码。                                  |
| `financial_institution_ispb` *        | string | 金融机构 ISPB 代码。                            |
| `account_type` *                      | string | 账户类型（`checking`、`savings`、`salary`、`payment`）。 |

### financial 对象

| 字段                        | 类型    | 描述                                       |
| --------------------------- | ------- | ------------------------------------------ |
| `financial_base_date` *     | string  | 财务基准日期（格式："YYYY-MM-DD"）。       |
| `interest_type` *           | string  | 利率类型。                                 |
| `issue_amount`              | number  | 发行总金额。                               |
| `issue_quantity`            | integer | 发行单位数量。                             |
| `unit_price`                | number  | 每单位发行价格。                           |
| `released_amount`           | number  | 释放的净金额。                             |
| `cet` / `annual_cet`        | number  | 有效总成本（月度与年度），百分比。         |
| `number_of_installments` *  | integer | 期数。                                     |
| `prefixed_interest_rate` *  | object  | 固定利率。                                 |
| `fine_delay_rate`           | object  | 滞纳金利率。                               |
| `contract_fine_rate`        | number  | 合同罚款百分比。                           |
| `fees`                      | array   | 费用列表。                                 |
| `installments`              | array   | 已计算的期次列表。                         |

### related_party 对象

`related_party_list` 中的每一项代表参与该操作的一方。

| 字段              | 类型    | 描述                                            |
| ----------------- | ------- | ----------------------------------------------- |
| `person_type` *   | string  | 人员类型（`natural` 自然人，`legal` 法人）。   |
| `name` *          | string  | 关联方名称。                                    |
| `document_number` * | string | CPF（自然人）或 CNPJ（法人）。                  |
| `role_type` *     | string  | 关联方在操作中的角色。**[role_type 枚举](#role_type-枚举)** |
| `street` *        | string  | 街道。                                          |
| `number` *        | string  | 门牌号。                                        |
| `neighborhood`    | string  | 街区。                                          |
| `postal_code` *   | string  | 邮政编码（格式："00000-000"）。                 |
| `city` *          | string  | 城市。                                          |
| `state` *         | string  | 州/省（2 个字母）。                             |
| `complement`      | string  | 地址补充信息。                                  |
| `is_pep`          | boolean | （自然人）是否为政治公众人物。                  |
| `marital_status`  | string  | （自然人）婚姻状况。                            |
| `property_system` | string  | （自然人）财产制度。                            |
| `birthdate`       | string  | （自然人）出生日期。                            |
| `mother_name`     | string  | （自然人）母亲姓名。                            |
| `occupation`      | string  | （自然人）职业。                                |
| `trading_name`    | string  | （法人）商号。                                  |
| `cnae_code`       | string  | （法人）CNAE 代码（格式："00.00-0-00"）。       |
| `company_type`    | string  | （法人）公司类型。                              |
| `foundation_date` | string  | （法人）成立日期。                              |

:::warning 注意
必填字段因 `person_type` 而异：
- **自然人（`natural`）**：除通用字段外，`is_pep` 为必填。
- **法人（`legal`）**：除通用字段外，`trading_name`、`cnae_code`、`company_type` 和 `foundation_date` 为必填。
:::

### role_type 枚举

| 枚举值 | 描述 |
|--------|------|
| `issuer` | 发行人。 |
| `investor` | 投资人。 |
| `cosigner` | 共同债务人。 |
| `fiduciary_debtor` | 信托债务人。 |
| `solidary_debtor` | 连带债务人。 |
| `guarantor` | 担保人。 |
| `bonafide_depositary` | 善意保管人。 |
| `intervening_guarantor` | 介入担保人。 |
| `intervening_consentor` | 介入同意人。 |
| `intervening_discharger` | 介入清偿人。 |
| `assignor` | 转让人。 |
| `endorser` | 背书人。 |
| `consulting` | 咨询方。 |
| `fund_administrator` | 基金管理人。 |
| `fund_representative` | 基金代表。 |
| `company_representative` | 公司代表。 |
| `attestant` | 见证人。 |
| `debtor` | 债务人。 |
| `bestowal` | 授予人。 |
| `manager` | 管理人。 |

:::tip
担保和基础资产在操作创建后通过 **单独的端点** 提交。请参阅本节的 **登记基础资产** 页面。
:::

### signature_method 枚举

| 枚举值 | 描述 |
|--------|------|
| `certifiqi` | 默认值。操作将发送至签名服务；创建签名信封，客户端将收到签名 URL（`signature_url`）。 |
| `qi_sign` | 操作将发送至签名服务；创建签名信封，客户端将收到签名 URL（`signature_url`）。此外还支持查询操作的签署人。 |

## **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": { ... }
}
```

响应返回所创建操作的完整 JSON，包括 `operation_key`、投资人与关联方列表，以及已计算的财务对象。

---

# 提交文件

URL: /zh-Hans/documentation/escrituracao/emissao-cra/envio-documento

此端点用于 **上传文件** 并返回标识该文件的 `document_key`。当其他操作端点需要先前已上传文件的键时，该 `document_key` 用于引用这些文件。

---

## **Request**

ENDPOINT /cra/upload
MÉTODO POST

Request Body

```json
{
    "document_base64": "string_b64"
}
```

### **Request Body Params**

| 字段              | 类型   | 描述                       | 必需 |
|-------------------|--------|----------------------------|------|
| `document_base64` * | string | base64 编码的文件内容。    | 是   |
| `document_name`   | string | 文件名称。                 | -    |

## **Response**

STATUS 201

Response Body

```json
{
    "document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b"
}
```

### **Response Body Params**

| 字段           | 类型   | 描述                          | 最大字符数 |
|----------------|--------|-------------------------------|------------|
| `document_key` * | string | 所上传文件的唯一键（UUID v4）。 | 36         |

---

---

# 提交操作的外部文件

URL: /zh-Hans/documentation/escrituracao/emissao-cra/envio-documento-externo

此端点允许将在外部签署的文件提交至书写系统，提交的 base64 将由书写方进行分析和批准。

:::warning 警告
此端点仅应用于使用 **client_side** 签名类型的操作，或用于提交 SA 或合作社类型公司的批准会议纪要。对于通过 QI Sign 或 Certifiqi 的流程，合同以正常方式生成。
:::

---

## 提交已签署文件 (POST)

### Request

ENDPOINT /cra/operation/ OPERATION-KEY /upload_signed_document
MÉTODO POST

### Path Params

| 字段            | 类型   | 描述                          | 字符数 |
|-----------------|--------|-------------------------------|--------|
| `OPERATION-KEY` | string | 操作的唯一键（UUID v4）。      | 36     |

---

### Request Body

Request Body

```json
{
    "contract_base64": "image_b64",
    "contract_type": "securitization_term"
}
```

### Request Body Params

| 字段                | 类型   | 描述               | 最大字符数                                                  |
|---------------------|--------|--------------------|------------------------------------------------------------|
| `contract_type` *   | string | 已签署文件的类型。 | **[contract_type 枚举](#contract_type-枚举)**              |
| `contract_base64` * | string | base64 格式的已签署文件。 | -                                                    |

### contract_type 枚举

| 枚举值              | 描述                                       |
|---------------------|--------------------------------------------|
| `securitization_term` | CRA 证券化条款。 |
| `adhesion_term` | CRA 加入条款。 |
| `sa_minute` | **SA** 公司CRA发行批准会议纪要。 |
| `ltda_minute` | **LTDA** 公司CRA发行批准会议纪要。 |
| `cop_minute` | **合作社** CRA发行批准会议纪要。 |

### Response

响应体为更新后的完整操作 JSON。

---

---

# 登记基础资产（Lastro）

URL: /zh-Hans/documentation/escrituracao/emissao-cri/cadastro-lastro

此端点用于登记CRI操作的 **基础资产**（lastro）。基础资产代表为证券化提供支撑的债权。资产文件以 base64 提交，其结构化数据随请求一并发送。

:::info
基础资产在 **操作创建后** 通过单独的请求提交。同一操作可登记多个基础资产。
:::

---

## **Request**

ENDPOINT /cri/operation/ OPERATION-KEY /underlying_asset
MÉTODO POST

### Path Params

| 字段            | 类型   | 描述                          | 字符数 |
|-----------------|--------|-------------------------------|--------|
| `OPERATION-KEY` * | string | 操作的唯一键（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

| 字段                      | 类型   | 描述                       | 最大字符数                                                           |
|---------------------------|--------|----------------------------|----------------------------------------------------------------------|
| `underlying_asset_type` * | string | 基础资产类型。             | **[underlying_asset_type 枚举](#underlying_asset_type-枚举)**        |
| `underlying_asset_base64` * | string | base64 格式的基础资产文件。 | -                                                                  |
| `underlying_asset_data` * | object | 基础资产数据（自由结构）。 | -                                                                    |

### underlying_asset_type 枚举

| 枚举值     | 描述   |
|------------|--------|
| `contract` | 合同。 |

## **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

| 字段                      | 类型   | 描述               |
|---------------------------|--------|--------------------|
| `underlying_asset_key` *  | string | 所登记基础资产的唯一键。 |
| `underlying_asset_type` * | string | 基础资产类型。     |
| `underlying_asset_data` * | object | 基础资产数据。     |

---

---

# 登记CRI操作

URL: /zh-Hans/documentation/escrituracao/emissao-cri/cadastro-operacao

此端点通过单个请求创建完整的CRI操作。

:::info
`financial` 对象为 **必填**，且必须以已计算好的形式提交，因为此端点不执行财务模拟。发行人及其银行账户必须事先登记。
:::

---

## **Request**

ENDPOINT /cri/create_operation
MÉTODO POST

请求体既可以是仅含 **必填字段的负载**（包含财务对象），也可以是同时包含关联方的 **完整负载**。两种变体见下文。

必填字段负载

```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
            }
        ]
    }
}
```

完整负载（含关联方）

```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**

| 字段                | 类型    | 描述                                       | 最大字符数                 |
| ------------------- | ------- | ------------------------------------------ | -------------------------- |
| `tenant_key` *      | string  | tenant 的唯一键。                          | -                          |
| `issuer_key` *      | string  | 发行人的唯一键（须事先登记）。             | -                          |
| `issue_number` *    | integer | 发行编号。                                 | -                          |
| `issue_series` *    | integer | 发行系列。                                 | -                          |
| `issue_date` *      | string  | 操作发行日期（格式："YYYY-MM-DD"）。       | -                          |
| `signature_method`  | string  | 操作中使用的签名方式。可选；省略时默认为 `certifiqi`。 | **[signature_method 枚举](#signature_method-枚举)** |
| `investors` *       | array   | 相关投资人列表。                           | **investors 对象**         |
| `financial` *       | object  | 操作的已计算财务数据。                     | **financial 对象**         |
| `contract_number`   | string  | 合同编号。                                 | -                          |
| `related_party_list` | array  | 操作的关联方（担保人、债务人等）。         | **related_party 对象**     |

### investors 对象

| 字段                        | 类型   | 描述                                       |
| --------------------------- | ------ | ------------------------------------------ |
| `investor_key` *            | string | 投资人的唯一键（须事先登记）。             |
| `bank_account` *            | object | 投资人的银行账户（**bank_account 对象**）。 |
| `subscription_percentage`   | number | 认购比例。                                 |
| `subscription_quantity`     | number | 认购数量。                                 |

### bank_account 对象

| 字段                                  | 类型   | 描述                                            |
| ------------------------------------- | ------ | ----------------------------------------------- |
| `account_number` *                    | string | 银行账户号码。                                  |
| `account_digit` *                     | string | 银行账户校验位。                                |
| `account_branch` *                    | string | 银行账户支行。                                  |
| `financial_institution_code_number`   | string | 金融机构代码。                                  |
| `financial_institution_ispb` *        | string | 金融机构 ISPB 代码。                            |
| `account_type` *                      | string | 账户类型（`checking`、`savings`、`salary`、`payment`）。 |

### financial 对象

| 字段                        | 类型    | 描述                                       |
| --------------------------- | ------- | ------------------------------------------ |
| `financial_base_date` *     | string  | 财务基准日期（格式："YYYY-MM-DD"）。       |
| `interest_type` *           | string  | 利率类型。                                 |
| `issue_amount`              | number  | 发行总金额。                               |
| `issue_quantity`            | integer | 发行单位数量。                             |
| `unit_price`                | number  | 每单位发行价格。                           |
| `released_amount`           | number  | 释放的净金额。                             |
| `cet` / `annual_cet`        | number  | 有效总成本（月度与年度），百分比。         |
| `number_of_installments` *  | integer | 期数。                                     |
| `prefixed_interest_rate` *  | object  | 固定利率。                                 |
| `fine_delay_rate`           | object  | 滞纳金利率。                               |
| `contract_fine_rate`        | number  | 合同罚款百分比。                           |
| `fees`                      | array   | 费用列表。                                 |
| `installments`              | array   | 已计算的期次列表。                         |

### related_party 对象

`related_party_list` 中的每一项代表参与该操作的一方。

| 字段              | 类型    | 描述                                            |
| ----------------- | ------- | ----------------------------------------------- |
| `person_type` *   | string  | 人员类型（`natural` 自然人，`legal` 法人）。   |
| `name` *          | string  | 关联方名称。                                    |
| `document_number` * | string | CPF（自然人）或 CNPJ（法人）。                  |
| `role_type` *     | string  | 关联方在操作中的角色。**[role_type 枚举](#role_type-枚举)** |
| `street` *        | string  | 街道。                                          |
| `number` *        | string  | 门牌号。                                        |
| `neighborhood`    | string  | 街区。                                          |
| `postal_code` *   | string  | 邮政编码（格式："00000-000"）。                 |
| `city` *          | string  | 城市。                                          |
| `state` *         | string  | 州/省（2 个字母）。                             |
| `complement`      | string  | 地址补充信息。                                  |
| `is_pep`          | boolean | （自然人）是否为政治公众人物。                  |
| `marital_status`  | string  | （自然人）婚姻状况。                            |
| `property_system` | string  | （自然人）财产制度。                            |
| `birthdate`       | string  | （自然人）出生日期。                            |
| `mother_name`     | string  | （自然人）母亲姓名。                            |
| `occupation`      | string  | （自然人）职业。                                |
| `trading_name`    | string  | （法人）商号。                                  |
| `cnae_code`       | string  | （法人）CNAE 代码（格式："00.00-0-00"）。       |
| `company_type`    | string  | （法人）公司类型。                              |
| `foundation_date` | string  | （法人）成立日期。                              |

:::warning 注意
必填字段因 `person_type` 而异：
- **自然人（`natural`）**：除通用字段外，`is_pep` 为必填。
- **法人（`legal`）**：除通用字段外，`trading_name`、`cnae_code`、`company_type` 和 `foundation_date` 为必填。
:::

### role_type 枚举

| 枚举值 | 描述 |
|--------|------|
| `issuer` | 发行人。 |
| `investor` | 投资人。 |
| `cosigner` | 共同债务人。 |
| `fiduciary_debtor` | 信托债务人。 |
| `solidary_debtor` | 连带债务人。 |
| `guarantor` | 担保人。 |
| `bonafide_depositary` | 善意保管人。 |
| `intervening_guarantor` | 介入担保人。 |
| `intervening_consentor` | 介入同意人。 |
| `intervening_discharger` | 介入清偿人。 |
| `assignor` | 转让人。 |
| `endorser` | 背书人。 |
| `consulting` | 咨询方。 |
| `fund_administrator` | 基金管理人。 |
| `fund_representative` | 基金代表。 |
| `company_representative` | 公司代表。 |
| `attestant` | 见证人。 |
| `debtor` | 债务人。 |
| `bestowal` | 授予人。 |
| `manager` | 管理人。 |

:::tip
担保和基础资产在操作创建后通过 **单独的端点** 提交。请参阅本节的 **登记基础资产** 页面。
:::

### signature_method 枚举

| 枚举值 | 描述 |
|--------|------|
| `certifiqi` | 默认值。操作将发送至签名服务；创建签名信封，客户端将收到签名 URL（`signature_url`）。 |
| `qi_sign` | 操作将发送至签名服务；创建签名信封，客户端将收到签名 URL（`signature_url`）。此外还支持查询操作的签署人。 |

## **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": { ... }
}
```

响应返回所创建操作的完整 JSON，包括 `operation_key`、投资人与关联方列表，以及已计算的财务对象。

---

# 提交文件

URL: /zh-Hans/documentation/escrituracao/emissao-cri/envio-documento

此端点用于 **上传文件** 并返回标识该文件的 `document_key`。当其他操作端点需要先前已上传文件的键时，该 `document_key` 用于引用这些文件。

---

## **Request**

ENDPOINT /cri/upload
MÉTODO POST

Request Body

```json
{
    "document_base64": "string_b64"
}
```

### **Request Body Params**

| 字段              | 类型   | 描述                       | 必需 |
|-------------------|--------|----------------------------|------|
| `document_base64` * | string | base64 编码的文件内容。    | 是   |
| `document_name`   | string | 文件名称。                 | -    |

## **Response**

STATUS 201

Response Body

```json
{
    "document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b"
}
```

### **Response Body Params**

| 字段           | 类型   | 描述                          | 最大字符数 |
|----------------|--------|-------------------------------|------------|
| `document_key` * | string | 所上传文件的唯一键（UUID v4）。 | 36         |

---

---

# 提交操作的外部文件

URL: /zh-Hans/documentation/escrituracao/emissao-cri/envio-documento-externo

此端点允许将在外部签署的文件提交至书写系统，提交的 base64 将由书写方进行分析和批准。

:::warning 警告
此端点仅应用于使用 **client_side** 签名类型的操作，或用于提交 SA 或合作社类型公司的批准会议纪要。对于通过 QI Sign 或 Certifiqi 的流程，合同以正常方式生成。
:::

---

## 提交已签署文件 (POST)

### Request

ENDPOINT /cri/operation/ OPERATION-KEY /upload_signed_document
MÉTODO POST

### Path Params

| 字段            | 类型   | 描述                          | 字符数 |
|-----------------|--------|-------------------------------|--------|
| `OPERATION-KEY` | string | 操作的唯一键（UUID v4）。      | 36     |

---

### Request Body

Request Body

```json
{
    "contract_base64": "image_b64",
    "contract_type": "securitization_term"
}
```

### Request Body Params

| 字段                | 类型   | 描述               | 最大字符数                                                  |
|---------------------|--------|--------------------|------------------------------------------------------------|
| `contract_type` *   | string | 已签署文件的类型。 | **[contract_type 枚举](#contract_type-枚举)**              |
| `contract_base64` * | string | base64 格式的已签署文件。 | -                                                    |

### contract_type 枚举

| 枚举值              | 描述                                       |
|---------------------|--------------------------------------------|
| `securitization_term` | CRI 证券化条款。 |
| `adhesion_term` | CRI 加入条款。 |
| `sa_minute` | **SA** 公司CRI发行批准会议纪要。 |
| `ltda_minute` | **LTDA** 公司CRI发行批准会议纪要。 |
| `cop_minute` | **合作社** CRI发行批准会议纪要。 |

### Response

响应体为更新后的完整操作 JSON。

---

---

# 更新操作的拨付账户

URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-conta-desembolso

此端点允许更新操作的拨付账户。

---

## **更新操作的拨付账户 (PUT)**

### **Request**
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /issuer_bank_account
MÉTODO PUT

### **Path Params**

| 字段 | 类型 | 描述 | 最大字符数 |
|-------------------|--------|-----------------------------------------------|-----------------|
| `OPERATION-KEY` * | string | 操作的唯一键（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

### **issuer_bank_account 对象**

| 字段 | 类型 | 描述 |
| --------------------------------------- | ------ | ------------------------------------------ |
| `account_number` *                    | string | 银行账户号码。 |
| `account_digit` *                     | string | 银行账户校验位。 |
| `account_branch` *                    | string | 银行账户支行。 |
| `financial_institution_code_number` * | string | 金融机构代码。 |
| `financial_institution_ispb` *        | string | 金融机构 ISPB 代码。 |
| `account_type` *                      | string | 账户类型（`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": [],
    "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**

| 字段 | 类型 | 描述 |
| ---------------------------- | ------ | ----------------------------------------------------- |
| `tenant_key` *             | string | tenant 的唯一键。 |
| `operation_key` *          | string | 操作的唯一键。 |
| `operation_status` *       | string | 操作的状态。 |
| `issuer_key` *             | string | 发行人的唯一键。 |
| `issuer_name` *            | string | 发行人的名称。 |
| `issuer_document_number` * | string | 发行人的证件号码。 |
| `financial` *              | object | **[financial 对象](#objeto-financial-response)** |

### financial response 对象

| 字段 | 类型 | 描述 | 最大字符数 |
| ---------------------------- | ------- | ---------------------------------------------------------- | ---------------------------------------------------------------------- |
| `financial_base_date` *    | string  | 操作的财务基准日期（格式："YYYY-MM-DD"）。 | - |
| `issue_amount` *           | number  | 操作发行的总金额。 | - |
| `released_amount` *        | number  | 操作中释放的净金额。 | - |
| `issue_quantity` *         | integer | 发行的总单位数量。 | - |
| `unit_price` *             | number  | 每单位发行价格。 | - |
| `cet` *                    | number  | 有效总成本（CET）百分比。 | - |
| `annual_cet` *             | number  | 年化 CET 百分比。 | - |
| `number_of_installments` * | integer | 总期数。 | - |
| `prefixed_interest_rate` * | object  | 包含固定利率详情的对象。 | **[prefixed_interest_rate 对象](#objeto-prefixed_interest_rate)** |
| `fees`                     | array   | 与操作相关的费用列表。 | **[fees 对象](#objeto-fees)** |
| `installments`             | array   | 操作中生成的期数详情列表。 | **[installments 对象](#objeto-installments)** |
| `fine_delay_rate` *        | object  | 包含滞纳金详情的对象。 | **[fine_delay_rate 对象](#objeto-fine_delay_rate)** |
| `contract_fine_rate` *     | number  | 合同罚款百分比。 | - |

### prefixed_interest_rate 对象

| 字段 | 类型 | 描述 | 最大字符数 |
| ------------------- | ------ | ------------------------------- | ---------------------------------------------------------------- |
| `interest_base` * | string | 利率计算基础。 | **[interest_base 枚举](#enumeradores-interest_base)** |
| `monthly_rate` *  | number | 适用的月利率。 | - |
| `daily_rate` *    | number | 适用的日利率。 | - |
| `annual_rate` *   | number | 适用的年利率。 | - |

### fees 对象

| 字段 | 类型 | 描述 | 最大字符数 |
| ----------------- | ------ | ---------------------------------------- | ---------------------------------------------------------------- |
| `amount` *      | number | 费率百分比值。 | - |
| `fee_amount` *  | number | 对应的货币金额。 | - |
| `amount_type` * | string | 费用值类型。 | **[amount_type 枚举](#enumeradores-amount_type)** |
| `fee_type` *    | string | 费用类型。 | **[fee_type 枚举](#enumeradores-fee_type)** |
| `type` *        | string | 费用收款方。 | **[fee_recipient 枚举](#enumeradores-fee_recipient)** |

### installments 对象

| 字段 | 类型 | 描述 |
| --------------------------------------- | ------- | ----------------------------------------------------- |
| `installment_number` *                | integer | 期数编号。 |
| `workdays` *                          | integer | 至到期日的工作日数。 |
| `calendar_days` *                     | integer | 至到期日的自然日数。 |
| `principal_amortization_amount` *     | number  | 本金摊还金额。 |
| `principal_amortization_unit_price` * | number  | 每单位摊还金额。 |
| `interest_amount` *                   | number  | 该期应计利息金额。 |
| `amount` *                            | number  | 该期总金额。 |
| `due_date` *                          | string  | 该期到期日（格式："YYYY-MM-DD"）。 |

---

# 更新操作的财务数据

URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-dados-financeiros

此端点允许更新操作中的财务数据，遵循与模拟端点中发送的 financial 对象相同的标准。

---

## **更新操作的财务数据 (PUT)**

### **Request**
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /financial
MÉTODO PUT

### **Path Params**

| 字段 | 类型 | 描述 | 最大字符数 |
|-------------------|--------|-----------------------------------------------|-----------------|
| `OPERATION-KEY` * | string | 操作的唯一键（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

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------|
| `interest_type` *            | string   | 适用的利率类型。 | **[interest_type 枚举](#enumeradores-interest_type)** |
| `financial_base_date` *      | string   | 操作基准日期（格式："YYYY-MM-DD"）。 | - |
| `released_amount` *          | number   | 操作释放的总金额。 | - |
| `number_of_installments` *   | integer  | 总期数。 | - |
| `prefixed_interest_rate` *   | object   | 包含固定利率详情的对象。 | **[prefixed_interest_rate 对象](#objeto-prefixed_interest_rate)** |
| `fine_delay_rate` *          | object   | 包含滞纳金详情的对象。 | **[fine_delay_rate 对象](#objeto-fine_delay_rate)** |
| `contract_fine_rate` *       | number   | 合同罚款百分比。 | - |
| `fees`                       | array    | 与操作相关的费用列表。 | **[fees 对象](#objeto-fees)** |

### prefixed_interest_rate 对象

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------|
| `interest_base` *            | string   | 利率计算基础。 | **[interest_base 枚举](#enumeradores-interest_base)** |
| `monthly_rate` *             | number   | 适用的月利率。 | - |

### fine_delay_rate 对象

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------|
| `interest_base` *            | string   | 罚款计算基础。 | **[interest_base 枚举](#enumeradores-interest_base)** |
| `monthly_rate` *             | number   | 月罚款率。 | - |

### fees 对象

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------|
| `amount` *                   | number   | 适用的费率值。 | - |
| `amount_type` *              | string   | 费用值类型。 | **[amount_type 枚举](#enumeradores-amount_type)** |
| `fee_type` *                 | string   | 费用类型。 | **[fee_type 枚举](#enumeradores-fee_type)** |
| `type` *                     | string   | 费用收款方。 | **[fee_recipient 枚举](#enumeradores-fee_recipient)** |

### interest_type 枚举

| 枚举值 | 描述 |
|--------------------|--------------------------------------------|
| `pre_price`       | Price 模型的固定利率。 |
| `pre_price_days`  | 按自然日计算的 Price 模型固定利率。 |
| `pre_sac`         | SAC 模型的固定利率。 |
| `post_sac`        | SAC 模型的浮动利率。 |

### interest_base 枚举

| 枚举值 | 描述 |
|--------------------|--------------------------------------------|
| `calendar_days`    | 自然日基础。 |
| `calendar_days_365`| 365 自然日基础。 |
| `workdays`        | 工作日基础。 |

### amount_type 枚举

| 枚举值 | 描述 |
|-------------|---------------------------|
| `percentage` | 百分比值。 |
| `absolute`   | 货币绝对值。 |

### fee_type 枚举

| 枚举值 | 描述 |
|-------------------------------------|-------------------------------------------|
| `bookkeeping_fee`                   | 融资书写费。 |
| `structuring_fee`                   | 融资结构费。 |

### fee_recipient 枚举

| 枚举值 | 描述 |
|-----------|-------------------------------------------------------|
| `internal` | 支付给书写方的费用。 |
| `external` | 支付给发起方的返佣。 |

## **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": [],
        "installment_list": []
    },
    "tags": [],
    "investor_list": [],
    "related_party_list": [],
    "collateral_list": [],
    "metadata_list": []
}
```

### **Response Body Params**

| 字段 | 类型 | 描述 |
| ---------------------------- | ------ | ----------------------------------------------------- |
| `tenant_key` *             | string | tenant 的唯一键。 |
| `operation_key` *          | string | 操作的唯一键。 |
| `operation_status` *       | string | 操作的状态。 |
| `issuer_key` *             | string | 发行人的唯一键。 |
| `issuer_name` *            | string | 发行人的名称。 |
| `issuer_document_number` * | string | 发行人的证件号码。 |
| `financial` *              | object | **[financial 对象](#objeto-financial-response)** |

### financial response 对象

| 字段 | 类型 | 描述 | 最大字符数 |
| ---------------------------- | ------- | ---------------------------------------------------------- | ---------------------------------------------------------------------- |
| `financial_base_date` *    | string  | 操作的财务基准日期（格式："YYYY-MM-DD"）。 | - |
| `issue_amount` *           | number  | 操作发行的总金额。 | - |
| `released_amount` *        | number  | 操作中释放的净金额。 | - |
| `issue_quantity` *         | integer | 发行的总单位数量。 | - |
| `unit_price` *             | number  | 每单位发行价格。 | - |
| `cet` *                    | number  | 有效总成本（CET）百分比。 | - |
| `annual_cet` *             | number  | 年化 CET 百分比。 | - |
| `number_of_installments` * | integer | 总期数。 | - |
| `prefixed_interest_rate` * | object  | 包含固定利率详情的对象。 | **[prefixed_interest_rate 对象](#objeto-prefixed_interest_rate)** |
| `fees`                     | array   | 与操作相关的费用列表。 | **[fees 对象](#objeto-fees)** |
| `installments`             | array   | 操作中生成的期数详情列表。 | **[installments 对象](#objeto-installments)** |
| `fine_delay_rate` *        | object  | 包含滞纳金详情的对象。 | **[fine_delay_rate 对象](#objeto-fine_delay_rate)** |
| `contract_fine_rate` *     | number  | 合同罚款百分比。 | - |

### prefixed_interest_rate 对象

| 字段 | 类型 | 描述 | 最大字符数 |
| ------------------- | ------ | ------------------------------- | ---------------------------------------------------------------- |
| `interest_base` * | string | 利率计算基础。 | **[interest_base 枚举](#enumeradores-interest_base)** |
| `monthly_rate` *  | number | 适用的月利率。 | - |
| `daily_rate` *    | number | 适用的日利率。 | - |
| `annual_rate` *   | number | 适用的年利率。 | - |

### fees 对象

| 字段 | 类型 | 描述 | 最大字符数 |
| ----------------- | ------ | ---------------------------------------- | ---------------------------------------------------------------- |
| `amount` *      | number | 费率百分比值。 | - |
| `fee_amount` *  | number | 对应的货币金额。 | - |
| `amount_type` * | string | 费用值类型。 | **[amount_type 枚举](#enumeradores-amount_type)** |
| `fee_type` *    | string | 费用类型。 | **[fee_type 枚举](#enumeradores-fee_type)** |
| `type` *        | string | 费用收款方。 | **[fee_recipient 枚举](#enumeradores-fee_recipient)** |

### installments 对象

| 字段 | 类型 | 描述 |
| --------------------------------------- | ------- | ----------------------------------------------------- |
| `installment_number` *                | integer | 期数编号。 |
| `workdays` *                          | integer | 至到期日的工作日数。 |
| `calendar_days` *                     | integer | 至到期日的自然日数。 |
| `principal_amortization_amount` *     | number  | 本金摊还金额。 |
| `principal_amortization_unit_price` * | number  | 每单位摊还金额。 |
| `interest_amount` *                   | number  | 该期应计利息金额。 |
| `amount` *                            | number  | 该期总金额。 |
| `due_date` *                          | string  | 该期到期日（格式："YYYY-MM-DD"）。 |

---

# 更新操作中的投资人数据

URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-investidores

此端点允许更新操作中的投资人数据。

---

## **更新操作中的投资人数据 (PUT)**

### **Request**
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /investors
MÉTODO PUT

### **Path Params**

| 字段 | 类型 | 描述 | 最大字符数 |
|-------------------|--------|-----------------------------------------------|-----------------|
| `OPERATION-KEY` * | string | 操作的唯一键（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**

### **investors 对象**

| 字段 | 类型 | 描述 |
| ----------------------------- | ------ | ------------------------------ |
| `investor_key` *            | string | 投资人的唯一键。 |
| `subscription_percentage` * | number | 认购比例。 |
| `bank_account` *            | object | 投资人的银行账户。 |

### **bank_account 对象**

| 字段 | 类型 | 描述 |
| --------------------------------------- | ------ | ------------------------------------------ |
| `account_number` *                    | string | 银行账户号码。 |
| `account_digit` *                     | string | 银行账户校验位。 |
| `account_branch` *                    | string | 银行账户支行。 |
| `financial_institution_code_number` * | string | 金融机构代码。 |
| `financial_institution_ispb` *        | string | 金融机构 ISPB 代码。 |
| `account_type` *                      | string | 账户类型（`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",
    "financial": {},
    "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": [],
    "collateral_list": [],
    "metadata_list": []
}
```

### **Response Body Params**

| 字段 | 类型 | 描述 |
| ---------------------------- | ------ | ----------------------------------------------------- |
| `tenant_key` *             | string | tenant 的唯一键。 |
| `operation_key` *          | string | 操作的唯一键。 |
| `operation_status` *       | string | 操作的状态。 |
| `issuer_key` *             | string | 发行人的唯一键。 |
| `issuer_name` *            | string | 发行人的名称。 |
| `issuer_document_number` * | string | 发行人的证件号码。 |
| `financial` *              | object | **[financial 对象](#objeto-financial-response)** |

---

# 更新操作的签名方式

URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-metodo-assinatura

此端点允许更新操作中的签名方式。

---

## **更新操作的签名方式 (PUT)**

### **Request**
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /signature_method
MÉTODO PUT

### **Path Params**

| 字段 | 类型 | 描述 | 最大字符数 |
|-------------------|--------|-----------------------------------------------|-----------------|
| `OPERATION-KEY` * | string | 操作的唯一键（UUID v4）。 | 36 |

Request Body

```json
{
    "signature_method": "qi_sign"
}
```

### Request Body Params

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------|
| `signature_method` *            | string   | 签名系统类型。 | certifiqi 或 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",
    "financial": {},
    "tags": [],
    "investor_list": [],
    "related_party_list": [],
    "collateral_list": [],
    "metadata_list": [],
    "signature_method": "qi_sign"
}
```

### **Response Body Params**

| 字段 | 类型 | 描述 |
| ---------------------------- | ------ | ----------------------------------------------------- |
| `tenant_key` *             | string | tenant 的唯一键。 |
| `operation_key` *          | string | 操作的唯一键。 |
| `operation_status` *       | string | 操作的状态。 |
| `issuer_key` *             | string | 发行人的唯一键。 |
| `issuer_name` *            | string | 发行人的名称。 |
| `issuer_document_number` * | string | 发行人的证件号码。 |
| `financial` *              | object | **[financial 对象](#objeto-financial-response)** |

---

# 在操作中添加担保品

URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/cadastro-garantia

此端点集合允许**添加**与操作关联的担保品。**担保品（collateral）将与操作文件一同提交签名**。每种担保品类型都有其所需文件的规则，所有担保品类型均在本文档中涵盖。

---

## **提交担保品 (POST)**

## **Request**
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /collateral
MÉTODO POST

### **Path Params**

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------|--------|-----------------------------------------------|-----------------|
| `OPERATION-KEY` *  | string | 操作的唯一键（UUID v4）。 | 36 |

---

担保品系统支持添加不同类型的工具，每种类型都有其附加文件的配置。本节涵盖所有可用的担保品模型及其相应的 payload。

### **担保品类型**

**[1 - 不动产信托转让](#alienação-fiduciária-de-imóvel)** 

**[2 - 车辆信托转让](#alienação-fiduciária-de-veículo)** 

**[3 - 航空器信托转让](#alienação-fiduciária-de-aeronave)** 

**[4 - 设备/产品/库存信托转让](#alienação-fiduciária-de-equipamentos-produtos-e-estoque)** 

**[5 - 艺术品信托转让](#alienação-fiduciária-de-obras-de-arte)** 

**[6 - 有价证券信托转让](#alienação-fiduciária-de-títulos-e-valores-mobiliários)**

**[7 - 股份和份额信托转让](#alienação-fiduciária-de-ações-e-cotas)** 

**[8 - 信贷权信托转让](#alienação-fiduciária-de-direitos-creditórios)** 

**[9 - 不动产抵押](#hipoteca-de-imóveis)** 

**[10 - 船舶抵押](#hipoteca-de-embarcações)** 

**[11 - 保证人](#aval)** 

**[12 - 担保人](#fiador)** 

**[13 - 银行保函](#fiança-bancária)** 

**[14 - 信用卡应收款](#recebiveis-de-cartão)** 

**[15 - 库存担保](#garantia-de-estoque)** 

**[16 - 担保品监控](#monitoramento-de-garantias)** 

**[17 - 其他担保品](#outras-garantias)** 

## **不动产信托转让**

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"
        }
    ]
}
```

### **文件类型**

| 枚举值 | 描述 |
|-----------------|-----------------------------------|
| `property_appraisal_report`**      | 不动产评估报告。 |
| `property_registration_updated`**      | 最新产权登记。 |
| `property_full_content_certificate`**      | 产权完整内容证明。 |
| `property_insurance_policy`      | 保险单（合同规定时要求）。 |
| `others`      | 其他文件。 |

:::warning
(**) 不动产信托转让必须提供
:::

## **车辆信托转让**

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"
        }
    ]
}
```

### **文件类型**

| 枚举值 | 描述 |
|-----------------|-----------------------------------|
| `vehicle_appraisal_report`**      | 车辆评估报告（最多延迟30天）或 FIPE 表。 |
| `vehicle_inspection_report`**      | 车辆检验报告。 |
| `vehicle_crv_certificate`**      | 最新车辆登记证书（CRLV）。 |
| `others`      | 其他文件。 |

:::warning
(**) 车辆信托转让必须提供
:::

## **航空器信托转让**

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"
        }
    ]
}
```

### **文件类型**

| 枚举值 | 描述 |
|-----------------|-----------------------------------|
| `aircraft_certificate_anac`**      | 登记证书 - ANAC。 |
| `aircraft_rab_consult`**      | 巴西航空登记册中的航空器查询。 |
| `aircraft_insurance_policy`**      | 保险单 - 受益人为基金。 |
| `aircraft_appraisal_report`**      | 航空器评估报告。 |
| `others`      | 其他文件。 |

:::warning
(**) 航空器信托转让必须提供
:::

## **设备产品和库存信托转让**

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"
        }
    ]
}
```

### **文件类型**

| 枚举值 | 描述 |
|-----------------|-----------------------------------|
| `equipment_purchase_invoice`**      | 发票 - 购买记录。 |
| `equipment_appraisal_report`**      | 设备评估报告（最多延迟30天）。 |
| `equipment_insurance_policy`      | 设备保险单（合同规定时要求）。 |
| `fiduciary_depositary_declaration`      | 忠实保管人声明。 |
| `others`      | 其他文件。 |

:::warning
(**) 设备/产品/库存信托转让必须提供
:::

## **艺术品信托转让**

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"
        }
    ]
}
```

### **文件类型**

| 枚举值 | 描述 |
|-----------------|-----------------------------------|
| `artwork_appraisal_report`**      | 艺术品评估报告。 |
| `artwork_storage_certificate`**      | 带合规证书的存储地点。 |
| `artwork_insurance_policy`      | 保险单（合同规定时要求）。 |
| `others`      | 其他文件。 |

:::warning
(**) 艺术品信托转让必须提供
:::

## **有价证券信托转让**

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"
        }
    ]
}
```

### **文件类型**

| 枚举值 | 描述 |
|-----------------|-----------------------------------|
| `securities_negotiation_block`**      | 在托管方处的交易冻结。 |
| `securities_registration_gravame`      | 带合规证书的存储地点。 |
| `others`      | 其他文件。 |

:::warning
(**) 有价证券信托转让必须提供
:::

## **股份和份额信托转让**

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"
        }
    ]
}
```

### **文件类型**

| 枚举值 | 描述 |
|-----------------|-----------------------------------|
| `share_registration_book`**      | 带质押注记的记名股份登记簿。 |
| `others`      | 其他文件。 |

:::warning
(**) 股份/份额信托转让/质押必须提供
:::

## **信贷权信托转让**

Request Body

```json
{
    "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff",
    "collateral_type": "fiduciary_assignment_shares"
}
```

### **文件类型**

| 枚举值 | 描述 |
|-----------------|-----------------------------------|
| `others`      | 其他文件。 |

## **不动产抵押**

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"
        }
    ]
}
```

### **文件类型**

| 枚举值 | 描述 |
|-----------------|-----------------------------------|
| `property_appraisal_report`**      | 不动产评估报告。 |
| `property_registration`**      | 最新产权登记。 |
| `property_full_content_certificate`**      | 产权完整内容证明。 |
| `property_insurance_policy`      | 保险单（合同规定时要求）。 |
| `others`      | 其他文件。 |

:::warning
(**) 不动产抵押必须提供
:::

## **船舶抵押**

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"
        }
    ]
}
```

### **文件类型**

| 枚举值 | 描述 |
|-----------------|-----------------------------------|
| `ship_registration`**      | 最新船舶产权登记。 |
| `ship_appraisal_report`**      | 船舶评估报告（最多延迟3个月）。 |
| `ship_insurance_policy`      | 船舶保险单（合同规定时要求）。 |
| `others`      | 其他文件。 |

:::warning
(**) 船舶抵押必须提供
:::

## **保证人**

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"
        }
    ]
}
```

### **文件类型**

| 枚举值 | 描述 |
|-----------------|-----------------------------------|
| `guarantor_civil_status_declaration`**      | 保证人婚姻状况声明。 |
| `guarantor_personal_document`**      | 保证人个人证件。 |
| `guarantor_income_tax_declaration`      | 保证人所得税申报表。 |
| `others`      | 其他文件。 |

:::warning
(**) 保证人必须提供
:::

## **担保人**

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"
        }
    ]
}
```

### **文件类型**

| 枚举值 | 描述 |
|-----------------|-----------------------------------|
| `surety_civil_status_declaration`**      | 担保人婚姻状况声明。 |
| `surety_personal_document`**      | 担保人个人证件。 |
| `surety_income_tax_declaration`      | 担保人所得税申报表。 |
| `others`      | 其他文件。 |

:::warning
(**) 担保人必须提供
:::

## **银行保函**

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"
        }
    ]
}
```

### **文件类型**

| 枚举值 | 描述 |
|-----------------|-----------------------------------|
| `others`      | 其他文件。 |

## **信用卡应收款**

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"
        }
    ]
}
```

### **文件类型**

| 枚举值 | 描述 |
|-----------------|-----------------------------------|
| `others`      | 其他文件。 |

## **库存担保**

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"
        }
    ]
}
```

### **文件类型**

| 枚举值 | 描述 |
|-----------------|-----------------------------------|
| `others`      | 其他文件。 |

## **担保品监控**

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"
        }
    ]
}
```

### **文件类型**

| 枚举值 | 描述 |
|-----------------|-----------------------------------|
| `guarantee_contract`**      | 担保合同。 |
| `guarantee_agent_contract`**      | 担保代理合同。 |
| `others`      | 其他文件。 |

:::warning
(**) 担保品监控必须提供
:::

---
## **Request Body Params**

| 字段 | 类型 | 描述 | 必填 |
|--------------------------------|----------|------------------------------------------------------------------|-------------|
| `collateral_document_key` * | string   | 担保工具的键。 | 是 |
| `collateral_type` *            | string   | 担保品类型。 | **[collateral_type 枚举](#enumeradores-collateral_type)** |
| `collateral_data`           | object   | 与担保品相关的元数据结构。 | 是 |
| `additional_documents` | list   | 与担保品相关的文件。 | - |

### **additional_documents 列表**

| 字段 | 类型 | 描述 | 必填 |
|--------------------------------|----------|------------------------------------------------------------------|-------------|
| `document_key` * | string   | 担保工具的键。 | 是 |
| `document_type` *            | string   | 担保品文件类型。 | 是 |

### **collateral_type 枚举**

| 枚举值 | 描述 |
|-----------------|-----------------------------------|
| `fiduciary_alienation_property`      | 不动产信托转让。 |
| `fiduciary_alienation_vehicle`      | 车辆信托转让。 |
| `fiduciary_alienation_aircraft`      | 航空器信托转让。 |
| `fiduciary_alienation_equipment`      | 设备/产品/库存信托转让。 |
| `fiduciary_alienation_artwork`      | 艺术品信托转让。 |
| `fiduciary_alienation_securities`      | 有价证券信托转让。 |
| `fiduciary_assignment_shares`      | 股份/份额信托转让/质押。 |
| `fiduciary_assignment_credit_rights`      | 信贷权信托转让。 |
| `mortgage_property`      | 不动产抵押。 |
| `mortgage_ship`      | 船舶抵押。 |
| `guarantor`      | 保证人。 |
| `surety`      | 担保人。 |
| `bank_surety`      | 银行保函。 |
| `card_receivables`      | 信用卡应收款。 |
| `stock_guarantee`      | 库存担保。 |
| `monitoring_guarantee`      | 担保品监控。 |
| `others`      | 其他担保品。 |

---

# 从操作中移除担保品

URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/remover-garantia

此端点允许**移除**与操作关联的担保品。

---

## **移除 Collateral (DELETE)**

## **Request**
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /collateral/ COLLATERAL-KEY
MÉTODO DELETE

### **Path Params**

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------|--------|-----------------------------------------------|-----------------|
| `OPERATION-KEY` * | string | 操作的唯一键（UUID v4）。 | 36 |
| `COLLATERAL-KEY` * | string | 待移除的担保品唯一键（UUID v4）。 | 36 |

## **Response**
STATUS 204

**响应体中不返回任何内容。**

---

# 文件上传

URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/upload-documento

此端点允许上传与操作关联的**文件**。这些文件可用于担保品系统，在担保工具之外添加附属文件。

---

## **上传文件 (POST)**

## **Request**
ENDPOINT /commercial_paper/upload
MÉTODO POST

Request Body

```json
{
  "document_base64": "sringb64"
}
```

### **Request Body Params**

| 字段 | 类型 | 描述 | 必填 |
|--------------------------------|----------|------------------------------------------------------------------|-------------|
| `document_base64` * | string   | Base64 编码的文件内容。 | 是 |

## **Response**
STATUS 201

Response Body

```json
{
  "document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b"
}
```

## **Response Body Params**

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------|----------|----------------------------------------------|-----------------|
| `document_key` * | string   | 已添加文件的唯一键（UUID v4）。 | 36 |
---

---

# 在操作中登记和删除元数据

URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-metadata-identificacao

此端点集合允许在操作中登记和删除元数据。

---

## **在操作中登记元数据 (POST)**

### **Request**
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /metadata
MÉTODO POST

### **Path Params**

| 字段 | 类型 | 描述 | 最大字符数 |
|-------------------|--------|-----------------------------------------------|-----------------|
| `OPERATION-KEY` * | string | 操作的唯一键（UUID v4）。 | 36 |

Request Body

```json
{
  "metadata_key": "custom_meta_field",
  "metadata_value": "custom_meta_value"
}
```

### **Request Body Params**

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------|----------|--------------------------------------|-----------------|
| `metadata_key` *   | string | 元数据键。 | 255 |
| `metadata_value` * | string | 元数据值。 | 1023 |

### **Response**
STATUS 201

Response Body

```json
{
  "metadata_key": "custom_meta_field",
  "metadata_value": "custom_meta_value"
}
```

### **Response Body Params**

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------|----------|--------------------------------------|-----------------|
| `metadata_key` *   | string | 元数据键。 | 255 |
| `metadata_value` * | string | 元数据值。 | 1023 |

---

## **从操作中删除元数据 (DELETE)**

### **Request**
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /metadata
MÉTODO DELETE

### **Path Params**

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------|--------|-----------------------------------------------|-----------------|
| `OPERATION-KEY` *  | string | 操作的唯一键（UUID v4）。 | 36 |

Request Body

```json
{
  "metadata_key": "custom_meta_field",
  "metadata_value": "custom_meta_value"
}
```

### **Request Body Params**

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------|----------|--------------------------------------|-----------------|
| `metadata_key` *   | string | 元数据键。 | 255 |
| `metadata_value` * | string | 元数据值。 | 1023 |

---

### **Response**
STATUS 204

**响应体中不返回任何内容。**

---

# 发送和删除关联方代表的文件

URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-documento

此端点集合允许发送和删除与操作关联方代表相关的文件。

---

## **发送代表文件 (POST)**

### **Request**
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /related_party/ RELATED-PARTY-KEY /document
MÉTODO POST

### **Path Params**

| 字段 | 类型 | 描述 | 最大字符数 |
|---------------------|--------|----------------------------------------------|-----------------|
| `OPERATION-KEY` *     | string | 操作的唯一键（UUID v4）。 | 36 |
| `RELATED-PARTY-KEY` * | string | 关联方的唯一键（UUID v4）。 | 36 |

Request Body

```json
{
  "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0",
  "document_type": "cnh"
}
```

### **Request Body Params**

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------|----------|-----------------------------------------------------------------|-----------------|
| `document_base64` * | string   | Base64 编码的文件内容。 | - |
| `document_type` *  | string   | 提交的文件类型。 | **[document_type 枚举](#enumeradores-document_type)** |

## **Response**
STATUS 201

Response Body

**场景 1：自动验证（OCR 成功）**

```json
{
  "document_key": "123e4567-e89b-12d3-a456-426614174000",
  "document_type": "cnh",
  "ocr_key": "6654f284-f690-4324-8c39-dcf0225ec8cf"
}
```
**含义**：文件已由我们的 OCR 自动处理并验证。

**场景 2：需要人工核查**

```json
{
    "document_key": "8bf591a8-c184-47db-afd2-a5196de14cc3",
    "document_type": "cnh",
    "ocr_key": null
}
```
**含义**：文件无法通过 OCR 自动验证，已转入人工核查队列。

:::warning 注意
成功请求的响应（提交成功）根据自动验证（OCR）结果会呈现两种不同行为。
:::
### **Response Body Params**

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------|----------|----------------------------------------------|-----------------|
| `document_key` * | string   | 提交文件的唯一标识符。 | 36 |
| `document_type` * | string   | 提交的文件类型。 | **[document_type 枚举](#enumeradores-document_type)** |
| `ocr_key`        | string   | 与提交文件关联的 OCR 键。 | 36 |

---

## **删除代表文件 (DELETE)**

### **Request**
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /related_party/ RELATED-PARTY-KEY /document/ DOCUMENT-KEY
MÉTODO DELETE

### **Path Params**

| 字段 | 类型 | 描述 | 最大字符数 |
|---------------------|--------|----------------------------------------------|-----------------|
| `OPERATION-KEY` *     | string | 操作的唯一键（UUID v4）。 | 36 |
| `RELATED-PARTY-KEY` * | string | 关联方的唯一键（UUID v4）。 | 36 |
| `DOCUMENT-KEY` *      | string | 待删除文件的唯一键。 | 36 |

### **Response**
STATUS 204

**响应体中不返回任何内容。**

### **document_type 枚举**

| 枚举值 | 描述 |
|---------------------------|-----------------------------------------|
| `proof_of_address`        | 地址证明。 |
| `letter_of_attorney`      | 委托书。 |
| `company_statute`         | 公司章程。 |
| `cnh`                     | 全国驾驶证（CNH）。 |
| `cnh_front`               | CNH 正面。 |
| `cnh_back`                | CNH 背面。 |
| `cnh_digital`             | 数字 CNH。 |
| `rg_front`                | 身份证正面。 |
| `rg_back`                 | 身份证背面。 |

---

# 发送和删除关联方代表的签名人组

URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-grupo-assinantes

此端点集合允许发送和删除与操作关联方代表相关的签名人组。

---

## **发送签名人组 (POST)**

### **Request**
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /related_party/ RELATED-PARTY-KEY /signer_group
MÉTODO POST

### **Path Params**

| 字段 | 类型 | 描述 | 最大字符数 |
|-----------------------|--------|----------------------------------------------|-----------------|
| `OPERATION-KEY` *     | string | 操作的唯一键（UUID v4）。 | 36 |
| `RELATED-PARTY-KEY` * | string | 关联方的唯一键（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**

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------------------|----------|--------------------------------------------------------|-----------------|
| `minimum_required_signers` * | integer  | 组内所需的最少签名人数。 | - |
| `signers` *                  | array    | 组内签名人列表。 | **[signers 对象](#objeto-signers)** |

---

### **signers 对象**

| 字段 | 类型 | 描述 | 最大字符数 |
|--------------------------|----------|-------------------------------------------------|-----------------|
| `name` *                | string   | 签名人全名。 | 255 |
| `document_number` *      | string   | 签名人 CPF（11 位数字）。 | 11 |
| `email` *               | string   | 签名人电子邮件地址。 | 1023 |
| `phone_number` *        | string   | 含国际区号的签名人电话号码。 | 20 |
| `is_group_mandatory` *  | boolean  | 指示签名人是否为必须签名人。 | - |

## **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**

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------------------|----------|-------------------------------------------------|-----------------|
| `signer_group_key` *         | string   | 签名人组的唯一键（UUID v4）。 | 36 |
| `minimum_required_signers` * | integer  | 组内所需的最少签名人数。 | - |
| `signers` *                  | array    | 组内签名人列表。 | **[signers 对象](#objeto-signers)** |

---

## **删除签名人组 (DELETE)**

### **Request**
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /related_party/ RELATED-PARTY-KEY /signer_group/ SIGNER-GROUP-KEY
MÉTODO DELETE

### **Path Params**

| 字段 | 类型 | 描述 | 最大字符数 |
|-----------------------|--------|----------------------------------------------|-----------------|
| `OPERATION-KEY` *     | string | 操作的唯一键（UUID v4）。 | 36 |
| `RELATED-PARTY-KEY` * | string | 关联方的唯一键（UUID v4）。 | 36 |
| `SIGNER-GROUP-KEY` *  | string | 签名人组的唯一键。 | 36 |

### **Response**
STATUS 204

**响应体中不返回任何内容。**

---

# 在特定文件中登记和删除关联方

URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-parte-relacionada-em-documento

此端点集合允许在操作的特定文件中登记和删除关联方。

---

## **将关联方添加到文件 (POST)**

### **Request**

ENDPOINT /commercial_paper/operation/ OPERATION-KEY /formalization_document /FORMALIZATION-DOCUMENT-KEY /related_party
MÉTODO POST

### **Path Params**

| 字段 | 类型 | 描述 | 最大字符数 |
| ------------------- | ------ | ------------------------------------- | ---------------- |
| `OPERATION-KEY` * | string | 操作的唯一键（UUID v4）。 | 36 |
| `FORMALIZATION-DOCUMENT-KEY` * | string | 操作文件的唯一键（UUID v4）。 | 36 |

Request Body

```json
{
  "related_party_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e"
}
```

### **Request Body Params**

| 字段 | 类型 | 描述 | 最大字符数 |
| --------------------- | ------ | ---------------------------------------------------------------------- | ------------------------------------------------------------ |
| `related_party_key` *     | string | 关联方的键。 | 36 |

## **Response**

STATUS 204

**响应体中不返回任何内容。**

## **删除关联方 (DELETE)**

### **Request**

ENDPOINT /commercial_paper/operation/ OPERATION-KEY /formalization_document/ FORMALIZATION-DOCUMENT-KEY /related_party
MÉTODO DELETE

### **Path Params**

| 字段 | 类型 | 描述 | 最大字符数 |
| ----------------------- | ------ | ------------------------------------- | ---------------- |
| `OPERATION-KEY` *     | string | 操作的唯一键（UUID v4）。 | 36 |
| `FORMALIZATION-DOCUMENT-KEY` * | string | 操作文件的唯一键（UUID v4）。 | 36 |

Request Body

```json
{
  "related_party_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e"
}
```

### **Response**

STATUS 204

**响应体中不返回任何内容。**

---

# 登记和删除关联方

URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/cadastrar-parte-relacionada

此端点集合允许在操作中登记和删除关联方。

:::warning
所有关联方默认会被添加到组成性条款（**commercial_paper**）中，如需将该关联方添加到特定文件，请在 **related_document_key** 字段中填写所需文件的键。
:::

---

## **登记关联方 (POST)**

### **Request**

ENDPOINT /commercial_paper/operation/ OPERATION-KEY /related_party
MÉTODO POST

### **Path Params**

| 字段 | 类型 | 描述 | 最大字符数 |
| ------------------- | ------ | ------------------------------------- | ---------------- |
| `OPERATION-KEY` * | string | 操作的唯一键（UUID v4）。 | 36 |

:::info 重要
**构建 payload 时请注意人员类型：**
- **自然人（PF）**：`"person_type": "natural"`
- **法人（PJ）**：`"person_type": "legal"`
:::

Request Body - 自然人（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 - 法人（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**

| 字段 | 类型 | 描述 | 最大字符数 |
| --------------------- | ------ | ---------------------------------------------------------------------- | ------------------------------------------------------------ |
| `person_type` *     | string | 人员类型。 | **[person_type 枚举](#enumeradores-person_type)** |
| `name` *            | string | 关联方名称。 | 255 |
| `document_number` * | string | CPF（格式："XXX.XXX.XXX-XX"）或 CNPJ（格式："XX.XXX.XXX/XXXX-XX"）。 | 14 |
| `street` *          | string | 地址街道。 | 500 |
| `neighborhood`      | string | 地址区域。 | 100 |
| `number` *          | string | 地址门牌号。 | 10 |
| `postal_code` *     | string | 邮政编码（格式："XXXXX-XXX"）。 | 8 |
| `city` *            | string | 地址城市。 | 255 |
| `state` *           | string | 州缩写（2个字符）。 | 2 |
| `role_type` *       | string | 关联方角色。 | **[role_type 枚举](#enumeradores-role_type)** |
| `related_document_key`        | string | 文件标识键（UUIDv4）。 | 36 |

### **person_type 枚举**

| 枚举值 | 描述 |
| ----------- | ---------------- |
| `natural` | 自然人 |
| `legal`   | 法人 |

### **自然人额外字段**

| 字段 | 类型 | 描述 | 最大字符数 |
| ---------------------------------- | ------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------- |
| `document_identification_number` | string  | 身份证号（无格式）。 | 20 |
| `marital_status`                 | string  | 婚姻状况。 | **[marital_status 枚举](#enumeradores-marital_status)** |
| `property_system`                | string  | 夫妻财产制度。 | **[property_system 枚举](#enumeradores-property_system)** |
| `birthdate`                      | string  | 出生日期（YYYY-MM-DD）。 | - |
| `nationality`                    | string  | 国籍。 | 255 |
| `mother_name`                    | string  | 母亲姓名。 | 255 |
| `father_name`                    | string  | 父亲姓名。 | 255 |
| `occupation`                     | string  | 职业。 | 255 |
| `is_pep` *                       | boolean | 指示关联方是否为政治公众人物（PEP）。 | |

### **法人额外字段**

| 字段 | 类型 | 描述 | 最大字符数 |
| --------------------- | ------ | -------------------------------------- | -------------------------------------------------------------- |
| `trading_name` *    | string | 公司商业名称。 | 1023 |
| `cnae_code` *       | string | 公司 CNAE 代码（10位数字）。 | 10 |
| `company_type` *    | string | 公司类型。 | **[company_type 枚举](#enumeradores-company_type)** |
| `foundation_date` * | string | 成立日期（YYYY-MM-DD）。 | - |

### **role_type 枚举**

| 枚举值 | 描述 |
| -------------------------- | ------------------------ |
| `cosigner`               | 共同签署人 |
| `fiduciary_debtor`       | 信托债务人 |
| `solidary_debtor`        | 连带债务人 |
| `guarantor`              | 担保人 |
| `bonafide_depositary`    | 忠实保管人 |
| `intervening_guarantor`  | 介入担保人 |
| `intervening_consentor`  | 介入同意人 |
| `intervening_discharger` | 介入清偿人 |
| `assignor`               | 出让人 |
| `endorser`               | 背书人 |
| `consulting`             | 顾问 |
| `fund_administrator`     | 基金管理人 |
| `fund_representative`    | 基金代表 |
| `company_representative` | 公司代表 |
| `attestant`              | 见证人 |
| `debtor`                 | 债务人 |
| `bestowal`               | 配偶同意 |
| `manager`                | 管理人 |

### marital_status 枚举

| 枚举值 | 描述 |
| ----------- | ---------------- |
| `single`    | 单身 |
| `married`   | 已婚 |
| `divorced`  | 离婚 |
| `widowed`   | 丧偶 |
| `separated` | 分居 |
| `stable_union`| 稳定伴侣关系 |

### property_system 枚举

| 枚举值 | 描述 |
| --------------------------------- | -------------------------------------- |
| `total_communion_of_goods`        | 完全共同财产制 |
| `partial_communion_of_goods`      | 部分共同财产制 |
| `total_separation_of_goods`       | 完全分别财产制 |
| `final_participation_of_acquisitions` | 婚后所得共同制 |
| `compulsory_separation_of_goods`  | 法定分别财产制 |

### company_type 枚举

| 枚举值 | 描述 |
| ------------------- | ---------------------------- |
| `ltda`             | 有限责任公司 |
| `sa`               | 股份公司 |
| `cop` | 合作社 |

## **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**

| 字段 | 类型 | 描述 | 最大字符数 |
| ----------------------- | ------- | ---------------------------------------------------- | ------------------------------------------------------------ |
| `related_party_key` * | string  | 关联方的唯一键。 | 36 |
| `name` *              | string  | 关联方名称。 | 255 |
| `document_number` *   | string  | 关联方的 CPF/CNPJ。 | 14 |
| `role_type` *         | string  | 关联方角色。 | 50 |
| `is_active` *         | boolean | 指示是否处于活动状态。 | - |
| `updated_at`          | string  | 最后更新日期（YYYY-MM-DD HH:mm:ss）。 | - |
| `person_type` *       | string  | 人员类型。 | **[person_type 枚举](#enumeradores-person_type)** |
| `street` *            | string  | 街道。 | 500 |
| `neighborhood`        | string  | 区域。 | 100 |
| `number` *            | string  | 门牌号。 | 10 |
| `postal_code` *       | string  | 邮政编码（仅数字）。 | 8 |
| `city` *              | string  | 城市。 | 255 |
| `state` *             | string  | 州缩写（2个字符）。 | 2 |

---

## **删除关联方 (DELETE)**

### **Request**

ENDPOINT /commercial_paper/operation/ OPERATION-KEY /related_party/ RELATED-PARTY-KEY
MÉTODO DELETE

### **Path Params**

| 字段 | 类型 | 描述 | 最大字符数 |
| ----------------------- | ------ | ------------------------------------- | ---------------- |
| `OPERATION-KEY` *     | string | 操作的唯一键（UUID v4）。 | 36 |
| `RELATED-PARTY-KEY` * | string | 关联方的唯一键。 | 36 |

### **Response**

STATUS 204

**响应体中不返回任何内容。**

---

# 登记商业票据操作

URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/criar-operacao

此端点允许根据财务数据和投资人数据创建新的商业票据操作。

---

## **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**

| 字段 | 类型 | 描述 | 最大字符数 |
| ------------------------- | ------ | ------------------------------------------------------ | ---------------------------------------------------------------- |
| `issuer_key` *          | string | 发行人的唯一键。 | - |
| `issuer_bank_account` * | object | 发行人的银行账户。 | **[issuer_bank_account 对象](#objeto-issuer_bank_account)** |
| `investors` *           | array  | 相关投资人列表。 | **[investors 对象](#objeto-investors)** |
| `issue_date` *          | string | 操作发行日期（格式："YYYY-MM-DD"）。 | - |
| `signature_method`      | string | 操作中使用的签名方式。可选；省略时默认为 `certifiqi`。 | **[signature_method 枚举值](#signature_method-枚举值)** |
| `financial` *           | object | 操作的财务数据。 | **[financial 对象](#objeto-financial)** |

### **issuer_bank_account 对象**

| 字段 | 类型 | 描述 |
| --------------------------------------- | ------ | ------------------------------------------ |
| `account_number` *                    | string | 银行账户号码。 |
| `account_digit` *                     | string | 银行账户校验位。 |
| `account_branch` *                    | string | 银行账户支行。 |
| `financial_institution_code_number` * | string | 金融机构代码。 |
| `financial_institution_ispb` *        | string | 金融机构 ISPB 代码。 |
| `account_type` *                      | string | 账户类型（`checking`、`savings`）。 |

### **investors 对象**

| 字段 | 类型 | 描述 |
| ----------------------------- | ------ | ------------------------------ |
| `investor_key` *            | string | 投资人的唯一键。 |
| `subscription_percentage` * | number | 认购比例。 |
| `bank_account` *            | object | 投资人的银行账户。 |

### **financial 对象**

| 字段 | 类型 | 描述 |
| ---------------------------- | ------- | -------------------------------------------- |
| `interest_type` *          | string  | 利率类型。 |
| `financial_base_date` *    | string  | 财务基准日期（格式："YYYY-MM-DD"）。 |
| `released_amount`         | number  | 释放金额。 |
| `issue_amount`         | number  | 发行金额。 |
| `number_of_installments` * | integer | 期数。 |
| `installments`  | array  | **[installments 对象](#objeto-installments)** |
| `prefixed_interest_rate` * | object  | **[prefixed_interest_rate 对象](#objeto-prefixed_interest_rate)** |
| `fine_delay_rate` *        | object  | 滞纳金利率。 |
| `contract_fine_rate` *     | number  | 合同罚款百分比。 |
| `fees`                     | array   | 费用列表。 |

:::warning 注意
**financial 对象**必须包含有效的参数组合才能被处理。接受的组合为：发行/释放金额 + 利率、发行/释放金额 + 每期金额、每期金额 + 利率、发行/释放金额 + 利率 + 每期摊还比例。
:::

### installments 对象

| 字段 | 类型 | 描述 |
|------------------------------|----------|-----|
| `due_date` *            | string   | 期次到期日（格式："YYYY-MM-DD"）。 |
| `amount`              | number   | 期次总金额。 |
| `principal_amortization_percentage`              | number   | 本金摊还百分比值。 |

### prefixed_interest_rate 对象

| 字段 | 类型 | 描述 |
|------------------------------|----------|-----|
| `interest_base` *            | string   | 利率计算基础。 |
| `daily_rate`              | number   | 适用的日利率。 |
| `monthly_rate`              | number   | 适用的月利率。 |
| `annual_rate`              | number   | 适用的年利率。 |

### signature_method 枚举值

| 值          | 描述                                                                                                         |
| ----------- | ------------------------------------------------------------------------------------------------------------ |
| `certifiqi` | 默认值。操作将发送至签名服务；创建签名信封，客户端将收到签名 URL（`signature_url`）。                          |
| `qi_sign`   | 操作将发送至签名服务；创建签名信封，客户端将收到签名 URL（`signature_url`）。此外还支持查询操作的签署人。 |

## **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**

| 字段 | 类型 | 描述 |
| ---------------------------- | ------ | ----------------------------------------------------- |
| `tenant_key` *             | string | tenant 的唯一键。 |
| `operation_key` *          | string | 操作的唯一键。 |
| `operation_status` *       | string | 操作的状态。 |
| `issuer_key` *             | string | 发行人的唯一键。 |
| `issuer_name` *            | string | 发行人的名称。 |
| `issuer_document_number` * | string | 发行人的证件号码。 |
| `financial` *              | object | **[financial 对象](#objeto-financial-response)** |

### financial response 对象

| 字段 | 类型 | 描述 | 最大字符数 |
| ---------------------------- | ------- | ---------------------------------------------------------- | ---------------------------------------------------------------------- |
| `financial_base_date` *    | string  | 操作的财务基准日期（格式："YYYY-MM-DD"）。 | - |
| `issue_amount` *           | number  | 操作发行的总金额。 | - |
| `released_amount` *        | number  | 操作中释放的净金额。 | - |
| `issue_quantity` *         | integer | 发行的总单位数量。 | - |
| `unit_price` *             | number  | 每单位发行价格。 | - |
| `cet` *                    | number  | 有效总成本（CET）百分比。 | - |
| `annual_cet` *             | number  | 年化 CET 百分比。 | - |
| `number_of_installments` * | integer | 总期数。 | - |
| `prefixed_interest_rate` * | object  | 包含固定利率详情的对象。 | **[prefixed_interest_rate 对象](#objeto-prefixed_interest_rate-response)** |
| `fees`                     | array   | 与操作相关的费用列表。 | **[fees 对象](#objeto-fees)** |
| `installments`             | array   | 操作中生成的期数详情列表。 | **[installments 对象](#objeto-installments-response)** |
| `fine_delay_rate` *        | object  | 包含滞纳金详情的对象。 | **[fine_delay_rate 对象](#objeto-fine_delay_rate)** |
| `contract_fine_rate` *     | number  | 合同罚款百分比。 | - |

### prefixed_interest_rate response 对象

| 字段 | 类型 | 描述 |
| ------------------- | ------ | ------------------------------- |
| `interest_base` * | string | 利率计算基础。 |
| `monthly_rate`   | number | 适用的月利率。 |
| `daily_rate`     | number | 适用的日利率。 |
| `annual_rate`    | number | 适用的年利率。 |

### fees 对象

| 字段 | 类型 | 描述 |
| ----------------- | ------ | ---------------------------------------- |
| `amount` *      | number | 费率百分比值。 |
| `fee_amount` *  | number | 对应的货币金额。 |
| `amount_type` * | string | 费用值类型。 |
| `fee_type` *    | string | 费用类型。 |
| `type` *        | string | 费用收款方。 |

### installments response 对象

| 字段 | 类型 | 描述 |
| --------------------------------------- | ------- | ----------------------------------------------------- |
| `installment_number` *                | integer | 期数编号。 |
| `workdays` *                          | integer | 至到期日的工作日数。 |
| `calendar_days` *                     | integer | 至到期日的自然日数。 |
| `principal_amortization_amount` *     | number  | 本金摊还金额。 |
| `principal_amortization_unit_price` * | number  | 每单位摊还金额。 |
| `interest_amount` *                   | number  | 该期应计利息金额。 |
| `amount` *                            | number  | 该期总金额。 |
| `due_date` *                          | string  | 该期到期日（格式："YYYY-MM-DD"）。 |

---

# Campos Extras (Extra Fields)

URL: /zh-Hans/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.                                                   |

---

# 取消操作

URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/cancelar-operacao

此端点允许将操作状态更改为"已取消"，适用于客户不再继续完成操作的最终状态。

---

## 取消操作 (PATCH)

### Request
ENDPOINT /commercial_paper/operation/ OPERATION-KEY
MÉTODO PATCH

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
|------------------|--------|----------------------------------------------------------|------------|
| `OPERATION-KEY`  | string | 操作的唯一键（UUID v4）。 | 36 |

---

### Request Body

```json
{
  "operation_status": "canceled"
}
```

### Request Body Params

| 字段 | 类型 | 描述 | 必填 |
|--------------------|----------|------------------------------------------------------------|-------------|
| `operation_status` | string   | 操作状态。必须设置为 `canceled`。 | 是 |

---

### Response

响应体为更新后的完整操作 JSON。

---

---

# 查询通过 QI SIGN 签署的操作合同链接

URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/consulta-link-assinado-qisign

此端点允许通过操作的唯一键查询特定操作中所有通过 QI SIGN 签署的文件。

---

:::warning 注意
 已签署合同的链接有效期为 24 小时。之后需要通过再次调用该端点来更新链接。
:::

## 查询操作的已签署链接 (GET)

### Request
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /signed_url
MÉTODO GET

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
|------------------|--------|----------------------------------------------------------|------------|
| `OPERATION-KEY`  | string | 操作的唯一键（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

| 字段 | 类型 | 描述 | 最大字符数 |
|-----------------------------------|----------|------------------------------------------------------|-----------------------------------------------------------------|
| `envelope_key`                    | string   | 信封的唯一键（UUID v4）。 | 36 |
| `status`               | string   | 信封的状态。 | [operation-status 枚举](#enumeradores-operation-status) |
| `documents`                | list   | 信封中的文件列表。 | - |

### document 对象

| 字段 | 类型 | 描述 | 最大字符数 |
|-------------------------------------|----------|------------------------------------------------|-----------------|
| `document_type`                    | string   | 文件类型。 | [document type 枚举](#enumeradores-document-type) |
| `signed_url`                    | string   | 已签署合同的下载 URL。 | - |
| `signers`                    | list   | 签名人列表。 | - |

## **operation-status 枚举**

| 枚举值 | 描述 |
|--------------------------------|----------------------------------------------------------------|
| `waiting_signature`            | 等待相关方签名。 |
| `signed`                       | 签名完成。 |
| `signature_rejected`           | 签名被拒绝。 |
| `canceled`                     | 操作已取消。 |

## **document-type 枚举**

| 枚举值 | 描述 |
|----------------------------------|------------------------------------------------------------------|
| `contract`                       | 合同标识符。 |
| `ncom_pre_price`                 | 商业票据 Pre price。 |
| `ncom_pre_price_days`            | 商业票据 Pre price days。 |
| `ncom_pre_sac`                   | 商业票据 Pre sac。 |
| `ncom_post_sac_cdi`              | 与 CDI 挂钩的 Pós sac 商业票据。 |
| `ncom_post_sac_ipca`             | 与 IPCA 挂钩的 Pós sac 商业票据。 |
| `ncom_post_sac_igpm`             | 与 IGP-M 挂钩的 Pós sac 商业票据。 |
| `ncom_post_price_cdi`            | 与 CDI 挂钩的 Pós price 商业票据。 |
| `ncom_post_price_ipca`           | 与 IPCA 挂钩的 Pós price 商业票据。 |
| `ncom_post_price_igpm`           | 与 IGP-M 挂钩的 Pós price 商业票据。 |
| `ncom_post_price_days_cdi`       | 与 CDI 挂钩的 Pós price days 商业票据。 |
| `ncom_post_price_days_ipca`      | 与 IPCA 挂钩的 Pós price days 商业票据。 |
| `ncom_post_price_days_igpm`      | 与 IGP-M 挂钩的 Pós price days 商业票据。 |
| `subscription_note`              | 认购公告。 |
| `adhesion_term`                  | 加入条款。 |

---

# 查询通过 QI SIGN 签署操作的链接

URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/consulta-link-assinatura-qisign

此端点允许通过操作的唯一键查询特定操作中所有通过 QI SIGN 进行签名的链接。

---

## 查询操作的签名链接 (GET)

### Request
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /signers
MÉTODO GET

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
|------------------|--------|----------------------------------------------------------|------------|
| `OPERATION-KEY`  | string | 操作的唯一键（UUID v4）。 | 36 |

---

### 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

| 字段 | 类型 | 描述 | 最大字符数 |
|-----------------------------------|----------|------------------------------------------------------|-----------------------------------------------------------------|
| `envelope_key`                    | string   | 信封的唯一键（UUID v4）。 | 36 |
| `status`               | string   | 信封的状态。 | [operation-status 枚举](#enumeradores-operation-status) |
| `documents`                | list   | 信封中的文件列表。 | - |

### document 对象

| 字段 | 类型 | 描述 | 最大字符数 |
|-------------------------------------|----------|------------------------------------------------|-----------------|
| `document_type`                    | string   | 文件类型。 | [document type 枚举](#enumeradores-document-type) |
| `signers`                    | list   | 签名人列表。 | - |

### signer 对象

| 字段 | 类型 | 描述 | 最大字符数 |
|-------------------------------------|----------|------------------------------------------------|-----------------|
| `document_number`                    | string   | 签名人的证件号码。 | 18 |
| `signature_url`                    | string   | 签名人的签名链接。 | - |
| `status`                    | string   | 签名人的状态。 | [status 枚举](#enumeradores-status) |
| `name`                    | string   | 签名人姓名。 | - |
| `email`                    | string   | 签名人电子邮件。 | - |

## **operation-status 枚举**

| 枚举值 | 描述 |
|--------------------------------|----------------------------------------------------------------|
| `waiting_signature`            | 等待相关方签名。 |
| `signed`                       | 签名完成。 |
| `signature_rejected`           | 签名被拒绝。 |
| `canceled`                     | 操作已取消。 |

## **status 枚举**

| 枚举值 | 描述 |
|--------------------------------|----------------------------------------------------------------|
| `on_signature`            | 等待相关方签名。 |
| `analyzed`            | 通过 API 完成签名。 |
| `signed`                       | 签名完成。 |
| `signature_rejected`           | 签名被拒绝。 |
| `canceled`                     | 操作已取消。 |
| `created`                      | 签名已创建。 |
| `submitted`                      | 已发送给签名人。 |
| `sending_sign_receipt`                      | 正在发送简化签名档案。 |
| `analyzing`                      | 签名人正在分析中。 |
| `completed`                      | 签名完成。 |
| `expired`                      | 签名已过期。 |
| `removed`                      | 签名人已移除。 |
| `failed_waiting_for_manual_fix`                      | 签名创建失败，需要 QI 人工处理。 |

## **document-type 枚举**

| 枚举值 | 描述 |
|----------------------------------|------------------------------------------------------------------|
| `contract`                       | 合同标识符。 |
| `ncom_pre_price`                 | 商业票据 Pre price。 |
| `ncom_pre_price_days`            | 商业票据 Pre price days。 |
| `ncom_pre_sac`                   | 商业票据 Pre sac。 |
| `ncom_post_sac_cdi`              | 与 CDI 挂钩的 Pós sac 商业票据。 |
| `ncom_post_sac_ipca`             | 与 IPCA 挂钩的 Pós sac 商业票据。 |
| `ncom_post_sac_igpm`             | 与 IGP-M 挂钩的 Pós sac 商业票据。 |
| `ncom_post_price_cdi`            | 与 CDI 挂钩的 Pós price 商业票据。 |
| `ncom_post_price_ipca`           | 与 IPCA 挂钩的 Pós price 商业票据。 |
| `ncom_post_price_igpm`           | 与 IGP-M 挂钩的 Pós price 商业票据。 |
| `ncom_post_price_days_cdi`       | 与 CDI 挂钩的 Pós price days 商业票据。 |
| `ncom_post_price_days_ipca`      | 与 IPCA 挂钩的 Pós price days 商业票据。 |
| `ncom_post_price_days_igpm`      | 与 IGP-M 挂钩的 Pós price days 商业票据。 |
| `subscription_note`              | 认购公告。 |
| `adhesion_term`                  | 加入条款。 |

---

# 通过键查询操作

URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-chave

此端点允许使用操作的唯一键查询特定操作的完整详情。

---

## 查询操作 (GET)

### Request
ENDPOINT /commercial_paper/operation/ OPERATION-KEY
MÉTODO GET

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
|------------------|--------|----------------------------------------------------------|------------|
| `OPERATION-KEY`  | string | 操作的唯一键（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",
    "financial": {},
    "tags": [],
    "investor_list": [],
    "related_party_list": [],
    "collateral_list": [],
    "metadata_list": [],
    "integralization_key": "d8fdb578-1e2a-4b79-8267-5b1763e56754",
    "security_key": "26299c0f-2127-45d4-b22e-f2b494d2f7ae"
}
```

### Response Body Params

| 字段 | 类型 | 描述 | 最大字符数 |
|-----------------------------------|----------|------------------------------------------------------|-----------------------------------------------------------------|
| `tenant_key` *                    | string   | tenant 的唯一键（UUID v4）。 | 36 |
| `operation_key` *                 | string   | 操作的唯一键（UUID v4）。 | 36 |
| `operation_type` *                | string   | 操作类型。`commercial_paper` | - |
| `operation_status` *              | string   | 操作状态。 | [operation_status 枚举](#enumeradores-operation_status) |
| `issuer_key` *                    | string   | 发行人的唯一键（UUID v4）。 | 36 |
| `issuer_name` *                   | string   | 发行人名称。 | - |
| `issuer_document_number` *        | string   | 发行人证件号码（CNPJ）。 | 18 |
| `issuer_bank_account` *           | object   | 发行人的银行数据。 | [bank_account 对象](#objeto-bank_account) |
| `issuer_onboarding_approved` *    | boolean  | 指示发行人的 onboarding 是否已获批准。 | - |
| `issue_number` *                  | integer  | 发行编号。 | - |
| `issue_series` *                  | integer  | 发行系列。 | - |
| `contract_number` *               | string   | 合同编号。 | - |
| `issue_date` *                    | string   | 发行日期（ISO 8601 格式）。 | - |
| `financial_base_date` *           | string   | 操作的财务基准日期（ISO 8601 格式）。 | - |
| `commercial_paper_template_key` * | string   | 商业票据模板的唯一键。 | 36 |
| `commercial_paper_document_key` * | string   | 商业票据文件的键。 | - |
| `adhesion_term_template_key` *    | string   | 加入条款模板的唯一键。 | 36 |
| `adhesion_term_document_key` *    | string   | 加入条款文件的键。 | - |
| `investor_list` *                 | object   | 投资人列表。 | [investor 对象](#objeto-investor) |

### bank_account 对象

| 字段 | 类型 | 描述 | 最大字符数 |
|-------------------------------------|----------|------------------------------------------------|-----------------|
| `account_type` *                    | string   | 账户类型（例如：checking）。 | - |
| `account_digit` *                    | string   | 银行账户校验位。 | - |
| `account_branch` *                    | string   | 银行支行。 | - |
| `account_number` *                    | string   | 银行账户号码。 | - |
| `financial_institution_ispb` *       | string   | 金融机构 ISPB 代码。 | - |
| `financial_institution_code_number` * | string   | 金融机构代码。 | - |

### financial 对象

| 字段 | 类型 | 描述 | 最大字符数 |
|-------------------------------------|----------|-----------------------------------------------------------------|-----------------------------------------------------------------|
| `financial_base_date` *             | string   | 操作的财务基准日期（ISO 8601 格式）。 | - |
| `issue_quantity` *                  | integer  | 发行的总单位数量。 | - |
| `unit_price` *                      | float    | 每单位发行价格。 | - |
| `issue_amount` *                    | float    | 发行总金额。 | - |
| `released_amount` *                 | float    | 释放总金额。 | - |
| `cet` *                             | float    | 操作的有效总成本（%）。 | - |
| `annual_cet` *                      | float    | 年化有效总成本（%）。 | - |
| `number_of_installments` *          | integer  | 操作的总期数。 | - |
| `prefixed_interest_rate` *          | object   | 固定利率。 | [prefixed_interest_rate 对象](#objeto-prefixed_interest_rate) |
| `fine_delay_rate` *                 | object   | 滞纳金利率。 | [fine_delay_rate 对象](#objeto-fine_delay_rate) |
| `contract_fine_rate` *              | float    | 合同罚款利率（%）。 | - |
| `financial_index`                   | string   | 参考金融指数（如适用）。 | - |
| `post_fixed_interest_rate`          | object   | 浮动利率（如适用）。 | - |
| `fees` *                            | array    | 适用费用列表。 | [fees 对象](#objeto-fees) |
| `installment_list` *                | array    | 期次列表。 | [installment 对象](#objeto-installment) |

### prefixed_interest_rate 对象

| 字段 | 类型 | 描述 | 最大字符数 |
|-----------------------|--------|------------------------------------------------------------|-----------------|
| `daily_rate` *        | float  | 日利率（%）。 | - |
| `annual_rate` *       | float  | 年化利率（%）。 | - |
| `monthly_rate` *      | float  | 月利率（%）。 | - |
| `interest_base` *     | string | 利率计算基础（`calendar_days_365`）。 | - |

## fine_delay_rate 对象

| 字段 | 类型 | 描述 | 最大字符数 |
|---------------------|--------|--------------------------------------------------|-----------------|
| `monthly_rate` *    | float  | 月滞纳金利率（%）。 | - |
| `interest_base` *   | string | 利率计算基础（`calendar_days_365`）。 | - |

## fees 对象

| 字段 | 类型 | 描述 | 最大字符数 |
|---------------|---------|------------------------------------------------|-----------------|
| `type` *      | string  | 费用类型（`internal`、`external`）。 | - |
| `amount` *    | float   | 适用费率百分比。 | - |
| `fee_type` *  | string  | 费用类型。 | - |
| `fee_amount` * | float  | 费用绝对值。 | - |
| `amount_type` * | string | 值类型（`percentage`、`fixed`）。 | - |

## installment 对象

| 字段 | 类型 | 描述 | 最大字符数 |
|-------------------------------------------|---------|----------------------------------------------------------|-----------------|
| `installment_number` *                    | integer | 期次编号。 | - |
| `workdays` *                               | integer | 至到期日的工作日数。 | - |
| `calendar_days` *                          | integer | 至到期日的自然日数。 | - |
| `principal_amortization_unit_price` *      | float   | 本金摊还单位值。 | - |
| `principal_amortization_amount` *          | float   | 本金摊还总额。 | - |
| `interest_amount` *                        | float   | 该期利息总额。 | - |
| `amount` *                                 | float   | 该期总金额。 | - |
| `due_principal` *                          | float   | 该期后待偿本金。 | - |
| `due_interest` *                           | float   | 该期后待偿利息。 | - |
| `due_date` *                               | string  | 该期到期日（ISO 8601 格式）。 | - |
| `has_interest` *                           | boolean | 指示该期是否含利息计费。 | - |

## investor 对象

| 字段 | 类型 | 描述 | 最大字符数 |
|--------------------------------|---------|----------------------------------------------------------------------|----------------------------------------------|
| `investor_key` *               | string  | 投资人的唯一键（UUID v4）。 | 36 |
| `investor_name` *              | string  | 投资人名称。 | - |
| `investor_document_number` *   | string  | 投资人证件号码（CNPJ/CPF）。 | 18 |
| `subscription_percentage` *    | float   | 投资人在操作中的参与比例。 | - |
| `subscription_quantity` *      | integer | 投资人认购的单位数量。 | - |
| `investor_onboarding_approved` * | boolean | 指示投资人的 onboarding 是否已获批准。 | - |
| `bank_account` *               | object  | 投资人的银行信息。 | [bank_account 对象](#objeto-bank_account) |

## **operation_status 枚举**

| 枚举值 | 描述 |
|--------------------------------|----------------------------------------------------------------|
| `in_filling`                   | 操作处于填写阶段。 |
| `in_analysis`                  | 操作正在分析中。 |
| `waiting_onboarding_approval`  | 等待发行人 onboarding 批准。 |
| `pending_signature_submission` | 等待提交签名。 |
| `waiting_signature`            | 等待相关方签名。 |
| `issued`                       | 操作已发行。 |
| `finished`                     | 操作已完成。 |
| `signature_rejected`           | 签名被拒绝。 |
| `onboarding_reproved`          | 发行人 onboarding 未获批准。 |
| `compliance_reproved`          | 合规审查未通过。 |
| `canceled`                     | 操作已取消。 |

---

# 通过筛选条件查询操作

URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-filtros

此端点允许使用可选筛选条件查询**商业票据**操作。

---

## **Request**
ENDPOINT /commercial_paper/operation
MÉTODO GET

### **Query Params**

| 字段 | 类型 | 描述 | 必填 |
|----------------------------|----------|-----------------------------------------------|-------------|
| `issuer_document_number`   | string   | 发行人证件号码（CNPJ）。 | 否 |
| `investor_document_number` | string   | 投资人证件号码（CPF/CNPJ）。 | 否 |
| `operation_status`         | string   | 操作状态。 | **[operation_status 枚举](#enumeradores-operation_status)** | 否 |
| `metadata_key`             | array    | 元数据键。 | 否 |
| `metadata_value`           | array    | 元数据值。 | 否 |

---

## **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**

#### **Data 对象**

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------------------|----------|-----------------------------------------------------------|-----------------|
| `tenant_key` *               | string   | tenant 的唯一键（UUID v4）。 | 36 |
| `operation_key` *            | string   | 操作的唯一键（UUID v4）。 | 36 |
| `operation_type` *           | string   | 操作类型。始终为 `commercial_paper`。 | 50 |
| `operation_status` *         | string   | 操作的当前状态。 | **[operation_status 枚举](#enumeradores-operation_status)** | 50 |
| `backoffice_analysis_status` | string   | 后台分析状态。 | 50 |
| `issuer_key` *               | string   | 与操作关联的发行人唯一键（UUID v4）。 | 36 |
| `issuer_name` *              | string   | 与操作关联的发行人名称。 | 255 |
| `issuer_document_number` *   | string   | 发行人证件号码（CNPJ）。 | 14 |
| `issue_number` *             | integer  | 与操作关联的发行编号。 | - |
| `contract_number` *          | string   | 与操作关联的合同编号。 | 20 |

#### **Pagination 对象**

| 字段 | 类型 | 描述 |
|-------------------|----------|----------------------------------------------------------|
| `current_page` *  | integer  | 查询的当前页。 |
| `next_page`       | integer  | 下一页（如存在）。 |
| `rows_per_page` * | integer  | 每页记录数。 |
| `total_pages` *   | integer  | 可用总页数。 |
| `total_rows` *    | integer  | 符合筛选条件的总记录数。 |

---

## **operation_status 枚举**

| 枚举值 | 描述 |
|--------------------------------|----------------------------------------------------------------|
| `in_filling`                   | 操作处于填写阶段。 |
| `in_analysis`                  | 操作正在分析中。 |
| `waiting_onboarding_approval`  | 等待发行人 onboarding 批准。 |
| `pending_signature_submission` | 等待提交签名。 |
| `waiting_signature`            | 等待相关方签名。 |
| `issued`                       | 操作已发行。 |
| `finished`                     | 操作已完成。 |
| `signature_rejected`           | 签名被拒绝。 |
| `onboarding_reproved`          | 发行人 onboarding 未获批准。 |
| `compliance_reproved`          | 合规审查未通过。 |
| `canceled`                     | 操作已取消。 |

---

# Consulta do Próximo Número de Emissão por Emissor

URL: /zh-Hans/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. | -               |

---

# 提交已签署的批准会议纪要

URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/envio-ata-aprovacao

此端点允许将 SA 或 COP 类型公司在外部签署的批准会议纪要提交至书写系统，提交的 base64 将由书写方进行分析和批准。

---

## 提交已签署的操作 (POST)

### Request
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /upload_signed_document
MÉTODO POST

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
|------------------|--------|----------------------------------------------------------|------------|
| `OPERATION-KEY`  | string | 操作的唯一键（UUID v4）。 | 36 |

---

### Request Body

Request Body

```json
{
    "contract_base64": "image_b64",
    "contract_type": "sa_minute"
}
```

### Response Body Params

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------|
| `contract_type` *            | string   | 已签署合同的类型。 | **[contract_type 枚举](#enumeradores-contract_type)** |
| `contract_base64` *          | string   | base64 格式的已签署合同。 | |

### contract_type 枚举

| 枚举值 | 描述 |
|--------------------|--------------------------------------------|
| `sa_minute`        | **SA** 公司商业票据发行批准会议纪要。 |
| `coo_minute`      | **合作社** 公司商业票据发行批准会议纪要。 |

### Response

响应体为更新后的完整操作 JSON。

---

---

# 提交操作的已签署合同

URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/envio-contratos-assinados

此端点允许将在外部签署的合同提交至书写系统，提交的 base64 将由书写方进行分析和批准。

:::warning 警告
此端点仅应用于使用 **client_side** 签名类型的操作，或用于提交 SA 或合作社类型公司的批准会议纪要。对于通过 QI Sign 或 Certifiqi 的流程，合同以正常方式生成。
:::

---

## 提交已签署的操作 (POST)

### Request
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /upload_signed_document
MÉTODO POST

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
|------------------|--------|----------------------------------------------------------|------------|
| `OPERATION-KEY`  | string | 操作的唯一键（UUID v4）。 | 36 |

---

### Request Body

Request Body

```json
{
    "contract_base64": "image_b64",
    "contract_type": "sa_minute"
}
```

### Response Body Params

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------|
| `contract_type` *            | string   | 已签署合同的类型。 | **[contract_type 枚举](#enumeradores-contract_type)** |
| `contract_base64` *          | string   | base64 格式的已签署合同。 | |

### contract_type 枚举

| 枚举值 | 描述 |
|--------------------|--------------------------------------------|
| `commercial_paper` | 商业票据组成性条款。 |
| `adhesion_term`    | 商业票据加入条款。 |
| `sa_minute`        | **SA** 公司商业票据发行批准会议纪要。 |
| `ltda_minute`      | **LTDA** 公司商业票据发行批准会议纪要。 |

### Response

响应体为更新后的完整操作 JSON。

---

---

# 将操作提交分析

URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/envio-para-analise

此端点允许将操作状态更改为"分析中"，将其发送至书写方进行合规验证流程。

---

## 将操作提交分析 (PATCH)

### Request
ENDPOINT /commercial_paper/operation/ OPERATION-KEY
MÉTODO PATCH

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
|------------------|--------|----------------------------------------------------------|------------|
| `OPERATION-KEY`  | string | 操作的唯一键（UUID v4）。 | 36 |

---

### Request Body

```json
{
  "operation_status": "in_analysis"
}
```

### Request Body Params

| 字段 | 类型 | 描述 | 必填 |
|--------------------|----------|------------------------------------------------------------|-------------|
| `operation_status` | string   | 操作状态。必须设置为 `in_analysis`。 | 是 |

---

### Response

响应体为更新后的完整操作 JSON。

---

---

# 将操作提交签名

URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/envio-para-assinatura

:::warning 警告
合规审查通过的操作会定期自动发送签名。此端点仅应在需要立即发送时使用。
:::

---

## 将操作提交签名 (POST)

### Request
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /send_to_signature
MÉTODO POST

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
|------------------|--------|----------------------------------------------------------|------------|
| `OPERATION-KEY`  | string | 操作的唯一键（UUID v4）。 | 36 |

---

### Request Body

无需请求体。

---

### Response

响应体为更新后的完整操作 JSON。

---

---

# 更改加入条款模板

URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/geracao-minutas/alterar-template-ta

此端点允许为特定操作更改加入条款模板。

### **Request**
ENDPOINT /commercial_paper/operation/ OPERATION-KEY
MÉTODO PATCH

### **Path Params**

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------|--------|-----------------------------------------------|-----------------|
| `OPERATION-KEY` *  | string | 操作的唯一键（UUID v4）。 | 36 |

---

Request Body

```json
{
  "adhesion_term_template_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e"
}
```

### **Request Body Params**

| 字段 | 类型 | 描述 | 必填 |
|--------------------------------------|----------|--------------------------------------------------|-------------|
| `adhesion_term_template_key` *    | string   | 要使用的新模板的唯一键（UUID v4）。 | 是 |

## Response

响应体为更新后的完整操作 JSON。

---

# 更改组成性条款模板

URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/geracao-minutas/alterar-template-tc

此端点允许为特定操作更改组成性条款模板。

### **Request**
ENDPOINT /commercial_paper/operation/ OPERATION-KEY
MÉTODO PATCH

### **Path Params**

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------|--------|-----------------------------------------------|-----------------|
| `OPERATION-KEY` *  | string | 操作的唯一键（UUID v4）。 | 36 |

---

Request Body

```json
{
  "commercial_paper_template_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e"
}
```

### **Request Body Params**

| 字段 | 类型 | 描述 | 必填 |
|--------------------------------------|----------|--------------------------------------------------|-------------|
| `commercial_paper_template_key` *    | string   | 要使用的新模板的唯一键（UUID v4）。 | 是 |

## Response

响应体为更新后的完整操作 JSON。

---

# 查询可用模板

URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/geracao-minutas/consulta-minutas-disponiveis

此端点允许查询书写系统中可用的所有模板。

### **Request**
ENDPOINT /document_template/document_template
MÉTODO GET

### **Query Params**

| 字段 | 类型 | 描述 | 必填 |
|----------------------------|----------|-----------------------------------------------|-------------|
| `document_type`            | string   | 文件类型。 | 否 |

---

## 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**

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------|----------|------------------------------------------------|-----------------|
| `document_key` * | string   | 模板的唯一键（UUID v4）。 | 36 |
| `document_type` * | string   | 生成的文件类型。 | 50 |

---

# 预览加入条款

URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/geracao-minutas/gerar-minuta-adesao

此端点允许使用预定义模板预览特定操作的加入条款草稿。

---
## **Request**
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /preview_adhesion_term
MÉTODO POST

### **Path Params**

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------|--------|-----------------------------------------------|-----------------|
| `OPERATION-KEY` *  | string | 操作的唯一键（UUID v4）。 | 36 |

Request Body

```json
{
  "template_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e"
}
```

### **Request Body Params**

| 字段 | 类型 | 描述 | 必填 |
|--------------------------------------|----------|--------------------------------------------------|-------------|
| `template_key` *    | string   | 要使用的新模板的唯一键（UUID v4）。 | 是 |

## **Response**
STATUS 201

Response Body

```json
{
  "operation_key": "a846cc4a-b542-4f66-9823-b6d5458bd127",
  "document_type": "adhesion_term",
  "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0"
}
```

### **Response Body Params**

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------|----------|------------------------------------------------|-----------------|
| `operation_key` * | string   | 操作的唯一键（UUID v4）。 | 36 |
| `document_type` * | string   | 生成的文件类型。始终为 `adhesion_term`。 | 50 |
| `document_base64` * | string   | Base64 编码的生成文件内容。 | - |

---

# 预览组成性条款

URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/geracao-minutas/gerar-minuta-contrato

此端点允许使用预定义模板为特定操作生成组成性条款草稿。

---

## **Request**
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /preview_commercial_paper
MÉTODO POST

### **Path Params**

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------|--------|-----------------------------------------------|-----------------|
| `OPERATION-KEY` *  | string | 操作的唯一键（UUID v4）。 | 36 |

Request Body

```json
{
  "template_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e"
}
```

### **Request Body Params**

| 字段 | 类型 | 描述 | 必填 |
|--------------------------------------|----------|--------------------------------------------------|-------------|
| `template_key` *    | string   | 要使用的新模板的唯一键（UUID v4）。 | 是 |

## **Response**
STATUS 201

Response Body

```json
{
  "operation_key": "a846cc4a-b542-4f66-9823-b6d5458bd127",
  "document_type": "commercial_paper",
  "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0"
}
```

### **Response Body Params**

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------|----------|------------------------------------------------|-----------------|
| `operation_key` * | string   | 操作的唯一键（UUID v4）。 | 36 |
| `document_type` * | string   | 生成的文件类型。始终为 `commercial_paper`。 | 50 |
| `document_base64` * | string   | Base64 编码的生成文件内容。 | - |

---

# 商业票据发行介绍

URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/inicio

商业票据是企业直接从市场上筹集资金的金融工具。该流程涉及多个环节，从发行人和投资人的登记，到财务条件的确定，直至证券的正式发行。每个环节对于确保合规性和筹资流程效率至关重要。

---

## 发行流程概览

商业票据的发行流程由多个环节构成，确保透明度、安全性和控制力。以下是流程的主要步骤：

1. **发行人和投资人登记**  
   希望发行商业票据的公司和有意购买这些证券的投资人需要在系统中进行登记。登记包括详细信息，如文件和银行账户。

2. **确定操作条件**  
   发行人确定操作的财务条件，包括利率、还款期数、发行和到期日期，以及任何费用和手续费。

3. **模拟**  
   在正式发行之前，进行模拟以计算发行金额、还款流程和其他财务细节。此环节允许根据发行人和投资人的需求调整操作条件。

4. **关联方和文件登记**  
   包括登记参与各方（如担保人和共同义务人），以及提交相关文件（如合同和条款）。

5. **文件生成和签署**  
   生成主要文件的草稿，如**加入条款**和**组成性条款**。批准后，文件被发送进行电子签名。

6. **提交分析和审批**  
   操作提交进行合规和后台分析，确保满足所有监管和合同要求。

7. **正式发行和登记**  
   审批通过后，商业票据正式发行并向投资人开放。

从接下来的页面开始，我们将详细探讨商业票据发行流程的每个环节，包括将您的系统集成到 API 的端点和实际示例。

---

# 财务条件模拟

URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/simulacao

此端点允许模拟操作的财务条件和付款流程

---

:::warning 注意
 **Request Body** 必须包含有效的参数组合才能被处理。接受的组合包括：
 - 发行金额/释放金额 + 利率
 - 发行金额/释放金额 + 每期金额
 - 每期金额 + 利率
 - 发行金额/释放金额 + 利率 + 每期摊销百分比。
:::

## Request
ENDPOINT /commercial_paper/simulation
MÉTODO POST

## 固定利率操作

发行金额 + 利率

```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,
}
```

释放金额 + 利率

```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"
}
```

每期金额 + 利率

```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"
        }
    ]
}
```

发行金额 + 每期摊销百分比 + 利率

```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"
        }
    ]
}
```

发行金额 + 每期金额

```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"
        }
    ]
}
```

## 浮动利率操作

发行金额 + 利率 + 浮动利率

```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"
}
```

释放金额 + 利率 + 浮动利率

```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"
}
```

每期金额 + 利率 + 浮动利率

```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"
}
```

发行金额 + 每期摊销百分比 + 利率 + 浮动利率

```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"
}
```

发行金额 + 每期金额 + 浮动利率

```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

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------|
| `interest_type` *            | string   | 应用的利率类型。 | **[interest_type 枚举](#enumeradores-interest_type)** |
| `financial_base_date` *      | string   | 操作基准日期（格式 "YYYY-MM-DD"）。 | - |
| `released_amount`           | number   | 操作中释放的总金额。 | - |
| `issue_amount`           | number   | 操作的发行金额。 | - |
| `number_of_installments` *   | integer  | 分期总数。 | - |
| `installments`    | array   | 包含每期详情的对象。 | **[installments 对象](#objeto-installments)** |
| `prefixed_interest_rate` *   | object   | 包含固定利率详情的对象。 | **[prefixed_interest_rate 对象](#objeto-prefixed_interest_rate)** |
| `fine_delay_rate` *          | object   | 包含违约罚款详情的对象。 | **[fine_delay_rate 对象](#objeto-fine_delay_rate)** |
| `contract_fine_rate` *       | number   | 以百分比表示的合同罚款。 | - |
| `fees`                       | array    | 与操作相关的费用列表。 | **[fees 对象](#objeto-fees)** |
| `post_fixed_interest_rate`    | number   | 浮动利率的利率值。 | - |
| `financial_index`   | string   | 浮动利率类型。 | **[financial_index 枚举](#enumeradores-financial_index)** |
| `first_due_date`    | date   | 第一期日期。 | - |
| `first_due_date_delay`    | number   | 第一期付款开始前的天数。 | - |

### installments 对象

| 字段 | 类型 | 描述 |
|------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|
| `due_date` *            | string   | 分期到期日（格式 "YYYY-MM-DD"）。 |
| `amount`              | number   | 分期总金额。 |
| `principal_amortization_percentage`              | number   | 本金的摊销百分比。 |

### prefixed_interest_rate 对象

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------|
| `interest_base` *            | string   | 利率计算基准。 | **[interest_base 枚举](#enumeradores-interest_base)** |
| `daily_rate`              | number   | 适用的日利率。 | - |
| `monthly_rate`              | number   | 适用的月利率。 | - |
| `annual_rate`              | number   | 适用的年利率。 | - |

### fine_delay_rate 对象

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------|
| `interest_base` *            | string   | 罚款计算基准。 | **[interest_base 枚举](#enumeradores-interest_base)** |
| `monthly_rate` *             | number   | 月罚款率。 | - |

### fees 对象

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------|
| `amount` *                   | number   | 适用的费用金额。 | - |
| `amount_type` *              | string   | 费用金额类型。 | **[amount_type 枚举](#enumeradores-amount_type)** |
| `fee_type` *                 | string   | 费用类型。 | **[fee_type 枚举](#enumeradores-fee_type)** |
| `type` *                     | string   | 费用收取方。 | **[fee_recipient 枚举](#enumeradores-fee_recipient)** |

### interest_type 枚举

| 枚举值 | 描述 |
|--------------------|-----------------------------------------|
| `pre_price`       | Price 模型固定利率。 |
| `pre_price_days`  | 按日历天数计算的 Price 模型固定利率。 |
| `pre_sac`         | SAC 模型固定利率。 |
| `post_sac`        | SAC 模型浮动利率。 |
| `post_price_days` | 按日历天数计算的 Price 模型浮动利率。 |

### financial_index 枚举

| 枚举值 | 描述 |
|--------------------|-----------------------------------------|
| `CDI`       | CDI 浮动利率 |
| `IPCA`  | IPCA 浮动利率 |
| `IGPM`         | IGPM 浮动利率 |

### interest_base 枚举

| 枚举值 | 描述 |
|--------------------|-----------------------------------------|
| `calendar_days`    | 日历天数基准。 |
| `calendar_days_365`| 365 日历天数基准。 |
| `workdays`        | 工作日基准。 |

### amount_type 枚举

| 枚举值 | 描述 |
|-------------|---------------------------|
| `percentage` | 百分比金额。 |
| `absolute`   | 货币绝对金额。 |

### fee_type 枚举

| 枚举值 | 描述 |
|-------------------------------------|-------------------------------------------|
| `bookkeeping_fee`                   | 融资书写费。 |
| `structuring_fee`                   | 融资结构费。 |

### fee_recipient 枚举

| 枚举值 | 描述 |
|-----------|-------------------------------------------------------|
| `internal` | 支付给书写方的费用。 |
| `external` | 支付给发起人的返点。 |

## 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

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------------------|----------|---------------------------------------------------------------------------------------------------------|-----------------|
| `financial_base_date` *      | string   | 操作的财务基准日期（格式 "YYYY-MM-DD"）。 | - |
| `issue_amount` *             | number   | 操作发行的总金额。 | - |
| `released_amount` *          | number   | 操作中释放的净金额。 | - |
| `issue_quantity` *           | integer  | 发行的总单位数量。 | - |
| `unit_price` *               | number   | 发行的单位价格。 | - |
| `cet` *                      | number   | 以百分比表示的总有效成本（CET）。 | - |
| `annual_cet` *               | number   | 以百分比表示的年化 CET。 | - |
| `number_of_installments` *   | integer  | 分期总数。 | - |
| `prefixed_interest_rate` *   | object   | 包含固定利率详情的对象。 | **[prefixed_interest_rate 对象](#objeto-response-prefixed_interest_rate)** |
| `fees`                       | array    | 与操作相关的费用列表。 | **[fees 对象](#objeto-fees)** |
| `installments`               | array    | 操作中生成的分期详情列表。 | **[installments 对象](#objeto-response-installments)** |
| `fine_delay_rate` *          | object   | 包含违约罚款详情的对象。 | **[fine_delay_rate 对象](#objeto-fine_delay_rate)** |
| `contract_fine_rate` *       | number   | 以百分比表示的合同罚款。 | - |

### Response prefixed_interest_rate 对象

| 字段 | 类型 | 描述 | 最大字符数 |
|---------------|----------|------------------------------------------------------------|-----------------|
| `interest_base` * | string  | 利率计算基准。 | **[interest_base 枚举](#enumeradores-interest_base)** |
| `monthly_rate` *  | number  | 适用的月利率。 | - |
| `daily_rate` *    | number  | 适用的日利率。 | - |
| `annual_rate` *   | number  | 适用的年利率。 | - |

### fees 对象

| 字段 | 类型 | 描述 | 最大字符数 |
|------------|--------|------------------------------------------------------------|-----------------|
| `amount` *  | number | 费用的百分比金额。 | - |
| `fee_amount` * | number | 费用对应的货币金额。 | - |
| `amount_type` * | string  | 费用金额类型。 | **[amount_type 枚举](#enumeradores-amount_type)** |
| `fee_type` * | string  | 费用类型。 | **[fee_type 枚举](#enumeradores-fee_type)** |
| `type` * | string  | 费用收取方。 | **[fee_recipient 枚举](#enumeradores-fee_recipient)** |

### Response installments 对象

| 字段 | 类型 | 描述 |
|----------------------------|----------|--------------------------------------------------------|
| `installment_number` *      | integer  | 分期编号。 |
| `workdays` *               | integer  | 到分期到期的工作日数。 |
| `calendar_days` *          | integer  | 到分期到期的日历天数。 |
| `principal_amortization_amount` * | number  | 本金摊销金额。 |
| `principal_amortization_unit_price` * | number  | 每单位摊销金额。 |
| `interest_amount` *        | number   | 分期应用的利息金额。 |
| `amount` *                 | number   | 分期总金额。 |
| `due_date` *               | string   | 分期到期日（格式 "YYYY-MM-DD"）。 |

---

# 登记债券操作

URL: /zh-Hans/documentation/escrituracao/emissao-debentures/cadastro-operacao

此端点通过单个请求创建完整的债券操作。

:::info
`financial` 对象为 **必填**，且必须以已计算好的形式提交，因为此端点不执行财务模拟。发行人及其银行账户必须事先登记。
:::

---

## **Request**

ENDPOINT /debenture/create_operation
MÉTODO POST

请求体既可以是仅含 **必填字段的负载**（包含财务对象），也可以是同时包含关联方的 **完整负载**。两种变体见下文。

必填字段负载

```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
            }
        ]
    }
}
```

完整负载（含关联方）

```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**

| 字段                | 类型    | 描述                                       | 最大字符数                 |
| ------------------- | ------- | ------------------------------------------ | -------------------------- |
| `tenant_key` *      | string  | tenant 的唯一键。                          | -                          |
| `issuer_key` *      | string  | 发行人的唯一键（须事先登记）。             | -                          |
| `issue_number` *    | integer | 发行编号。                                 | -                          |
| `issue_series` *    | integer | 发行系列。                                 | -                          |
| `issue_date` *      | string  | 操作发行日期（格式："YYYY-MM-DD"）。       | -                          |
| `signature_method`  | string  | 操作中使用的签名方式。可选；省略时默认为 `certifiqi`。 | **[signature_method 枚举](#signature_method-枚举)** |
| `investors` *       | array   | 相关投资人列表。                           | **investors 对象**         |
| `financial` *       | object  | 操作的已计算财务数据。                     | **financial 对象**         |
| `contract_number`   | string  | 合同编号。                                 | -                          |
| `related_party_list` | array  | 操作的关联方（担保人、债务人等）。         | **related_party 对象**     |

### investors 对象

| 字段                        | 类型   | 描述                                       |
| --------------------------- | ------ | ------------------------------------------ |
| `investor_key` *            | string | 投资人的唯一键（须事先登记）。             |
| `bank_account` *            | object | 投资人的银行账户（**bank_account 对象**）。 |
| `subscription_percentage`   | number | 认购比例。                                 |
| `subscription_quantity`     | number | 认购数量。                                 |

### bank_account 对象

| 字段                                  | 类型   | 描述                                            |
| ------------------------------------- | ------ | ----------------------------------------------- |
| `account_number` *                    | string | 银行账户号码。                                  |
| `account_digit` *                     | string | 银行账户校验位。                                |
| `account_branch` *                    | string | 银行账户支行。                                  |
| `financial_institution_code_number`   | string | 金融机构代码。                                  |
| `financial_institution_ispb` *        | string | 金融机构 ISPB 代码。                            |
| `account_type` *                      | string | 账户类型（`checking`、`savings`、`salary`、`payment`）。 |

### financial 对象

| 字段                        | 类型    | 描述                                       |
| --------------------------- | ------- | ------------------------------------------ |
| `financial_base_date` *     | string  | 财务基准日期（格式："YYYY-MM-DD"）。       |
| `interest_type` *           | string  | 利率类型。                                 |
| `issue_amount`              | number  | 发行总金额。                               |
| `issue_quantity`            | integer | 发行单位数量。                             |
| `unit_price`                | number  | 每单位发行价格。                           |
| `released_amount`           | number  | 释放的净金额。                             |
| `cet` / `annual_cet`        | number  | 有效总成本（月度与年度），百分比。         |
| `number_of_installments` *  | integer | 期数。                                     |
| `prefixed_interest_rate` *  | object  | 固定利率。                                 |
| `fine_delay_rate`           | object  | 滞纳金利率。                               |
| `contract_fine_rate`        | number  | 合同罚款百分比。                           |
| `fees`                      | array   | 费用列表。                                 |
| `installments`              | array   | 已计算的期次列表。                         |

### related_party 对象

`related_party_list` 中的每一项代表参与该操作的一方。

| 字段              | 类型    | 描述                                            |
| ----------------- | ------- | ----------------------------------------------- |
| `person_type` *   | string  | 人员类型（`natural` 自然人，`legal` 法人）。   |
| `name` *          | string  | 关联方名称。                                    |
| `document_number` * | string | CPF（自然人）或 CNPJ（法人）。                  |
| `role_type` *     | string  | 关联方在操作中的角色。**[role_type 枚举](#role_type-枚举)** |
| `street` *        | string  | 街道。                                          |
| `number` *        | string  | 门牌号。                                        |
| `neighborhood`    | string  | 街区。                                          |
| `postal_code` *   | string  | 邮政编码（格式："00000-000"）。                 |
| `city` *          | string  | 城市。                                          |
| `state` *         | string  | 州/省（2 个字母）。                             |
| `complement`      | string  | 地址补充信息。                                  |
| `is_pep`          | boolean | （自然人）是否为政治公众人物。                  |
| `marital_status`  | string  | （自然人）婚姻状况。                            |
| `property_system` | string  | （自然人）财产制度。                            |
| `birthdate`       | string  | （自然人）出生日期。                            |
| `mother_name`     | string  | （自然人）母亲姓名。                            |
| `occupation`      | string  | （自然人）职业。                                |
| `trading_name`    | string  | （法人）商号。                                  |
| `cnae_code`       | string  | （法人）CNAE 代码（格式："00.00-0-00"）。       |
| `company_type`    | string  | （法人）公司类型。                              |
| `foundation_date` | string  | （法人）成立日期。                              |

:::warning 注意
必填字段因 `person_type` 而异：
- **自然人（`natural`）**：除通用字段外，`is_pep` 为必填。
- **法人（`legal`）**：除通用字段外，`trading_name`、`cnae_code`、`company_type` 和 `foundation_date` 为必填。
:::

### role_type 枚举

| 枚举值 | 描述 |
|--------|------|
| `issuer` | 发行人。 |
| `investor` | 投资人。 |
| `cosigner` | 共同债务人。 |
| `fiduciary_debtor` | 信托债务人。 |
| `solidary_debtor` | 连带债务人。 |
| `guarantor` | 担保人。 |
| `bonafide_depositary` | 善意保管人。 |
| `intervening_guarantor` | 介入担保人。 |
| `intervening_consentor` | 介入同意人。 |
| `intervening_discharger` | 介入清偿人。 |
| `assignor` | 转让人。 |
| `endorser` | 背书人。 |
| `consulting` | 咨询方。 |
| `fund_administrator` | 基金管理人。 |
| `fund_representative` | 基金代表。 |
| `company_representative` | 公司代表。 |
| `attestant` | 见证人。 |
| `debtor` | 债务人。 |
| `bestowal` | 授予人。 |
| `manager` | 管理人。 |

:::tip
担保和基础资产在操作创建后通过 **单独的端点** 提交。请参阅本节的 **提交担保** 页面。
:::

### signature_method 枚举

| 枚举值 | 描述 |
|--------|------|
| `certifiqi` | 默认值。操作将发送至签名服务；创建签名信封，客户端将收到签名 URL（`signature_url`）。 |
| `qi_sign` | 操作将发送至签名服务；创建签名信封，客户端将收到签名 URL（`signature_url`）。此外还支持查询操作的签署人。 |

## **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": { ... }
}
```

响应返回所创建操作的完整 JSON，包括 `operation_key`、投资人与关联方列表，以及已计算的财务对象。

---

# 提交文件

URL: /zh-Hans/documentation/escrituracao/emissao-debentures/envio-documento

此端点用于 **上传文件** 并返回标识该文件的 `document_key`。该 `document_key` 用于在其他端点中引用文件——例如 [提交担保](./envio-garantia.md) 中的 `collateral_document_key` 和 `additional_documents`。

---

## **Request**

ENDPOINT /debenture/upload
MÉTODO POST

Request Body

```json
{
    "document_base64": "string_b64"
}
```

### **Request Body Params**

| 字段              | 类型   | 描述                       | 必需 |
|-------------------|--------|----------------------------|------|
| `document_base64` * | string | base64 编码的文件内容。    | 是   |
| `document_name`   | string | 文件名称。                 | -    |

## **Response**

STATUS 201

Response Body

```json
{
    "document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b"
}
```

### **Response Body Params**

| 字段           | 类型   | 描述                          | 最大字符数 |
|----------------|--------|-------------------------------|------------|
| `document_key` * | string | 所上传文件的唯一键（UUID v4）。 | 36         |

---

---

# 提交操作的外部文件

URL: /zh-Hans/documentation/escrituracao/emissao-debentures/envio-documento-externo

此端点允许将在外部签署的文件提交至书写系统，提交的 base64 将由书写方进行分析和批准。

:::warning 警告
此端点仅应用于使用 **client_side** 签名类型的操作，或用于提交 SA 或合作社类型公司的批准会议纪要。对于通过 QI Sign 或 Certifiqi 的流程，合同以正常方式生成。
:::

---

## 提交已签署文件 (POST)

### Request

ENDPOINT /debenture/operation/ OPERATION-KEY /upload_signed_document
MÉTODO POST

### Path Params

| 字段            | 类型   | 描述                          | 字符数 |
|-----------------|--------|-------------------------------|--------|
| `OPERATION-KEY` | string | 操作的唯一键（UUID v4）。      | 36     |

---

### Request Body

Request Body

```json
{
    "contract_base64": "image_b64",
    "contract_type": "debenture"
}
```

### Request Body Params

| 字段                | 类型   | 描述               | 最大字符数                                                  |
|---------------------|--------|--------------------|------------------------------------------------------------|
| `contract_type` *   | string | 已签署文件的类型。 | **[contract_type 枚举](#contract_type-枚举)**              |
| `contract_base64` * | string | base64 格式的已签署文件。 | -                                                    |

### contract_type 枚举

| 枚举值              | 描述                                       |
|---------------------|--------------------------------------------|
| `debenture` | 债券发行契约。 |
| `adhesion_term` | 债券 加入条款。 |
| `sa_minute` | **SA** 公司债券发行批准会议纪要。 |
| `ltda_minute` | **LTDA** 公司债券发行批准会议纪要。 |
| `cop_minute` | **合作社** 债券发行批准会议纪要。 |

### Response

响应体为更新后的完整操作 JSON。

---

---

# 提交操作担保

URL: /zh-Hans/documentation/escrituracao/emissao-debentures/envio-garantia

此端点允许为债券操作 **添加担保（collateral）**。担保将与操作文件一起提交签署。每种担保类型（`collateral_type`）都有各自的必需文件规则，见下文。

:::info `document_key` 的来源
`collateral_document_key` 和（`additional_documents` 中的）`document_key` 引用先前已上传的文件。每个键都通过 [提交文件](./envio-documento.md) 端点（`POST /debenture/upload`）获取，该端点接收 Base64 文件并返回对应的 `document_key`。
:::

---

## **Request**

ENDPOINT /debenture/operation/ OPERATION-KEY /collateral
MÉTODO POST

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
|------|------|------|--------|
| `OPERATION-KEY` * | string | 操作的唯一键（UUID v4）。 | 36 |

---

## 担保类型

:::warning
标记为 **必需** 的文件是相应担保类型所要求的。
:::

### 不动产信托让与 (`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" }
    ]
}
```

#### 文件类型

| 枚举值 | 描述 | 必需 |
|--------|------|------|
| `property_appraisal_report` | 不动产评估报告。 | 是 |
| `property_registration_updated` | 更新的不动产登记。 | 是 |
| `property_full_content_certificate` | 不动产登记全文证明。 | 是 |
| `property_insurance_policy` | 保险单（如合同要求）。 | - |
| `others` | 其他文件。 | - |

### 车辆信托让与 (`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" }
    ]
}
```

#### 文件类型

| 枚举值 | 描述 | 必需 |
|--------|------|------|
| `vehicle_appraisal_report` | 车辆评估报告或 FIPE 表。 | 是 |
| `vehicle_inspection_report` | 检验报告。 | 是 |
| `vehicle_crv_certificate` | 更新的车辆登记证（CRLV）。 | 是 |
| `others` | 其他文件。 | - |

### 航空器信托让与 (`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" }
    ]
}
```

#### 文件类型

| 枚举值 | 描述 | 必需 |
|--------|------|------|
| `aircraft_certificate_anac` | 注册证书（ANAC）。 | 是 |
| `aircraft_rab_consult` | 巴西航空登记（RAB）查询。 | 是 |
| `aircraft_insurance_policy` | 保险单（基金为受益人）。 | 是 |
| `aircraft_appraisal_report` | 航空器评估报告。 | 是 |
| `others` | 其他文件。 | - |

### 设备/产品/库存信托让与 (`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" }
    ]
}
```

#### 文件类型

| 枚举值 | 描述 | 必需 |
|--------|------|------|
| `equipment_purchase_invoice` | 采购发票。 | 是 |
| `equipment_appraisal_report` | 设备评估报告。 | 是 |
| `equipment_insurance_policy` | 设备保险单（如适用）。 | - |
| `fiduciary_depositary_declaration` | 善意保管人声明。 | - |
| `others` | 其他文件。 | - |

### 艺术品信托让与 (`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" }
    ]
}
```

#### 文件类型

| 枚举值 | 描述 | 必需 |
|--------|------|------|
| `artwork_appraisal_report` | 艺术品评估报告。 | 是 |
| `artwork_storage_certificate` | 存放地点合规证明。 | 是 |
| `artwork_insurance_policy` | 保险单（如适用）。 | - |
| `others` | 其他文件。 | - |

### 证券信托让与 (`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" }
    ]
}
```

#### 文件类型

| 枚举值 | 描述 | 必需 |
|--------|------|------|
| `securities_negotiation_block` | 在托管人处的交易冻结。 | 是 |
| `securities_registration_gravame` | 留置权登记。 | - |
| `others` | 其他文件。 | - |

### 股份/股权信托让与 (`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" }
    ]
}
```

#### 文件类型

| 枚举值 | 描述 | 必需 |
|--------|------|------|
| `share_registration_book` | 记名股份登记簿（含留置权批注）。 | 是 |
| `others` | 其他文件。 | - |

### 不动产抵押 (`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" }
    ]
}
```

#### 文件类型

| 枚举值 | 描述 | 必需 |
|--------|------|------|
| `property_appraisal_report` | 不动产评估报告。 | 是 |
| `property_registration` | 更新的产权登记。 | 是 |
| `property_full_content_certificate` | 不动产登记全文证明。 | 是 |
| `property_insurance_policy` | 保险单（如合同要求）。 | - |
| `others` | 其他文件。 | - |

### 船舶抵押 (`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" }
    ]
}
```

#### 文件类型

| 枚举值 | 描述 | 必需 |
|--------|------|------|
| `ship_registration` | 更新的船舶产权登记。 | 是 |
| `ship_appraisal_report` | 船舶评估报告。 | 是 |
| `ship_insurance_policy` | 船舶保险单（如适用）。 | - |
| `others` | 其他文件。 | - |

### 票据保证（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" }
    ]
}
```

#### 文件类型

| 枚举值 | 描述 | 必需 |
|--------|------|------|
| `guarantor_civil_status_declaration` | 担保人婚姻状况声明。 | 是 |
| `guarantor_personal_document` | 担保人身份证件。 | - |
| `guarantor_income_tax_declaration` | 担保人所得税申报。 | - |
| `others` | 其他文件。 | - |

### 保证（保证人） (`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" }
    ]
}
```

#### 文件类型

| 枚举值 | 描述 | 必需 |
|--------|------|------|
| `surety_civil_status_declaration` | 保证人婚姻状况声明。 | 是 |
| `surety_personal_document` | 保证人身份证件。 | 是 |
| `surety_income_tax_declaration` | 保证人所得税申报。 | 是 |
| `others` | 其他文件。 | - |

### 保险 (`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" }
    ]
}
```

#### 文件类型

| 枚举值 | 描述 | 必需 |
|--------|------|------|
| `insurance_policy_endorsed` | 已背书保险单。 | 是 |
| `insurance_policy_with_expiration_and_renewal` | 含有效期与续保的保险单。 | 是 |
| `others` | 其他文件。 | - |

### 担保监控 (`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" }
    ]
}
```

#### 文件类型

| 枚举值 | 描述 | 必需 |
|--------|------|------|
| `guarantee_contract` | 担保合同。 | 是 |
| `guarantee_agent_contract` | 担保代理合同。 | 是 |
| `others` | 其他文件。 | - |

---

## Request Body Params

| 字段 | 类型 | 描述 | 必需 |
|------|------|------|------|
| `collateral_document_key` * | string | 担保工具文件的键。 | 是 |
| `collateral_type` * | string | 担保类型。 | **[collateral_type 枚举](#collateral_type-枚举)** |
| `additional_documents` | array | 担保的附加文件。 | - |

### additional_documents

| 字段 | 类型 | 描述 | 必需 |
|------|------|------|------|
| `document_key` * | string | 文件键。 | 是 |
| `document_type` * | string | 文件类型。 | 是 |

### collateral_type 枚举

| 枚举值 | 描述 |
|--------|------|
| `fiduciary_alienation_property` | 不动产信托让与. |
| `fiduciary_alienation_vehicle` | 车辆信托让与. |
| `fiduciary_alienation_aircraft` | 航空器信托让与. |
| `fiduciary_alienation_equipment` | 设备/产品/库存信托让与. |
| `fiduciary_alienation_artwork` | 艺术品信托让与. |
| `fiduciary_alienation_securities` | 证券信托让与. |
| `fiduciary_assignment_shares` | 股份/股权信托让与. |
| `mortgage_property` | 不动产抵押. |
| `mortgage_ship` | 船舶抵押. |
| `guarantor` | 票据保证（Aval）. |
| `surety` | 保证（保证人）. |
| `insurance` | 保险. |
| `monitoring_guarantee` | 担保监控. |
| `bank_surety` | 银行保函。 |
| `fiduciary_assignment_credit_rights` | 债权信托转让。 |
| `card_receivables` | 卡应收款。 |
| `stock_guarantee` | 库存担保。 |
| `others` | 其他担保。 |

## Response

响应体为更新后的完整操作 JSON，新担保位于 `collateral_list` 中。

---

---

# 更新发行人登记

URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/alteracao-cadastro/

要对发行人登记进行修改，需要将其状态设置为"in_filling"，这将重新启用所有添加/删除端点。

完成修改后，必须再次将登记提交分析，状态为"in_analysis"。

---

## Request

ENDPOINT /issuer_management/issuer/ ISSUER-KEY
MÉTODO PATCH

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
| -------------- | ------ | ---------------------------------- | ---------- |
| `ISSUER-KEY` | string | 发行人的唯一键（UUID v4）。 | 36 |

### Request Body

Request Body

```json
{
  "issuer_status": "in_filling"
}
```

### Request Body Params

| 字段 | 类型 | 描述 | 必填 |
| ------------------ | ------ | ---------------------------------------------------- | ------------ |
| `issuer_status`* | string | 发行人的新状态。接受值：`in_filling`。 | 是 |

## Response

响应为发行人更新后的完整 JSON。

---

# 登记发行人签名人组

URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor

此端点允许登记与已登记发行人关联的签名人组。

---

## Request

ENDPOINT /issuer_management/issuer/ ISSUER-KEY /signer_group
MÉTODO POST

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
| -------------- | ------ | ---------------------------------- | ---------- |
| `ISSUER-KEY` | string | 发行人的唯一键（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

| 字段 | 类型 | 描述 | 最大字符数 |
| ------------------------------ | ------- | ---------------------------------------------------------------- | -------------------------------------- |
| `minimum_required_signers` * | integer | 验证该组所需的最少签名人数。 | - |
| `signers` *                  | array   | 组成签名人组的 Signer 对象列表。 | **[Signer 对象](#objeto-signer)** |

### Signer 对象

| 字段 | 类型 | 描述 | 最大字符数 |
| ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------- | --------------------- |
| `name` *               | string  | 签名人全名。 | 255 |
| `document_number` *    | string  | 签名人的 CPF（格式"XXX.XXX.XXX-XX"）。 | 11 |
| `email` *              | string  | 签名人电子邮件地址。 | 1023 |
| `phone_number`*        | string  | 签名人电话号码（完整格式：国家代码、区号和号码。例如：+5511999999999）。 | 20 |
| `is_group_mandatory` * | boolean | 指示签名人在组内是必须还是可选的。 | - |

## 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

| 字段 | 类型 | 描述 | 最大字符数 |
| ---------------------------- | ------- | ---------------------------------------------------------- | -------------------------------------- |
| `signer_group_key`         | string  | 签名人组的唯一标识符（UUID v4）。 | 36 |
| `minimum_required_signers` | integer | 组内所需的最少签名人数。 | - |
| `signers` *                | array   | 组成签名人组的 Signer 对象列表。 | **[Signer 对象](#objeto-signer)** |

---

# 删除发行人签名人组

URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor-remocao

此端点允许删除与已登记发行人关联的签名人组。

---

## Request
ENDPOINT /issuer_management/issuer/ ISSUER-KEY /signer_group/ SIGNER-GROUP-KEY
MÉTODO DELETE

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
|--------------------|--------|----------------------------------------------------------|------------|
| `ISSUER-KEY`       | string | 发行人的唯一键（UUID v4）。 | 36 |
| `SIGNER-GROUP-KEY` | string | 待删除签名人组的唯一键（UUID v4）。 | 36 |

## Response
STATUS 204

响应体中不返回任何内容。

---

# 发行人基本登记

URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/cadastro-basico

此端点允许登记发行人的基本信息。

## 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

| 字段 | 类型 | 描述 | 最大字符数 |
| --------------------- | ------ | ----------------------------------------------------- | -------------------------------------------------------------- |
| `name` *            | string | 公司全名。 | 255 |
| `document_number` * | string | 公司 CNPJ（格式："XX.XXX.XXX/XXXX-XX"）。 | 14 |
| `trading_name`*     | string | 公司商业名称。 | 1023 |
| `cnae_code`*        | string | 公司 CNAE 代码（格式："XX.XX-X-XX"）。 | 7 |
| `company_type`*     | string | 公司类型。 | **[company_type 枚举](#enumeradores-company_type)** |
| `foundation_date`*  | string | 公司成立日期（格式："YYYY-MM-DD"）。 | - |
| `address` *         | string | 地址引用对象。 | **[address 对象](#objeto-address)** |
| `annual_revenues`  | number | 出让人年收入申报。 | - |
| `is_in_national_financial_system`  | boolean | 指示出让人是否为国家金融系统（SFN）成员。 | - |

### Address 对象

| 字段 | 类型 | 描述 | 最大字符数 |
| ----------------- | ------ | ---------------------------------------- | ---------------- |
| `street` *      | string | 公司地址街道名称。 | 500 |
| `neighborhood` * | string | 公司地址区域名称。 | 100 |
| `number` *      | string | 地址门牌号。 | 10 |
| `postal_code` * | string | 邮政编码（格式："XXXXX-XXX"）。 | 8 |
| `city` *        | string | 地址城市名称。 | 255 |
| `state` *       | string | 州缩写（2个字符）。 | 2 |
| `complement`    | string | 地址补充信息（如适用）。 | 100 |

### company_type 枚举

| 枚举值 | 描述 |
| -------- | ------------------ |
| `ltda` | 有限责任公司 |
| `sa`   | 股份公司 |
| `cop`  | 合作社 |

## 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

| 字段 | 类型 | 描述 | 最大字符数 |
| ------------------------- | ------ | ----------------------------------- | -------------------------------------------------------------- |
| `issuer_key`            | string | 发行人的唯一键（UUID）。 | 36 |
| `name`                  | string | 发行人全名。 | 255 |
| `document_number`       | string | 发行人的 CNPJ。 | 14 |
| `status`                | string | 发行人状态。 | - |
| `person_type`           | string | 人员类型。 | **[person_type 枚举](#enumeradores-person_type)** |
| `trading_name`          | string | 发行人商业名称。 | 1023 |
| `cnae_code`             | string | 发行人的 CNAE 代码。 | 7 |
| `company_type`          | string | 公司类型。 | **[company_type 枚举](#enumeradores-company_type)** |
| `foundation_date`       | string | 发行人成立日期。 | - |
| `address`               | string | 地址引用对象。 | **[address 对象](#objeto-address)** |
| `registration_datetime` | string | 发行人注册日期和时间。 | - |
| `expiration_date`       | string | 发行人到期日期。 | - |
| `annual_revenues`  | number | 出让人年收入申报。 | - |
| `is_in_national_financial_system`  | boolean | 指示出让人是否为国家金融系统（SFN）成员。 | - |

### person_type 枚举

| 枚举值 | 描述 |
| ----------- | ---------------- |
| `legal`   | 法人 |
| `natural` | 自然人 |

:::warning 警告
登记发行人时，将预留一个内部账户，该账户仅在操作完成后才会开设。
:::

### payment_bank_account 对象

| 字段 | 类型 | 描述 | 最大字符数 |
| -------------------- | ------ | --------------------------- | ---------------- |
| `account_digit` *  | string | 银行账户校验位。 | - |
| `account_branch` * | string | 银行支行。 | - |
| `account_number` * | string | 银行账户号码。 | - |

---

# 登记发行人银行账户

URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor

此端点允许登记与已登记发行人关联的银行账户。

---

## Request

ENDPOINT /issuer_management/issuer/ ISSUER-KEY /bank_account
MÉTODO POST

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
| -------------- | ------ | ---------------------------------- | ---------- |
| `ISSUER-KEY` | string | 发行人的唯一键（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

| 字段 | 类型 | 描述 | 最大字符数 |
| -------------------------------------- | ------ | ------------------------------------------------------------ | -------------------------------------------------------------- |
| `account_number` *                   | string | 银行账户号码，只能包含数字。 | 20 |
| `account_digit` *                    | string | 账户校验位，只能包含一位数字。 | 1 |
| `account_branch` *                   | string | 银行支行号码，只能包含数字。 | 6 |
| `financial_institution_code_number`* | string | 金融机构代码（3位数字）。 | 3 |
| `financial_institution_ispb` *       | string | 金融机构 ISPB 代码（8位数字）。 | 8 |
| `account_type` *                     | string | 银行账户类型。 | **[account_type 枚举](#enumeradores-account_type)** |

### account_type 枚举

| 枚举值 | 描述 |
| ------------ | ------------------ |
| `checking` | 活期账户 |
| `savings`  | 储蓄账户 |
| `salary`   | 工资账户 |
| `payment`  | 支付账户 |

## 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

| 字段 | 类型 | 描述 | 最大字符数 |
| ------------------------------------- | ------ | ------------------------------------------------------------- | -------------------------------------------------------------- |
| `bank_account_key`                  | string | 已登记银行账户的唯一标识符（UUID v4）。 | 36 |
| `account_number`                    | string | 银行账户号码。 | 20 |
| `account_digit`                     | string | 银行账户校验位。 | 1 |
| `account_branch`                    | string | 银行支行号码。 | 6 |
| `financial_institution_code_number` | string | 金融机构代码。 | 3 |
| `financial_institution_ispb`        | string | 金融机构 ISPB 代码。 | 8 |
| `account_type`                      | string | 银行账户类型。 | **[account_type 枚举](#enumeradores-account_type)** |

---

# Definição de Conta Bancária Principal do Emissor

URL: /zh-Hans/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.                                           |

---

# 删除发行人银行账户

URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor-remocao

此端点允许删除与已登记发行人关联的银行账户。

---

## Request
ENDPOINT /issuer_management/issuer/ ISSUER-KEY /bank_account/ BANK-ACCOUNT-KEY
MÉTODO DELETE

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
|--------------------|--------|------------------------------------------------------|------------|
| `ISSUER-KEY`       | string | 发行人的唯一键（UUID v4）。 | 36 |
| `BANK-ACCOUNT-KEY` | string | 待删除银行账户的唯一键（UUID v4）。 | 36 |

---

## Response
STATUS 204

响应体中不返回任何内容。

---

---

# 提交发行人文件

URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor

此端点允许提交与已登记发行人关联的文件。

---

## Request

ENDPOINT /issuer_management/issuer/ ISSUER-KEY /document
MÉTODO POST

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
| -------------- | ------ | ---------------------------------- | ---------- |
| `ISSUER-KEY` | string | 发行人的唯一键（UUID v4）。 | 36 |

### Request Body

Request Body

```json
{
  "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0",
  "document_type": "proof_of_address"
}
```

### Request Body Params

| 字段 | 类型 | 描述 | 最大字符数 |
| --------------------- | ------ | ------------------------------------------------------- | ---------------------------------------------------------------- |
| `document_base64` * | string | Base64 编码的文件内容。 | - |
| `document_type` *   | string | 提交文件的类型。 | **[document_type 枚举](#enumeradores-document_type)** |

### document_type 枚举

| 枚举值 | 描述 |
| ------------------------------- | ---------------------------------- |
| `proof_of_address`              | 地址证明 |
| `letter_of_attorney`            | 授权书 |
| `company_statute` *               | 公司章程或合同 |
| `commercial_board_certificate`  | 商业委员会证书 |
| `board_election_record`         | 董事会选举记录 |
| `manager_declaration`           | 经理声明 |
| `financial_statement`           | 财务报表 |
| `credit_report`                 | 信用报告 |
| `manager_statement`             | 管理员声明 |
| `compliance_statement`          | 合规声明 |
| `cnpj_card`                     | CNPJ 卡 |
| `additional_document`           | 附加文件 |

:::warning 注意
所有登记均需提供 **company_statute**（公司章程）。
:::

## Response

STATUS 201

Response Body

**场景 1：自动验证（OCR 成功）**

```json
{
    "document_key": "123e4567-e89b-12d3-a456-426614174000",
    "document_type": "proof_of_address",
    "ocr_key": "6654f284-f690-4324-8c39-dcf0225ec8cf"
}
```
**含义**：文件已由 OCR 自动处理和验证。

**场景 2：需要人工审核**

```json
{
    "document_key": "8bf591a8-c184-47db-afd2-a5196de14cc3",
    "document_type": "cnpj_card",
    "ocr_key": null
}
```
**含义**：文件无法通过 OCR 自动验证，已转入人工审核队列。

:::warning 注意
成功请求（提交成功）的响应有两种不同行为，取决于自动验证（OCR）的结果。
:::

### Response Body Params

| 字段 | 类型 | 描述 | 最大长度 |
| ----------------- | ------ | ---------------------------------------------------- | ---------------------------------------------------------------- |
| `document_key`  | string | 提交文件的唯一标识符（UUID v4）。 | 36 |
| `document_type` | string | 提交文件的类型。 | **[document_type 枚举](#enumeradores-document_type)** |
| `ocr_key`       | string | 与提交文件关联的 OCR 键。 | 36 |

---

# 删除发行人文件

URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor-remocao

此端点允许删除已提交至发行人登记的文件。

---

## Request
ENDPOINT /issuer_management/issuer/ ISSUER-KEY /document/ DOCUMENT-KEY
MÉTODO DELETE

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
|----------------|--------|------------------------------------------|------------|
| `ISSUER-KEY`   | string | 发行人的唯一键（UUID v4）。 | 36 |
| `DOCUMENT-KEY` | string | 待删除文件的唯一键（UUID v4）。 | 36 |

## Response
STATUS 204

响应体中不返回任何内容。

---

# 提交发行人代表文件

URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor

此端点允许提交与已登记发行人的代表关联的文件。

---
## Request
ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_representative/ ISSUER-REPRESENTATIVE-KEY /document
MÉTODO POST

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------|--------|---------------------------------------------------|------------|
| `ISSUER-KEY`                | string | 发行人的唯一键（UUID v4）。 | 36 |
| `ISSUER-REPRESENTATIVE-KEY` | string | 发行人代表的唯一键（UUID v4）。 | 36 |

### Request Body
Request Body

```json
{
  "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0",
  "document_type": "cnh"
}
```

### Request Body Params

| 字段 | 类型 | 描述 | 最大字符数 |
|--------------------|----------|-------------------------------------------------------------------------------------------|-----------------------|
| `document_base64` *| string   | Base64 编码的文件内容。 | - |
| `document_type` *  | string   | 提交文件的类型。 | **[document_type 枚举](#enumeradores-document_type)** |

### document_type 枚举
| 枚举值 | 描述 |
| ------------------------------- | ---------------------------------- |
| `cnh`                           | 驾驶证 |
| `cnh_front`                     | 驾驶证正面 |
| `cnh_back`                      | 驾驶证背面 |
| `cnh_digital`                   | 数字驾驶证 |
| `rg_front`                      | 身份证正面 |
| `rg_back`                       | 身份证背面 |
| `proof_of_address`              | 地址证明 |
| `letter_of_attorney`            | 授权书 |
| `passport`                      | 护照 |
| `national_registry_of_foreigners`| 外国人国家登记 |

:::warning 注意
所有登记均需至少提供一份身份证件（cnh、rg、passport 或 national_registry_of_foreigners），且如果代表类型为 **attorney**（代理人），还需提供授权书（letter_of_attorney）。
:::

## Response
STATUS 201

Response Body

**场景 1：自动验证（OCR 成功）**

```json
{
  "document_key": "123e4567-e89b-12d3-a456-426614174000",
  "document_type": "cnh",
  "ocr_key": "6654f284-f690-4324-8c39-dcf0225ec8cf"
}
```
**含义**：文件已由 OCR 自动处理和验证。

**场景 2：需要人工审核**

```json
{
    "document_key": "8bf591a8-c184-47db-afd2-a5196de14cc3",
    "document_type": "cnh",
    "ocr_key": null
}
```
**含义**：文件无法通过 OCR 自动验证，已转入人工审核队列。

:::warning 注意
成功请求（提交成功）的响应有两种不同行为，取决于自动验证（OCR）的结果。
:::

### Response Body Params

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------|----------|-----------------------------------------------------|-----------------------|
| `document_key`   | string   | 提交文件的唯一标识符（UUID v4）。 | 36 |
| `document_type`  | string   | 提交文件的类型。 | **[document_type 枚举](#enumeradores-document_type)** |
| `ocr_key`        | string   | 与提交文件关联的 OCR 键。 | 36 |

---

# 删除发行人代表文件

URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor-remocao

此端点允许删除与已登记发行人代表关联的文件。

---

## Request
ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_representative/ ISSUER-REPRESENTATIVE-KEY /document/ DOCUMENT-KEY
MÉTODO DELETE

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------|--------|---------------------------------------------------|------------|
| `ISSUER-KEY`                | string | 发行人的唯一键（UUID v4）。 | 36 |
| `ISSUER-REPRESENTATIVE-KEY` | string | 发行人代表的唯一键（UUID v4）。 | 36 |
| `DOCUMENT-KEY`              | string | 待删除文件的唯一键（UUID v4）。 | 36 |

## Response
STATUS 204

响应体中不返回任何内容。

---

# 登记发行人联系信息

URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor

此端点允许登记与已登记发行人关联的联系信息。

---

## Request

ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_contact_information
MÉTODO POST

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
| -------------- | ------ | ---------------------------------- | ---------- |
| `ISSUER-KEY` | string | 发行人的唯一键（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

| 字段 | 类型 | 描述 | 最大字符数 |
| --------------------- | ------ | ----------------------------------------------------------------------------------------------------------------- | --------------------- |
| `name` *            | string | 联系人全名。 | 255 |
| `document_number` * | string | 联系人证件号码（CPF，格式"XXX.XXX.XXX-XX"）。 | 14 |
| `email`*            | string | 联系人电子邮件地址。 | 1023 |
| `phone_number`*     | string | 联系人电话号码（完整格式：国家代码、区号和号码。例如：+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

| 字段 | 类型 | 描述 | 最大字符数 |
| ---------------------------------- | ------ | --------------------------------------------------------------------- | --------------------- |
| `issuer_contact_information_key` | string | 已登记联系信息的唯一标识符（UUID v4）。 | 36 |
| `name`                           | string | 联系人全名。 | 255 |
| `document_number`                | string | 联系人证件号码（CPF）。 | 11 |
| `email`                          | string | 联系人电子邮件地址。 | 1023 |
| `phone_number`                   | string | 联系人电话号码。 | 20 |

---

# Definição de Contato Principal do Emissor

URL: /zh-Hans/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.                                           |

---

# 删除发行人联系信息

URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor-remocao

此端点允许删除与已登记发行人关联的联系信息。

---

## Request
ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_contact_information/ ISSUER-CONTACT-INFORMATION-KEY
MÉTODO DELETE

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
|----------------------------------|--------|-----------------------------------------------------------|------------|
| `ISSUER-KEY`                     | string | 发行人的唯一键（UUID v4）。 | 36 |
| `ISSUER-CONTACT-INFORMATION-KEY` | string | 待删除联系信息的唯一键（UUID v4）。 | 36 |

## Response
STATUS 204

响应体中不返回任何内容。

---

# 登记发行人代表

URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor

此端点允许登记与已登记发行人关联的代表。

---

## Request

ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_representative
MÉTODO POST

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
| -------------- | ------ | ---------------------------------- | ---------- |
| `ISSUER-KEY` | string | 发行人的唯一键（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

| 字段 | 类型 | 描述 | 最大字符数 |
| ---------------------------------- | ------- | --------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `name` *                         | string  | 发行人代表的全名。 | 255 |
| `document_number` *              | string  | 证件号码（CPF，格式"XXX.XXX.XXX-XX"）。 | 11 |
| `birthdate`                      | string  | 代表的出生日期，ISO 8601 格式（YYYY-MM-DD）。 | - |
| `document_identification_number` | string  | 身份证件号码。 | 255 |
| `marital_status`                 | string  | 代表的婚姻状况。 | **[marital_status 枚举](#enumeradores-marital_status)** |
| `property_system`                | string  | 财产制度。 | **[property_system 枚举](#enumeradores-property_system)** |
| `nationality` * | string | 受益人所在国家。 | 3，依据 ISO 3166-1 alpha-3 |
| `mother_name`                    | string  | 代表母亲的全名。 | 1023 |
| `father_name`                    | string  | 代表父亲的全名。 | 1023 |
| `occupation`                     | string  | 代表的职业或工作。 | 255 |
| `is_pep`                         | boolean | 指示代表是否为政治敏感人物（PEP）。 | - |
| `address` *                      | string  | 地址引用对象。 | **[address 对象](#objeto-address)** |
| `annual_revenues`  | number | 出让人年收入申报。 | - |
| `related_party_type` * | 枚举 | 关联方的关系类型。 | 参见 **[关联方类型枚举](#related-party-type)** |

### Address 对象

| 字段 | 类型 | 描述 | 最大字符数 |
| ----------------- | ------ | ---------------------------------------- | ---------------- |
| `street` *      | string | 公司地址街道名称。 | 500 |
| `neighborhood`  | string | 公司地址区域名称。 | 100 |
| `number` *      | string | 地址门牌号。 | 10 |
| `postal_code` * | string | 邮政编码（格式"XXXXX-XXX"）。 | 8 |
| `city` *        | string | 地址城市名称。 | 255 |
| `state` *       | string | 州缩写（2个字符）。 | 2 |
| `complement`    | string | 地址补充信息（如适用）。 | 100 |

### marital_status 枚举

| 枚举值 | 描述 |
| ---------------- | ------------------ |
| `single`       | 未婚 |
| `married`      | 已婚 |
| `widower`      | 丧偶 |
| `separated`    | 分居 |
| `stable_union` | 同居关系 |
| `divorced`     | 离婚 |

### property_system 枚举

| 枚举值 | 描述 |
| --------------------------------------- | --------------------------------- |
| `total_communion_of_goods`            | 完全财产共同制 |
| `partial_communion_of_goods`          | 部分财产共同制 |
| `total_separation_of_goods`           | 完全财产分离制 |
| `final_participation_of_acquisitions` | 婚后所得共同制 |
| `compulsory_separation_of_goods`      | 强制财产分离制 |

### Related Party Type

| 枚举值 | 描述 |
| ----------------------- | ------------- |
| **president**     | 总裁 |
| **partner**       | 合伙人 |
| **administrator** | 管理员 |
| **director**      | 董事 |
| **manager**       | 经理 |
| **attorney**      | 代理人 |

---

## 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

| 字段 | 类型 | 描述 | 最大字符数 |
| --------------------------------------- | ------- | -------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `issuer_representative_key`           | string  | 发行人代表的唯一标识符（UUID v4）。 | 36 |
| `name`                                | string  | 发行人代表的全名。 | 255 |
| `document_number`                     | string  | 代表的证件号码（格式"XXX.XXX.XXX-XX"）。 | 11 |
| `document_identification_number`      | string  | 身份证件号码。 | 255 |
| `marital_status`                      | string  | 代表的婚姻状况。 | **[marital_status 枚举](#enumeradores-marital_status)** |
| `property_system`                     | string  | 财产制度。 | **[property_system 枚举](#enumeradores-property_system)** |
| `birthdate`                           | string  | 代表的出生日期。 | - |
| `nationality` * | string | 受益人所在国家。 | 3，依据 ISO 3166-1 alpha-3 |
| `mother_name`                         | string  | 代表母亲的全名。 | 1023 |
| `father_name`                         | string  | 代表父亲的全名。 | 1023 |
| `occupation`                          | string  | 代表的职业或工作。 | 255 |
| `is_pep`                              | boolean | 指示代表是否为政治敏感人物（PEP）。 | - |
| `address` *                           | string  | 地址引用对象。 | **[address 对象](#objeto-address)** |
| `issuer_representative_document_list` | array   | 与代表关联的文件列表。 | - |
| `annual_revenues`  | number | 出让人年收入申报。 | - |
| `related_party_type` * | 枚举 | 关联方的关系类型。 | 参见 **[关联方类型枚举](#related-party-type)** |

---

# 删除发行人代表

URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor-remocao

此端点允许删除已提交至发行人登记的代表。

---

## Request
ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_representative/ ISSUER-REPRESENTATIVE-KEY
MÉTODO DELETE

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------|--------|--------------------------------------------------------|------------|
| `ISSUER-KEY`                | string | 发行人的唯一键（UUID v4）。 | 36 |
| `ISSUER-REPRESENTATIVE-KEY` | string | 待删除代表的唯一键（UUID v4）。 | 36 |

## Response
STATUS 204

响应体中不返回任何内容。

---

# 查询发行人

URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-chave

此端点允许通过唯一键查询系统中已登记发行人的完整详情。

---

## Request
ENDPOINT /issuer_management/issuer/ ISSUER-KEY
MÉTODO GET

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
|--------------|--------|------------------------------------------|------------|
| `ISSUER-KEY` | string | 发行人的唯一键（UUID v4）。 | 36 |

## Response
RESPONSE STATUS 200

状态为 *in_filling* 的 Response Body

```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

状态为 *reproved* 的 Response Body

```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": [],
    "signer_group_list": [],
    "issuer_representative_list": [],
    "issuer_contact_information_list": [],
    "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": [],
        "documents": [],
        "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

状态为 *approved* 的 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",
    "bank_account_list": [],
    "signer_group_list": [],
    "issuer_representative_list": [],
    "issuer_contact_information_list": [],
    "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": [],
        "documents": [],
        "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

| 字段 | 类型 | 描述 | 最大字符数 |
|--------|----------|--------------------------------------------------------|-------------------------------------------------|
| `issuer_key` | string   | 发行人的唯一标识符。 | 36 |
| `name` | string   | 发行人全名。 | 255 |
| `document_number` | string   | 发行人证件号码（CNPJ）。 | 14 |
| `status` | string   | 发行人状态。 | **[status 枚举](#enumeradores-status)** |
| `backoffice_analysis_status`| string   | 后台分析状态。 | - |
| `person_type` | string   | 人员类型（`legal` 或 `natural`）。 | - |
| `trading_name` | string   | 发行人商业名称。 | 1023 |
| `cnae_code` | string   | 发行人的 CNAE 代码。 | 10 |
| `company_type` | string   | 公司类型：`sa`、`ltda`、`cop`、`-`。 | 50 |
| `foundation_date` | string   | 发行人成立日期。 | - |
| `signer_group_list` | array    | 与发行人关联的签名人组列表。 | - |
| `bank_account_list` | array    | 与发行人关联的银行账户列表。 | - |
| `issuer_representative_list` | array    | 发行人代表列表。 | - |
| `issuer_contact_information_list` | array    | 与发行人关联的联系信息列表。 | - |
| `issuer_document_list` | array    | 发行人已登记的文件列表。 | - |
| `address`         | string   | 地址引用对象。 | **[address 对象](#objeto-address)** |
| `annual_revenues`  | number | 出让人年收入申报。 | - |
| `is_in_national_financial_system`  | boolean | 指示出让人是否为国家金融系统（SFN）成员。 | - |
| `last_analysis`  | object | 分析对象。 | **[分析定义](#definição-de-análise)**。 |

### Address 对象

| 字段 | 类型 | 描述 | 最大字符数 |
|---------------------|----------|-----------------------------------------------------|-----------------|
| `street`          | string   | 公司地址街道名称。 | 500 |
| `neighborhood`      | string   | 公司地址区域名称。 | 100 |
| `number`         | string   | 地址门牌号。 | 10 |
| `postal_code`     | string   | 邮政编码（仅数字）。 | 8 |
| `city`           | string   | 地址城市名称。 | 255 |
| `state`           | string   | 州缩写（2个字符）。 | 2 |
| `complement`        | string   | 地址补充信息（如适用）。 | 100 |

### status 枚举
| 枚举值 | 描述 |
|--------|-----------------|
| `in_filling` | 填写中 |
| `in_analysis`	  | 分析中 |
| `canceled`	 | 已取消 |
| `approved`	 | 已批准 |
| `reproved`	 | 未批准 |
| `expired`	 | 已过期 |

### payment_bank_account 对象

| 字段 | 类型 | 描述 | 最大字符数 |
|-------------------------------------|----------|------------------------------------------------|-----------------|
| `account_digit`                    | string   | 银行账户校验位。 | - |
| `account_branch`                    | string   | 银行支行。 | - |
| `account_number`                    | string   | 银行账户号码。 | - |

### 分析定义

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `analysis_key` | string | 分析标识符。 | 36 |
| `analysis_number` | integer | 分析序列号。 | - |
| `status` | string | 分析状态。 | 参见 **[分析状态枚举](#analysis-status)**。 |
| `analysis_related_parties` | array | 分析中的关联方。 | 参见 **[分析关联方定义](#definição-de-partes-relacionadas-de-análise)**。 |
| `documents` | array | 分析文件。 | 参见 **[分析文件定义](#definição-de-documentos)**。 |
| `analysis_data` | object | 产生该分析的请求有效载荷。 | - |
| `analysis_datetime` | string | 分析创建日期时间对象。 | - |
| `reproval_reason` | string | 分析拒绝原因枚举。 | 参见 **[拒绝原因枚举](#analysis-reproval-reason)**。 |
| `reproval_details` | string | 分析拒绝详细信息的自由文本字段。 | - |

---

### Analysis Status

| 枚举值 | 描述 |
| ----------------------- | --------------------- |
| **pending_documents**  | 文件待提交 |
| **sent_to_analysis**   | 已发送分析 |
| **pending_internal_validation** | 文件验证中 |
| **in_manual_analysis** | 合规人工分析中 |
| **approved**           | 已批准 |
| **reproved**           | 未批准 |

---

### 文件定义

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `document_key` | string | 文件标识符。 | 36 |
| `document_type` | string | 文件类型。 |  |
| `status` | string | 文件状态。 |  |
| `observation` | string | 提交的备注。 | - |

---

### 分析关联方定义

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `analysis_related_party_key` | string | 关联方标识符。 | 36 |
| `document_number` | string | 关联方的证件号码。 | 14 至 18 |
| `name` | string | 关联方名称。 | 1 至 255 |
| `documents` | array | 关联方分析文件。 |  |

---

### Analysis Reproval Reason
| 枚举值 | 描述 |
|--------------|---------------|
| **assignor_update**   | 因后续注册更新而取消分析 |
| **insuficient_documents**  | 未提交验证权限的最少文件 |
| **compliance_reproval**  | 合规团队分析后拒绝关联关系 |
| **unidentified_related_parties** | 已提交关联方但无法证明关联关系 |
| **invalid_documents** | 文件无效/已过期 |
| **missing_related_parties** | 未提交必需关联方 |

---

---

# 按过滤条件查询发行人

URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-filtro

此端点允许使用证件号码（CNPJ）或姓名查询系统中已登记的发行人。

---

## Request
ENDPOINT /issuer_management/issuer
MÉTODO GET

### Query Params

| 字段 | 类型 | 描述 | 必填 |
|-------------------|----------|------------------------------------|-------------|
| `document_number` | string   | 发行人的证件号码。 | 否 |
| `name`            | string   | 发行人姓名。 | 否 |
| `page`            | integer  | 查询的当前页码。 | 否 |
| `rows_per_page`   | integer  | 每页记录数。 | 否 |

## 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

| 字段 | 类型 | 描述 | |
|--------------|--------|---------------------|-----------------------------------------------------------------|
| `data`       | list   | 结果列表。 | **[简化发行人对象](#objeto-emissor-simplificado)** |
| `pagination` | object | 分页数据。 | **[分页对象](#objeto-paginacao)** |

### 简化发行人对象

| 字段 | 类型 | 描述 | 最大字符数 |
|-------------------|----------|-------------------------------------------------------------|-------------------------------------------------|
| `issuer_key` | string   | 发行人的唯一标识符（UUID v4）。 | 36 |
| `name`     | string   | 发行人全名。 | 255 |
| `document_number` | string | 发行人的证件号码（CNPJ）。 | 14 |
| `status`   | string   | 发行人当前状态。 | **[status 枚举](#enumeradores-status)** |

### status 枚举
| 枚举值 | 描述 |
|--------|-----------------|
| `in_filling` | 填写中 |
| `in_analysis`	  | 分析中 |
| `canceled`	 | 已取消 |
| `approved`	 | 已批准 |
| `reproved`	 | 未批准 |
| `expired`	 | 已过期 |

### 分页对象

| 字段 | 类型 | 描述 |
|-------------------|----------|------------------------------------------|
| `current_page`    | integer  | 查询的当前页码。 |
| `next_page`       | integer  | 下一页（如果存在）。 |
| `rows_per_page`   | integer  | 每页记录数。 |
| `total_pages`     | integer  | 总页数。 |
| `total_rows`      | integer  | 找到的总记录数。 |

---

# 提交发行人分析

URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/envio-analise/

此端点允许将发行人的状态更改为分析中，将其发送至验证流程。

---

## Request

ENDPOINT /issuer_management/issuer/ ISSUER-KEY
MÉTODO PATCH

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
| -------------- | ------ | ---------------------------------- | ---------- |
| `ISSUER-KEY` | string | 发行人的唯一键（UUID v4）。 | 36 |

### Request Body

Request Body

```json
{
  "issuer_status": "in_analysis"
}
```

### Request Body Params

| 字段 | 类型 | 描述 | 必填 |
| ----------------- | ------ | ------------------------------------------------------- | ------------ |
| `issuer_status` | string | 发行人的新状态。接受值：`in_analysis`。 | 是 |

## Response

响应为发行人更新后的完整 JSON。

---

# 介绍

URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/inicio

发行人登记部分对于开始发行商业票据至关重要。本节将说明整个流程，从提交初始信息到提交分析。

要访问以下章节中讨论的服务，请联系团队 [suporte.dcm@qitech.com.br](mailto:suporte.dcm@qitech.com.br)，以便在沙盒环境和生产环境中进行相应授权。

### 发行人登记

在此步骤中，必须提交发行人及其代表的所有信息、文件、联系信息、签名人组和银行账户。

一旦信息提交完成，登记将被发送至出让人登记团队进行分析，批准后该发行人将有资格参与票据发行。

如果登记已在 QI CTVM 出让人登记平台上完成，则可以使用登记访问申请端点轻松重用该登记。

### 更新发行人

如需更新登记，必须重新提交所有发行人信息及所需修改。提交后，将生成新的分析进行验证。

一旦新的分析获批，发行人的新登记数据将正式生效。

---

# 申请访问发行人数据

URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/solicitacao-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": [],
    "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"
    }
}
```

### Response Body Params

| 字段 | 类型 | 描述 | 最大字符数 |
|--------|----------|--------------------------------------------------------|-------------------------------------------------|
| `issuer_key` | string   | 发行人的唯一标识符。 | 36 |
| `name` | string   | 发行人全名。 | 255 |
| `document_number` | string   | 发行人证件号码（CNPJ）。 | 14 |
| `status` | string   | 发行人状态。 | **[status 枚举](#enumeradores-status)** |
| `backoffice_analysis_status`| string   | 后台分析状态。 | - |
| `person_type` | string   | 人员类型（`legal` 或 `natural`）。 | - |
| `trading_name` | string   | 发行人商业名称。 | 1023 |
| `cnae_code` | string   | 发行人的 CNAE 代码。 | 10 |
| `company_type` | string   | 公司类型，接受：`sa`、`ltda`、`cop`。 | 50 |
| `foundation_date` | string   | 发行人成立日期。 | - |
| `signer_group_list` | array    | 与发行人关联的签名人组列表。 | - |
| `bank_account_list` | array    | 与发行人关联的银行账户列表。 | - |
| `issuer_representative_list` | array    | 发行人代表列表。 | - |
| `issuer_contact_information_list` | array    | 与发行人关联的联系信息列表。 | - |
| `issuer_document_list` | array    | 发行人已登记的文件列表。 | - |
| `address` *         | string   | 地址引用对象。 | **[address 对象](#objeto-address)** |

### Address 对象

| 字段 | 类型 | 描述 | 最大字符数 |
|---------------------|----------|-----------------------------------------------------|-----------------|
| `street` *          | string   | 公司地址街道名称。 | 500 |
| `neighborhood`      | string   | 公司地址区域名称。 | 100 |
| `number` *          | string   | 地址门牌号。 | 10 |
| `postal_code` *     | string   | 邮政编码（仅数字）。 | 8 |
| `city` *            | string   | 地址城市名称。 | 255 |
| `state` *           | string   | 州缩写（2个字符）。 | 2 |
| `complement`        | string   | 地址补充信息（如适用）。 | 100 |

### status 枚举
| 枚举值 | 描述 |
|--------|-----------------|
| `in_filling` | 填写中 |
| `in_analysis`	  | 分析中 |
| `canceled`	 | 已取消 |
| `approved`	 | 已批准 |
| `reproved`	 | 未批准 |
| `expired`	 | 已过期 |

### payment_bank_account 对象

| 字段 | 类型 | 描述 | 最大字符数 |
|-------------------------------------|----------|------------------------------------------------|-----------------|
| `account_digit` *                    | string   | 银行账户校验位。 | - |
| `account_branch` *                    | string   | 银行支行。 | - |
| `account_number` *                    | string   | 银行账户号码。 | - |

---

# 更新投资人登记

URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/alteracao-cadastro/

要对投资人登记进行修改，需要将其状态设置为"in_filling"，这将重新启用所有添加/删除端点。

完成修改后，必须再次将登记提交分析，状态为"in_analysis"。

---

## Request
ENDPOINT /investor_management/investor/ INVESTOR-KEY
MÉTODO PATCH

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
|--------------|--------|------------------------------------------|------------|
| `INVESTOR-KEY` | string | 投资人的唯一键（UUID v4）。 | 36 |

### Request Body

Request Body

```json
{
  "investor_status": "in_filling"
}
```

### Request Body Params

| 字段 | 类型 | 描述 | 必填 |
|------------------|----------|-----------------------------------------------------|-------------|
| `investor_status`  | string   | 投资人的新状态。接受值：`in_filling`。 | 是 |

## Response

响应为投资人更新后的完整 JSON。

---

# 登记投资人签名人组

URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/assinantes-investidor

此端点允许登记与已登记投资人关联的签名人组。

---

## Request

ENDPOINT /investor_management/investor/ INVESTOR-KEY /signer_group
MÉTODO POST

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
| -------------- | ------ | ---------------------------------- | ---------- |
| `INVESTOR-KEY` | string | 投资人的唯一键（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

| 字段 | 类型 | 描述 | 最大字符数 |
| ------------------------------ | ------- | ---------------------------------------------------------------- | -------------------------------------- |
| `minimum_required_signers` * | integer | 验证该组所需的最少签名人数。 | - |
| `signers` *                  | array   | 组成签名人组的 Signer 对象列表。 | **[Signer 对象](#objeto-signer)** |

### Signer 对象

| 字段 | 类型 | 描述 | 最大字符数 |
| ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------- | --------------------- |
| `name` *               | string  | 签名人全名。 | 255 |
| `document_number` *    | string  | 签名人的 CPF（格式"XXX.XXX.XXX-XX"）。 | 11 |
| `email` *              | string  | 签名人电子邮件地址。 | 1023 |
| `phone_number`*        | string  | 签名人电话号码（完整格式：国家代码、区号和号码。例如：+5511999999999）。 | 20 |
| `is_group_mandatory` * | boolean | 指示签名人在组内是必须还是可选的。 | - |

## 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

| 字段 | 类型 | 描述 | 最大字符数 |
| ---------------------------- | ------- | ---------------------------------------------------------- | -------------------------------------- |
| `signer_group_key`         | string  | 签名人组的唯一标识符（UUID v4）。 | 36 |
| `minimum_required_signers` | integer | 组内所需的最少签名人数。 | - |
| `signers` *                | array   | 组成签名人组的 Signer 对象列表。 | **[Signer 对象](#objeto-signer)** |

---

# 删除投资人签名人组

URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/assinantes-investidor-remocao

此端点允许删除与已登记投资人关联的签名人组。

---

## Request
ENDPOINT /investor_management/investor/ INVESTOR-KEY /signer_group/ SIGNER-GROUP-KEY
MÉTODO DELETE

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
|--------------------|--------|----------------------------------------------------------|------------|
| `INVESTOR-KEY`       | string | 投资人的唯一键（UUID v4）。 | 36 |
| `SIGNER-GROUP-KEY` | string | 待删除签名人组的唯一键（UUID v4）。 | 36 |

## Response
STATUS 204

响应体中不返回任何内容。

---

# 投资人基本登记

URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/cadastro-basico

此端点允许登记投资人的基本信息。

## Request

ENDPOINT /investor_management/investor
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"
  }
}
```

### Request Body Params

| 字段 | 类型 | 描述 | 最大字符数 |
| --------------------- | ------ | ----------------------------------------------------- | -------------------------------------------------------------- |
| `name` *            | string | 公司全名。 | 255 |
| `document_number` * | string | 公司 CNPJ（格式："XX.XXX.XXX/XXXX-XX"）。 | 14 |
| `trading_name`*     | string | 公司商业名称。 | 1023 |
| `cnae_code`*        | string | 公司 CNAE 代码（格式："XXXXX-XXX"）。 | 7 |
| `company_type`*     | string | 公司类型。 | **[company_type 枚举](#enumeradores-company_type)** |
| `foundation_date`*  | string | 公司成立日期（格式："YYYY-MM-DD"）。 | - |
| `address` *         | string | 地址引用对象。 | **[address 对象](#objeto-address)** |

### Address 对象

| 字段 | 类型 | 描述 | 最大字符数 |
| ----------------- | ------ | -------------------------------------------- | ---------------- |
| `street` *      | string | 公司地址街道名称。 | 500 |
| `neighborhood` * | string | 公司地址区域名称。 | 100 |
| `number` *      | string | 地址门牌号。 | 10 |
| `postal_code` * | string | 邮政编码（格式"XXXXX-XXX"）。 | 8 |
| `city` *        | string | 地址城市名称。 | 255 |
| `state` *       | string | 州缩写（2个字符）。 | 2 |
| `complement`    | string | 地址补充信息（如适用）。 | 100 |

### company_type 枚举

| 枚举值 | 描述 |
| -------- | ------------------ |
| `ltda` | 有限责任公司 |
| `sa`   | 股份公司 |
| `cop`  | 合作社 |

## Response

STATUS 201

Response Body

```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"
  }
```

### Response Body Params

| 字段 | 类型 | 描述 | 最大字符数 |
| ------------------------- | ------ | -------------------------------------- | -------------------------------------------------------------- |
| `investor_key`          | string | 投资人的唯一键（UUID）。 | 36 |
| `name`                  | string | 投资人全名。 | 255 |
| `document_number`       | string | 投资人的 CNPJ。 | 14 |
| `status`                | string | 投资人状态。 | - |
| `person_type`           | string | 人员类型。 | **[person_type 枚举](#enumeradores-person_type)** |
| `trading_name`          | string | 投资人商业名称。 | 1023 |
| `cnae_code`             | string | 投资人的 CNAE 代码。 | 7 |
| `company_type`          | string | 公司类型。 | **[company_type 枚举](#enumeradores-company_type)** |
| `foundation_date`       | string | 投资人成立日期。 | - |
| `address`               | string | 地址引用对象。 | **[address 对象](#objeto-address)** |
| `registration_datetime` | string | 投资人注册日期和时间。 | - |
| `expiration_date`       | string | 投资人到期日期。 | - |

### person_type 枚举

| 枚举值 | 描述 |
| ----------- | ---------------- |
| `legal`   | 法人 |
| `natural` | 自然人 |

---

# 登记投资人银行账户

URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/conta-bancaria-investidor

此端点允许登记与已登记投资人关联的银行账户。

---

## Request

ENDPOINT /investor_management/investor/ INVESTOR-KEY /bank_account
MÉTODO POST

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
| -------------- | ------ | ---------------------------------- | ---------- |
| `INVESTOR-KEY` | string | 投资人的唯一键（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

| 字段 | 类型 | 描述 | 最大字符数 |
| -------------------------------------- | ------ | ------------------------------------------------------------ | -------------------------------------------------------------- |
| `account_number` *                   | string | 银行账户号码，只能包含数字。 | 20 |
| `account_digit` *                    | string | 账户校验位，只能包含一位数字。 | 1 |
| `account_branch` *                   | string | 银行支行号码，只能包含数字。 | 6 |
| `financial_institution_code_number`* | string | 金融机构代码（3位数字）。 | 3 |
| `financial_institution_ispb` *       | string | 金融机构 ISPB 代码（8位数字）。 | 8 |
| `account_type` *                     | string | 银行账户类型。 | **[account_type 枚举](#enumeradores-account_type)** |

### account_type 枚举

| 枚举值 | 描述 |
| ------------ | ------------------ |
| `checking` | 活期账户 |
| `savings`  | 储蓄账户 |
| `salary`   | 工资账户 |
| `payment`  | 支付账户 |

## 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

| 字段 | 类型 | 描述 | 最大字符数 |
| ------------------------------------- | ------ | ------------------------------------------------------------- | -------------------------------------------------------------- |
| `bank_account_key`                  | string | 已登记银行账户的唯一标识符（UUID v4）。 | 36 |
| `account_number`                    | string | 银行账户号码。 | 20 |
| `account_digit`                     | string | 银行账户校验位。 | 1 |
| `account_branch`                    | string | 银行支行号码。 | 6 |
| `financial_institution_code_number` | string | 金融机构代码。 | 3 |
| `financial_institution_ispb`        | string | 金融机构 ISPB 代码。 | 8 |
| `account_type`                      | string | 银行账户类型。 | **[account_type 枚举](#enumeradores-account_type)** |

---

# 删除投资人银行账户

URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/conta-bancaria-investidor-remocao

此端点允许删除与已登记投资人关联的银行账户。

---

## Request
ENDPOINT /investor_management/investor/ INVESTOR-KEY /bank_account/ BANK-ACCOUNT-KEY
MÉTODO DELETE

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
|--------------------|--------|------------------------------------------------------|------------|
| `INVESTOR-KEY`       | string | 投资人的唯一键（UUID v4）。 | 36 |
| `BANK-ACCOUNT-KEY` | string | 待删除银行账户的唯一键（UUID v4）。 | 36 |

---

## Response
STATUS 204

响应体中不返回任何内容。

---

---

# 提交投资人文件

URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/documentos-investidor

此端点允许提交与已登记投资人关联的文件。

---

## Request

ENDPOINT /investor_management/investor/ INVESTOR-KEY /document
MÉTODO POST

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
| -------------- | ------ | ---------------------------------- | ---------- |
| `INVESTOR-KEY` | string | 投资人的唯一键（UUID v4）。 | 36 |

### Request Body

Request Body

```json
{
  "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0",
  "document_type": "proof_of_address"
}
```

### Request Body Params

| 字段 | 类型 | 描述 | 最大字符数 |
| --------------------- | ------ | ------------------------------------------------------- | ---------------------------------------------------------------- |
| `document_base64` * | string | Base64 编码的文件内容。 | - |
| `document_type` *   | string | 提交文件的类型。 | **[document_type 枚举](#enumeradores-document_type)** |

### document_type 枚举

| 枚举值 | 描述 |
| ------------------------------- | ---------------------------------- |
| `proof_of_address`              | 地址证明 |
| `letter_of_attorney`            | 授权书 |
| `company_statute` *               | 公司章程或合同 |
| `commercial_board_certificate`  | 商业委员会证书 |
| `board_election_record`         | 董事会选举记录 |
| `manager_declaration`           | 经理声明 |
| `financial_statement`           | 财务报表 |
| `credit_report`                 | 信用报告 |
| `manager_statement`             | 管理员声明 |
| `compliance_statement`          | 合规声明 |
| `cnpj_card`                     | CNPJ 卡 |
| `additional_document`           | 附加文件 |

:::warning 注意
所有登记均需提供 **company_statute**（公司章程）。
:::

## Response

STATUS 201

Response Body

**场景 1：自动验证（OCR 成功）**

```json
{
    "document_key": "123e4567-e89b-12d3-a456-426614174000",
    "document_type": "proof_of_address",
    "ocr_key": "6654f284-f690-4324-8c39-dcf0225ec8cf"
}
```
**含义**：文件已由 OCR 自动处理和验证。

**场景 2：需要人工审核**

```json
{
    "document_key": "8bf591a8-c184-47db-afd2-a5196de14cc3",
    "document_type": "cnpj_card",
    "ocr_key": null
}
```
**含义**：文件无法通过 OCR 自动验证，已转入人工审核队列。

:::warning 注意
成功请求（提交成功）的响应有两种不同行为，取决于自动验证（OCR）的结果。
:::

### Response Body Params

| 字段 | 类型 | 描述 | 最大长度 |
| ----------------- | ------ | ---------------------------------------------------- | ---------------------------------------------------------------- |
| `document_key`  | string | 提交文件的唯一标识符（UUID v4）。 | 36 |
| `document_type` | string | 提交文件的类型。 | **[document_type 枚举](#enumeradores-document_type)** |
| `ocr_key`       | string | 与提交文件关联的 OCR 键。 | 36 |

---

# 删除投资人文件

URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/documentos-investidor-remocao

此端点允许删除已提交至投资人登记的文件。

---

## Request
ENDPOINT /investor_management/investor/ INVESTOR-KEY /document/ DOCUMENT-KEY
MÉTODO DELETE

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
|----------------|--------|------------------------------------------|------------|
| `INVESTOR-KEY`   | string | 投资人的唯一键（UUID v4）。 | 36 |
| `DOCUMENT-KEY` | string | 待删除文件的唯一键（UUID v4）。 | 36 |

## Response
STATUS 204

响应体中不返回任何内容。

---

# 上传投资者代表文件

URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/documentos-representantes-investidor

此端点允许上传与之前注册的投资者代表关联的文件。

---
## Request
ENDPOINT /investor_management/investor/ INVESTOR-KEY /investor_representative/ INVESTOR-REPRESENTATIVE-KEY /document
MÉTODO POST

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------|--------|---------------------------------------------------|------------|
| `INVESTOR-KEY` | string | 投资者的唯一键（UUID v4）。 | 36 |
| `INVESTOR-REPRESENTATIVE-KEY` | string | 投资者代表的唯一键（UUID v4）。 | 36 |

### Request Body
Request Body
```json
{
  "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0",
  "document_type": "cnh"
}
```

### Request Body Params

| 字段 | 类型 | 描述 | 最大字符数 |
|--------------------|----------|-------------------------------------------------------------------------------------------|-----------------------|
| `document_base64` * | string | Base64 编码的文件内容。 | - |
| `document_type` * | string | 上传的文件类型。可接受的值： | **[document_type 枚举值](#enumeradores-document_type)** |

### document_type 枚举值
| 枚举值 | 描述 |
|--------|-------------------------|
| `cnh` | 驾驶执照 |
| `cnh_front` | 驾驶执照正面 |
| `cnh_back` | 驾驶执照背面 |
| `cnh_digital` | 电子版驾驶执照 PDF |
| `rg_front` | 身份证正面 |
| `rg_back` | 身份证背面 |
| `danfe` | DANFE |
| `proof_of_address` | 居住证明 |
| `letter_of_attorney` | 授权委托书 |

## 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

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------|----------|-----------------------------------------------------|-----------------------|
| `document_key` | string | 上传文件的唯一标识符（UUID v4）。 | 36 |
| `document_type` | string | 上传的文件类型。 | **[document_type 枚举值](#enumeradores-document_type)** |
| `ocr_key` | string | 与上传文件关联的 OCR 键。 | 36 |

---

# 删除投资者代表文件

URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/documentos-representantes-investidor-remocao

此端点允许删除与之前注册的投资者代表关联的文件。

---

## Request
ENDPOINT /investor_management/investor/ INVESTOR-KEY /investor_representative/ INVESTOR-REPRESENTATIVE-KEY /document/ DOCUMENT-KEY
MÉTODO DELETE

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------|--------|---------------------------------------------------|------------|
| `INVESTOR-KEY` | string | 投资者的唯一键（UUID v4）。 | 36 |
| `INVESTOR-REPRESENTATIVE-KEY` | string | 投资者代表的唯一键（UUID v4）。 | 36 |
| `DOCUMENT-KEY` | string | 要删除的文件的唯一键（UUID v4）。 | 36 |

## Response
STATUS 204

响应体中不返回任何内容。

---

# 注册投资者联系信息

URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/informacao-contato-investidor

此端点允许注册与之前注册的投资者关联的联系信息。

---

## Request

ENDPOINT /investor_management/investor/ INVESTOR-KEY /investor_contact_information
MÉTODO POST

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
| ---------------- | ------ | ------------------------------------- | ---------- |
| `INVESTOR-KEY` | string | 投资者的唯一键（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

| 字段 | 类型 | 描述 | 最大字符数 |
| --------------------- | ------ | ----------------------------------------------------------------------------------------------------------------- | --------------------- |
| `name` * | string | 联系人全名。 | 255 |
| `document_number` * | string | 联系人文件编号（CPF格式，"XX.XXX.XXX/XXXX-XX"）。 | 11 |
| `email` * | string | 联系人的电子邮件地址。 | 1023 |
| `phone_number` * | string | 联系人的电话号码（完整格式：国家代码、区号和号码。示例：+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

| 字段 | 类型 | 描述 | 最大字符数 |
| ------------------------------------ | ------ | --------------------------------------------------------------------- | --------------------- |
| `investor_contact_information_key` | string | 注册联系信息的唯一标识符（UUID v4）。 | 36 |
| `name` | string | 联系人全名。 | 255 |
| `document_number` | string | 联系人文件编号（CPF）。 | 11 |
| `email` | string | 联系人的电子邮件地址。 | 1023 |
| `phone_number` | string | 联系人的电话号码。 | 20 |

---

# 删除投资者联系信息

URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/informacao-contato-investidor-remocao

此端点允许删除与之前注册的投资者关联的联系信息。

---

## Request
ENDPOINT /investor_management/investor/ INVESTOR-KEY /investor_contact_information/ INVESTOR-CONTACT-INFORMATION-KEY
MÉTODO DELETE

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
|----------------------------------|--------|-----------------------------------------------------------|------------|
| `INVESTOR-KEY` | string | 投资者的唯一键（UUID v4）。 | 36 |
| `INVESTOR-CONTACT-INFORMATION-KEY` | string | 要删除的联系信息的唯一键（UUID v4）。 | 36 |

## Response
STATUS 204

响应体中不返回任何内容。

---

# 登记投资人代表

URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/representantes-investidor

此端点允许登记与已登记投资人关联的代表。

---

## Request

ENDPOINT /investor_management/investor/ INVESTOR-KEY /investor_representative
MÉTODO POST

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
| -------------- | ------ | ---------------------------------- | ---------- |
| `INVESTOR-KEY` | string | 投资人的唯一键（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

| 字段 | 类型 | 描述 | 最大字符数 |
| ---------------------------------- | ------- | --------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `name` *                         | string  | 投资人代表的全名。 | 255 |
| `document_number` *              | string  | 证件号码（CPF，格式"XXX.XXX.XXX-XX"）。 | 11 |
| `birthdate`                      | string  | 代表的出生日期，ISO 8601 格式（YYYY-MM-DD）。 | - |
| `document_identification_number` | string  | 身份证件号码。 | 255 |
| `marital_status`                 | string  | 代表的婚姻状况。 | **[marital_status 枚举](#enumeradores-marital_status)** |
| `property_system`                | string  | 财产制度。 | **[property_system 枚举](#enumeradores-property_system)** |
| `nationality` * | string | 受益人所在国家。 | 3，依据 ISO 3166-1 alpha-3 |
| `mother_name`                    | string  | 代表母亲的全名。 | 1023 |
| `father_name`                    | string  | 代表父亲的全名。 | 1023 |
| `occupation`                     | string  | 代表的职业或工作。 | 255 |
| `is_pep`                         | boolean | 指示代表是否为政治敏感人物（PEP）。 | - |
| `address` *                      | string  | 地址引用对象。 | **[address 对象](#objeto-address)** |
| `annual_revenues`  | number | 出让人年收入申报。 | - |
| `related_party_type` * | 枚举 | 关联方的关系类型。 | 参见 **[关联方类型枚举](#related-party-type)** |

### Address 对象

| 字段 | 类型 | 描述 | 最大字符数 |
| ----------------- | ------ | ---------------------------------------- | ---------------- |
| `street` *      | string | 公司地址街道名称。 | 500 |
| `neighborhood`  | string | 公司地址区域名称。 | 100 |
| `number` *      | string | 地址门牌号。 | 10 |
| `postal_code` * | string | 邮政编码（格式"XXXXX-XXX"）。 | 8 |
| `city` *        | string | 地址城市名称。 | 255 |
| `state` *       | string | 州缩写（2个字符）。 | 2 |
| `complement`    | string | 地址补充信息（如适用）。 | 100 |

### marital_status 枚举

| 枚举值 | 描述 |
| ---------------- | ------------------ |
| `single`       | 未婚 |
| `married`      | 已婚 |
| `widower`      | 丧偶 |
| `separated`    | 分居 |
| `stable_union` | 同居关系 |
| `divorced`     | 离婚 |

### property_system 枚举

| 枚举值 | 描述 |
| --------------------------------------- | --------------------------------- |
| `total_communion_of_goods`            | 完全财产共同制 |
| `partial_communion_of_goods`          | 部分财产共同制 |
| `total_separation_of_goods`           | 完全财产分离制 |
| `final_participation_of_acquisitions` | 婚后所得共同制 |
| `compulsory_separation_of_goods`      | 强制财产分离制 |

### Related Party Type

| 枚举值 | 描述 |
| ----------------------- | ------------- |
| **president**     | 总裁 |
| **partner**       | 合伙人 |
| **administrator** | 管理员 |
| **director**      | 董事 |
| **manager**       | 经理 |
| **attorney**      | 代理人 |

---

## 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": "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,
  "investor_representative_document_list": []
}
```

### Response Body Params

| 字段 | 类型 | 描述 | 最大字符数 |
| --------------------------------------- | ------- | -------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `investor_representative_key`           | string  | 投资人代表的唯一标识符（UUID v4）。 | 36 |
| `name`                                | string  | 投资人代表的全名。 | 255 |
| `document_number`                     | string  | 代表的证件号码（格式"XXX.XXX.XXX-XX"）。 | 11 |
| `document_identification_number`      | string  | 身份证件号码。 | 255 |
| `marital_status`                      | string  | 代表的婚姻状况。 | **[marital_status 枚举](#enumeradores-marital_status)** |
| `property_system`                     | string  | 财产制度。 | **[property_system 枚举](#enumeradores-property_system)** |
| `birthdate`                           | string  | 代表的出生日期。 | - |
| `nationality` * | string | 受益人所在国家。 | 3，依据 ISO 3166-1 alpha-3 |
| `mother_name`                         | string  | 代表母亲的全名。 | 1023 |
| `father_name`                         | string  | 代表父亲的全名。 | 1023 |
| `occupation`                          | string  | 代表的职业或工作。 | 255 |
| `is_pep`                              | boolean | 指示代表是否为政治敏感人物（PEP）。 | - |
| `address` *                           | string  | 地址引用对象。 | **[address 对象](#objeto-address)** |
| `investor_representative_document_list` | array   | 与代表关联的文件列表。 | - |
| `annual_revenues`  | number | 出让人年收入申报。 | - |
| `related_party_type` * | 枚举 | 关联方的关系类型。 | 参见 **[关联方类型枚举](#related-party-type)** |

---

# 删除投资人代表

URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/representantes-investidor-remocao

此端点允许删除已提交至投资人登记的代表。

---

## Request
ENDPOINT /investor_management/investor/ INVESTOR-KEY /investor_representative/ INVESTOR-REPRESENTATIVE-KEY
MÉTODO DELETE

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------|--------|--------------------------------------------------------|------------|
| `INVESTOR-KEY`                | string | 投资人的唯一键（UUID v4）。 | 36 |
| `INVESTOR-REPRESENTATIVE-KEY` | string | 待删除代表的唯一键（UUID v4）。 | 36 |

## Response
STATUS 204

响应体中不返回任何内容。

---

# 查询投资人

URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-chave

此端点允许通过唯一键查询系统中已登记投资人的完整详情。

---

## Request
ENDPOINT /investor_management/investor/ INVESTOR-KEY
MÉTODO GET

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
|--------------|--------|------------------------------------------|------------|
| `INVESTOR-KEY` | string | 投资人的唯一键（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

| 字段 | 类型 | 描述 | 最大字符数 |
|--------|----------|--------------------------------------------------------|-------------------------------------------------|
| `investor_key` | string   | 投资人的唯一标识符。 | 36 |
| `name` | string   | 投资人全名。 | 255 |
| `document_number` | string   | 投资人证件号码（CNPJ）。 | 14 |
| `status` | string   | 投资人状态。 | **[status 枚举](#enumeradores-status)** |
| `backoffice_analysis_status`| string   | 后台分析状态。 | - |
| `person_type` | string   | 人员类型（`legal` 或 `natural`）。 | - |
| `trading_name` | string   | 投资人商业名称。 | 1023 |
| `cnae_code` | string   | 投资人的 CNAE 代码。 | 10 |
| `company_type` | string   | 公司类型。 | 50 |
| `foundation_date` | string   | 投资人成立日期。 | - |
| `signer_group_list` | array    | 与投资人关联的签名人组列表。 | - |
| `bank_account_list` | array    | 与投资人关联的银行账户列表。 | - |
| `investor_representative_list` | array    | 投资人代表列表。 | - |
| `investor_contact_information_list` | array    | 与投资人关联的联系信息列表。 | - |
| `investor_document_list` | array    | 投资人已登记的文件列表。 | - |
| `address`         | string   | 地址引用对象。 | **[address 对象](#objeto-address)** |

### Address 对象

| 字段 | 类型 | 描述 | 最大字符数 |
|---------------------|----------|-----------------------------------------------------|-----------------|
| `street`          | string   | 公司地址街道名称。 | 500 |
| `neighborhood`      | string   | 公司地址区域名称。 | 100 |
| `number`         | string   | 地址门牌号。 | 10 |
| `postal_code`     | string   | 邮政编码（仅数字）。 | 8 |
| `city`           | string   | 地址城市名称。 | 255 |
| `state`           | string   | 州缩写（2个字符）。 | 2 |
| `complement`        | string   | 地址补充信息（如适用）。 | 100 |

### status 枚举
| 枚举值 | 描述 |
|--------|-----------------|
| `in_filling` | 填写中 |
| `in_analysis`	  | 分析中 |
| `canceled`	 | 已取消 |
| `approved`	 | 已批准 |
| `reproved`	 | 未批准 |
| `expired`	 | 已过期 |

---

# 按过滤条件查询投资人

URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-filtro

此端点允许使用证件号码（CNPJ）或姓名查询系统中已登记的投资人。

---

## Request
ENDPOINT /investor_management/investor
MÉTODO GET

### Query Params

| 字段 | 类型 | 描述 | 必填 |
|-------------------|----------|------------------------------------|-------------|
| `document_number` | string   | 投资人的证件号码。 | 否 |
| `name`            | string   | 投资人姓名。 | 否 |
| `page`            | integer  | 查询的当前页码。 | 否 |
| `rows_per_page`   | integer  | 每页记录数。 | 否 |

## 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

| 字段 | 类型 | 描述 | |
|--------------|--------|---------------------|-----------------------------------------------------------------|
| `data`       | list   | 结果列表。 | **[简化投资人对象](#objeto-investidor-simplificado)** |
| `pagination` | object | 分页数据。 | **[分页对象](#objeto-paginacao)** |

### 简化投资人对象

| 字段 | 类型 | 描述 | 最大字符数 |
|-------------------|----------|-------------------------------------------------------------|-------------------------------------------------|
| `investor_key` | string   | 投资人的唯一标识符（UUID v4）。 | 36 |
| `name`     | string   | 投资人全名。 | 255 |
| `document_number` | string | 投资人的证件号码（CNPJ）。 | 14 |
| `status`   | string   | 投资人当前状态。 | **[status 枚举](#enumeradores-status)** |

### status 枚举
| 枚举值 | 描述 |
|--------|-----------------|
| `in_filling` | 填写中 |
| `in_analysis`	  | 分析中 |
| `canceled`	 | 已取消 |
| `approved`	 | 已批准 |
| `reproved`	 | 未批准 |
| `expired`	 | 已过期 |

### 分页对象

| 字段 | 类型 | 描述 |
|-------------------|----------|------------------------------------------|
| `current_page`    | integer  | 查询的当前页码。 |
| `next_page`       | integer  | 下一页（如果存在）。 |
| `rows_per_page`   | integer  | 每页记录数。 |
| `total_pages`     | integer  | 总页数。 |
| `total_rows`      | integer  | 找到的总记录数。 |

---

# 提交投资人分析

URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/envio-analise/

此端点允许将投资人的状态更改为分析中，将其发送至验证流程。

---

## Request

ENDPOINT /investor_management/investor/ INVESTOR-KEY
MÉTODO PATCH

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
| -------------- | ------ | ---------------------------------- | ---------- |
| `INVESTOR-KEY` | string | 投资人的唯一键（UUID v4）。 | 36 |

### Request Body

Request Body

```json
{
  "investor_status": "in_analysis"
}
```

### Request Body Params

| 字段 | 类型 | 描述 | 必填 |
| ----------------- | ------ | ------------------------------------------------------- | ------------ |
| `investor_status` | string | 投资人的新状态。接受值：`in_analysis`。 | 是 |

## Response

响应为投资人更新后的完整 JSON。

---

# 介绍

URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/inicio

投资人登记部分对于开始发行商业票据至关重要。本节将说明整个流程，从提交初始信息到提交分析。

要访问以下章节中讨论的服务，请联系团队 [suporte.dcm@qitech.com.br](mailto:suporte.dcm@qitech.com.br)，以便在沙盒环境和生产环境中进行相应授权。

### 投资人登记

在此步骤中，必须提交投资人及其代表的所有信息、文件、联系信息、签名人组和银行账户。

一旦信息提交完成，登记将被发送至分析团队，批准后该投资人将有资格参与票据发行。

### 更新投资人

如需更新登记，必须重新提交所有投资人信息及所需修改。提交后，将生成新的分析进行验证。

一旦新的分析获批，投资人的新登记数据将正式生效。

---

# **申请访问投资人数据**

URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/solicitacao-acesso

已登记具有**唯一登记**的投资人的客户需要**申请访问投资人数据**，以便在书写系统中以该投资人作为参与方开展业务。

提交该申请后，**投资人将收到一封电子邮件，说明如何批准或拒绝访问**。

---

## **申请访问 (POST)**

### **Request**
ENDPOINT /investor_management/investor/ INVESTOR-KEY /data_access_request
MÉTODO POST

### **Path Params**

| 字段 | 类型 | 描述 | 最大字符数 |
|---------------|--------|-----------------------------------------------|-----------------|
| `INVESTOR-KEY` * | string | 投资人的唯一键（UUID v4）。 | 36 |

---

## **Request Body**  

无需请求体。

---

## **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**

| 字段 | 类型 | 描述 | 最大字符数 |
|--------------------------------|----------|-------------------------------------------------------------|-----------------|
| `data_access_request_key` *    | string   | 访问申请的唯一键（UUID v4）。 | 36 |
| `requested_at` *               | string   | 申请日期和时间（ISO 8601 格式）。 | - |
| `responded_at`                 | string   | 申请回复的日期和时间（如已回复）。 | - |
| `data_access_request_status` * | string   | 申请状态。 | **[data_access_request_status 枚举](#enumeradores-data_access_request_status)** |

---

## **查询申请状态 (GET)**

客户可以查看其申请是否已获批准、被拒绝或仍在审核中。

## **Request**
ENDPOINT /investor_management/investor/ INVESTOR-KEY /data_access_request
MÉTODO GET

### **Path Params**

| 字段 | 类型 | 描述 | 最大字符数 |
|---------------|--------|-----------------------------------------------|-----------------|
| `INVESTOR-KEY` * | string | 投资人的唯一键（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**

| 字段 | 类型 | 描述 | 最大字符数 |
|--------------------------------|----------|-------------------------------------------------------------|-----------------|
| `data_access_request_key` *    | string   | 访问申请的唯一键（UUID v4）。 | 36 |
| `requested_at` *               | string   | 申请日期和时间（ISO 8601 格式）。 | - |
| `responded_at`                 | string   | 申请回复的日期和时间（如已回复）。 | - |
| `data_access_request_status` * | string   | 申请状态。 | **[data_access_request_status 枚举](#enumeradores-data_access_request_status)** |

---

## **data_access_request_status 枚举**

| 枚举值 | 描述 |
|-------------|------------------------------------------------------|
| `in_analysis` | 申请正在由投资人审核中。 |
| `approved`   | 访问已获批准，客户可以查看投资人数据。 |
| `reproved`   | 申请已被拒绝，客户将无法访问投资人数据。 |

---

# 查询交易凭证

URL: /zh-Hans/documentation/escrituracao/integralizacao-cotas/consulta-comprovante-transacao

此端点用于获取 QI Tech 为某次认缴执行的某笔 BaaS TED 的凭证（PDF 与元数据）。一次认缴流程（投资者付款 → 费用 → 拨付）可能产生多笔 TED，您通过 `transaction_type` 查询参数选择需要的那一笔。

如果同一次认缴中存在多笔同类型的 TED（例如多笔 `extraordinary_event_payment`），此端点仅返回最新的一笔。如需列出全部，请使用 **[查询认缴交易列表](./consulta-transacoes-integralizacao.md)**。

---

## 查询交易凭证 (GET)

### Request
ENDPOINT /account_liquidation/integralization/ INTEGRALIZATION-KEY /transaction_receipt
MÉTODO GET

### Path Params

| 字段                  | 类型   | 描述                                       | 字符数 |
|-----------------------|--------|--------------------------------------------|--------|
| `INTEGRALIZATION-KEY` | string | 认缴的唯一键（UUID v4）。                  | 36     |

### Query Params

| 字段               | 类型   | 描述                                                                                                  | 是否必填 |
|--------------------|--------|-------------------------------------------------------------------------------------------------------|----------|
| `transaction_type` | string | 要查询的 TED 类型。**[transaction_type 枚举值](#transaction_type-枚举值)**                            | 是       |

---

### 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

| 字段                 | 类型   | 描述                                                                                              |
|----------------------|--------|---------------------------------------------------------------------------------------------------|
| `transaction_key`    | string | BaaS 侧 TED 的唯一键 — 与 `consulta-transacoes-integralizacao` 返回的值相同。                     |
| `transaction_amount` | number | QI Tech 记录的 TED 金额。                                                                         |
| `transaction_status` | string | TED 在 BaaS 侧的状态（如 `settled`、`paid`）。                                                    |
| `pdf_encoded_string` | string | base64 编码的银行凭证字符串，解码后即可获取 PDF。                                                 |

---

### transaction_type 枚举值

| 枚举                          | 描述                                                              |
|-------------------------------|-------------------------------------------------------------------|
| `disbursement`                | 将发行人净额拨付到发行人银行账户的 TED。                          |
| `bookkeeping_fee_internal`    | 支付给 QI CTVM 的内部簿记费 TED。                                 |
| `bookkeeping_fee_external`    | 支付给客户外部簿记账户的 TED。                                    |
| `structuring_fee`             | 支付给客户结构化账户的 TED。                                      |
| `extraordinary_event_payment` | 因特殊清算事件支付给投资者的 TED。                                |

---

### 错误

| HTTP | 代码                                                | 触发条件                                                                                          |
|------|-----------------------------------------------------|---------------------------------------------------------------------------------------------------|
| 400  | `HTTPMissingParam`                                  | 未提供 `transaction_type` 查询参数。                                                              |
| 400  | `HTTPInvalidParam`                                  | `transaction_type` 不在允许的取值范围内。                                                         |
| 404  | `ACL000004` (`IntegralizationTransactionNotFound`)  | 不存在所请求类型的 TED，或该认缴从未完成清算（无任何 TED 记录）。                                 |

:::note
404 与 `ACL000004` 在所有场景下（未知键、从未清算的认缴、缺失的 TED 类型）的返回相同 — 这是设计意图，不区分具体场景。如果需要确认认缴是否存在，请先查询其交易列表。
:::

---

# Consulta de Conta de Liquidação

URL: /zh-Hans/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. |

---

# 按键查询认缴

URL: /zh-Hans/documentation/escrituracao/integralizacao-cotas/consulta-processo-integralizacao

此端点允许使用唯一键查询认缴流程的详情。

---

## 查询认缴流程 (GET)

### Request
ENDPOINT /integralization/integralization_process/ INTEGRALIZATION-KEY
MÉTODO GET

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
|------------------------|--------|------------------------------------------------------------------|------------|
| `INTEGRALIZATION-KEY`  | string | 认缴的唯一键（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

| 字段 | 类型 | 描述 |
|------------------------------------------------------------------------|------------|------------------------------------------------------------------------------------------------------|
| `tenant_key`                                                           | string     | 与认缴关联的租户唯一键。 |
| `integralization_key`                                                  | string     | 认缴的唯一键。 |
| `operation_key`                                                        | string     | 关联操作的唯一键。 |
| `operation_type`                                                       | string     | 操作类型。可能的值：`commercial_paper`。 |
| `contract_number`                                                      | string     | 与认缴关联的合同编号。 |
| `issue_number`                                                         | integer    | 与认缴关联的发行编号。 |
| `issue_series`                                                         | integer    | 与认缴关联的发行系列。 |
| `issuer_key`                                                           | string     | 关联发行人的唯一键。 |
| `issuer_name`                                                          | string     | 与认缴关联的发行人名称。 |
| `issuer_document_number`                                               | string     | 发行人证件号码。 |
| `issuer_bank_account`                                                  | object     | 发行人银行账户数据。 |
| `issuer_bank_account.account_type`                                     | string   | 银行账户类型（`checking` 等）。 |
| `issuer_bank_account.account_digit`                                    | string   | 银行账户校验位。 |
| `issuer_bank_account.account_branch`                                   | string   | 银行支行。 |
| `issuer_bank_account.account_number`                                   | string   | 银行账户号码。 |
| `issuer_bank_account.financial_institution_ispb`                       | string   | 金融机构 ISPB。 |
| `issuer_bank_account.financial_institution_code_number`                | string | 金融机构代码。 |
| `subscripted_quantity`                                                 | integer    | 已认购的总股份数量。 |
| `subscripted_total_amount`                                             | number     | 已认购股份的总价值。 |
| `integralized_quantity`                                                | integer    | 已认缴的总股份数量。 |
| `issue_quantity`                                                       | integer    | 操作中发行的总股份数量。 |
| `integralization_status`                                               | string     | **[integralization_status 枚举](#enumeradores-integralization_status)** |
| `subscription_list`                                                    | array      | 与认缴关联的认购列表。**[subscription 对象](#objeto-subscription)** |

### subscription 对象

| 字段 | 类型 | 描述 |
|------------------------------------------------------------------------|------------|---------------------------------------------------------------------------------------------------------------|
| `subscription_key`                                   | string   | 认购的唯一键。 |
| `investor_key`                                       | string   | 与认购关联的投资人唯一键。 |
| `investor_name`                                      | string   | 投资人名称。 |
| `investor_document_number`                           | string   | 投资人证件号码（CPF 或 CNPJ）。 |
| `investor_bank_account`                              | object   | 投资人银行数据。 |
| `subscription_date`                                  | string   | 认购日期（格式：YYYY-MM-DD）。 |
| `financial_base_date`                                | string   | 认购财务基准日期（格式：YYYY-MM-DD）。 |
| `subscripted_quantity`                               | integer  | 已认购的股份数量。 |
| `unit_price`                                         | number   | 每股单价。 |
| `expected_amount`                                    | number   | 认购预期总金额。 |
| `paid_amount`                                        | number   | 已确认支付的认购金额。 |
| `subscription_note_template_key`                     | string   | 认购公告模板键。 |
| `subscription_note_document_key`                     | string   | 认购公告文件键。 |
| `subscription_note_signature_status`                 | string | 认购公告签名状态。 |
| `subscription_payment_list`                          | array    | 与认购关联的付款列表。**[subscription_payment 对象](#objeto-subscription_payment)** |

### subscription_payment 对象

| 字段 | 类型 | 描述 |
|------------------------------------------------------------------------|------------|----------------------------------------------------------------------------------------|
| `subscription_payment_key` | string   | 认购付款的唯一键。 |
| `payment_receipt_document_key`                                         | string   | 付款凭证文件键。 |
| `description`                                                          | string   | 付款凭证说明。 |
| `amount`                                                               | number   | 已登记的付款金额。 |
| `subscription_payment_status`                                          | string   | 付款状态。可能的值：`waiting_confirmation`、`confirmed`、`denied`。 |
| `updated_at`                                                           | string   | 付款最后更新日期和时间（格式：ISO 8601）。 |

### integralization_status 枚举

| 枚举值 | 描述 |
| ------------------------------- | ---------------------------------- |
| `pending`              | 认购待处理。 |
| `finished`            | 认缴已完成。 |
| `canceled`               | 认缴已取消。 |

---

# 查询认缴交易列表

URL: /zh-Hans/documentation/escrituracao/integralizacao-cotas/consulta-transacoes-integralizacao

此端点返回 QI Tech 为某次认缴执行的所有 BaaS TED 元数据 — 不包含 PDF。适用于了解凭证数量、执行顺序及对应的 `transaction_key`。如需获取某笔 TED 的 PDF，请使用 **[查询交易凭证](./consulta-comprovante-transacao.md)**。

响应按时间顺序排列（`created_at` 升序），包含本周期内的所有 TED（拨付、费用与特殊事件）。当存在多笔同类型 TED（如多笔 `extraordinary_event_payment`）时，全部都会出现在此处 — 与凭证端点不同（凭证端点仅返回最新一笔）。

---

## 查询交易列表 (GET)

### Request
ENDPOINT /account_liquidation/integralization/ INTEGRALIZATION-KEY /transactions
MÉTODO GET

### Path Params

| 字段                  | 类型   | 描述                                       | 字符数 |
|-----------------------|--------|--------------------------------------------|--------|
| `INTEGRALIZATION-KEY` | string | 认缴的唯一键（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

| 字段                 | 类型   | 描述                                                                                          |
|----------------------|--------|-----------------------------------------------------------------------------------------------|
| `transaction_key`    | string | BaaS 侧 TED 的唯一键。                                                                        |
| `external_id`        | string | 该 TED 所属的 `integralization_key`。                                                         |
| `transaction_amount` | number | QI Tech 记录的 TED 金额。请勿用作会计对账的权威值。                                           |
| `transaction_type`   | string | TED 类型。**[transaction_type 枚举值](./consulta-comprovante-transacao.md#transaction_type-枚举值)** |
| `transaction_status` | string | 当前 TED 状态（如 `paid`、`settled`）。                                                       |
| `created_at`         | string | 记录创建时间（ISO 8601）。                                                                    |

---

# 股份认缴介绍

URL: /zh-Hans/documentation/escrituracao/integralizacao-cotas/inicio

商业票据发行流程完成后，操作将处于已发行（issued）状态。

默认情况下，签署组建条款后，股份认购认缴流程将自动进行。

查询处于已发行状态的操作时，将有一个名为 `integralization_key` 的字段，可通过该字段跟踪认缴流程。

认缴流程包括：

- 股份认购
- 签署认购公告
- 付款登记
- 付款确认

---

# 登记认购

URL: /zh-Hans/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/cadastro-subscricao

此端点允许登记投资人认购某一认缴操作中特定数量股份的意向。

---

## 登记认购 (POST)

### Request

ENDPOINT /integralization/integralization_process/ INTEGRALIZATION-KEY /subscription
MÉTODO POST

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
| ----------------------- | ------ | ------------------------------------------- | ---------- |
| `INTEGRALIZATION-KEY` | string | 认缴的唯一键（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

| 字段 | 类型 | 描述 |
| ------------------------------------------------------------ | ------- | ------------------------------------------------------- |
| `investor_key`*                                            | string  | 投资人的唯一键（UUID v4）。 |
| `investor_bank_account`*                                   | object  | 投资人银行账户数据。 |
| `investor_bank_account.account_number`*                    | string  | 投资人银行账户号码。 |
| `investor_bank_account.account_digit`*                     | string  | 投资人银行账户校验位。 |
| `investor_bank_account.account_branch`*                    | string  | 投资人银行支行。 |
| `investor_bank_account.financial_institution_code_number`* | string  | 投资人金融机构代码。 |
| `investor_bank_account.financial_institution_ispb`*        | string  | 投资人金融机构 ISPB。 |
| `subscripted_quantity`*                                    | integer | 投资人希望认购的股份数量。 |
| `financial_base_date`*                                     | string  | 财务基准日期。 |
| `subscription_date`*                                       | string  | 认购日期。 |
| `subscription_note_template_key`*                          | string  | 认购公告模板。 |

---

### 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": []
}
```

### **Response Body Params**

| 字段 | 类型 | 描述 |
| ---------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `subscription_key`               | string  | 认购的唯一键（UUID v4）。 |
| `investor_key`                   | string  | 与认购关联的投资人唯一键（UUID v4）。 |
| `investor_name`                  | string  | 投资人名称。 |
| `investor_document_number`       | string  | 投资人证件号码（CPF 或 CNPJ）。 |
| `investor_bank_account`          | object  | **[investor_bank_account 对象](#objeto-investor_bank_account)**。 |
| `subscription_date`              | string  | 认购日期（格式：YYYY-MM-DD）。 |
| `financial_base_date`            | string  | 认购财务基准日期（格式：YYYY-MM-DD）。 |
| `subscripted_quantity`           | integer | 已认购的股份数量。 |
| `unit_price`                     | number  | 已认购股份的单价。 |
| `expected_amount`                | number  | 认购预期总金额。 |
| `paid_amount`                    | number  | 认购已支付总金额。 |
| `subscription_note_template_key` | string  | 认购公告模板的唯一键（UUID v4）。 |
| `subscription_note_document_key` | string  | 认购公告文件的唯一键。 |
| `envelope_signature_status`      | string  | 认购公告签名状态。 |
| `envelope_signature_url`         | string  | 认购公告签名 URL。 |
| `envelope_key`                   | string  | 签名信封键。 |
| `subscription_payment_list`      | array   | 与认购关联的付款列表。**[subscription_payment_list 对象](#objeto-subscription_payment_list)**。 |

---

### investor_bank_account 对象

| 字段 | 类型 | 描述 |
| ------------------------------------- | ------ | ----------------------------------------------------- |
| `account_number`                    | string | 投资人银行账户号码。 |
| `account_digit`                     | string | 投资人银行账户校验位。 |
| `account_branch`                    | string | 投资人银行支行。 |
| `financial_institution_code_number` | string | 投资人金融机构代码。 |
| `financial_institution_ispb`        | string | 投资人金融机构 ISPB。 |

### subscription_payment_list 对象

| 字段 | 类型 | 描述 |
| -------------------------------- | ------ | -------------------------------------------------------------------------------------------- |
| `subscription_payment_key`     | string | 认购付款的唯一键（UUID v4）。 |
| `payment_receipt_document_key` | string | 付款凭证文件键。 |
| `description`                  | string | 付款凭证说明。 |
| `amount`                       | number | 已登记的付款金额。 |
| `subscription_payment_status`  | string | 付款状态。可能的值：`waiting_confirmation`、`confirmed`、`denied`。 |
| `updated_at`                   | string | 付款最后更新日期和时间（格式：ISO 8601）。 |

---

# 取消认购

URL: /zh-Hans/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/cancelar-subscricao

---

### Request
ENDPOINT /integralization/integralization_process/ INTEGRALIZATION-KEY /subscription/ SUBSCRIPTION-KEY
MÉTODO PATCH

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
|------------------|--------|------------------------------------------------------|------------|
| `INTEGRALIZATION-KEY`  | string | 认缴流程的唯一键（UUID v4）。 | 36 |
| `SUBSCRIPTION-KEY`  | string | 认购的唯一键（UUID v4）。 | 36 |

---

### Request Body

```json
{
  "subscription_status": "canceled"
}
```
### Request Body Params

| 字段 | 类型 | 描述 | 必填 |
|-------------------|----------|-----------------------------------------|-------------|
| `subscription_status` | string   | 接受值：`canceled`。 | 是 |

---

### Response

STATUS 200

将返回已更新的认购实例。

---

---

# 确认或拒绝认购付款

URL: /zh-Hans/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/confirmacao-pagamento

此端点允许确认或拒绝与认缴认购关联的付款。付款状态将根据请求体中提供的值进行更新。

---

## 更新付款状态 (PATCH)

### Request

ENDPOINT /integralization_integralization_process/ INTEGRALIZATION-KEY /subscription/ SUBSCRIPTION-KEY /subscription_payment/ SUBSCRIPTION-PAYMENT-KEY
MÉTODO PATCH

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
| ---------------------------- | ------ | ---------------------------------------------------- | ---------- |
| `INTEGRALIZATION-KEY`      | string | 认缴的唯一键（UUID v4）。 | 36 |
| `SUBSCRIPTION-KEY`         | string | 关联认购的唯一键（UUID v4）。 | 36 |
| `SUBSCRIPTION-PAYMENT-KEY` | string | 认购付款的唯一键（UUID v4）。 | 36 |

---

### Request Body

```json
{
  "subscription_payment_status": "confirmed"
}
```

### Request Body Params

| 字段 | 类型 | 描述 | 必填 |
| -------------------------------- | ------ | ------------------------------------------------------------------------- | ------------ |
| `subscription_payment_status`* | string | 新付款状态。可能的值：`confirmed` 或 `denied`。 | 是 |

---

### 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

| 字段 | 类型 | 描述 |
| ------------------------------- | ------ | ------------------------------------------------------------------------------------------------------ |
| `subscription_payment_key`    | string | 认购付款的唯一键（UUID v4）。 |
| `amount`                      | number | 已登记付款的申报金额。 |
| `description`                 | number | 收据内容说明。 |
| `subscription_payment_status` | string | 已更新的付款状态。可能的值：`waiting_confirmation`、`confirmed`、`denied`。 |
| `updated_at`                  | string | 付款状态更新日期和时间（格式：ISO 8601）。 |

---

# 查询认购

URL: /zh-Hans/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/consulta-subscricao-cotas

此端点允许查询进行中的认购。

---

## 查询认购 (GET)

### Request
ENDPOINT /integralization/integralization_process/ INTEGRALIZATION-KEY /subscription/ SUBSCRIPTION-KEY
MÉTODO GET

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
|-----------------------|--------|------------------------------------------|------------|
| `INTEGRALIZATION-KEY` | string | 认缴的唯一键（UUID v4）。 | 36 |
| `SUBSCRIPTION-KEY`    | string | 认购的唯一键（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": []
}
```

---

### **Response Body Params**

| 字段 | 类型 | 描述 |
|-----------------------------------------------------------|------------|---------------------------------------------------------------------------|
| `subscription_key`                                        | string     | 认购的唯一键（UUID v4）。 |
| `investor_key`                                            | string     | 与认购关联的投资人唯一键（UUID v4）。 |
| `investor_name`                                           | string     | 投资人名称。 |
| `investor_document_number`                                | string     | 投资人证件号码（CPF 或 CNPJ）。 |
| `investor_bank_account`                                   | object     | **[investor_bank_account 对象](#objeto-investor_bank_account)**。 |
| `subscription_date`                                       | string     | 认购日期（格式：YYYY-MM-DD）。 |
| `financial_base_date`                                     | string     | 认购财务基准日期（格式：YYYY-MM-DD）。 |
| `subscripted_quantity`                                    | integer    | 已认购的股份数量。 |
| `unit_price`                                              | number     | 已认购股份的单价。 |
| `expected_amount`                                         | number     | 认购预期总金额。 |
| `paid_amount`                                             | number     | 认购已支付总金额。 |
| `subscription_note_template_key`                          | string     | 认购公告模板的唯一键（UUID v4）。 |
| `subscription_note_document_key`                          | string     | 认购公告文件的唯一键。 |
| `envelope_signature_status`                               | string     | 认购公告签名状态。 |
| `envelope_signature_url`                                  | string     | 认购公告签名 URL。 |
| `envelope_key`                                            | string     | 签名信封键。 |
| `subscription_payment_list`                               | array      | 与认购关联的付款列表。**[subscription_payment_list 对象](#objeto-subscription_payment_list)**。 |

---

### investor_bank_account 对象

| 字段 | 类型 | 描述 |
|--------------------------------|------------|---------------------------------------------------------|
| `account_number`              | string     | 投资人银行账户号码。 |
| `account_digit`               | string     | 投资人银行账户校验位。 |
| `account_branch`              | string     | 投资人银行支行。 |
| `financial_institution_code_number` | string | 投资人金融机构代码。 |
| `financial_institution_ispb`   | string     | 投资人金融机构 ISPB。 |

### subscription_payment_list 对象

| 字段 | 类型 | 描述 |
|-----------------------------------------------------------|------------|---------------------------------------------------------------------------|
| `subscription_payment_key`                                | string     | 认购付款的唯一键（UUID v4）。 |
| `payment_receipt_document_key`                            | string     | 付款凭证文件键。 |
| `description`                                             | string     | 付款凭证说明。 |
| `amount`                                                 | number     | 已登记的付款金额。 |
| `subscription_payment_status`                             | string     | 付款状态。可能的值：`waiting_confirmation`、`confirmed`、`denied`。 |
| `updated_at`                                              | string     | 付款最后更新日期和时间（格式：ISO 8601）。 |

---

# 登记认购付款

URL: /zh-Hans/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/registro-de-pagamento

此端点允许登记与认缴认购关联的付款。付款包括申报金额和 Base64 格式的凭证。

---

## 登记付款 (POST)

### Request

ENDPOINT /integralization_integralization_process/ INTEGRALIZATION-KEY /subscription/ SUBSCRIPTION-KEY /subscription_payment
MÉTODO POST

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
| ----------------------- | ------ | ------------------------------------------------- | ---------- |
| `INTEGRALIZATION-KEY` | string | 认缴的唯一键（UUID v4）。 | 36 |
| `SUBSCRIPTION-KEY`    | string | 关联认购的唯一键（UUID v4）。 | 36 |

---

### Request Body

```json
{
  "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0",
  "amount": 100000.00,
  "description": "Comprovante de pagamento Itau R$100.000,00"
}
```

### Request Body Params

| 字段 | 类型 | 描述 | 必填 |
| -------------------- | ------- | ---------------------------------------------- | ------------ |
| `document_base64`* | string  | Base64 编码的付款凭证。 | 是 |
| `amount`*          | number  | 已付款的申报金额。 | 是 |
| `description`      | *number | 凭证内容说明。 | 是 |

---

### 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

| 字段 | 类型 | 描述 |
| ------------------------------- | ------ | ----------------------------------------------------------------------------------------------- |
| `subscription_payment_key`    | string | 认购付款的唯一键（UUID v4）。 |
| `amount`                      | number | 已登记付款的申报金额。 |
| `subscription_payment_status` | string | 当前付款状态。可能的值：`waiting_confirmation`、`confirmed`、`denied`。 |
| `description`                 | number | 凭证内容说明。 |

---

---

# 接收 Webhooks

URL: /zh-Hans/documentation/escrituracao/introducao/autenticacao_webhooks

Webhooks 的签名采用对称密钥加密策略，即 QI CTVM 和集成合作伙伴共享同一密钥。
配置 Webhooks 时，我们将生成一个 Signature Key 并提供给您。QI 系统发出的每个请求都将携带一个 SIGNATURE header，该 header 是用此密钥签名的 JWT。编码使用 HS256 算法。

以下是使用 Python 对签名进行解码的示例：

```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)
```

我们建议集成合作伙伴除了验证签名外，还应验证我们的 IP 地址，因为我们所有请求都来自同一 IP，具体 IP 根据环境而定：

|环境| IP |
|--------|----|
|生产| -  |
|沙盒 | -  |

:::danger 注意！
QI CTVM 的 webhooks 不应以严格方式映射。
我们的 API 返回的 webhook 载荷中可能会包含额外字段。
:::

---

# 商业票据书写

URL: /zh-Hans/documentation/escrituracao/introducao/

本文档旨在描述操作**商业票据**发行所需的流程、端点和数据结构。

注意：如有任何流程疑问，请联系 [suporte.dcm@qitech.com.br](mailto:suporte.dcm@qitech.com.br) 并详细说明您的问题/疑问，我们将为您提供协助。

## 环境（Hosts）

QI CTVM 拥有两个环境：沙盒和生产。两个环境具有完全相同的代码和行为，但沙盒环境的货币金额完全为虚构数据，而生产环境则进行有效的金融交易。

沙盒环境专为开发人员进行集成测试而创建，准备好上线生产时，只需更新生产环境变量参数即可。

| 环境 | Host |
|----------|----------------------------------------------|
| 沙盒 | https://api.sandbox.securities.qidtvm.com.br |
| 生产 | https://api.securities.qidtvm.com.br |

---

# 测试端点

URL: /zh-Hans/documentation/escrituracao/introducao/teste-autenticacao/endpoints_de_teste

## GET 方法

### Request

ENDPOINT /authentication_test
MÉTODO GET

### Response

STATUS 200

Response Body

```json
{
  "success": "Congrats!"
}
```

## 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!"
}

```

---

# 认证测试

URL: /zh-Hans/documentation/escrituracao/introducao/teste-autenticacao/teste_de_autenticacao

### 1. 介绍

本节将说明请求应如何构建才能被我们的系统接受。
首先，在 header 中 API-CLIENT-KEY 字段填入 QI CTVM 团队提供的 Api Key。
然后，需要使用集成合作伙伴的私钥创建一个 AUTHORIZATION header 进行签名；

以下将使用 Python 逐步演示 AUTHORIZATION 的创建过程。

### 2. 导入库
此 Python 示例使用 5 个库来完成认证过程。

```python
from datetime import datetime
import json
from jose import jwt
from hashlib import md5
import requests
```

### 3. 插入私钥和集成密钥
```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. 定义变量
定义每个请求特有的方法、端点和内容变量（本示例使用 "POST" 方法访问端点 "/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. 构建签名基础字典
```python title="Dicionário base"

dict_to_sign = {"timestamp": today_str, "method": method, "uri": endpoint}

```

#### 5.1. 如有必要，添加内容
对于有 _body_ 的请求，需要添加该内容的 md5 字节值。由于我们系统中所有请求均通过 JSON 格式传输，
可以使用以下方式：

```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. 对 header 进行加密
使用 JWT 库进行加密（此代码示例中，我们在 javascript 中使用 jsonwebtoken 作为 jwt）

```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. 组装最终 header

```python
headers = {"API-CLIENT-KEY": api_key, "AUTHORIZATION": encoded_header_token}
```

```python title="Definindo url final"
url = f"{base_url}{endpoint}"
```

### 发起请求

```python
resp = requests.post(url=url, headers=headers, json=body)
print(resp.json())
```

---

# 密钥交换

URL: /zh-Hans/documentation/escrituracao/introducao/troca_de_chaves

## 1. 签名请求

我们 API 的所有请求必须使用 **HTTPs** 协议，采用 **TLS 1.2 或 1.3**，并包含两个 Header：

1. API-CLIENT-KEY：由我们的集成团队提供的密钥，用于标识特定集成；
2. AUTHORIZATION：请求签名，按本手册说明的方式执行；

QI CTVM 标准采用非对称密钥，包含两个不同的密钥：用于签名的 私钥 和用于读取的 公钥 。集成合作伙伴需使用 JWT 标准通过私钥进行签名。
集成合作伙伴负责生成密钥对，并将公钥提供给 QI CTVM 团队，以便我们验证您的请求。

:::caution **注意**
 私钥专供集成合作伙伴使用，必须妥善保管。QI CTVM 在任何情况下都不会要求您与我们共享私钥。
:::

## 2. 生成密钥对

要在 UNIX 计算机上生成私钥，执行以下命令：

```bash
$ ssh-keygen -t ecdsa -b 521 -m PEM -f private.key
```

并从此私钥生成公钥。

```bash
$ openssl ec -in private.key -pubout -outform PEM -out public.key.pub
```

生成的公钥文件（public.key.pub）需发送给 QI Tech 团队，并等待集成配置完成。

---

# 查询资产

URL: /zh-Hans/documentation/escrituracao/operacoes-ativas/consulta-security

此端点允许使用唯一键查询资产的详情。

---

## **Request**
ENDPOINT /security/security/ SECURITY-KEY
MÉTODO GET

### **Path Params**

| 字段 | 类型 | 描述 | 字符数 |
|--------------|--------|-----------------------------------------------|------------|
| `SECURITY-KEY` | string | 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": {},
    "investment_list": []
}
```

## **Response Body Params**

| 字段 | 类型 | 描述 |
|------------------------------|----------|--------------------------------------------------------------|
| `tenant_key`                 | string   | 与 security 关联的租户唯一键。 |
| `security_key`               | string   | security 的唯一键。 |
| `operation_key`              | string   | 与 security 关联的操作唯一键。 |
| `operation_type`             | string   | 操作类型。可能的值：`commercial_paper`。 |
| `contract_number`            | string   | 与 security 关联的合同编号。 |
| `issuer_key`                 | string   | 关联发行人的唯一键。 |
| `issuer_name`                | string   | security 发行人名称。 |
| `issuer_document_number`     | string   | 发行人证件号码（CPF/CNPJ）。 |
| `issuer_bank_account`        | object   | **[issuer_bank_account 对象](#objeto-bank_account)**。 |
| `financial_base_date`        | string   | security 的财务基准日期。 |
| `current_unit_price`         | number   | security 的当前单价。 |
| `latest_accrual_date`        | string   | 最后一次计息日期。 |
| `integralized_quantity`      | integer  | 已认缴的总股份数量。 |
| `issue_quantity`             | integer  | 操作中发行的总股份数量。 |
| `security_status`            | string   | security 状态。可能的值：`active`、`inactive`。 |
| `is_defaulted`              | boolean  | 指示 security 是否违约（`true` 或 `false`）。 |
| `financial`                  | object   | **[financial 对象](#objeto-financial)**。 |
| `investment_list`            | array    | 投资列表。**[investment 对象](#objeto-investment)**。 |

---

### **bank_account 对象**

| 字段 | 类型 | 描述 |
|--------------------------------|----------|-------------------------------------------------|
| `account_number`              | string   | 发行人银行账户号码。 |
| `account_digit`               | string   | 发行人银行账户校验位。 |
| `account_branch`              | string   | 发行人银行支行。 |
| `financial_institution_ispb`  | string   | 发行人金融机构 ISPB。 |
| `financial_institution_code_number` | string | 发行人金融机构代码。 |

---

### **financial 对象**

| 字段 | 类型 | 描述 |
|--------------------------------|----------|-------------------------------------------------|
| `financial_base_date`          | string   | 财务基准日期。 |
| `issue_quantity`               | integer  | 已发行股份数量。 |
| `unit_price`                   | number   | 每股单价。 |
| `issue_amount`                 | number   | 发行总金额。 |
| `released_amount`              | number   | 已释放总金额。 |
| `cet`                          | number   | 总有效成本（CET）。 |
| `annual_cet`                   | number   | 年化总有效成本。 |
| `number_of_installments`       | integer  | 总分期数。 |
| `prefixed_interest_rate`       | object   | **[prefixed_interest_rate 对象](#objeto-prefixed_interest_rate)**。 |
| `post_fixed_interest_rate`     | object   | **[post_fixed_interest_rate 对象](#objeto-post_fixed_interest_rate)**。 |
| `financial_index`              | object   | **[financial_index 对象](#objeto-financial_index)**。 |
| `fine_delay_rate`              | object   | **[fine_delay_rate 对象](#objeto-fine_delay_rate)**。 |
| `contract_fine_rate`           | number   | 违约罚款。 |
| `fees`                         | array    | 费用列表。**[fees 对象](#objeto-fees)**。 |
| `installment_list`             | array    | 分期列表。**[installment 对象](#objeto-installment)**。 |

---

### **investment 对象**

| 字段 | 类型 | 描述 |
|--------------------------------|----------|-------------------------------------------------|
| `investment_key`               | string   | 投资的唯一键。 |
| `acquisition_date`             | string   | 投资获取日期。 |
| `acquisition_unit_price`       | number   | 获取时的单价。 |
| `acquisition_amount`           | number   | 获取总金额。 |
| `acquisition_quantity`         | integer  | 已获取股份数量。 |
| `investor_key`                 | string   | 投资人的唯一键。 |
| `investor_name`                | string   | 投资人名称。 |
| `investor_document_number`     | string   | 投资人证件（CPF/CNPJ）。 |
| `investor_bank_account`        | object   | **[investor_bank_account 对象](#objeto-bank_account)**。 |
| `total_sell_amount`            | number   | 已实现销售总金额。 |
| `total_yield_amount`           | number   | 总收益金额。 |
| `total_amortization_amount`    | number   | 总摊销金额。 |
| `current_quantity`             | integer  | 当前股份数量。 |
| `investment_transaction_list`  | array    | 交易列表。**[investment_transaction 对象](#objeto-investment_transaction)**。 |

---

### **investment_transaction 对象**

| 字段 | 类型 | 描述 |
|--------------------------------|----------|-------------------------------------------------|
| `transaction_type`             | string   | 交易类型（`integralization`、`maturity`）。 |
| `transaction_date`             | string   | 交易日期。 |
| `transaction_unit_price`       | number   | 交易时的单价。 |
| `transaction_amount`           | number   | 交易总金额。 |
| `transaction_quantity`         | integer  | 已交易股份数量。 |
| `amortization_amount`          | number   | 交易中的摊销金额。 |
| `yield_amount`                 | number   | 交易中的收益金额。 |
| `old_quantity`                 | integer  | 交易前的股份数量。 |
| `new_quantity`                 | integer  | 交易后的股份数量。 |
| `investment_transaction_origin`| string   | 交易来源（`subscription`、`settlement_process_payment`）。 |
| `investment_transaction_origin_key` | string | 交易来源键。 |

### **prefixed_interest_rate 对象**

| 字段 | 类型 | 描述 |
|---------------------|--------|--------------------------------------------------|
| `daily_rate`       | number | 固定日利率。 |
| `annual_rate`      | number | 固定年利率。 |
| `monthly_rate`     | number | 固定月利率。 |
| `interest_base`    | string | 利息计算基础（`calendar_days_365`）。 |

---

### **post_fixed_interest_rate 对象**

| 字段 | 类型 | 描述 |
|---------------------|--------|---------------------------------------------------|
| `daily_rate`       | number | 浮动日利率。 |
| `annual_rate`      | number | 浮动年利率。 |
| `monthly_rate`     | number | 浮动月利率。 |
| `interest_base`    | string | 利息计算基础（`calendar_days_365`）。 |

---

### **financial_index 对象**

| 字段 | 类型 | 描述 |
|------------------|--------|-------------------------------------------------|
| `index_type`    | string | 金融指数类型（`CDI`、`IPCA` 等）。 |
| `index_value`   | number | 金融指数值。 |

---

### **fine_delay_rate 对象**

| 字段 | 类型 | 描述 |
|---------------------|--------|------------------------------------------------|
| `daily_rate`       | number | 逾期付款日利率。 |
| `annual_rate`      | number | 逾期付款年利率。 |
| `monthly_rate`     | number | 逾期付款月利率。 |
| `interest_base`    | string | 利息计算基础（`calendar_days_365`）。 |

---

### **fees 对象**

| 字段 | 类型 | 描述 |
|-------------|---------|--------------------------------------------|
| `type`      | string  | 费用类型（`internal`、`external`）。 |
| `amount`    | number  | 费率的百分比或绝对值。 |
| `fee_type`  | string  | 费用类型。 |
| `fee_amount`| number  | 已应用费用的货币金额。 |
| `amount_type` | string | 金额类型（`percentage`、`absolute`）。 |

---

### **installment 对象**

| 字段 | 类型 | 描述 |
|----------------------------------------|---------|-----------------------------------------------------------|
| `installment_key`                      | string  | 分期的唯一键。 |
| `installment_status`                   | string  | 分期状态。 |
| `installment_number`                   | integer | 计划中的分期序号。 |
| `workdays`                              | integer | 到期前的工作日数量。 |
| `calendar_days`                         | integer | 到期前的日历日数量。 |
| `principal_amortization_unit_price`     | number  | 本金摊销单价。 |
| `principal_amortization_amount`         | number  | 本金摊销总金额。 |
| `interest_amount`                       | number  | 分期利息总金额。 |
| `interest_amount_unit_price`            | number  | 分期利息单价。 |
| `post_fixed_interest_amount`            | number  | 分期浮动利息总金额。 |
| `post_fixed_interest_amount_unit_price` | number  | 分期浮动利息单价。 |
| `amount`                                | number  | 分期总金额。 |
| `due_principal`                         | number  | 分期前未偿还本金金额。 |
| `due_interest`                          | number  | 分期前未偿还利息金额。 |
| `due_date`                              | string  | 分期到期日。 |
| `has_interest`                          | boolean | 指示分期是否含有利息（`true` 或 `false`）。 |
| `current_unit_price`                    | number  | 分期更新的单价。 |
| `latest_accrual_date`                   | string  | 分期最后计息日期。 |
| `paid_at`                               | string  | 分期付款日期（如适用）。 |
| `paid_amount`                           | number  | 分期已支付总金额（如适用）。 |
| `settlement_process_list`               | array   | 清算流程列表。**[settlement_process 对象](#objeto-settlement_process)** |

### **settlement_process 对象**

| 字段 | 类型 | 描述 |
|-----------------------------------------|---------|--------------------------------------------------------------------------------------------------------------------------|
| `settlement_process_key`                | string  | 清算流程的唯一键。 |
| `installment_key`                        | string  | 与清算关联的分期唯一键。 |
| `due_date`                               | string  | 关联分期的到期日。 |
| `reference_date`                         | string  | 清算参考日期。 |
| `current_integralized_quantity`          | integer | 清算时已认缴的股份数量。 |
| `principal_amortization_amount`          | number  | 本金摊销金额。 |
| `interest_amount`                        | number  | 清算中支付的利息总金额。 |
| `post_fixed_interest_amount`             | number  | 清算中支付的浮动利息金额。 |
| `fine_amount`                            | number  | 已应用罚款金额（如有）。 |
| `total_amount`                           | number  | 清算总金额。 |
| `expected_total_amount`                   | number  | 清算预期总金额。 |
| `paid_amount`                            | number  | 清算中已支付总金额。 |
| `settlement_process_status`              | string  | 清算状态（`waiting_payment`、`paid`、`canceled`）。 |
| `paid_at`                                | string  | 清算付款日期（如适用）。 |
| `settlement_process_payment_list`        | array   | 与清算关联的付款列表。**[settlement_process_payment 对象](#objeto-settlement_process_payment)** |

### **settlement_process_payment 对象**  

| 字段 | 类型 | 描述 |
|---------------------------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------|
| `settlement_process_payment_key`           | string  | 清算流程付款的唯一键。 |
| `investment`                                | object  | 投资信息。**[investment 对象](#objeto-investment)**。 |
| `investment_quantity`                       | integer | 付款中涉及的投资股份数量。 |
| `amount`                                    | number  | 已付款金额。 |
| `paid_at`                                   | string  | 付款日期和时间（ISO 8601 格式）。 |
| `settlement_process_payment_status`        | string  | 付款状态（`waiting_payment`、`paid`、`canceled`）。 |
| `settlement_process_payment_type`          | string  | 付款类型（`manual`）。 |
| `settlement_process_payment_receipt_list`  | array   | 付款收据列表。**[settlement_process_payment_receipt 对象](#objeto-settlement_process_payment_receipt)**。 |

### **settlement_process_payment_receipt 对象**  

| 字段 | 类型 | 描述 |
|---------------------------------------------|--------|-------------------------------------------------------------------|
| `settlement_process_payment_receipt_key`    | string | 清算流程付款收据的唯一键。 |
| `settlement_process_payment_receipt_status` | string | 收据状态（`waiting_confirmation`、`confirmed`、`denied`）。 |
| `amount`                                    | number | 收据金额。 |
| `updated_at`                                | string | 收据最后更新日期和时间（ISO 8601 格式）。 |

### **security_status 枚举**

| 枚举值 | 描述 |
|-----------|------------------------------------------------------|
| `issued`  | security 已发行，但尚未激活。 |
| `active`  | security 已激活且进行中。 |
| `matured` | security 已到期。 |
| `canceled` | security 已取消。 |

### **installment_status 枚举**

| 枚举值 | 描述 |
|-----------------------------|-----------------------------------------------------------------------|
| `created`                   | 分期已创建，但尚未开放付款。 |
| `opened`                    | 分期已开放。 |
| `waiting_payment`           | 分期等待投资人付款。 |
| `paid_partial`              | 分期已部分支付。 |
| `paid`                      | 分期已全额支付。 |
| `paid_early`                | 分期已提前支付。 |
| `overdue`                   | 分期已到期且未支付。 |
| `paid_partial_overdue`      | 分期在到期后已部分支付。 |
| `paid_overdue`              | 分期在到期后已支付。 |
| `canceled`                  | 分期已取消，无需支付。 |
| `unmonitored`               | 分期未被监控付款。 |

---

# 查询投资人持仓

URL: /zh-Hans/documentation/escrituracao/operacoes-ativas/posicao-investidor

此端点允许查询投资人的综合持仓，返回其 security 持有信息。

---

## Request
ENDPOINT /security/investor/ INVESTOR-KEY
MÉTODO GET

### Path Params

| 字段 | 类型 | 描述 | 字符数 |
|--------------|--------|-----------------------------------------------|------------|
| `INVESTOR-KEY` | string | 投资人的唯一键（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

| 字段 | 类型 | 描述 |
|----------------------------|----------|--------------------------------------------------------------------|
| `investor_key`             | string   | 投资人的唯一键。 |
| `investor_name`            | string   | 投资人名称。 |
| `investor_document_number` | string   | 投资人证件号码（CNPJ）。 |
| `total_current_amount`     | number   | 投资人综合总金额。 |
| `investment_list`          | array    | 投资人持有的 security 列表。**[investment 对象](#objeto-investment)** |

### investment 对象

| 字段 | 类型 | 描述 |
|-----------------------|----------|--------------------------------------------------|
| `current_unit_price`  | number   | security 的当前单价。 |
| `current_quantity`    | integer  | 投资人当前持有的 security 数量。 |
| `security_key`        | string   | 关联 security 的唯一键。 |
| `contract_number`     | string   | security 的合同编号。 |
| `investment_key`      | string   | 投资人投资的唯一键。 |
| `current_amount`      | number   | 投资人持仓的当前金额。 |

---

# 商业票据书写集成路线图

URL: /zh-Hans/documentation/escrituracao/roteiro-integracao/roteiro-integracao-padrao

同质化路线图描述了集成合作伙伴在进入生产环境发行商业票据之前，需要在 QI Tech 沙盒环境（测试环境）中测试的所有功能和特性。

本路线图描述了产品所涉及的所有资源和功能。

:::warning 注意
**所有测试必须强制在 QI Tech 沙盒环境（测试环境）中进行。
在沙盒环境中执行的操作均为虚拟金融操作，仅用于 API 功能测试。**
:::

## 书写 API 注册与认证
| 代码 | 步骤 | 描述 | 文档链接 | 前提条件 |
| --- | --- | --- | --- | --- |
| CAB0001* | 公钥交换 | 与平台运营团队（suporte.dcm@qitech.com.br）进行公钥交换 | [文档链接](/documentation/escrituracao/introducao/troca_de_chaves) |  |
| CAB0002* | 调用认证测试 | 从平台团队获取 API 密钥后，完成调用认证测试 | [文档链接](/documentation/escrituracao/introducao/teste-autenticacao/teste_de_autenticacao) <br/><br/> [文档链接](/documentation/escrituracao/introducao/teste-autenticacao/endpoints_de_teste) | CAB0001 |
| CAB0003* | Webhooks 配置 | 配置 QI 发送 webhooks 的 URL。 | [文档链接](/documentation/escrituracao/introducao/autenticacao_webhooks) <br/><br/> [文档链接](/documentation/escrituracao/configuracao-webhooks) <br/><br/> [文档链接](/documentation/escrituracao/webhooks-escrituracao) | CAB0001 和 CAB0002 |

## 发行人同质化

:::warning 注意
**对于发行人同质化流程，如果客户已完成与 QI TECH 出让人登记系统的集成，可以重复使用这些登记，简化书写系统的同质化流程。**
:::

### 通过书写系统在 QI TECH 出让人系统中完成登记的发行人同质化

| 代码 | 步骤 | 描述 | 文档链接 | 前提条件 |
| --- | --- | --- | --- | --- |
| CED1001* | 重用出让人登记 | 使用 CNPJ 重用出让人登记。 | [文档链接](/documentation/escrituracao/homologacao-emissor/solicitacao-acesso) |  
| CED1002* | 已登记发行人列表 | 按 CNPJ、名称筛选的已登记出让人列表 | [文档链接](/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-filtro) |  
| CED1003* | 发行人详情 | 通过 issuer_key 查看已登记发行人的详情 | [文档链接](/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-chave) |  

### 通过书写系统完成登记的发行人同质化

| 代码 | 步骤 | 描述 | 文档链接 | 前提条件 |
| --- | --- | --- | --- | --- |
| CED0001* | 发行人基本登记 | 创建发行人，提交基本登记信息。 | [文档链接](/documentation/escrituracao/homologacao-emissor/cadastro/cadastro-basico) |
| CED0002* | 发行人文件上传和删除 | 上传和删除与已登记发行人关联的文件 | [文档链接](/documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor) <br/><br/> [文档链接](/documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor-remocao) | CED0001 |
| CED0003* | 发行人代表的登记和删除 | 上传和删除与已登记发行人关联的代表 | [文档链接](/documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor) <br/><br/> [文档链接](/documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor-remocao) | CED0001 | 
| CED0004* | 发行人代表文件的上传和删除 | 上传和删除与已登记发行人代表关联的文件 | [文档链接](/documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor) <br/><br/> [文档链接](/documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor-remocao) | CED0001, CED0003 |
| CED0005* | 发行人银行账户的登记和删除 | 登记和删除与已登记发行人关联的银行账户 | [文档链接](/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor) <br/><br/> [文档链接](/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor-remocao) | CED0001 |
| CED0006* | 发行人签署人组的登记和删除 | 登记和删除与已登记发行人关联的签署人组 | [文档链接](/documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor) <br/><br/> [文档链接](/documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor-remocao) | CED0001 |
| CED0007* | 发行人联系信息的登记和删除 | 登记和删除与已登记发行人关联的联系信息 | [文档链接](/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor) <br/><br/> [文档链接](/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor-remocao) | CED0001 |
| CED0008* | 提交发行人分析 | 此端点允许将发行人状态更改为分析中，将其提交到验证流程。 | [文档链接](/documentation/escrituracao/homologacao-emissor/envio-analise/) | CED0001, CED0002, CED0003, CED0004, CED0005, CED0006, CED0007 |
| CED0009* | 修改发行人登记 | 修改发行人以允许编辑 | [文档链接](/documentation/escrituracao/homologacao-emissor/alteracao-cadastro/) | CED0001, CED0002, CED0003, CED0004, CED0005, CED0006, CED0007 |
| CED0010* | 已登记发行人列表 | 按 CNPJ、名称筛选的已登记出让人列表 | [文档链接](/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-filtro) 
| CED0011* | 发行人详情 | 通过 issuer_key 查看已登记发行人的详情 | [文档链接](/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-chave) |  

## 投资人同质化

:::warning 注意
**对于投资人同质化流程，如果客户有固定基金，可以在设置时登记，简化集成。**
:::

### 通过设置完成登记的投资人同质化

| 代码 | 步骤 | 描述 | 文档链接 | 前提条件 |
| --- | --- | --- | --- | --- |
| INV1001* | 已登记投资人列表 | 按 CNPJ、名称筛选的已登记基金列表 | [文档链接](/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-filtro) |  
| INV1002* | 投资人详情 | 通过 investor_key 查看已登记投资人的详情 | [文档链接](/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-chave) |  

### 通过书写系统完成登记的投资人同质化

| 代码 | 步骤 | 描述 | 文档链接 | 前提条件 |
| --- | --- | --- | --- | --- |
| INV0001* | 投资人基本登记 | 创建投资人，提交基本登记信息。 | [文档链接](/documentation/escrituracao/homologacao-investidor/cadastro/cadastro-basico) |
| INV0002* | 投资人文件上传和删除 | 上传和删除与已登记投资人关联的文件 | [文档链接](/documentation/escrituracao/homologacao-investidor/cadastro/documentos-investidor) <br/><br/> [文档链接](/documentation/escrituracao/homologacao-investidor/cadastro/documentos-investidor-remocao) | INV0001 |
| INV0003* | 投资人代表的登记和删除 | 上传和删除与已登记投资人关联的代表 | [文档链接](/documentation/escrituracao/homologacao-investidor/cadastro/representantes-investidor) <br/><br/> [文档链接](/documentation/escrituracao/homologacao-investidor/cadastro/representantes-investidor-remocao) | INV0001 | 
| INV0004* | 投资人代表文件的上传和删除 | 上传和删除与已登记投资人代表关联的文件 | [文档链接](/documentation/escrituracao/homologacao-investidor/cadastro/documentos-representantes-investidor) <br/><br/> [文档链接](/documentation/escrituracao/homologacao-investidor/cadastro/documentos-representantes-investidor-remocao) | INV0001, INV0003 |
| INV0005* | 投资人银行账户的登记和删除 | 登记和删除与已登记投资人关联的银行账户 | [文档链接](/documentation/escrituracao/homologacao-investidor/cadastro/conta-bancaria-investidor) <br/><br/> [文档链接](/documentation/escrituracao/homologacao-investidor/cadastro/conta-bancaria-investidor-remocao) | INV0001 |
| INV0006* | 投资人签署人组的登记和删除 | 登记和删除与已登记投资人关联的签署人组 | [文档链接](/documentation/escrituracao/homologacao-investidor/cadastro/assinantes-investidor) <br/><br/> [文档链接](/documentation/escrituracao/homologacao-investidor/cadastro/assinantes-investidor-remocao) | INV0001 |
| INV0007* | 投资人联系信息的登记和删除 | 登记和删除与已登记投资人关联的联系信息 | [文档链接](/documentation/escrituracao/homologacao-investidor/cadastro/informacao-contato-investidor) <br/><br/> [文档链接](/documentation/escrituracao/homologacao-investidor/cadastro/informacao-contato-investidor-remocao) | INV0001 |
| INV0008* | 提交投资人分析 | 此端点允许将投资人状态更改为分析中，将其提交到验证流程。 | [文档链接](/documentation/escrituracao/homologacao-investidor/envio-analise/) | INV0001, INV0002, INV0003, INV0004, INV0005, INV0006, INV0007 |
| INV0009* | 修改投资人登记 | 修改投资人以允许编辑 | [文档链接](/documentation/escrituracao/homologacao-investidor/alteracao-cadastro/) | INV0001, INV0002, INV0003, INV0004, INV0005, INV0006, INV0007 |
| INV0010* | 已登记投资人列表 | 按 CNPJ、名称筛选的已登记基金列表 | [文档链接](/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-filtro) 
| INV0011* | 投资人详情 | 通过 investor_key 查看已登记投资人的详情 | [文档链接](/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-chave) |  

## 商业票据发行

完成发行人和投资人登记后，即可进行商业票据发行。为此，存在多种发行流程组合，将在下方详细说明。

| 代码 | 步骤 | 描述 | 文档链接 | 前提条件 |
| --- | --- | --- | --- | --- |
| COM0001* | 财务条件模拟 | 模拟操作的财务条件和付款流程 | [文档链接](/documentation/escrituracao/emissao-de-notas/simulacao) |
| COM0002* | 商业票据操作登记 | 根据财务数据和投资人信息创建新的商业票据操作。 | [文档链接](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/criar-operacao) | COM0001 |
| COM0003* | 相关方的登记和删除 | 登记和删除与操作相关的相关方 | [文档链接](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/cadastrar-parte-relacionada) | COM0002 | 
| COM0004* | 相关方代表文件的上传和删除 | 上传和删除与操作相关方代表关联的文件 | [文档链接](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-documento)| COM0002, COM0003 |
| COM0005* | 相关方代表签署人组的上传和删除 | 上传和删除与操作相关方代表关联的签署人组 | [文档链接](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-grupo-assinantes) | COM0002, COM0003 |
| COM0006 | 预览章程协议 | 使用预定义模板为特定操作生成章程协议草稿。 | [文档链接](/documentation/escrituracao/emissao-de-notas/geracao-minutas/gerar-minuta-contrato) | COM0002 |
| COM0007* | 修改章程协议模板 | 修改特定操作的章程协议模板 | [文档链接](/documentation/escrituracao/emissao-de-notas/geracao-minutas/alterar-template-tc) | COM0002 |
| COM0008* | 文件上传 | 上传与操作相关的文件。返回的 "document_key" 可用于担保系统等场景 | [文档链接](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/upload-documento) | COM0002 |
| COM0009* | 操作担保上传 | 添加与操作相关的担保 | [文档链接](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/cadastro-garantia) | COM0002, COM0008 |
| COM0010* | 合同/担保中相关方的登记和删除 | 登记和删除操作中特定合同/担保的相关方 | [文档链接](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-parte-relacionada-em-documento) | COM0002, COM0003 |
| COM0011* | 提交操作分析 | 将操作状态更改为"分析中"，提交到书写方的合规验证流程 | [文档链接](/documentation/escrituracao/emissao-de-notas/envio-para-analise) | COM0002, COM0003, COM0004, COM0005, COM0006, COM0007, COM0008, COM0009 |
| COM0012* | 提交已签署的批准纪要 | 此端点允许向书写系统提交外部签署的 SA 或 COP 类型公司的批准纪要（base64 格式），该纪要将由书写方审核批准。 | [文档链接](/documentation/escrituracao/emissao-de-notas/envio-ata-aprovacao) | COM0002 |
| COM0013* | 按筛选条件查询操作 | 使用可选筛选条件查询商业票据操作 | [文档链接](/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-filtros) | COM0002, COM0003, COM0004, COM0005, COM0006, COM0007, COM0008, COM0009 |
| COM0014* | 按密钥查询操作 | 使用唯一密钥查询特定操作的完整详情。 | [文档链接](/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-chave) | COM0002, COM0003, COM0004, COM0005, COM0006, COM0007, COM0008, COM0009 |

### 通过 QI SIGN 签名的情况

| 代码 | 步骤 | 描述 | 文档链接 | 前提条件 |
| --- | --- | --- | --- | --- |
| COM0015* | 查询操作的 QI SIGN 签名链接 | 使用唯一密钥查询特定操作通过 QI SIGN 签名的所有链接。 | [文档链接](/documentation/escrituracao/emissao-de-notas/consulta-link-assinatura-qisign) | COM0002, COM0003, COM0004, COM0005, COM0006, COM0007, COM0008, COM0009 |
| COM0016* | 查询操作的 QI SIGN 已签署合同链接 | 使用唯一密钥查询特定操作通过 QI SIGN 签署的所有文件 | [文档链接](/documentation/escrituracao/emissao-de-notas/consulta-link-assinado-qisign) | COM0002, COM0003, COM0004, COM0005, COM0006, COM0007, COM0008, COM0009 |

## 整合/认购流程

| 代码 | 步骤 | 描述 | 文档链接 | 前提条件 |
| --- | --- | --- | --- | --- |
| INT0001* | 按密钥查询整合 | 使用唯一密钥查询整合流程的详情 | [文档链接](/documentation/escrituracao/integralizacao-cotas/consulta-processo-integralizacao) |
| INT0002* | 查询认购 | 查询进行中的认购 | [文档链接](/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/consulta-subscricao-cotas) | INT0001 |
| INT0003 | 认购登记 | 登记投资人认购整合中特定数量份额的意向（在需要调整认购日期时有用） | [文档链接](/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/cadastro-subscricao) | INT0001, INT0002 |
| INT0004 | 取消认购 | 取消认购（在需要调整认购日期时有用） | [文档链接](/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/cancelar-subscricao) | INT0001, INT0002 |

## 错误映射

发行人、投资人和商业票据 API 的错误可在 [**错误目录链接**](/documentation/escrituracao/catalogo-erros/catalogo-erros) 中找到

---

# Roteiro de Integração de escrituração de notas comerciais

URL: /zh-Hans/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: /zh-Hans/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

URL: /zh-Hans/documentation/escrituracao/webhooks-escrituracao

## 概述

书写 webhooks 允许您实时接收有关商业票据发行流程中状态变更和重要事件的通知。当事件发生时，QI Tech 会自动向您系统中配置的 URL 发送 HTTP POST 载荷。

## Webhooks 配置

要接收 webhooks，您需要在系统中配置端点 URL。请参阅 [webhooks 配置文档](./introducao/autenticacao_webhooks.md) 了解如何注册和管理您的 webhook URL 的更多详情。

### 认证和安全

QI Tech 发送的所有 webhooks 在 `Signature` header 中包含 HMAC-SHA256 签名。您的系统必须验证此签名，以确保接收数据的真实性和完整性。有关验证流程的更多信息，请参阅 [webhooks 认证文档](./introducao/autenticacao_webhooks.md)。

## 可用事件

### 发行人管理

#### 发行人登记已批准

当发行人的登记被合规团队批准时发送。

**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"
  }
}
```

#### 发行人登记未批准

当发行人的登记被合规团队拒绝时发送。

**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"
  }
}
```

### 投资人管理

#### 投资人登记已批准

当投资人的登记被合规团队批准时发送。

**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"
  }
}
```

#### 投资人登记未批准

当投资人的登记被合规团队拒绝时发送。

**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"
  }
}
```

### 操作管理

#### 操作已批准

当操作被合规团队批准并准备好发送签名时发送。

**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"
  }
}
```

#### 操作已发送签名

当操作被发送给相关方签名时发送。

**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"
  }
}
```

#### 操作已签名并发行

当操作被所有各方签署时发送。此事件确认商业票据已成功发行。

**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"
  }
}
```

#### 操作已取消

当操作被取消时发送。

**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"
  }
}
```

### 认购管理

#### 认购已发送签名

当认购被创建并发送给投资人签名时发送。

**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"
  }
}
```

#### 认购已签名

当认购被所有各方签署并等待付款时发送。

**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"
  }
}
```

#### 认购已完成

当认购在付款确认后完全完成时发送。

**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"
  }
}
```

### 认购付款管理

#### 付款凭证已添加

当付款凭证被添加并等待确认时发送。

**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"
  }
}
```

#### 付款凭证已批准

当付款凭证被批准和确认时发送。

**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"
  }
}
```

## 事件流程

### 商业票据发行流程

1. **发行人登记** → `issuer_status_change`（approved/reproved）
2. **投资人登记** → `investor_status_change`（approved/reproved）
3. **创建操作** → `operation_status_change`（pending_signature_submission）
4. **发送签名** → `operation_status_change`（waiting_signature）
5. **操作发行** → `operation_status_change`（issued）

### 认购流程

1. **创建认购** → `subscription_status_change`（waiting_signature）
2. **签名完成** → `subscription_status_change`（waiting_payment）
3. **添加凭证** → `subscription_payment_status_change`（waiting_confirmation）
4. **付款确认** → `subscription_payment_status_change`（confirmed）
5. **认购完成** → `subscription_status_change`（finished）

## 最佳实践

1. **快速响应**：尽快返回 HTTP 2xx 状态以确认收到 webhook。
2. **异步处理**：对于耗时操作，立即确认接收并异步处理事件。
3. **幂等性**：实现幂等逻辑，因为网络故障时 webhooks 可能会重新发送。
4. **签名验证**：处理 webhook 前务必验证 HMAC 签名。
5. **日志和监控**：保留所有收到的 webhooks 的详细日志，用于审计和调试。

## 参考

- [Webhooks 配置](./introducao/autenticacao_webhooks.md)

---

# Aprovação de Reserva

URL: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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.
:::

### 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.
:::

### 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 (cada um responde solidária e ilimitadamente pelo cumprimento das obrigações). Exibida no **Quadro III-A** + Cláusula 4 da CCB. 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 `guarantors` (recomendado)

Caso o financiamento tenha um ou mais avalistas, informe-os neste array. Cada avalista aparece em uma linha do **Quadro III-A – AVALISTAS** da CCB, e todos respondem solidária e ilimitadamente pelas obrigações descritas na **Cláusula 4** das Condições Gerais.

| 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: /zh-Hans/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: /zh-Hans/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.
:::

---

# 修改人员联系方式

URL: /zh-Hans/documentation/gestao_de_usuarios/alteracao_de_contato_de_pessoa

## 1. 请求令牌

ENDPOINT /person/token_request
方法 POST

### Body Params

| 字段 | 类型 | 描述 |
|---|---|---|
| `contact_type` | string | 联系方式类型：`sms` 或 `email` |
| `person_contact_update` | object | 包含联系方式更新数据的对象 |

### person_contact_update 对象

| 字段 | 类型 | 描述 |
|---|---|---|
| `person_key` | string | 人员的唯一标识符 |
| `phone_number` | string | 新电话号码 |
| `email` | string | 新电子邮件地址 |

---

## 2. 令牌验证

ENDPOINT /person/token_validation
方法 POST

### Body Params

| 字段 | 类型 | 描述 |
|---|---|---|
| `token` | string | 收到的验证令牌 |
| `agent_document_number` | string | 操作员的 CPF |
| `person_contact_update` | object | 包含联系方式更新数据的对象（与请求令牌中相同）|

---

# 修改关联联系方式

URL: /zh-Hans/documentation/gestao_de_usuarios/alteracao_de_contato_de_vinculo

## 1. 请求令牌

ENDPOINT /professional_data/token_request
方法 POST

### Body Params

| 字段 | 类型 | 描述 |
|---|---|---|
| `contact_type` | string | 联系方式类型：`sms` 或 `email` |
| `professional_data_contact_update` | object | 包含联系方式更新数据的对象 |

### professional_data_contact_update 对象

| 字段 | 类型 | 描述 |
|---|---|---|
| `natural_person` | string | 自然人的唯一标识符 |
| `professional_data_key` | string | 职业数据的唯一标识符 |
| `email` | string | 新电子邮件地址 |
| `phone_number` | string | 新电话号码 |

---

## 2. 令牌验证

ENDPOINT /professional_data/token_validation
方法 POST

### Body Params

| 字段 | 类型 | 描述 |
|---|---|---|
| `token` | string | 收到的验证令牌 |
| `professional_data_contact_update` | object | 包含联系方式更新数据的对象（与请求令牌中相同）|

---

# 修改个人数据

URL: /zh-Hans/documentation/gestao_de_usuarios/alteracao_de_dados_pessoais

ENDPOINT /person/PERSON_KEY/personal_data
方法 PATCH

## Body Params

| 字段 | 类型 | 描述 |
|---|---|---|
| `name` | string | 人员姓名 |
| `date_of_birth` | string | 出生日期（格式 "YYYY-MM-DD"）|
| `profession` | string | 职业 |
| `mother_name` | string | 母亲姓名 |
| `father_name` | string | 父亲姓名 |
| `birth_place` | string | 出生地 |
| `spouse_name` | string | 配偶姓名 |
| `is_pep` | boolean | 是否为政治公众人物（PEP）|
| `revenue_amount` | float | 月收入 |
| `onboarding_key` | string | Onboarding 的唯一标识符 |

---

# 修改地址

URL: /zh-Hans/documentation/gestao_de_usuarios/alteracao_de_endereco

ENDPOINT /person/PERSON_KEY/address
方法 PUT

## Body Params

| 字段 | 类型 | 描述 |
|---|---|---|
| `street` | string | 街道名称 |
| `complement` | string | 地址补充信息 |
| `state` | string | 州（两位大写字母）|
| `number` | string | 门牌号 |
| `neighborhood` | string | 社区/街区 |
| `postal_code` | string | 邮政编码（仅数字）|
| `city` | string | 城市 |

---

# 查询关联方

URL: /zh-Hans/documentation/gestao_de_usuarios/consulta_partes_relacionadas

ENDPOINT /account/ACCOUNT_KEY/related_parties
方法 GET

此端点用于查询法人（PJ）账户的关联方。

## 响应字段

| 字段 | 类型 | 描述 |
|---|---|---|
| `allowed_users` | array | 授权用户列表 |
| `legal_person_key` | string | 法人实体的唯一标识符 |
| `owner_document_number` | string | 账户所有人的 CNPJ 或 CPF |
| `owner_name` | string | 账户所有人名称 |

### allowed_users 对象

| 字段 | 类型 | 描述 |
|---|---|---|
| `natural_person_document_number` | string | 自然人的 CPF |
| `natural_person_key` | string | 自然人的唯一标识符 |
| `natural_person_name` | string | 自然人姓名 |
| `professional_data_key` | string | 职业数据的唯一标识符 |

---

# 创建人员

URL: /zh-Hans/documentation/gestao_de_usuarios/criacao_de_pessoa

## 1. 请求令牌

ENDPOINT /person/token_request
方法 POST

## 2. 令牌验证

ENDPOINT /person/token_validation
方法 POST

### person_creation 对象

| 字段 | 类型 | 描述 |
|---|---|---|
| `address` | object | 人员地址 |
| `date_of_birth` | string | 出生日期（格式 "YYYY-MM-DD"）|
| `document_identification_number` | string | 身份证件号码 |
| `email` | string | 电子邮件地址 |
| `document_number` | string | CPF（仅数字）|
| `is_pep` | boolean | 是否为政治公众人物（PEP）|
| `mother_name` | string | 母亲姓名 |
| `name` | string | 人员姓名 |
| `nationality` | string | 国籍 |
| `birth_place` | string | 出生地 |
| `person_type` | string | 人员类型（自然人或法人）|
| `phone_number` | string | 电话号码 |

---

# 删除关联

URL: /zh-Hans/documentation/gestao_de_usuarios/exclusao_de_vinculo

## 1. 请求令牌

ENDPOINT /professional_data/token_request
方法 POST

## 2. 令牌验证

ENDPOINT /professional_data/token_validation
方法 POST

此流程用于删除自然人与法人之间的职业数据关联。

### Body Params

| 字段 | 类型 | 描述 |
|---|---|---|
| `natural_person` | string | 自然人的唯一标识符 |
| `legal_person` | string | 法人实体的唯一标识符 |

---

# 添加关联

URL: /zh-Hans/documentation/gestao_de_usuarios/inclusao_de_vinculo

## 1. 请求令牌

ENDPOINT /professional_data/token_request
方法 POST

## 2. 令牌验证

ENDPOINT /professional_data/token_validation
方法 POST

此流程用于在自然人与法人之间创建职业数据关联，包括角色和产品权限。

### Body Params

| 字段 | 类型 | 描述 |
|---|---|---|
| `natural_person` | string | 自然人的唯一标识符 |
| `legal_person` | string | 法人实体的唯一标识符 |
| `natural_person_roles` | array | 角色列表 |
| `post_type` | string | 职位类型 |

### natural_person_roles 对象

| 字段 | 类型 | 描述 |
|---|---|---|
| `product_type` | string | 产品类型 |
| `role_type` | string | 角色类型 |

---

# 双因素授权（TFA）简介

URL: /zh-Hans/documentation/gestao_de_usuarios/tfa_introducao

双因素授权（TFA）系统用于验证敏感操作。该流程分为两个步骤：

## 流程

1. **令牌请求（token_request）**：系统向用户发送验证令牌（通过 SMS 或 email）。
2. **令牌验证（token_validation）**：用户提交收到的令牌以确认操作。

:::info Sandbox 环境

在 Sandbox 环境中，验证令牌始终为 **`329329`**。

:::

---

# Consulta Offline de Saldo

URL: /zh-Hans/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"
}
```

---

# INSS 工资贷款

URL: /zh-Hans/documentation/guides/INSS/intro

面向 INSS 受益人的工资贷款操作集成指南。

## 操作

### 新信贷和纯再融资

- **[完整流程](/documentation/guides/INSS/new-credit-and-refinancing/end-to-end)** — 从预约到结算的新信贷或纯再融资操作分步指南。
- **[重新计算](/documentation/guides/INSS/new-credit-and-refinancing/recalculate)** — 如何重新计算现有操作的分期付款和利率。

### 携号转网 + 再融资

- **[完整流程](/documentation/guides/INSS/portability+refinancing/end-to-end)** — 携号转网与再融资的分步指南，包括债务查询和背书。

## 查询

- **[离线余额查询](/documentation/guides/INSS/inquiries/offline-balance-request)** — 向 INSS 异步查询受益人的余额和额度。

## 预约

- **[优先队列](/documentation/guides/INSS/reservations/priority-reservation)** — 将预约标记为 `fixed_rate` 以优先处理。
- **[插队请求](/documentation/guides/INSS/reservations/priority-request)** — 使用令牌桶的同步请求，用于立即处理。

## 签名

- **[批量签名](/documentation/guides/INSS/signatures/batch-signature)** — 将多个操作合并为 QI Sign 中的单个签名信封。

---

# Mocks (Sandbox)

URL: /zh-Hans/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

---

# INSS 手册 - 新增信贷或再融资

URL: /zh-Hans/documentation/guides/INSS/new-credit-and-refinancing/end-to-end

:::info 另请参阅
- [转入移植 + 再融资](/documentation/manual_inss/fluxo_completo_portabilidade_refin)
:::

:::danger 注意！
QI Tech 的 webhook 不应以严格方式映射。
返回的 webhook payload 中可能会添加额外字段。
:::

:::info Webhook 重发
您可以按照文档中的详细说明查询并重发 webhook：[Webhook 重发](/documentation/notificacoes/reenvio_de_notificacoes)。
:::

:::info 授权条款有效期
授权条款自签署之日起有效期为 30 天。在有效期内，可以在无需重新发送客户授权的情况下查询福利数据。
:::

## 1 - 通过合作方完成授权条款后查询福利列表：

### Request

情形 1：福利持有人即为授权条款的签署人。

ENDPOINT /social_security/benefits_request
MÉTODO POST

在 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"
			}
		}
	}
}
```

情形 2：福利持有人不是授权条款的签署人（有法定代表人）。

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 注意
在有法定代表人的情况下，需要在 **"legal_representative_document_number"** 字段中填写法定代表人的 CPF，且 **"signer"** 对象中的数据也应填写法定代表人的信息。
:::

--- 

"***document_key***"：使用 /upload 端点返回的 GUID。

除了在 "authorization_term.signed_object.document_key" 对象中使用已签署 PDF 文档的密钥外，也可以通过 "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"
}
```

福利列表查询成功时：

### 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"
	}]
}
```

| 字段                      | 描述                                | 值                                       |
|---------------------------|-------------------------------------|------------------------------------------|
| benefit_status            | 福利状态                            | [枚举值](#benefit_status_enumerator) |

福利列表查询失败时

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"
	}
}
```

### 失败 webhook 字段详解

| 字段                      | 描述                                | 值                                       |
|---------------------------|-------------------------------------|------------------------------------------|
| enumerator                | Dataprev 代码的映射返回值           | [枚举值](#dataprev_benefits_errors_enumerators) |

### 在 Sandbox 中模拟福利查询的成功与失败场景：
场景模拟基于操作中提供的 CPF 的第一位数字。

**11.1.** 对于以数字 1 开头的 CPF，将通过 Webhook 返回异步成功响应。

**11.2.** 对于其他 CPF，将根据输入的 CPF 的第一位数字，按照下表返回异步错误响应。

| CPF 首位数字 | 枚举值                 | 描述                 |
|--------------|------------------------|----------------------|
| 2            | inexistent_beneficiary | no beneficiary found |

:::caution 注意
所有第一位数字未映射到对应场景的 CPF，将收到一个包含未映射测试场景标准错误的 webhook。

| 枚举值        | 描述                                                             |
|---------------|------------------------------------------------------------------|
| mock_error    | Informed document number is not a valid mock on test environment |
:::

---

## 2 - 查询福利数据：{#consulta-de-dados}

### 情形 1

使用已提交的授权条款查询福利数据。

#### Request

ENDPOINT /social_security/balance_request
MÉTODO POST

在 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"
}
```

### 情形 2

提交授权条款时查询福利数据。

#### 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 授权条款有效期
授权条款自签署之日起有效期为 30 天。在有效期内，可以在无需重新发送客户授权的情况下查询福利数据。如果尚未发送授权，则需要在此请求中发送条款。
:::

:::caution 注意
在有法定代表人的情况下，需要在 **"legal_representative_document_number"** 字段中填写法定代表人的 CPF，且 **"signer"** 对象中的数据也应填写法定代表人的信息。
:::

--- 

#### 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

福利数据查询成功时

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
        }
}
```

#### 成功 webhook 字段详解

| 字段                        | 描述                                                                                                                         | 值                                            |
|-----------------------------|------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------|
| assistance_type             | 福利类型                                                                                                                     | [枚举值](#benefit_type_enumerator)            |
| benefit_status              | 福利状态                                                                                                                     | [枚举值](#benefit_status_enumerator)          |
| has_entity_representation   | 是否有代理实体（不允许批注）                                                                                                  | True 或 False                                 |
| alimony_code                | 赡养费分类                                                                                                                   | not_payer, payer, benefit                     |
| has_judicial_concession     | 福利是否通过临时禁令批准                                                                                                      | True 或 False                                 |
| has_power_of_attorney       | 是否有代理人？                                                                                                               | True 或 False                                 |
| credit_type                 | 信贷类型 - 福利收款方式                                                                                                      | Magnetic_card, checking_account               |
| benefit_situation           | 福利状态                                                                                                                     | [枚举值](#benefit_situation_enumerator)       |
| used_total_balance          | 已用于贷款批注、保留用于可携性、再融资、变更、RMC 和 RCC 的总金额                                                            | 数值                                          |
| max_total_balance           | 对应福利种类可承诺的金额                                                                                                     | 数值                                          |
| available_total_balance     | 所有方式下可用于贷款的总金额（max_total_balance 与 used_total_balance 的差值）                                               | 数值                                          |
| benefit_quota_expiration_date | 福利终止日期。该信息仅适用于部分遗属抚恤金福利。                                                                           | 字符串或空值
| block_type                  | 福利锁定类型                                                                                                                 | [枚举值](#block_type_enumerator)
| politically_exposed.type    | 政治敏感人士                                                                                                                 | [枚举值](#politically_exposed_enumerator)
| is_politically_exposed      | 是否为政治敏感人士                                                                                                           | True 或 False

### 锁定 webhook

福利被锁定时

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"
    }
}
```

#### 锁定 webhook 字段详解

| 字段                      | 描述                  | 值                                       |
|---------------------------|-----------------------|------------------------------------------|
| benefit_blocked           | 锁定状态              | True |
| balance_request_date      | 查询日期              | 字符串 |
| block_date                | 锁定日期              | 字符串或空值 |
| block_type                | 锁定类型              | [枚举值](#block_type_enumerator) |

### 失败 webhook

福利列表查询失败时

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"
	}
}
```

#### 失败 webhook 字段详解

| 字段                      | 描述                                | 值                                       |
|---------------------------|-------------------------------------|------------------------------------------|
| enumerator                | Dataprev 代码的映射返回值           | [枚举值](#dataprev_balance_errors_enumerators) |

### 在 Sandbox 中模拟福利查询的成功与失败场景：
场景模拟基于操作中提供的 CPF 的第一位数字。

**11.1.** 对于以数字 1 开头的 CPF，将通过 Webhook 返回异步成功响应。

**11.2.** 对于其他 CPF，将根据输入的 CPF 的第一位数字，按照下表返回异步错误响应。

| CPF 首位数字 | 枚举值                 | 描述                 |
|--------------|------------------------|----------------------|
| 2            | inexistent_beneficiary | no beneficiary found |

:::caution 注意
所有第一位数字未映射到对应场景的 CPF，将收到一个包含未映射测试场景标准错误的 webhook。

| 枚举值        | 描述                                                             |
|---------------|------------------------------------------------------------------|
| mock_error    | Informed document number is not a valid mock on test environment |
:::

---

## 3 - 债务模拟：

### 新增信贷 Request

ENDPOINT /debt_simulation
MÉTODO POST

在 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": "social_security"
        }
    ]
}
```

**放款金额**

```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

ENDPOINT /debt_simulation
MÉTODO POST

**分期金额**

```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"
        }
    ]
}
```
  

**放款金额**

```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
上述请求中包含 2 次模拟。第一次固定客户的分期金额（放款金额可变），第二次固定放款金额（分期金额可变）。
::: 

### 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
                }
            }
        ]
    }
}
```

---
## 4 - 发行操作：
:::caution 注意
对于自福利发放日起未满 90 天且不允许批注的操作，需确保 disbursement_date 与 limit_days_to_disburse 之和所得日期晚于 90 天之后。
如果不满足此规则，操作将被永久取消，CancelReason 为：social_security_margin_release_after_disbursement_end_date。
:::
"collateral_data" 对象中的 "assistance_type" 字段指贷款所使用的福利类型，该值在福利数据查询中返回。查看可能的值（枚举值），请参阅[枚举值表](#benefit_type_enumerator)。

:::warning 注意
`credit_agent` 对象代表信贷代理人，有时称为推销员，负责发起此债务。此字段在发行代扣贷款债务时为必填项。
:::

### Request

情形 1：无法定代表人的发行

ENDPOINT /debt
MÉTODO POST

在 Playground 中测试

**新增信贷**

```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
        }
    ]
}
  ```
**再融资**

```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"
        }
    ]
}

  ```

**新增信贷 - 薪资增长**

```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
        }
    ]
}

  ```

情形 2：有法定代表人的发行

ENDPOINT /debt
MÉTODO POST

**新增信贷**

```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
        }
    ]
}
```
**再融资**

```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"
        }
    ]
}
```
**新增信贷 - 薪资增长**

```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"
        }
    ]
}
```

含折扣的 financial 对象示例

```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

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"
                }
            }
        ]
    }
} 
```

如果操作在最后一个放款日期选项前未签署或批注，合作方将收到有关操作取消的 webhook：

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"
}
```

### 在 Sandbox 中模拟批注成功与失败场景：
场景模拟基于操作中提供的 CPF 的第一位数字。

**11.1.** 对于以数字 1 开头的 CPF，将通过 Webhook 返回异步成功响应。

**11.2.** 对于其他 CPF，将根据输入的 CPF 的第一位数字，按照下表返回异步错误响应。

**11.3.** 操作为 "cancel" 的错误将收到包含操作最终结果的 webhook。

| CPF 首位数字 | 枚举值                       | 描述                                                                              | 操作   |
|--------------|------------------------------|-----------------------------------------------------------------------------------|--------|
| 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 注意
所有第一位数字未映射到对应场景的 CPF，将收到一个包含未映射测试场景标准错误的 webhook。

| 枚举值        | 描述                                                             |
|---------------|------------------------------------------------------------------|
| mock_error    | Informed document number is not a valid mock on test environment |
:::

## 5 - 文件提交

必须提交合同补充数据（根据 INSS 第 138 号规范性指令）。

文件应通过[文件上传端点](../upload_de_documentos)提交，并遵循以下格式规范：

| 验证项       | 值           |
|--------------|--------------|
| 格式         | JPEG         |
| 最小尺寸     | 250 x 250 px |
| 最大尺寸     |     2 MB     |

:::caution 注意
不符合最小或最大尺寸规定的关联文件的合同将被永久取消。
:::

文件上传后，必须在操作创建的 payload 中或之后通过以下端点提供已提交文件的密钥：

ENDPOINT /debt/ DEBT-KEY /related_party/ RELATED-PARTY-KEY /attached_document
MÉTODO POST

在 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 信息
**related_party_key** 在债务创建的响应中，位于 **borrower** 对象内返回。
:::

## 6 - 操作正式化

文件提交后，操作可以进行正式化。

若由法定代表人签署，在 "**data.contract.signers[i]**" 字段中将返回法定代表人的数据，且 "**data.contract.signers[i].signer_role**" 对象的值将为 "**issuer_legal_representative**"。

**签署 payload 中必须包含与第 5 条中提交文件相关的必填字段。必填字段如下：_ip_address_ 和 _signature_datetime_。**

### Request

ENDPOINT /debt/ DEBT-KEY /signed
MÉTODO POST

在 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 注意
签署提交的 payload 因合作方的正式化流程而异，需与 QI Tech 集成团队对接确认。
:::

#### _Biometry Analysis Reference_ 枚举值
| 枚举值        | 描述                                                                                                                                                                                                                                                               |
|---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **serpro**    | 当 similarity_score 通过查询 Detran 带照片文件库（通过 Serpro 提供的服务）获得时使用                                                                                                                                                                               |
| **tse**       | 当 similarity_score 通过查询 TSE 带照片文件库获得时使用                                                                                                                                                                                                           |
| **not_found** | 当面部生物识别在上述任何政府数据库（serpro 或 tse）中均未找到时填写。此时 similarity_score 应为 null 或合作方返回的自拍与带照片官方文件的相似度评分。 |

:::danger QI Sign
QI Tech 提供符合第 138 号规范性指令规定的签署服务，包含面部生物识别和文件提交。

如需报价，请联系我们的商务团队：

comercial@qitech.com.br 或 (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"
}
```

  收到签署后，将对已提交文件和 assistance_type 字段进行验证。
  
  如果提交了未映射的福利类型 [(assistance_type)](#benefit_type_enumerator)，操作将被永久取消。
  
  文件验证同样适用，如存在重复、缺失或不符合最低标准的文件，操作也将被永久取消。

  在这两种情况下，都会发送包含以下 payload 的 webhook：

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"
}
```

## 7 - 批注与取消批注

:::caution 注意
	要成功创建批注请求，需要**事先**对福利进行有效的数据查询。
	为此，只需按照第 [2 - 查询福利数据](#consulta-de-dados) 条的步骤操作即可。
:::
### 因超出额度导致批注失败
如果新受益人类别或薪资增长类别的预留在批注尝试时收到超额响应，批注请求的状态将变为"等待合作方操作"，并将以以下格式发送 webhook 以通知相关情况：

WEBHOOK_TYPE social_security_margin_exceeded_for_new_beneficiary 或 social_security_margin_exceeded_for_minimum_wage_increase
STATUS Pending requester action

Webhook Body

**新受益人**

```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"
    }
}
```
  
**薪资增长**

```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"
    }
}
```

### 因缺少有效福利数据查询导致批注失败

如果在批注请求之前未成功完成福利数据查询，批注请求的状态将变为"等待合作方操作"，并将以以下格式发送 webhook 以通知相关情况：

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"
    }
}
```

如需继续，应采取以下操作：

1. 按照第 2 条 - [查询福利数据](#consulta-de-dados) 的步骤查询相关福利数据；  
2. 按以下格式发送请求，告知查询已完成。

ENDPOINT /social_security/reservation/external_key/ DEBT-KEY /validate_reservation
MÉTODO POST

在 Playground 中测试

:::info 重要
	此请求不仅确认存在有效的福利数据查询，还会验证创建批注所发送的信息是否正确，从而允许流程继续进行。
:::

### 请求优先级系统（插队）

由于 Dataprev 的限制，每秒最多允许 **25 个请求**，请求系统以异步方式运行，即批注尝试被组织到队列中进行处理。因此，请求将根据操作类型和成功概率进行优先排序。

在这种情况下，为了避免在批注成功概率高但下次批注尝试还需等待较长时间的情况下损失额度，开发了此系统，允许以同步方式（即无需等待队列）发出请求。

然而，为确保适当控制并防止该系统被滥用，实施了**令牌桶**机制，工作原理如下：

- 每个请求消耗一个令牌；
- 如果请求产生成功的批注，令牌将归还桶中；
- 否则，令牌将被消耗；
- 每个桶有最大令牌数量限制；
- 定期启动令牌补充例程，将已消耗的令牌补充至最大限制；
- 如果令牌耗尽，在例程补充新令牌之前将无法发出新请求。

令牌桶系统示例

在此示例中，桶的配置为：
- **最大令牌数：** 10
- **补充时间：** 30分钟

**第 0 小时：** 桶以最大容量创建；

**第 9 分钟：** 发出一个请求，但合同未批注（错误），导致消耗 1 个令牌；

**第 17 分钟：** 发出一个请求，合同批注成功（成功），令牌数量不变；

**第 30 分钟：** 第一次令牌补充，桶恢复至最大容量；

**第 47 分钟：** 成功发出 10 个请求，无令牌消耗；

**第 1 小时：** 第二次令牌补充，但由于桶已满，令牌数量保持不变；

**第 1:12 小时：** 5 个请求出错，消耗 5 个令牌；

**第 1:30 小时：** 第三次令牌补充，桶有 6 个令牌；

**第 1:38 小时：** 6 个请求出错，耗尽所有令牌；

**第 1:51 小时：** 尝试发出请求，但由于桶中没有令牌，请求被阻止；

**第 2 小时：** 第四次令牌补充，桶有 1 个令牌，允许新的请求尝试；

要发出优先请求，只需使用与要批注的操作对应的 DEBT-KEY 调用以下端点：

#### Request

ENDPOINT /social_security/reservation/external_key/ DEBT-KEY /priority_request
MÉTODO POST

在 Playground 中测试

#### Response

Response Body - 成功
```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 - 错误

```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"
}

无可用令牌错误：
{
    "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"
}

```

最后，可以在无需向优先端点发出请求的情况下查询桶的当前配置。为此，我们提供了以下查询端点：

#### Request

ENDPOINT /social_security/bucket_configuration
MÉTODO GET

在 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"
}

```

### 批注成功
批注成功时，合作方将收到以下 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"
}
```

### 批注失败时更正数据
可以在批注尝试中更正银行数据、福利编号和合同名称。只需使用以下调用：

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

在 Playground 中测试

Request Body

**银行数据**

```json
{
	"disbursement_bank_account": {
		"bank_code": "123",
		"account_digit": "1",
		"account_branch": "1234",
		"account_number": "5678",
		"document_number": "12345678901"
	}
}

```
  
**福利编号**

```json
{
	"benefit_number": 1234567890
}
```

**姓名**

```json
{
	"name": "Nome do Beneficiário"
}
```

### 取消批注

合同的取消批注通过永久取消路由执行。该路由为合同设置最终状态，不可重试，并触发已批注额度的取消批注。

要执行永久取消，应使用以下端点：

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

在 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"
}
```

## 8 - 放款失败

### TED

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

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"
      }
```

## 9 - 重新呈现付款

更改放款日期而不影响操作的财务金额。

### Request

ENDPOINT /debt/ DEBT-KEY /change_disbursement_date
MÉTODO POST

在 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)

## 10 - 获取最后一次请求的响应

last response 是一种简单、客观地映射 QI 与 Dataprev 之间通信响应的方式，可以知道此次请求的时间及获得的返回值（通过枚举值）。枚举值与 Dataprev 的返回代码直接相关，分为两种形式："errors"（错误）和 "success"（成功）。

每个枚举值都有详细描述和 Dataprev 的参考代码。我们可以在下面更详细地了解 last response 数据的呈现方式。

### 成功情形

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

在 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"
  }
}
```

### 请求返回字段详解
| 字段                      | 描述                                | 值                                       |
|---------------------------|-------------------------------------|------------------------------------------|
| enumerator                | Dataprev 代码的映射返回值           | [枚举值](#dataprev_response_enumerator_success)|
| reservation_method        | 预留批注方式                        | portability, new_credit, refinancing|

### 错误情形

#### 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"
  }
}
```

### 请求返回字段详解
| 字段                      | 描述                                | 值                                       |
|---------------------------|-------------------------------------|------------------------------------------|
| enumerator                | Dataprev 代码的映射返回值           | [枚举值](#dataprev_response_enumerator_errors)|
| reservation_method        | 预留批注方式                        | portability, new_credit, refinancing|

## 11 - 获取最后一次福利查询

通过此端点可以查询最后一次在 Dataprev 查询福利的时间。

#### Request
ENDPOINT /social_security/benefit/BENEFIT-NUMBER
MÉTODO GET

在 Playground 中测试

#### Response

Response Body

```json
{
    "last_balance_check": "2025-08-22T19:13:02Z",
    "status": "pending_balance_request"
}
```

## 12 - 最后一次批注尝试的响应 webhook

如果操作批注未成功，将进行重试，并发送以下 webhook，详述批注失败原因、此次尝试的时间及使用的批注方式：

WEBHOOK_TYPE credit_operation.collateral

        *Body:*

**body.json**

```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": "new_credit",
		}
	}
}

```

## 13. 枚举值映射

### Dataprev 批注错误返回表 {#dataprev_response_enumerator_errors}
| Dataprev 代码 | 枚举值                                           | 描述                                                        | 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                           | 取消             |
| HX            | reservation_already_included                     | Reservation already included                                | 确认批注  |
| 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           | 取消             |
| 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           |

### 批注成功返回表 {#dataprev_response_enumerator_success}
| Dataprev 代码 | 枚举值                   | 描述                                    |
|--------|--------------------------|-----------------------------------------|
| 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   |

### 余额查询错误返回表 {#dataprev_balance_errors_enumerators}
| 代码   | 枚举值                                | 描述                                                                            |
|--------|---------------------------------------|---------------------------------------------------------------------------------|
| 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. |

### 福利查询错误返回表 {#dataprev_benefits_errors_enumerators}
| 代码   | 枚举值                                | 描述                                                                            |
|--------|---------------------------------------|---------------------------------------------------------------------------------|
| 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                                |

### 福利状况表 {#benefit_situation_enumerator}
| 项目 |
|-------|
| 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 |

### 福利状态表 {#benefit_status_enumerator}

| 枚举值     | 描述                                                |
|------------|-----------------------------------------------------|
| Elegible   | 有资格申请贷款                                      |
| Inelegible | 福利不符合贷款资格                                  |
| Blocked    | 福利符合资格，但被锁定无法申请贷款                  |

### 锁定类型表 {#block_type_enumerator}

| 枚举值                  | 描述                                                |
|-------------------------|-----------------------------------------------------|
| not_blocked             | 无锁定                                              |
| blocked_by_benefitiary  | 被受益人锁定                                        |
| blocked_by_tbm          | 因 TBM 锁定                                         |
| blocked_in_concession   | 在授予过程中锁定                                    |

### 政治敏感人士类型表 {#politically_exposed_enumerator}

| 枚举值 | 描述                                                |
|--------|-----------------------------------------------------|
| 0      | 非政治敏感人士                                      |
| 1      | 政治敏感人士 - 第 1 级                              |

### 福利类型表 {#benefit_type_enumerator}

| 代码  | 福利                                                     |
| --- | ------------------------------------------------ |
| 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                                      |

---

# 重新计算信贷操作

URL: /zh-Hans/documentation/guides/INSS/new-credit-and-refinancing/recalculate

重新计算信贷操作

根据**新的分期付款面值**重新计算现有信贷操作的财务条款。适用于受益人的可扣除额度发生变化，需要调整分期付款金额的情况。

:::tip 优势
- **保留原始条款** — 利率、期限和操作结构保持不变，仅分期付款金额发生变化
- **即时响应** — 操作在同一调用中重新计算并返回，无需异步处理
- **自动验证** — 端点在应用前验证前置条件、利率限制和 INSS 规则
:::

## 请求

端点 /v2/credit_operation/ CREDIT_OPERATION_KEY /recalculate
方法 POST

### 路径参数

credit_operation_key
string (UUID)
必填
要重新计算的信贷操作的唯一标识。

### 请求体参数

installment_face_value
number
必填
新的分期付款面值。必须小于或等于原始值，且高于最低允许值。

```python
{
    "installment_face_value": 180.50
}
```

:::caution 注意
新的 `installment_face_value` 只能从原始值**降低**。端点会拒绝超过原始值或超出允许变化范围的值。
:::

### 前置条件

操作必须满足以下**所有**条件才能被重新计算：

| 条件 | 不满足时的错误 |
|------|----------------|
| 操作存在 | [`COP000027`](#COP000027) (404) |
| 请求方拥有该操作 | [`QIT000005`](#QIT000005) (403) |
| 担保类型为 `social_security` | [`COP000276`](#COP000276) |
| 状态：`waiting_signature`、`issued` 或 `canceled` | [`COP000489`](#COP000489) |
| 担保尚未设立 | [`COP000489`](#COP000489) |
| 操作类型：`structured_operation` | [`COP000489`](#COP000489) |
| 放款截止日期未过期 | [`COP000489`](#COP000489) |
| 原始操作包含 `installment_face_value` | [`COP000489`](#COP000489) |
| 新值在允许范围内 | [`COP000490`](#COP000490) |

## 响应

状态 200

返回完整的重新计算后的信贷操作对象 — 与[按 credit_operation_key 查询](/documentation/emissao_de_divida/consulta_por_credit_operation_key)的结构相同。

## 错误

| HTTP 状态码 | QI 错误码 | 描述 | 翻译 |
|-------------|-----------|------|------|
| 404 | <span id="COP000027">`COP000027`</span> | Credit Operation not found | 未找到信贷操作 |
| 403 | <span id="QIT000005">`QIT000005`</span> | Selected agent does not own this item | 所选代理不拥有此项目 |
| 400 | <span id="COP000276">`COP000276`</span> | Collateral type doesn't allow recalculation | 担保类型不允许重新计算操作 |
| 400 | <span id="COP000335">`COP000335`</span> | Assignment amount exceeds operation final amount | 转让金额超过操作最终金额 |
| 400 | <span id="COP000339">`COP000339`</span> | Final disbursement amount cannot be negative | 最终放款金额不能为负数 |
| 400 | <span id="COP000489">`COP000489`</span> | Operation not allowed to be recalculated | 信贷操作不允许被重新计算 |
| 400 | <span id="COP000490">`COP000490`</span> | Installment face value variance not allowed | 分期付款面值变化不在允许范围内 |

COP000489 错误的详细原因

`COP000489` 代码用于不同的未满足前置条件。响应中的 `reason` 字段指示具体原因：

| 原因 | 描述 |
|------|------|
| 状态无效 | 信贷操作状态不允许重新计算 |
| 担保已设立 | 信贷操作的担保已经设立 |
| 操作类型无效 | 信贷操作类型不允许重新计算 |
| 放款日期已过期 | 信贷操作的放款截止日期已过 |
| 缺少分期付款值 | 原始操作中未提供分期付款面值 |

---

# Anuência (pending confirmation)

URL: /zh-Hans/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: /zh-Hans/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: /zh-Hans/documentation/guides/INSS/portability+refinancing/consultas-e-enumeradores

Consultas e Enumeradores

Endpoints auxiliares e tabelas de referência para o fluxo de Port+Refin INSS.

## 9 - Consulta de Lista de Participantes do CTC - CIP:

        **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\>"
    }
]
 
```

## 10 - 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 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 - Credit Transfer
ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /CREDIT-OPERATION-TYPE/collateral
MÉTODO GET

#### PATH PARAMETERS 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](#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](#dataprev_response_enumerator_errors) |
| reservation_method        | Método de averbação da reserva      | portability, new_credit, refinancing|
## 11 - Webhook de resposta 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](#dataprev_response_enumerator_errors) |
| reservation_method        | Método de averbação da reserva      | portability, new_credit, refinancing|

## 12 - Consulta de portabilidade de origem

É 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"
    }
}

```

## 13. 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.

        **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
    }
```

## 14. Mapeamento de enumeradores

### 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                           | Teimosinha             |
| 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           | Teimosinha             |
| 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}

| Enumerador | Descrição                                           |
|------------|-----------------------------------------------------|
| 0          | Sem bloqueio                                        |
| 1          | Bloqueado pelo Segurado                             |
| 2          | Bloqueado por TBM                                   |
| 3          | 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                                      |

---

# INSS 贷款转移 + 再融资手册

URL: /zh-Hans/documentation/guides/INSS/portability+refinancing/end-to-end

:::info 另请参阅
- [新贷款或再融资](/documentation/manual_inss/manual_credito_novo)
:::

:::danger 注意！
QI Tech 的 webhooks 不应以严格方式进行映射。
我们 API 返回的 webhook payload 中可能会包含额外字段。
:::

:::info 重新发送 Webhooks
您可以按照以下文档中的详细说明查询并重新发送 webhooks：[重新发送 Webhooks](/documentation/notificacoes/reenvio_de_notificacoes)。
:::

要启动 INSS 贷款转移 + 再融资流程，首先需要收集福利数据以检查资格，以及福利支付账户数据。第 1 和第 2 条描述了查询特定受益人福利列表的程序以及查询福利数据的程序。

## 1 - 通过合作方正式授权书查询福利列表：

        **1.1.** 福利持有人是授权书的签署人。

        **请求**

- ENDPOINT /social_security/benefits_request
- MÉTODO POST

Testar no Playground

        *Payload：*

**payload.json**

```json
{
	"document_number": "16514548091",
	"authorization_term": {
		"document_number": "16514548091",
		"signature": {
			"signer": {
				"name": "Nome Devedor",
				"phone": {
					"number": "887577622",
					"area_code": "19",
					"country_code": "55"
				},
				"document_number": "16514548091"
			},
			"authentication_type": "opt_in",
			"authenticity": {
				"timestamp": "2023-12-05T21:04:06",
				"ip_address": "200.223.171.82",
				"fingerprint": {
					"lat": "-44.00524157713981",
					"long": "-19.807649431219804",
					"name": "Nome Cliente",
					"model": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_6_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.6 Mobile/15E148 Safari/604.1",
					"localeHashValue": "hash cliente"
				},
				"third_party_additional_data": {},
				"session_id": "3571e292-3a83-4011-904d-20ee963022ef"
			},
			"signed_object": {
				"document_key": "cfbc8469-89ea-4a80-9f64-ba7b1566c68b"
			}
		}
	}
}
```

        **1.2.** 福利持有人**不是**授权书的签署人（有法定代理人）。

:::caution 注意

由于本例中授权书的签署人是法定代理人，填写 **signer** 对象的数据为法定代理人的数据。

:::

        **请求**

- ENDPOINT /social_security/benefits_request
- MÉTODO POST

        *Payload：*

**payload.json**

```json
{
	"document_number": "16514548091",
	"authorization_term": {
		"document_number": "16514548091",
        "legal_representative_document_number": "70957091060",
		"signature": {
			"signer": {
				"name": "Nome Representante legal",
				"phone": {
					"number": "887577622",
					"area_code": "19",
					"country_code": "55"
				},
				"document_number": "70957091060"
			},
			"authentication_type": "opt_in",
			"authenticity": {
				"timestamp": "2023-12-05T21:04:06",
				"ip_address": "200.223.171.82",
				"fingerprint": {
					"lat": "-44.00524157713981",
					"long": "-19.807649431219804",
					"name": "Nome Cliente",
					"model": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_6_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.6 Mobile/15E148 Safari/604.1",
					"localeHashValue": "hash cliente"
				},
				"third_party_additional_data": {},
				"session_id": "3571e292-3a83-4011-904d-20ee963022ef"
			},
			"signed_object": {
				"document_key": "cfbc8469-89ea-4a80-9f64-ba7b1566c68b"
			}
		}
	}
}

```

:::caution 注意
在有法定代理人的情况下，需要在 **"legal_representative_document_number"** 字段中填写法定代理人的 CPF，且 **"signer"** 对象中的数据应填写法定代理人的数据。
:::

--- 

        "**document_key**"：使用 /upload 端点返回的 GUID

:::info
**除了**在 **"authorization_term.signed_object.document_key"** 对象中提供签名 PDF 文档的键之外，也可以通过 **"authorization_term.signed_object.raw_text"** 对象发送授权书的纯文本内容。
:::

        **响应**

- MÉTODO POST
- ENDPOINT social_security/benefits_request

**body.json**

```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"
        }
    ]
}

```

福利列表查询成功时：

        **Webhook**

- WEBHOOK_TYPE social_security_benefits_request
- STATUS Success

        *Body：*

**body.json**

```json
{
    "webhook": {
        "key": "54cddd0f-b976-4266-91ea-90279bfb49a1",
        "data": [
            {
                "grant_date": [
                    "2010-10-18"
                ],
                "benefit_number": 2052711150,
                "benefit_status": "elegible"
            }
        ],
        "status": "success",
        "webhook_type": "social_security_benefits_request",
        "event_datetime": "2023-12-22T13:20:44"
    }
}
```

| 字段                       | 描述                                 | 值                                |
|---------------------------|-------------------------------------|----------------------------------|
| benefit_number            | 福利编号                              | - |
| benefit_status            | 福利状态                              | [枚举值](#benefit_status_enumerator) |

福利列表查询失败时：

        **Webhook**

- WEBHOOK_TYPE social_security_benefits_request
- STATUS Failure

        *Body：*

**body.json**

```json

{
    "webhook": {
        "key": "0020653e-c3b0-4606-af31-2ea4a577a5ce",
        "data": {
            "enumerator": "inexistent_beneficiary",
            "description": "no beneficiary found"
        },
        "status": "failure",
        "webhook_type": "social_security_benefits_request",
        "event_datetime": "2023-12-22T15:46:31"
    }
}

```

### 失败 Webhook 中的字段详情

| 字段                       | 描述                                 | 值                                |
|---------------------------|-------------------------------------|----------------------------------|
| enumerator                | Dataprev 代码的映射返回值              | [枚举值](#dataprev_benefits_errors_enumerators) |
### 在 Sandbox 中模拟福利查询的成功和失败场景：
场景模拟基于操作中填写的 CPF 的第一位数字。

**11.1.** 对于以数字 1 开头的 CPF，将通过 Webhook 返回异步成功响应。

**11.2.** 对于其他 CPF，将根据输入的 CPF 的第一位数字返回异步错误响应，如下表所示。

| CPF 开头 | 枚举值                  | 描述                  |
|---------------|------------------------|----------------------|
| 2             | inexistent_beneficiary | no beneficiary found |

:::caution 注意
所有第一位数字没有映射场景的 CPF 将收到一个包含未映射测试场景标准错误的 webhook。

| 枚举值         | 描述                                                              |
|---------------|------------------------------------------------------------------|
| mock_error    | Informed document number is not a valid mock on test environment |
:::

--- 

## 2 - 查询福利数据 {#consulta-de-dados}
        **2.1.** 使用之前提交的授权书查询福利数据。

        **请求**
- MÉTODO POST
- ENDPOINT /social_security/balance_request

Testar no Playground

        *Payload：*

**payload.json**

```json
{
    "document_number": "16514548091",
    "benefit_number": 2052711150
}

```

        **响应**

- MÉTODO POST
- ENDPOINT /social_security/balance_request

        *Body：*

**body.json**

```json
{
    "balance_request_key": "ffda1935-9cad-47df-b848-cd33c96024e4",
    "document_number": "16514548091",
    "status": "pending_authorization",
    "authorization_term": {
        "authorization_term_key": "19196811-366f-4422-a729-4d0aa552449b",
        "status": "allowed"
    },
    "status_events": [
        {
            "status": "pending_authorization",
            "event_date": "2023-12-22T16:18:18"
        }
    ]
}

```

        **2.2.** 随授权书一同提交进行福利数据查询。

        **请求**

- MÉTODO POST
- ENDPOINT /social_security/balance_request

        *Payload：*

**payload.json**

```json
{
    "document_number": "14950479032",
    "benefit_number": 22255220,
	"authorization_term": {
		"document_number": "14950479032",
                "legal_representative_document_number": "32866210050", // CPF do representante legal (caso aplicável)
		"signature": {
			"signer": {
				"name": "Nome Cliente",
				"phone": {
					"number": "887577622",
					"area_code": "19",
					"country_code": "55"
				},
				"document_number": "14950479032"
			},
			"authentication_type": "opt_in",
			"authenticity": {
				"timestamp": "2023-12-05T21:04:06",
				"ip_address": "200.223.171.82",
				"fingerprint": {
					"lat": "-44.00524157713981",
					"long": "-19.807649431219804",
					"name": "Nome Cliente",
					"model": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_6_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.6 Mobile/15E148 Safari/604.1",
					"localeHashValue": "hash cliente"
				},
				"third_party_additional_data": {},
				"session_id": "b75c7ac2-3be3-41b6-b769-4d982a5824a2"
			},
			"signed_object": {
				"document_key": "cfbc8469-89ea-4a80-9f64-ba7b1566c68b"
			}
		}
	}
}

```

:::caution 注意
在有法定代理人的情况下，需要在 **"legal_representative_document_number"** 字段中填写法定代理人的 CPF，且 **"signer"** 对象中的数据应填写法定代理人的数据。
:::

--- 

        **响应**

- MÉTODO POST
- ENDPOINT /social_security/balance_request

- Body：

**body.json**

```json

{
    "balance_request_key": "ffda1935-9cad-47df-b848-cd33c96024e4",
    "document_number": "14950479032",
    "status": "pending_authorization",
    "authorization_term": {
        "authorization_term_key": "19196811-366f-4422-a729-4d0aa552449b",
        "status": "signed"
    },
    "status_events": [
        {
            "status": "pending_authorization",
            "event_date": "2023-12-22T16:18:18"
        }
    ]
}
 
```

福利数据查询成功时

         **Webhook**

- WEBHOOK_TYPE /social_security/balance_request
- STATUS Success

        *Body：*
 
**body.json**

```json
{
    "webhook": {
        "key": "ffda1935-9cad-47df-b848-cd33c96024e4",
        "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
        },
        "status": "success",
        "webhook_type": "social_security_balance_request",
        "event_datetime": "2023-12-22T16:18:21"
    }
}

```

### 成功 Webhook 中的字段详情

| 字段                       | 描述                                                                                                                         | 值                                             |
|---------------------------|-----------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------|
| assistance_type           | 福利类型                                                                                                                     | [枚举值](#benefit_type_enumerator)              |
| benefit_status            | 福利状态                                                                                                                     | [枚举值](#benefit_status_enumerator)           |
| has_entity_representation | 是否有代理实体（不允许背书）                                                                                                   | True 或 False                                 |
| alimony_code              | 赡养费分类器                                                                                                                  | not_payer, payer, benefit                     |
| has_judicial_concession   | 通过临时禁令批准的福利                                                                                                          | True 或 False                                 |
| has_power_of_attorney     | 是否有代理人？                                                                                                                | True 或 False                                 |
| credit_type               | 信贷类型 - 福利领取方式                                                                                                         | Magnetic_card, checking_account               |
| benefit_situation         | 福利状态                                                                                                                      | [枚举值](#benefit_situation_enumerator)        |
| used_total_balance        | 用于贷款背书、转移预留、再融资、变更、RMC 和 RCC 的已占用总金额                                                                     | 数值                                           |
| max_total_balance         | 相应福利类型可占用的金额上限                                                                                                     | 数值                                           |
| available_total_balance   | 可用于贷款的总金额（所有模式之和，即 max_total_balance 与 used_total_balance 之差）                                                | 数值                                           |
| benefit_quota_expiration_date   | 福利终止日期。该信息仅适用于部分死亡养恤金。                                                                                    | 字符串或空值   
| block_type                | 福利锁定类型                                                                                                                  | [枚举值](#block_type_enumerator)
| politically_exposed.type    | 政治敏感人士                                                                                                                  | [枚举值](#politically_exposed_enumerator)
| is_politically_exposed      | 政治敏感人士                                                                                                                  | True 或 False

福利列表查询失败时

        **Webhook**

- WEBHOOK_TYPE /social_security/balance_request
- STATUS Failure

        *Body:*

**body.json**

```json
{
    "webhook": {
        "key": "37a14593-b934-457c-8cf6-e51f184b1f1c",
        "data": {
            "enumerator": "inexistent_beneficiary",
            "description": "no beneficiary found"
        },
        "status": "failure",
        "webhook_type": "social_security_balance_request",
        "event_datetime": "2023-12-22T16:22:29"
    }
}

```

### 失败 Webhook 中的字段详情

| 字段                       | 描述                                 | 值                                |
|---------------------------|-------------------------------------|----------------------------------|
| enumerator                | Dataprev 代码的映射返回值              | [枚举值](#dataprev_balance_errors_enumerators) |
### 在 Sandbox 中模拟福利数据查询的成功和失败场景：
场景模拟基于操作中填写的 CPF 的第一位数字。

**11.1.** 对于以数字 1 开头的 CPF，将通过 Webhook 返回异步成功响应。

**11.2.** 对于其他 CPF，将根据输入的 CPF 的第一位数字返回异步错误响应，如下表所示。

| CPF 开头 | 枚举值                  | 描述                  |
|---------------|------------------------|----------------------|
| 2             | inexistent_beneficiary | no beneficiary found |

:::caution Atenção
所有未映射到第一位数字场景的 CPF，将收到一个包含未映射测试场景标准错误的 webhook。

| Enumerador    | Descrição                                                        |
|---------------|------------------------------------------------------------------|
| mock_error    | Informed document number is not a valid mock on test environment |
:::

---

## 3 - 录入提案：
:::caution 注意
    要使转移和再融资的背书申请成功创建，需要**事先**对福利进行有效的数据查询。
    为此，只需按照 [2 - 查询福利数据](#consulta-de-dados) 中的步骤操作。
:::

### 因缺乏有效福利数据查询导致的背书失败

如果在发出背书请求之前未成功进行福利数据查询，背书请求的状态将变为等待合作方操作，并以以下格式发送 webhook 以通知此事：

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"
    }
}
```

要继续操作，需执行以下步骤：

1. 按照第 2 条 - [查询福利数据](#consulta-de-dados) 中的步骤查询相关福利数据；
2. 按以下格式发送请求以告知查询已完成。

ENDPOINT /social_security/reservation/external_key/ DEBT-KEY /validate_reservation
MÉTODO POST

Testar no Playground

:::info 重要
    此请求不仅确认存在有效的福利数据查询，还验证用于创建背书的信息是否正确，从而允许流程继续。
:::

**3.1. 录入含再融资的转移提案：** 此录入方式用于执行信贷合同的转移，最终向债务人释放更多资金。转移后释放的金额称为"找零"。转移提案和再融资提案可以在同一个请求中生成。

提案录入时需发送以下信息：

- 信贷借款人的注册数据。

- 法定代理人的注册数据（如适用）。

- 转移操作的财务数据，始终需提供期数以及利率或分期面值之一。

- 再融资操作的财务数据（用于结清转移操作并释放找零的操作），以及用于支付找零的银行账户数据（如福利数据查询中返回的账户）。

- 负责提案发起的信贷代理，也称为'pastinha'。

- 未偿余额、原始合同编号和原始债权人的 ISPB。由于再融资操作没有固定的放款日期，放款日期的变化会影响操作金额，因此需要说明是利率（"**monthly_interest_rate**"）固定还是向客户释放的金额（"**disbursed_amount**"）固定。

**如果提案针对文盲客户，委托人和证人的数据必须在提案创建 payload 的 additional_data 字段中发送。但需要事先与 QI Tech 确认将使用哪些信息和格式**

        **3.1.1. 录入固定利率的含再融资转移提案：** 以下是固定操作利率的提案录入示例：

        **Request**

- MÉTODO POST
- STATUS /v2/credit_transfer/proposal

在 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",
        "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",
        "document_identification_date": "2019-01-28",
        "document_identification_type": "rg",
        "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 里约格兰德州的宽限期
根据 DATAPREV 通知，来自里约格兰德州的福利在 2024 年 6 月 28 日之后生成的新再融资合同中可有最多 **6 个月**的宽限期。
为此，需要在上述 payload 的 "**collateral_data**" 中添加一个名为 "**number_of_grace_periods**" 的字段。该字段将包含所需宽限月数的值，如以下示例所示：
```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
"**related_parties**" 列表仅应在有法定代理人的操作时发送。
发送时，必须包含法定代理人的注册数据，且 "**role_type**" 字段应发送值："**issuer_legal_representative**"。
:::

:::info
在 "**origin_contract.ispb**" 字段中填写原始债权机构的 **ISPB**。
**ISPB** 是机构 CNPJ 的基础部分。要获取 CTC - CIP（信贷转移中心）每个参与机构的完整 **ISPB** 列表，只需使用 CTC 参与者查询端点（索引）：
:::

        **3.1.2. 录入固定释放金额的含再融资转移提案：**

         以下是固定向客户释放金额的提案录入示例：

        **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",
		"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",
        "document_identification_type": "rg",
        "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": {}
}
```

        **3.1.3. 响应**

- MÉTODO POST
- STATUS /v2/credit_transfer/proposal

        *Body：*

**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-04-22",
                        "calendar_days": 31,
                        "due_date": "2024-04-22",
                        "due_principal": 656.9717533805768,
                        "installment_number": 3,
                        "pre_fixed_amount": 8.963122696164149,
                        "principal_amortization_amount": 78.22687730383585,
                        "total_amount": 87.19,
                        "workdays": 20
                    },
                    {
                        "business_due_date": "2024-05-22",
                        "calendar_days": 30,
                        "due_date": "2024-05-22",
                        "due_principal": 578.744876076741,
                        "installment_number": 4,
                        "pre_fixed_amount": 7.639487642788938,
                        "principal_amortization_amount": 79.55051235721106,
                        "total_amount": 87.19,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2024-06-24",
                        "calendar_days": 33,
                        "due_date": "2024-06-24",
                        "due_principal": 499.19436371952986,
                        "installment_number": 5,
                        "pre_fixed_amount": 7.253119731550034,
                        "principal_amortization_amount": 79.93688026844997,
                        "total_amount": 87.19,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2024-07-22",
                        "calendar_days": 28,
                        "due_date": "2024-07-22",
                        "due_principal": 419.2574834510799,
                        "installment_number": 6,
                        "pre_fixed_amount": 5.163027422441386,
                        "principal_amortization_amount": 82.02697257755861,
                        "total_amount": 87.19,
                        "workdays": 20
                    },
                    {
                        "business_due_date": "2024-08-22",
                        "calendar_days": 31,
                        "due_date": "2024-08-22",
                        "due_principal": 337.2305108735213,
                        "installment_number": 7,
                        "pre_fixed_amount": 4.600865151805861,
                        "principal_amortization_amount": 82.58913484819413,
                        "total_amount": 87.19,
                        "workdays": 23
                    },
                    {
                        "business_due_date": "2024-09-23",
                        "calendar_days": 32,
                        "due_date": "2024-09-23",
                        "due_principal": 254.64137602532716,
                        "installment_number": 8,
                        "pre_fixed_amount": 3.586947657335553,
                        "principal_amortization_amount": 83.60305234266444,
                        "total_amount": 87.19,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2024-10-22",
                        "calendar_days": 29,
                        "due_date": "2024-10-22",
                        "due_principal": 171.0383236826627,
                        "installment_number": 9,
                        "pre_fixed_amount": 2.18198682510524,
                        "principal_amortization_amount": 85.00801317489476,
                        "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,
                "contract_fees": [
                    {
                        "amount": 0.5,
                        "amount_type": "percentage",
                        "fee_amount": 1.03,
                        "fee_type": "tac"
                    }
                ],
                "disbursed_issue_amount": 1000.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": 1005.24,
                        "installment_number": 1,
                        "pre_fixed_amount": 28.92478321729087,
                        "principal_amortization_amount": 81.07521678270913,
                        "total_amount": 110.0,
                        "workdays": 40
                    },
                    {
                        "business_due_date": "2024-03-22",
                        "calendar_days": 29,
                        "due_date": "2024-03-22",
                        "due_principal": 924.1647832172908,
                        "installment_number": 2,
                        "pre_fixed_amount": 12.344286518064438,
                        "principal_amortization_amount": 97.65571348193556,
                        "total_amount": 110.0,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2024-04-22",
                        "calendar_days": 31,
                        "due_date": "2024-04-22",
                        "due_principal": 826.5090697353553,
                        "installment_number": 3,
                        "pre_fixed_amount": 11.806660138520433,
                        "principal_amortization_amount": 98.19333986147957,
                        "total_amount": 110.0,
                        "workdays": 20
                    },
                    {
                        "business_due_date": "2024-05-22",
                        "calendar_days": 30,
                        "due_date": "2024-05-22",
                        "due_principal": 728.3157298738757,
                        "installment_number": 4,
                        "pre_fixed_amount": 10.06605046134725,
                        "principal_amortization_amount": 99.93394953865275,
                        "total_amount": 110.0,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2024-06-24",
                        "calendar_days": 33,
                        "due_date": "2024-06-24",
                        "due_principal": 628.381780335223,
                        "installment_number": 5,
                        "pre_fixed_amount": 9.559924513271145,
                        "principal_amortization_amount": 100.44007548672886,
                        "total_amount": 110.0,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2024-07-22",
                        "calendar_days": 28,
                        "due_date": "2024-07-22",
                        "due_principal": 527.9417048484942,
                        "installment_number": 6,
                        "pre_fixed_amount": 6.807113809566991,
                        "principal_amortization_amount": 103.19288619043301,
                        "total_amount": 110.0,
                        "workdays": 20
                    },
                    {
                        "business_due_date": "2024-08-22",
                        "calendar_days": 31,
                        "due_date": "2024-08-22",
                        "due_principal": 424.7488186580611,
                        "installment_number": 7,
                        "pre_fixed_amount": 6.067525608326975,
                        "principal_amortization_amount": 103.93247439167303,
                        "total_amount": 110.0,
                        "workdays": 23
                    },
                    {
                        "business_due_date": "2024-09-23",
                        "calendar_days": 32,
                        "due_date": "2024-09-23",
                        "due_principal": 320.8163442663881,
                        "installment_number": 8,
                        "pre_fixed_amount": 4.731771911001933,
                        "principal_amortization_amount": 105.26822808899807,
                        "total_amount": 110.0,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2024-10-22",
                        "calendar_days": 29,
                        "due_date": "2024-10-22",
                        "due_principal": 215.54811617739003,
                        "installment_number": 9,
                        "pre_fixed_amount": 2.87912691853476,
                        "principal_amortization_amount": 107.12087308146523,
                        "total_amount": 110.0,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2024-11-22",
                        "calendar_days": 31,
                        "due_date": "2024-11-22",
                        "due_principal": 108.4272430959248,
                        "installment_number": 10,
                        "pre_fixed_amount": 1.5688802916587754,
                        "principal_amortization_amount": 108.43111970834123,
                        "total_amount": 110.0,
                        "workdays": 22
                    }
                ],
                "issue_amount": 1005.24,
                "number_of_installments": 10,
                "prefixed_interest_rate": {
                    "annual_rate": 0.17905959,
                    "daily_rate": 0.00045765,
                    "interest_base": "calendar_days",
                    "monthly_rate": 0.01382107
                },
                "total_iof": 4.21
            }
        ],
        "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"
        }
    ]
}

```

以下是提案录入响应中返回的部分字段的定义和描述： 

**[A]**: ***“portability_credit_operation.disbursement_options.iof_amount”***：在转移操作中，IOF 始终为零。

**[B]**: ***“portability_credit_operation.disbursement_options.disbursed_issue_amount”***：等于原始合同的未偿余额。

**[C]**: ***“portability_credit_operation.disbursement_options.issue_amount”***：为转移操作的金额。

:::tip Relação
[C] = [A] + [B]
:::

**[D]**: ***“refinancing_credit_operation.disbursement_options.iof_amount”***：再融资操作（找零）的 IOF 金额。

**[E]**: ***“refinancing_credit_operation.disbursement_options.disbursed_issue_amount”***：用于结清转移操作未偿余额的金额。

:::tip Relação
[E] = [C]
::: 

**[F]**: **"refinancing_credit_operation.disbursement_options.final_disbursement_amount"**：释放给客户（找零）的金额，发送至在提案录入时指定的放款账户（应为福利数据查询时返回的账户信息）。

**[G]**: **“refinancing_credit_operation.disbursement_options.issue_amount”**：再融资金额。

:::tip Relação
{"\n"}
[G] = [F] + [E] + [D]
{"\n"}
:::

“**portability_credit_operation.disbursement_options.collateral_constituted**“ 和 “**refinancing_credit_operation.disbursement_options.collateral_constituted**“ 字段表示客户的边际额度是否已在 Dataprev 中背书。转移的背书流程将在原始合同结清资金发送至原始债权机构后启动（第 **6.4.** 条）。再融资的背书流程在合作方决定继续再融资操作时启动（第 **7.1.1.** 和 **7.2.** 条）。

 

     **3.2. 录入转移提案：**

        转移提案（纯转移）的录入方式与第 3.1.1 条所述类似，但发送时不含 **"refinancing_credit_operation"** 对象。

        **Request**

- MÉTODO POST
- STATUS /v2/credit_transfer/proposal

        *Body:*

**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",
        "document_identification_type": "rg",
         "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,
                "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-04-22",
                        "calendar_days": 31,
                        "due_date": "2024-04-22",
                        "due_principal": 656.9717533805768,
                        "installment_number": 3,
                        "pre_fixed_amount": 8.963122696164149,
                        "principal_amortization_amount": 78.22687730383585,
                        "total_amount": 87.19,
                        "workdays": 20
                    },
                    {
                        "business_due_date": "2024-05-22",
                        "calendar_days": 30,
                        "due_date": "2024-05-22",
                        "due_principal": 578.744876076741,
                        "installment_number": 4,
                        "pre_fixed_amount": 7.639487642788938,
                        "principal_amortization_amount": 79.55051235721106,
                        "total_amount": 87.19,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2024-06-24",
                        "calendar_days": 33,
                        "due_date": "2024-06-24",
                        "due_principal": 499.19436371952986,
                        "installment_number": 5,
                        "pre_fixed_amount": 7.253119731550034,
                        "principal_amortization_amount": 79.93688026844997,
                        "total_amount": 87.19,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2024-07-22",
                        "calendar_days": 28,
                        "due_date": "2024-07-22",
                        "due_principal": 419.2574834510799,
                        "installment_number": 6,
                        "pre_fixed_amount": 5.163027422441386,
                        "principal_amortization_amount": 82.02697257755861,
                        "total_amount": 87.19,
                        "workdays": 20
                    },
                    {
                        "business_due_date": "2024-08-22",
                        "calendar_days": 31,
                        "due_date": "2024-08-22",
                        "due_principal": 337.2305108735213,
                        "installment_number": 7,
                        "pre_fixed_amount": 4.600865151805861,
                        "principal_amortization_amount": 82.58913484819413,
                        "total_amount": 87.19,
                        "workdays": 23
                    },
                    {
                        "business_due_date": "2024-09-23",
                        "calendar_days": 32,
                        "due_date": "2024-09-23",
                        "due_principal": 254.64137602532716,
                        "installment_number": 8,
                        "pre_fixed_amount": 3.586947657335553,
                        "principal_amortization_amount": 83.60305234266444,
                        "total_amount": 87.19,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2024-10-22",
                        "calendar_days": 29,
                        "due_date": "2024-10-22",
                        "due_principal": 171.0383236826627,
                        "installment_number": 9,
                        "pre_fixed_amount": 2.18198682510524,
                        "principal_amortization_amount": 85.00801317489476,
                        "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": "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"
        }
    ]
}
```
 

        **3.3. 恢复提案数据：**

- MÉTODO GET
- STATUS /v2/credit_transfer/proposal/PROPOSAL-KEY ou REQUESTER_CONTROL_KEY

## Path Params
| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `proposal_key` | string | 提案标识键 | - |
| `requester_control_key` | string | 客户标识键，用于在超时或重复操作时检索提案数据，替代 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,
                "contract_fee_amount": 0,
                "contract_fees": [],
                "disbursed_issue_amount": 17879.22,
                "disbursement_date": "2025-06-02",
                "external_contract_fee_amount": 0,
                "external_contract_fees": [],
                "final_disbursement_amount": 17879.22,
                "installments": [
                    {
                        "business_due_date": "2025-07-03",
                        "calendar_days": 30,
                        "due_date": "2025-07-02",
                        "due_principal": 17879.22,
                        "installment_number": 1,
                        "pre_fixed_amount": 309.31052471,
                        "principal_amortization_amount": 146.66947529,
                        "total_amount": 455.98,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2025-08-05",
                        "calendar_days": 31,
                        "due_date": "2025-08-02",
                        "due_principal": 17732.55052471,
                        "installment_number": 2,
                        "pre_fixed_amount": 317.08981019,
                        "principal_amortization_amount": 138.89018981,
                        "total_amount": 455.98,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2025-09-03",
                        "calendar_days": 31,
                        "due_date": "2025-09-02",
                        "due_principal": 17593.6603349,
                        "installment_number": 3,
                        "pre_fixed_amount": 314.60620447,
                        "principal_amortization_amount": 141.37379553,
                        "total_amount": 455.98,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2025-10-03",
                        "calendar_days": 30,
                        "due_date": "2025-10-02",
                        "due_principal": 17452.28653937,
                        "installment_number": 4,
                        "pre_fixed_amount": 301.92457539,
                        "principal_amortization_amount": 154.05542461,
                        "total_amount": 455.98,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2025-11-04",
                        "calendar_days": 31,
                        "due_date": "2025-11-02",
                        "due_principal": 17298.23111476,
                        "installment_number": 5,
                        "pre_fixed_amount": 309.3234001,
                        "principal_amortization_amount": 146.6565999,
                        "total_amount": 455.98,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2025-12-03",
                        "calendar_days": 30,
                        "due_date": "2025-12-02",
                        "due_principal": 17151.57451486,
                        "installment_number": 6,
                        "pre_fixed_amount": 296.72225705,
                        "principal_amortization_amount": 159.25774295,
                        "total_amount": 455.98,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2026-01-05",
                        "calendar_days": 31,
                        "due_date": "2026-01-02",
                        "due_principal": 16992.31677191,
                        "installment_number": 7,
                        "pre_fixed_amount": 303.85310294,
                        "principal_amortization_amount": 152.12689706,
                        "total_amount": 455.98,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2026-02-03",
                        "calendar_days": 31,
                        "due_date": "2026-02-02",
                        "due_principal": 16840.18987485,
                        "installment_number": 8,
                        "pre_fixed_amount": 301.13280115,
                        "principal_amortization_amount": 154.84719885,
                        "total_amount": 455.98,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2026-03-03",
                        "calendar_days": 28,
                        "due_date": "2026-03-02",
                        "due_principal": 16685.342676,
                        "installment_number": 9,
                        "pre_fixed_amount": 269.25826857,
                        "principal_amortization_amount": 186.72173143,
                        "total_amount": 455.98,
                        "workdays": 18
                    },
                    {
                        "business_due_date": "2026-04-06",
                        "calendar_days": 31,
                        "due_date": "2026-04-02",
                        "due_principal": 16498.62094457,
                        "installment_number": 10,
                        "pre_fixed_amount": 295.024936,
                        "principal_amortization_amount": 160.955064,
                        "total_amount": 455.98,
                        "workdays": 23
                    },
                    {
                        "business_due_date": "2026-05-05",
                        "calendar_days": 30,
                        "due_date": "2026-05-02",
                        "due_principal": 16337.66588057,
                        "installment_number": 11,
                        "pre_fixed_amount": 282.64163683,
                        "principal_amortization_amount": 173.33836317,
                        "total_amount": 455.98,
                        "workdays": 18
                    },
                    {
                        "business_due_date": "2026-06-03",
                        "calendar_days": 31,
                        "due_date": "2026-06-02",
                        "due_principal": 16164.3275174,
                        "installment_number": 12,
                        "pre_fixed_amount": 289.0471699,
                        "principal_amortization_amount": 166.9328301,
                        "total_amount": 455.98,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2026-07-03",
                        "calendar_days": 30,
                        "due_date": "2026-07-02",
                        "due_principal": 15997.3946873,
                        "installment_number": 13,
                        "pre_fixed_amount": 276.75494483,
                        "principal_amortization_amount": 179.22505517,
                        "total_amount": 455.98,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2026-08-04",
                        "calendar_days": 31,
                        "due_date": "2026-08-02",
                        "due_principal": 15818.16963213,
                        "installment_number": 14,
                        "pre_fixed_amount": 282.85724601,
                        "principal_amortization_amount": 173.12275399,
                        "total_amount": 455.98,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2026-09-03",
                        "calendar_days": 31,
                        "due_date": "2026-09-02",
                        "due_principal": 15645.04687814,
                        "installment_number": 15,
                        "pre_fixed_amount": 279.76150064,
                        "principal_amortization_amount": 176.21849936,
                        "total_amount": 455.98,
                        "workdays": 23
                    },
                    {
                        "business_due_date": "2026-10-05",
                        "calendar_days": 30,
                        "due_date": "2026-10-02",
                        "due_principal": 15468.82837878,
                        "installment_number": 16,
                        "pre_fixed_amount": 267.61074714,
                        "principal_amortization_amount": 188.36925286,
                        "total_amount": 455.98,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2026-11-04",
                        "calendar_days": 31,
                        "due_date": "2026-11-02",
                        "due_principal": 15280.45912592,
                        "installment_number": 17,
                        "pre_fixed_amount": 273.24201767,
                        "principal_amortization_amount": 182.73798233,
                        "total_amount": 455.98,
                        "workdays": 19
                    },
                    {
                        "business_due_date": "2026-12-03",
                        "calendar_days": 30,
                        "due_date": "2026-12-02",
                        "due_principal": 15097.72114359,
                        "installment_number": 18,
                        "pre_fixed_amount": 261.19059158,
                        "principal_amortization_amount": 194.78940842,
                        "total_amount": 455.98,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2027-01-05",
                        "calendar_days": 31,
                        "due_date": "2027-01-02",
                        "due_principal": 14902.93173517,
                        "installment_number": 19,
                        "pre_fixed_amount": 266.49115076,
                        "principal_amortization_amount": 189.48884924,
                        "total_amount": 455.98,
                        "workdays": 20
                    },
                    {
                        "business_due_date": "2027-02-03",
                        "calendar_days": 31,
                        "due_date": "2027-02-02",
                        "due_principal": 14713.44288593,
                        "installment_number": 20,
                        "pre_fixed_amount": 263.10275025,
                        "principal_amortization_amount": 192.87724975,
                        "total_amount": 455.98,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2027-03-03",
                        "calendar_days": 28,
                        "due_date": "2027-03-02",
                        "due_principal": 14520.56563618,
                        "installment_number": 21,
                        "pre_fixed_amount": 234.32436707,
                        "principal_amortization_amount": 221.65563293,
                        "total_amount": 455.98,
                        "workdays": 18
                    },
                    {
                        "business_due_date": "2027-04-05",
                        "calendar_days": 31,
                        "due_date": "2027-04-02",
                        "due_principal": 14298.91000325,
                        "installment_number": 22,
                        "pre_fixed_amount": 255.69015876,
                        "principal_amortization_amount": 200.28984124,
                        "total_amount": 455.98,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2027-05-04",
                        "calendar_days": 30,
                        "due_date": "2027-05-02",
                        "due_principal": 14098.62016201,
                        "installment_number": 23,
                        "pre_fixed_amount": 243.90614356,
                        "principal_amortization_amount": 212.07385644,
                        "total_amount": 455.98,
                        "workdays": 19
                    },
                    {
                        "business_due_date": "2027-06-03",
                        "calendar_days": 31,
                        "due_date": "2027-06-02",
                        "due_principal": 13886.54630557,
                        "installment_number": 24,
                        "pre_fixed_amount": 248.31635619,
                        "principal_amortization_amount": 207.66364381,
                        "total_amount": 455.98,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2027-07-05",
                        "calendar_days": 30,
                        "due_date": "2027-07-02",
                        "due_principal": 13678.88266176,
                        "installment_number": 25,
                        "pre_fixed_amount": 236.64468436,
                        "principal_amortization_amount": 219.33531564,
                        "total_amount": 455.98,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2027-08-03",
                        "calendar_days": 31,
                        "due_date": "2027-08-02",
                        "due_principal": 13459.54734612,
                        "installment_number": 26,
                        "pre_fixed_amount": 240.68084889,
                        "principal_amortization_amount": 215.29915111,
                        "total_amount": 455.98,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2027-09-03",
                        "calendar_days": 31,
                        "due_date": "2027-09-02",
                        "due_principal": 13244.24819501,
                        "installment_number": 27,
                        "pre_fixed_amount": 236.83091388,
                        "principal_amortization_amount": 219.14908612,
                        "total_amount": 455.98,
                        "workdays": 23
                    },
                    {
                        "business_due_date": "2027-10-05",
                        "calendar_days": 30,
                        "due_date": "2027-10-02",
                        "due_principal": 13025.09910889,
                        "installment_number": 28,
                        "pre_fixed_amount": 225.33422821,
                        "principal_amortization_amount": 230.64577179,
                        "total_amount": 455.98,
                        "workdays": 20
                    },
                    {
                        "business_due_date": "2027-11-04",
                        "calendar_days": 31,
                        "due_date": "2027-11-02",
                        "due_principal": 12794.4533371,
                        "installment_number": 29,
                        "pre_fixed_amount": 228.78777503,
                        "principal_amortization_amount": 227.19222497,
                        "total_amount": 455.98,
                        "workdays": 20
                    },
                    {
                        "business_due_date": "2027-12-03",
                        "calendar_days": 30,
                        "due_date": "2027-12-02",
                        "due_principal": 12567.26111213,
                        "installment_number": 30,
                        "pre_fixed_amount": 217.41363039,
                        "principal_amortization_amount": 238.56636961,
                        "total_amount": 455.98,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2028-01-04",
                        "calendar_days": 31,
                        "due_date": "2028-01-02",
                        "due_principal": 12328.69474252,
                        "installment_number": 31,
                        "pre_fixed_amount": 220.45917593,
                        "principal_amortization_amount": 235.52082407,
                        "total_amount": 455.98,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2028-02-03",
                        "calendar_days": 31,
                        "due_date": "2028-02-02",
                        "due_principal": 12093.17391845,
                        "installment_number": 32,
                        "pre_fixed_amount": 216.24764114,
                        "principal_amortization_amount": 239.73235886,
                        "total_amount": 455.98,
                        "workdays": 23
                    },
                    {
                        "business_due_date": "2028-03-03",
                        "calendar_days": 29,
                        "due_date": "2028-03-02",
                        "due_principal": 11853.44155959,
                        "installment_number": 33,
                        "pre_fixed_amount": 198.17224791,
                        "principal_amortization_amount": 257.80775209,
                        "total_amount": 455.98,
                        "workdays": 19
                    },
                    {
                        "business_due_date": "2028-04-04",
                        "calendar_days": 31,
                        "due_date": "2028-04-02",
                        "due_principal": 11595.6338075,
                        "installment_number": 34,
                        "pre_fixed_amount": 207.35073152,
                        "principal_amortization_amount": 248.62926848,
                        "total_amount": 455.98,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2028-05-03",
                        "calendar_days": 30,
                        "due_date": "2028-05-02",
                        "due_principal": 11347.00453902,
                        "installment_number": 35,
                        "pre_fixed_amount": 196.3031904,
                        "principal_amortization_amount": 259.6768096,
                        "total_amount": 455.98,
                        "workdays": 19
                    },
                    {
                        "business_due_date": "2028-06-05",
                        "calendar_days": 31,
                        "due_date": "2028-06-02",
                        "due_principal": 11087.32772942,
                        "installment_number": 36,
                        "pre_fixed_amount": 198.2613071,
                        "principal_amortization_amount": 257.7186929,
                        "total_amount": 455.98,
                        "workdays": 23
                    },
                    {
                        "business_due_date": "2028-07-04",
                        "calendar_days": 30,
                        "due_date": "2028-07-02",
                        "due_principal": 10829.60903652,
                        "installment_number": 37,
                        "pre_fixed_amount": 187.35224766,
                        "principal_amortization_amount": 268.62775234,
                        "total_amount": 455.98,
                        "workdays": 19
                    },
                    {
                        "business_due_date": "2028-08-03",
                        "calendar_days": 31,
                        "due_date": "2028-08-02",
                        "due_principal": 10560.98128418,
                        "installment_number": 38,
                        "pre_fixed_amount": 188.84928855,
                        "principal_amortization_amount": 267.13071145,
                        "total_amount": 455.98,
                        "workdays": 23
                    },
                    {
                        "business_due_date": "2028-09-05",
                        "calendar_days": 31,
                        "due_date": "2028-09-02",
                        "due_principal": 10293.85057273,
                        "installment_number": 39,
                        "pre_fixed_amount": 184.07251228,
                        "principal_amortization_amount": 271.90748772,
                        "total_amount": 455.98,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2028-10-03",
                        "calendar_days": 30,
                        "due_date": "2028-10-02",
                        "due_principal": 10021.94308501,
                        "installment_number": 40,
                        "pre_fixed_amount": 173.37962586,
                        "principal_amortization_amount": 282.60037414,
                        "total_amount": 455.98,
                        "workdays": 20
                    },
                    {
                        "business_due_date": "2028-11-06",
                        "calendar_days": 31,
                        "due_date": "2028-11-02",
                        "due_principal": 9739.34271087,
                        "installment_number": 41,
                        "pre_fixed_amount": 174.15691709,
                        "principal_amortization_amount": 281.82308291,
                        "total_amount": 455.98,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2028-12-05",
                        "calendar_days": 30,
                        "due_date": "2028-12-02",
                        "due_principal": 9457.51962796,
                        "installment_number": 42,
                        "pre_fixed_amount": 163.61509946,
                        "principal_amortization_amount": 292.36490054,
                        "total_amount": 455.98,
                        "workdays": 19
                    },
                    {
                        "business_due_date": "2029-01-03",
                        "calendar_days": 31,
                        "due_date": "2029-01-02",
                        "due_principal": 9165.15472742,
                        "installment_number": 43,
                        "pre_fixed_amount": 163.88940603,
                        "principal_amortization_amount": 292.09059397,
                        "total_amount": 455.98,
                        "workdays": 20
                    },
                    {
                        "business_due_date": "2029-02-05",
                        "calendar_days": 31,
                        "due_date": "2029-02-02",
                        "due_principal": 8873.06413345,
                        "installment_number": 44,
                        "pre_fixed_amount": 158.66630229,
                        "principal_amortization_amount": 297.31369771,
                        "total_amount": 455.98,
                        "workdays": 23
                    },
                    {
                        "business_due_date": "2029-03-05",
                        "calendar_days": 28,
                        "due_date": "2029-03-02",
                        "due_principal": 8575.75043574,
                        "installment_number": 45,
                        "pre_fixed_amount": 138.39042799,
                        "principal_amortization_amount": 317.58957201,
                        "total_amount": 455.98,
                        "workdays": 18
                    },
                    {
                        "business_due_date": "2029-04-03",
                        "calendar_days": 31,
                        "due_date": "2029-04-02",
                        "due_principal": 8258.16086373,
                        "installment_number": 46,
                        "pre_fixed_amount": 147.67072888,
                        "principal_amortization_amount": 308.30927112,
                        "total_amount": 455.98,
                        "workdays": 20
                    },
                    {
                        "business_due_date": "2029-05-03",
                        "calendar_days": 30,
                        "due_date": "2029-05-02",
                        "due_principal": 7949.85159261,
                        "installment_number": 47,
                        "pre_fixed_amount": 137.53244087,
                        "principal_amortization_amount": 318.44755913,
                        "total_amount": 455.98,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2029-06-05",
                        "calendar_days": 31,
                        "due_date": "2029-06-02",
                        "due_principal": 7631.40403348,
                        "installment_number": 48,
                        "pre_fixed_amount": 136.46319254,
                        "principal_amortization_amount": 319.51680746,
                        "total_amount": 455.98,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2029-07-03",
                        "calendar_days": 30,
                        "due_date": "2029-07-02",
                        "due_principal": 7311.88722602,
                        "installment_number": 49,
                        "pre_fixed_amount": 126.49565666,
                        "principal_amortization_amount": 329.48434334,
                        "total_amount": 455.98,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2029-08-03",
                        "calendar_days": 31,
                        "due_date": "2029-08-02",
                        "due_principal": 6982.40288268,
                        "installment_number": 50,
                        "pre_fixed_amount": 124.85788785,
                        "principal_amortization_amount": 331.12211215,
                        "total_amount": 455.98,
                        "workdays": 23
                    },
                    {
                        "business_due_date": "2029-09-04",
                        "calendar_days": 31,
                        "due_date": "2029-09-02",
                        "due_principal": 6651.28077053,
                        "installment_number": 51,
                        "pre_fixed_amount": 118.93683055,
                        "principal_amortization_amount": 337.04316945,
                        "total_amount": 455.98,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2029-10-03",
                        "calendar_days": 30,
                        "due_date": "2029-10-02",
                        "due_principal": 6314.23760108,
                        "installment_number": 52,
                        "pre_fixed_amount": 109.23631711,
                        "principal_amortization_amount": 346.74368289,
                        "total_amount": 455.98,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2029-11-06",
                        "calendar_days": 31,
                        "due_date": "2029-11-02",
                        "due_principal": 5967.49391819,
                        "installment_number": 53,
                        "pre_fixed_amount": 106.70949513,
                        "principal_amortization_amount": 349.27050487,
                        "total_amount": 455.98,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2029-12-04",
                        "calendar_days": 30,
                        "due_date": "2029-12-02",
                        "due_principal": 5618.22341332,
                        "installment_number": 54,
                        "pre_fixed_amount": 97.19527093,
                        "principal_amortization_amount": 358.78472907,
                        "total_amount": 455.98,
                        "workdays": 18
                    },
                    {
                        "business_due_date": "2030-01-03",
                        "calendar_days": 31,
                        "due_date": "2030-01-02",
                        "due_principal": 5259.43868425,
                        "installment_number": 55,
                        "pre_fixed_amount": 94.04819751,
                        "principal_amortization_amount": 361.93180249,
                        "total_amount": 455.98,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2030-02-05",
                        "calendar_days": 31,
                        "due_date": "2030-02-02",
                        "due_principal": 4897.50688176,
                        "installment_number": 56,
                        "pre_fixed_amount": 87.57620769,
                        "principal_amortization_amount": 368.40379231,
                        "total_amount": 455.98,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2030-03-07",
                        "calendar_days": 28,
                        "due_date": "2030-03-02",
                        "due_principal": 4529.10308945,
                        "installment_number": 57,
                        "pre_fixed_amount": 73.08800782,
                        "principal_amortization_amount": 382.89199218,
                        "total_amount": 455.98,
                        "workdays": 20
                    },
                    {
                        "business_due_date": "2030-04-03",
                        "calendar_days": 31,
                        "due_date": "2030-04-02",
                        "due_principal": 4146.21109727,
                        "installment_number": 58,
                        "pre_fixed_amount": 74.14169146,
                        "principal_amortization_amount": 381.83830854,
                        "total_amount": 455.98,
                        "workdays": 20
                    },
                    {
                        "business_due_date": "2030-05-03",
                        "calendar_days": 30,
                        "due_date": "2030-05-02",
                        "due_principal": 3764.37278873,
                        "installment_number": 59,
                        "pre_fixed_amount": 65.12365318,
                        "principal_amortization_amount": 390.85634682,
                        "total_amount": 455.98,
                        "workdays": 20
                    },
                    {
                        "business_due_date": "2030-06-04",
                        "calendar_days": 31,
                        "due_date": "2030-06-02",
                        "due_principal": 3373.51644191,
                        "installment_number": 60,
                        "pre_fixed_amount": 60.32452504,
                        "principal_amortization_amount": 395.65547496,
                        "total_amount": 455.98,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2030-07-03",
                        "calendar_days": 30,
                        "due_date": "2030-07-02",
                        "due_principal": 2977.86096695,
                        "installment_number": 61,
                        "pre_fixed_amount": 51.51699784,
                        "principal_amortization_amount": 404.46300216,
                        "total_amount": 455.98,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2030-08-05",
                        "calendar_days": 31,
                        "due_date": "2030-08-02",
                        "due_principal": 2573.39796479,
                        "installment_number": 62,
                        "pre_fixed_amount": 46.0169715,
                        "principal_amortization_amount": 409.9630285,
                        "total_amount": 455.98,
                        "workdays": 23
                    },
                    {
                        "business_due_date": "2030-09-03",
                        "calendar_days": 31,
                        "due_date": "2030-09-02",
                        "due_principal": 2163.43493629,
                        "installment_number": 63,
                        "pre_fixed_amount": 38.68609721,
                        "principal_amortization_amount": 417.29390279,
                        "total_amount": 455.98,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2030-10-03",
                        "calendar_days": 30,
                        "due_date": "2030-10-02",
                        "due_principal": 1746.1410335,
                        "installment_number": 64,
                        "pre_fixed_amount": 30.20824171,
                        "principal_amortization_amount": 425.77175829,
                        "total_amount": 455.98,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2030-11-05",
                        "calendar_days": 31,
                        "due_date": "2030-11-02",
                        "due_principal": 1320.36927521,
                        "installment_number": 65,
                        "pre_fixed_amount": 23.61057098,
                        "principal_amortization_amount": 432.36942902,
                        "total_amount": 455.98,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2030-12-03",
                        "calendar_days": 30,
                        "due_date": "2030-12-02",
                        "due_principal": 887.99984619,
                        "installment_number": 66,
                        "pre_fixed_amount": 15.36239827,
                        "principal_amortization_amount": 440.61760173,
                        "total_amount": 455.98,
                        "workdays": 19
                    },
                    {
                        "business_due_date": "2031-01-03",
                        "calendar_days": 31,
                        "due_date": "2031-01-02",
                        "due_principal": 447.38224446,
                        "installment_number": 67,
                        "pre_fixed_amount": 8.59775554,
                        "principal_amortization_amount": 447.38224446,
                        "total_amount": 455.98,
                        "workdays": 21
                    }
                ],
                "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,
                "contract_fee_amount": 0,
                "contract_fees": [],
                "disbursed_issue_amount": 20373.27,
                "disbursement_date": "2025-06-02",
                "external_contract_fee_amount": 0,
                "external_contract_fees": [],
                "final_disbursement_amount": 2494.05,
                "installments": [
                    {
                        "business_due_date": "2025-07-03",
                        "calendar_days": 30,
                        "due_date": "2025-07-02",
                        "due_principal": 20458.57,
                        "installment_number": 1,
                        "pre_fixed_amount": 378.48354031,
                        "principal_amortization_amount": 82.99645969,
                        "total_amount": 461.48,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2025-08-05",
                        "calendar_days": 31,
                        "due_date": "2025-08-02",
                        "due_principal": 20375.57354031,
                        "installment_number": 2,
                        "pre_fixed_amount": 389.63243305,
                        "principal_amortization_amount": 71.84756695,
                        "total_amount": 461.48,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2025-09-03",
                        "calendar_days": 31,
                        "due_date": "2025-09-02",
                        "due_principal": 20303.72597336,
                        "installment_number": 3,
                        "pre_fixed_amount": 388.25852609,
                        "principal_amortization_amount": 73.22147391,
                        "total_amount": 461.48,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2025-10-03",
                        "calendar_days": 30,
                        "due_date": "2025-10-02",
                        "due_principal": 20230.50449945,
                        "installment_number": 4,
                        "pre_fixed_amount": 374.2643286,
                        "principal_amortization_amount": 87.2156714,
                        "total_amount": 461.48,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2025-11-04",
                        "calendar_days": 31,
                        "due_date": "2025-11-02",
                        "due_principal": 20143.28882805,
                        "installment_number": 5,
                        "pre_fixed_amount": 385.19056262,
                        "principal_amortization_amount": 76.28943738,
                        "total_amount": 461.48,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2025-12-03",
                        "calendar_days": 30,
                        "due_date": "2025-12-02",
                        "due_principal": 20066.99939067,
                        "installment_number": 6,
                        "pre_fixed_amount": 371.23948413,
                        "principal_amortization_amount": 90.24051587,
                        "total_amount": 461.48,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2026-01-05",
                        "calendar_days": 31,
                        "due_date": "2026-01-02",
                        "due_principal": 19976.7588748,
                        "installment_number": 7,
                        "pre_fixed_amount": 382.00608928,
                        "principal_amortization_amount": 79.47391072,
                        "total_amount": 461.48,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2026-02-03",
                        "calendar_days": 31,
                        "due_date": "2026-02-02",
                        "due_principal": 19897.28496408,
                        "installment_number": 8,
                        "pre_fixed_amount": 380.48634736,
                        "principal_amortization_amount": 80.99365264,
                        "total_amount": 461.48,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2026-03-03",
                        "calendar_days": 28,
                        "due_date": "2026-03-02",
                        "due_principal": 19816.29131144,
                        "installment_number": 9,
                        "pre_fixed_amount": 341.95166774,
                        "principal_amortization_amount": 119.52833226,
                        "total_amount": 461.48,
                        "workdays": 18
                    },
                    {
                        "business_due_date": "2026-04-06",
                        "calendar_days": 31,
                        "due_date": "2026-04-02",
                        "due_principal": 19696.76297918,
                        "installment_number": 10,
                        "pre_fixed_amount": 376.65186051,
                        "principal_amortization_amount": 84.82813949,
                        "total_amount": 461.48,
                        "workdays": 23
                    },
                    {
                        "business_due_date": "2026-05-05",
                        "calendar_days": 30,
                        "due_date": "2026-05-02",
                        "due_principal": 19611.93483969,
                        "installment_number": 11,
                        "pre_fixed_amount": 362.82079004,
                        "principal_amortization_amount": 98.65920996,
                        "total_amount": 461.48,
                        "workdays": 18
                    },
                    {
                        "business_due_date": "2026-06-03",
                        "calendar_days": 31,
                        "due_date": "2026-06-02",
                        "due_principal": 19513.27562973,
                        "installment_number": 12,
                        "pre_fixed_amount": 373.14311891,
                        "principal_amortization_amount": 88.33688109,
                        "total_amount": 461.48,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2026-07-03",
                        "calendar_days": 30,
                        "due_date": "2026-07-02",
                        "due_principal": 19424.93874864,
                        "installment_number": 13,
                        "pre_fixed_amount": 359.3613624,
                        "principal_amortization_amount": 102.1186376,
                        "total_amount": 461.48,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2026-08-04",
                        "calendar_days": 31,
                        "due_date": "2026-08-02",
                        "due_principal": 19322.82011104,
                        "installment_number": 14,
                        "pre_fixed_amount": 369.50112832,
                        "principal_amortization_amount": 91.97887168,
                        "total_amount": 461.48,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2026-09-03",
                        "calendar_days": 31,
                        "due_date": "2026-09-02",
                        "due_principal": 19230.84123936,
                        "installment_number": 15,
                        "pre_fixed_amount": 367.74225996,
                        "principal_amortization_amount": 93.73774004,
                        "total_amount": 461.48,
                        "workdays": 23
                    },
                    {
                        "business_due_date": "2026-10-05",
                        "calendar_days": 30,
                        "due_date": "2026-10-02",
                        "due_principal": 19137.10349932,
                        "installment_number": 16,
                        "pre_fixed_amount": 354.03641035,
                        "principal_amortization_amount": 107.44358965,
                        "total_amount": 461.48,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2026-11-04",
                        "calendar_days": 31,
                        "due_date": "2026-11-02",
                        "due_principal": 19029.65990967,
                        "installment_number": 17,
                        "pre_fixed_amount": 363.89516477,
                        "principal_amortization_amount": 97.58483523,
                        "total_amount": 461.48,
                        "workdays": 19
                    },
                    {
                        "business_due_date": "2026-12-03",
                        "calendar_days": 30,
                        "due_date": "2026-12-02",
                        "due_principal": 18932.07507444,
                        "installment_number": 18,
                        "pre_fixed_amount": 350.24338454,
                        "principal_amortization_amount": 111.23661546,
                        "total_amount": 461.48,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2027-01-05",
                        "calendar_days": 31,
                        "due_date": "2027-01-02",
                        "due_principal": 18820.83845898,
                        "installment_number": 19,
                        "pre_fixed_amount": 359.90197117,
                        "principal_amortization_amount": 101.57802883,
                        "total_amount": 461.48,
                        "workdays": 20
                    },
                    {
                        "business_due_date": "2027-02-03",
                        "calendar_days": 31,
                        "due_date": "2027-02-02",
                        "due_principal": 18719.26043015,
                        "installment_number": 20,
                        "pre_fixed_amount": 357.95954268,
                        "principal_amortization_amount": 103.52045732,
                        "total_amount": 461.48,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2027-03-03",
                        "calendar_days": 28,
                        "due_date": "2027-03-02",
                        "due_principal": 18615.73997283,
                        "installment_number": 21,
                        "pre_fixed_amount": 321.23484813,
                        "principal_amortization_amount": 140.24515187,
                        "total_amount": 461.48,
                        "workdays": 18
                    },
                    {
                        "business_due_date": "2027-04-05",
                        "calendar_days": 31,
                        "due_date": "2027-04-02",
                        "due_principal": 18475.49482096,
                        "installment_number": 22,
                        "pre_fixed_amount": 353.2981285,
                        "principal_amortization_amount": 108.1818715,
                        "total_amount": 461.48,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2027-05-04",
                        "calendar_days": 30,
                        "due_date": "2027-05-02",
                        "due_principal": 18367.31294946,
                        "installment_number": 23,
                        "pre_fixed_amount": 339.79528536,
                        "principal_amortization_amount": 121.68471464,
                        "total_amount": 461.48,
                        "workdays": 19
                    },
                    {
                        "business_due_date": "2027-06-03",
                        "calendar_days": 31,
                        "due_date": "2027-06-02",
                        "due_principal": 18245.62823482,
                        "installment_number": 24,
                        "pre_fixed_amount": 348.90249875,
                        "principal_amortization_amount": 112.57750125,
                        "total_amount": 461.48,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2027-07-05",
                        "calendar_days": 30,
                        "due_date": "2027-07-02",
                        "due_principal": 18133.05073357,
                        "installment_number": 25,
                        "pre_fixed_amount": 335.46143442,
                        "principal_amortization_amount": 126.01856558,
                        "total_amount": 461.48,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2027-08-03",
                        "calendar_days": 31,
                        "due_date": "2027-08-02",
                        "due_principal": 18007.03216799,
                        "installment_number": 26,
                        "pre_fixed_amount": 344.33993928,
                        "principal_amortization_amount": 117.14006072,
                        "total_amount": 461.48,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2027-09-03",
                        "calendar_days": 31,
                        "due_date": "2027-09-02",
                        "due_principal": 17889.89210727,
                        "installment_number": 27,
                        "pre_fixed_amount": 342.09992543,
                        "principal_amortization_amount": 119.38007457,
                        "total_amount": 461.48,
                        "workdays": 23
                    },
                    {
                        "business_due_date": "2027-10-05",
                        "calendar_days": 30,
                        "due_date": "2027-10-02",
                        "due_principal": 17770.5120327,
                        "installment_number": 28,
                        "pre_fixed_amount": 328.75446853,
                        "principal_amortization_amount": 132.72553147,
                        "total_amount": 461.48,
                        "workdays": 20
                    },
                    {
                        "business_due_date": "2027-11-04",
                        "calendar_days": 31,
                        "due_date": "2027-11-02",
                        "due_principal": 17637.78650123,
                        "installment_number": 29,
                        "pre_fixed_amount": 337.27902945,
                        "principal_amortization_amount": 124.20097055,
                        "total_amount": 461.48,
                        "workdays": 20
                    },
                    {
                        "business_due_date": "2027-12-03",
                        "calendar_days": 30,
                        "due_date": "2027-12-02",
                        "due_principal": 17513.58553068,
                        "installment_number": 30,
                        "pre_fixed_amount": 324.0013283,
                        "principal_amortization_amount": 137.4786717,
                        "total_amount": 461.48,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2028-01-04",
                        "calendar_days": 31,
                        "due_date": "2028-01-02",
                        "due_principal": 17376.10685898,
                        "installment_number": 31,
                        "pre_fixed_amount": 332.27505371,
                        "principal_amortization_amount": 129.20494629,
                        "total_amount": 461.48,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2028-02-03",
                        "calendar_days": 31,
                        "due_date": "2028-02-02",
                        "due_principal": 17246.90191269,
                        "installment_number": 32,
                        "pre_fixed_amount": 329.80432878,
                        "principal_amortization_amount": 131.67567122,
                        "total_amount": 461.48,
                        "workdays": 23
                    },
                    {
                        "business_due_date": "2028-03-03",
                        "calendar_days": 29,
                        "due_date": "2028-03-02",
                        "due_principal": 17115.22624147,
                        "installment_number": 33,
                        "pre_fixed_amount": 305.98351411,
                        "principal_amortization_amount": 155.49648589,
                        "total_amount": 461.48,
                        "workdays": 19
                    },
                    {
                        "business_due_date": "2028-04-04",
                        "calendar_days": 31,
                        "due_date": "2028-04-02",
                        "due_principal": 16959.72975558,
                        "installment_number": 34,
                        "pre_fixed_amount": 324.31287176,
                        "principal_amortization_amount": 137.16712824,
                        "total_amount": 461.48,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2028-05-03",
                        "calendar_days": 30,
                        "due_date": "2028-05-02",
                        "due_principal": 16822.56262734,
                        "installment_number": 35,
                        "pre_fixed_amount": 311.21740475,
                        "principal_amortization_amount": 150.26259525,
                        "total_amount": 461.48,
                        "workdays": 19
                    },
                    {
                        "business_due_date": "2028-06-05",
                        "calendar_days": 31,
                        "due_date": "2028-06-02",
                        "due_principal": 16672.30003209,
                        "installment_number": 36,
                        "pre_fixed_amount": 318.81648942,
                        "principal_amortization_amount": 142.66351058,
                        "total_amount": 461.48,
                        "workdays": 23
                    },
                    {
                        "business_due_date": "2028-07-04",
                        "calendar_days": 30,
                        "due_date": "2028-07-02",
                        "due_principal": 16529.63652151,
                        "installment_number": 37,
                        "pre_fixed_amount": 305.79827186,
                        "principal_amortization_amount": 155.68172814,
                        "total_amount": 461.48,
                        "workdays": 19
                    },
                    {
                        "business_due_date": "2028-08-03",
                        "calendar_days": 31,
                        "due_date": "2028-08-02",
                        "due_principal": 16373.95479337,
                        "installment_number": 38,
                        "pre_fixed_amount": 313.11137486,
                        "principal_amortization_amount": 148.36862514,
                        "total_amount": 461.48,
                        "workdays": 23
                    },
                    {
                        "business_due_date": "2028-09-05",
                        "calendar_days": 31,
                        "due_date": "2028-09-02",
                        "due_principal": 16225.58616823,
                        "installment_number": 39,
                        "pre_fixed_amount": 310.27419199,
                        "principal_amortization_amount": 151.20580801,
                        "total_amount": 461.48,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2028-10-03",
                        "calendar_days": 30,
                        "due_date": "2028-10-02",
                        "due_principal": 16074.38036022,
                        "installment_number": 40,
                        "pre_fixed_amount": 297.37603298,
                        "principal_amortization_amount": 164.10396702,
                        "total_amount": 461.48,
                        "workdays": 20
                    },
                    {
                        "business_due_date": "2028-11-06",
                        "calendar_days": 31,
                        "due_date": "2028-11-02",
                        "due_principal": 15910.2763932,
                        "installment_number": 41,
                        "pre_fixed_amount": 304.24467264,
                        "principal_amortization_amount": 157.23532736,
                        "total_amount": 461.48,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2028-12-05",
                        "calendar_days": 30,
                        "due_date": "2028-12-02",
                        "due_principal": 15753.04106584,
                        "installment_number": 42,
                        "pre_fixed_amount": 291.43125611,
                        "principal_amortization_amount": 170.04874389,
                        "total_amount": 461.48,
                        "workdays": 19
                    },
                    {
                        "business_due_date": "2029-01-03",
                        "calendar_days": 31,
                        "due_date": "2029-01-02",
                        "due_principal": 15582.99232195,
                        "installment_number": 43,
                        "pre_fixed_amount": 297.98617451,
                        "principal_amortization_amount": 163.49382549,
                        "total_amount": 461.48,
                        "workdays": 20
                    },
                    {
                        "business_due_date": "2029-02-05",
                        "calendar_days": 31,
                        "due_date": "2029-02-02",
                        "due_principal": 15419.49849646,
                        "installment_number": 44,
                        "pre_fixed_amount": 294.85975959,
                        "principal_amortization_amount": 166.62024041,
                        "total_amount": 461.48,
                        "workdays": 23
                    },
                    {
                        "business_due_date": "2029-03-05",
                        "calendar_days": 28,
                        "due_date": "2029-03-02",
                        "due_principal": 15252.87825605,
                        "installment_number": 45,
                        "pre_fixed_amount": 263.20501023,
                        "principal_amortization_amount": 198.27498977,
                        "total_amount": 461.48,
                        "workdays": 18
                    },
                    {
                        "business_due_date": "2029-04-03",
                        "calendar_days": 31,
                        "due_date": "2029-04-02",
                        "due_principal": 15054.60326628,
                        "installment_number": 46,
                        "pre_fixed_amount": 287.8820411,
                        "principal_amortization_amount": 173.5979589,
                        "total_amount": 461.48,
                        "workdays": 20
                    },
                    {
                        "business_due_date": "2029-05-03",
                        "calendar_days": 30,
                        "due_date": "2029-05-02",
                        "due_principal": 14881.00530738,
                        "installment_number": 47,
                        "pre_fixed_amount": 275.29859478,
                        "principal_amortization_amount": 186.18140522,
                        "total_amount": 461.48,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2029-06-05",
                        "calendar_days": 31,
                        "due_date": "2029-06-02",
                        "due_principal": 14694.82390216,
                        "installment_number": 48,
                        "pre_fixed_amount": 281.00215088,
                        "principal_amortization_amount": 180.47784912,
                        "total_amount": 461.48,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2029-07-03",
                        "calendar_days": 30,
                        "due_date": "2029-07-02",
                        "due_principal": 14514.34605304,
                        "installment_number": 49,
                        "pre_fixed_amount": 268.51539866,
                        "principal_amortization_amount": 192.96460134,
                        "total_amount": 461.48,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2029-08-03",
                        "calendar_days": 31,
                        "due_date": "2029-08-02",
                        "due_principal": 14321.3814517,
                        "installment_number": 50,
                        "pre_fixed_amount": 273.86098795,
                        "principal_amortization_amount": 187.61901205,
                        "total_amount": 461.48,
                        "workdays": 23
                    },
                    {
                        "business_due_date": "2029-09-04",
                        "calendar_days": 31,
                        "due_date": "2029-09-02",
                        "due_principal": 14133.76243965,
                        "installment_number": 51,
                        "pre_fixed_amount": 270.27323853,
                        "principal_amortization_amount": 191.20676147,
                        "total_amount": 461.48,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2029-10-03",
                        "calendar_days": 30,
                        "due_date": "2029-10-02",
                        "due_principal": 13942.55567818,
                        "installment_number": 52,
                        "pre_fixed_amount": 257.93727685,
                        "principal_amortization_amount": 203.54272315,
                        "total_amount": 461.48,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2029-11-06",
                        "calendar_days": 31,
                        "due_date": "2029-11-02",
                        "due_principal": 13739.01295503,
                        "installment_number": 53,
                        "pre_fixed_amount": 262.72463128,
                        "principal_amortization_amount": 198.75536872,
                        "total_amount": 461.48,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2029-12-04",
                        "calendar_days": 30,
                        "due_date": "2029-12-02",
                        "due_principal": 13540.25758631,
                        "installment_number": 54,
                        "pre_fixed_amount": 250.49476224,
                        "principal_amortization_amount": 210.98523776,
                        "total_amount": 461.48,
                        "workdays": 18
                    },
                    {
                        "business_due_date": "2030-01-03",
                        "calendar_days": 31,
                        "due_date": "2030-01-02",
                        "due_principal": 13329.27234855,
                        "installment_number": 55,
                        "pre_fixed_amount": 254.88935591,
                        "principal_amortization_amount": 206.59064409,
                        "total_amount": 461.48,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2030-02-05",
                        "calendar_days": 31,
                        "due_date": "2030-02-02",
                        "due_principal": 13122.68170446,
                        "installment_number": 56,
                        "pre_fixed_amount": 250.93882097,
                        "principal_amortization_amount": 210.54117903,
                        "total_amount": 461.48,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2030-03-07",
                        "calendar_days": 28,
                        "due_date": "2030-03-02",
                        "due_principal": 12912.14052543,
                        "installment_number": 57,
                        "pre_fixed_amount": 222.81303385,
                        "principal_amortization_amount": 238.66696615,
                        "total_amount": 461.48,
                        "workdays": 20
                    },
                    {
                        "business_due_date": "2030-04-03",
                        "calendar_days": 31,
                        "due_date": "2030-04-02",
                        "due_principal": 12673.47355928,
                        "installment_number": 58,
                        "pre_fixed_amount": 242.34882657,
                        "principal_amortization_amount": 219.13117343,
                        "total_amount": 461.48,
                        "workdays": 20
                    },
                    {
                        "business_due_date": "2030-05-03",
                        "calendar_days": 30,
                        "due_date": "2030-05-02",
                        "due_principal": 12454.34238585,
                        "installment_number": 59,
                        "pre_fixed_amount": 230.40533128,
                        "principal_amortization_amount": 231.07466872,
                        "total_amount": 461.48,
                        "workdays": 20
                    },
                    {
                        "business_due_date": "2030-06-04",
                        "calendar_days": 31,
                        "due_date": "2030-06-02",
                        "due_principal": 12223.26771713,
                        "installment_number": 60,
                        "pre_fixed_amount": 233.73975368,
                        "principal_amortization_amount": 227.74024632,
                        "total_amount": 461.48,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2030-07-03",
                        "calendar_days": 30,
                        "due_date": "2030-07-02",
                        "due_principal": 11995.52747081,
                        "installment_number": 61,
                        "pre_fixed_amount": 221.91725546,
                        "principal_amortization_amount": 239.56274454,
                        "total_amount": 461.48,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2030-08-05",
                        "calendar_days": 31,
                        "due_date": "2030-08-02",
                        "due_principal": 11755.96472627,
                        "installment_number": 62,
                        "pre_fixed_amount": 224.80374013,
                        "principal_amortization_amount": 236.67625987,
                        "total_amount": 461.48,
                        "workdays": 23
                    },
                    {
                        "business_due_date": "2030-09-03",
                        "calendar_days": 31,
                        "due_date": "2030-09-02",
                        "due_principal": 11519.2884664,
                        "installment_number": 63,
                        "pre_fixed_amount": 220.27789222,
                        "principal_amortization_amount": 241.20210778,
                        "total_amount": 461.48,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2030-10-03",
                        "calendar_days": 30,
                        "due_date": "2030-10-02",
                        "due_principal": 11278.08635862,
                        "installment_number": 64,
                        "pre_fixed_amount": 208.64459505,
                        "principal_amortization_amount": 252.83540495,
                        "total_amount": 461.48,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2030-11-05",
                        "calendar_days": 31,
                        "due_date": "2030-11-02",
                        "due_principal": 11025.25095367,
                        "installment_number": 65,
                        "pre_fixed_amount": 210.83064708,
                        "principal_amortization_amount": 250.64935292,
                        "total_amount": 461.48,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2030-12-03",
                        "calendar_days": 30,
                        "due_date": "2030-12-02",
                        "due_principal": 10774.60160075,
                        "installment_number": 66,
                        "pre_fixed_amount": 199.33012714,
                        "principal_amortization_amount": 262.14987286,
                        "total_amount": 461.48,
                        "workdays": 19
                    },
                    {
                        "business_due_date": "2031-01-03",
                        "calendar_days": 31,
                        "due_date": "2031-01-02",
                        "due_principal": 10512.45172789,
                        "installment_number": 67,
                        "pre_fixed_amount": 201.02463059,
                        "principal_amortization_amount": 260.45536941,
                        "total_amount": 461.48,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2031-02-04",
                        "calendar_days": 31,
                        "due_date": "2031-02-02",
                        "due_principal": 10251.99635848,
                        "installment_number": 68,
                        "pre_fixed_amount": 196.04406604,
                        "principal_amortization_amount": 265.43593396,
                        "total_amount": 461.48,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2031-03-04",
                        "calendar_days": 28,
                        "due_date": "2031-03-02",
                        "due_principal": 9986.56042452,
                        "installment_number": 69,
                        "pre_fixed_amount": 172.32896602,
                        "principal_amortization_amount": 289.15103398,
                        "total_amount": 461.48,
                        "workdays": 18
                    },
                    {
                        "business_due_date": "2031-04-03",
                        "calendar_days": 31,
                        "due_date": "2031-04-02",
                        "due_principal": 9697.40939054,
                        "installment_number": 70,
                        "pre_fixed_amount": 185.43896238,
                        "principal_amortization_amount": 276.04103762,
                        "total_amount": 461.48,
                        "workdays": 23
                    },
                    {
                        "business_due_date": "2031-05-05",
                        "calendar_days": 30,
                        "due_date": "2031-05-02",
                        "due_principal": 9421.36835292,
                        "installment_number": 71,
                        "pre_fixed_amount": 174.29531237,
                        "principal_amortization_amount": 287.18468763,
                        "total_amount": 461.48,
                        "workdays": 19
                    },
                    {
                        "business_due_date": "2031-06-03",
                        "calendar_days": 31,
                        "due_date": "2031-06-02",
                        "due_principal": 9134.18366529,
                        "installment_number": 72,
                        "pre_fixed_amount": 174.66866385,
                        "principal_amortization_amount": 286.81133615,
                        "total_amount": 461.48,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2031-07-03",
                        "calendar_days": 30,
                        "due_date": "2031-07-02",
                        "due_principal": 8847.37232914,
                        "installment_number": 73,
                        "pre_fixed_amount": 163.67638606,
                        "principal_amortization_amount": 297.80361394,
                        "total_amount": 461.48,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2031-08-05",
                        "calendar_days": 31,
                        "due_date": "2031-08-02",
                        "due_principal": 8549.5687152,
                        "installment_number": 74,
                        "pre_fixed_amount": 163.48934932,
                        "principal_amortization_amount": 297.99065068,
                        "total_amount": 461.48,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2031-09-03",
                        "calendar_days": 31,
                        "due_date": "2031-09-02",
                        "due_principal": 8251.57806452,
                        "installment_number": 75,
                        "pre_fixed_amount": 157.79101538,
                        "principal_amortization_amount": 303.68898462,
                        "total_amount": 461.48,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2031-10-03",
                        "calendar_days": 30,
                        "due_date": "2031-10-02",
                        "due_principal": 7947.8890799,
                        "installment_number": 76,
                        "pre_fixed_amount": 147.03594616,
                        "principal_amortization_amount": 314.44405384,
                        "total_amount": 461.48,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2031-11-04",
                        "calendar_days": 31,
                        "due_date": "2031-11-02",
                        "due_principal": 7633.44502606,
                        "installment_number": 77,
                        "pre_fixed_amount": 145.97075033,
                        "principal_amortization_amount": 315.50924967,
                        "total_amount": 461.48,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2031-12-03",
                        "calendar_days": 30,
                        "due_date": "2031-12-02",
                        "due_principal": 7317.93577639,
                        "installment_number": 78,
                        "pre_fixed_amount": 135.38181019,
                        "principal_amortization_amount": 326.09818981,
                        "total_amount": 461.48,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2032-01-05",
                        "calendar_days": 31,
                        "due_date": "2032-01-02",
                        "due_principal": 6991.83758658,
                        "installment_number": 79,
                        "pre_fixed_amount": 133.70159544,
                        "principal_amortization_amount": 327.77840456,
                        "total_amount": 461.48,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2032-02-03",
                        "calendar_days": 31,
                        "due_date": "2032-02-02",
                        "due_principal": 6664.05918202,
                        "installment_number": 80,
                        "pre_fixed_amount": 127.43364441,
                        "principal_amortization_amount": 334.04635559,
                        "total_amount": 461.48,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2032-03-03",
                        "calendar_days": 29,
                        "due_date": "2032-03-02",
                        "due_principal": 6330.01282643,
                        "installment_number": 81,
                        "pre_fixed_amount": 113.16704446,
                        "principal_amortization_amount": 348.31295554,
                        "total_amount": 461.48,
                        "workdays": 19
                    },
                    {
                        "business_due_date": "2032-04-05",
                        "calendar_days": 31,
                        "due_date": "2032-04-02",
                        "due_principal": 5981.69987089,
                        "installment_number": 82,
                        "pre_fixed_amount": 114.3852108,
                        "principal_amortization_amount": 347.0947892,
                        "total_amount": 461.48,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2032-05-04",
                        "calendar_days": 30,
                        "due_date": "2032-05-02",
                        "due_principal": 5634.60508169,
                        "installment_number": 83,
                        "pre_fixed_amount": 104.24019272,
                        "principal_amortization_amount": 357.23980728,
                        "total_amount": 461.48,
                        "workdays": 19
                    },
                    {
                        "business_due_date": "2032-06-03",
                        "calendar_days": 31,
                        "due_date": "2032-06-02",
                        "due_principal": 5277.36527441,
                        "installment_number": 84,
                        "pre_fixed_amount": 100.91655422,
                        "principal_amortization_amount": 360.56344578,
                        "total_amount": 461.48,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2032-07-05",
                        "calendar_days": 30,
                        "due_date": "2032-07-02",
                        "due_principal": 4916.80182863,
                        "installment_number": 85,
                        "pre_fixed_amount": 90.9608327,
                        "principal_amortization_amount": 370.5191673,
                        "total_amount": 461.48,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2032-08-03",
                        "calendar_days": 31,
                        "due_date": "2032-08-02",
                        "due_principal": 4546.28266133,
                        "installment_number": 86,
                        "pre_fixed_amount": 86.93640801,
                        "principal_amortization_amount": 374.54359199,
                        "total_amount": 461.48,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2032-09-03",
                        "calendar_days": 31,
                        "due_date": "2032-09-02",
                        "due_principal": 4171.73906934,
                        "installment_number": 87,
                        "pre_fixed_amount": 79.77418846,
                        "principal_amortization_amount": 381.70581154,
                        "total_amount": 461.48,
                        "workdays": 23
                    },
                    {
                        "business_due_date": "2032-10-05",
                        "calendar_days": 30,
                        "due_date": "2032-10-02",
                        "due_principal": 3790.0332578,
                        "installment_number": 88,
                        "pre_fixed_amount": 70.1156144,
                        "principal_amortization_amount": 391.3643856,
                        "total_amount": 461.48,
                        "workdays": 20
                    },
                    {
                        "business_due_date": "2032-11-04",
                        "calendar_days": 31,
                        "due_date": "2032-11-02",
                        "due_principal": 3398.6688722,
                        "installment_number": 89,
                        "pre_fixed_amount": 64.99113358,
                        "principal_amortization_amount": 396.48886642,
                        "total_amount": 461.48,
                        "workdays": 20
                    },
                    {
                        "business_due_date": "2032-12-03",
                        "calendar_days": 30,
                        "due_date": "2032-12-02",
                        "due_principal": 3002.18000578,
                        "installment_number": 90,
                        "pre_fixed_amount": 55.54032942,
                        "principal_amortization_amount": 405.93967058,
                        "total_amount": 461.48,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2033-01-04",
                        "calendar_days": 31,
                        "due_date": "2033-01-02",
                        "due_principal": 2596.2403352,
                        "installment_number": 91,
                        "pre_fixed_amount": 49.64667309,
                        "principal_amortization_amount": 411.83332691,
                        "total_amount": 461.48,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2033-02-03",
                        "calendar_days": 31,
                        "due_date": "2033-02-02",
                        "due_principal": 2184.40700829,
                        "installment_number": 92,
                        "pre_fixed_amount": 41.77137962,
                        "principal_amortization_amount": 419.70862038,
                        "total_amount": 461.48,
                        "workdays": 23
                    },
                    {
                        "business_due_date": "2033-03-03",
                        "calendar_days": 28,
                        "due_date": "2033-03-02",
                        "due_principal": 1764.69838791,
                        "installment_number": 93,
                        "pre_fixed_amount": 30.45179077,
                        "principal_amortization_amount": 431.02820923,
                        "total_amount": 461.48,
                        "workdays": 18
                    },
                    {
                        "business_due_date": "2033-04-05",
                        "calendar_days": 31,
                        "due_date": "2033-04-02",
                        "due_principal": 1333.67017868,
                        "installment_number": 94,
                        "pre_fixed_amount": 25.50314255,
                        "principal_amortization_amount": 435.97685745,
                        "total_amount": 461.48,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2033-05-03",
                        "calendar_days": 30,
                        "due_date": "2033-05-02",
                        "due_principal": 897.69332123,
                        "installment_number": 95,
                        "pre_fixed_amount": 16.60732624,
                        "principal_amortization_amount": 444.87267376,
                        "total_amount": 461.48,
                        "workdays": 19
                    },
                    {
                        "business_due_date": "2033-06-03",
                        "calendar_days": 31,
                        "due_date": "2033-06-02",
                        "due_principal": 452.82064747,
                        "installment_number": 96,
                        "pre_fixed_amount": 8.65935253,
                        "principal_amortization_amount": 452.82064747,
                        "total_amount": 461.48,
                        "workdays": 23
                    }
                ],
                "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
对于纯转移提案数据的恢复，"refinancing_credit_operation" 对象将不会被返回。
:::

### 带新 CCB 签名的再融资数据更正：
在再融资尚未被接受之前，可以更正再融资操作的财务数据和银行数据。

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 
再融资操作键、文档键、文档 URL、related_party_key 和借款人 related_party_key 将在此操作后更改，需要重新签署 CCB。
:::

### 再融资数据更正：
可以重新计算再融资操作的分期金额而无需生成新的 CCB。新金额将根据录入时提供的利率，应用于当前未偿余额来计算。

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"
	}
}

```

### 转移和再融资数据更正：
可以更正银行数据、福利编号和姓名，直到转移合同状态变为 "pending_response" 之前。

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"
}
```

### 在沙盒中模拟背书的成功和失败场景：
场景模拟基于操作中提供的 CPF 第一位数字。

**11.1.** 对于以数字 1 开头的 CPF，将通过 Webhook 返回异步成功响应。

**11.2.** 对于其他 CPF，将根据输入的 CPF 第一位数字，按照下表返回异步错误响应。

**11.3.** 操作为 "cancel" 的错误将收到包含操作最终结果的 webhook。

| 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
所有未映射到第一位数字场景的 CPF，将收到一个包含未映射测试场景标准错误的 webhook。

| Enumerador    | Descrição                                                        |
|---------------|------------------------------------------------------------------|
| mock_error    | Informed document number is not a valid mock on test environment |
:::
---

## 4 - 文件上传

根据 INSS 第 138 号规范性指令，必须发送合同的补充数据。

文件必须通过[文件上传端点](../upload_de_documentos)发送。

| Validações     | Valores      |
|----------------|--------------|
| Formato        | JPEG         |
| Tamanho mínimo | 250 x 250 px |
| Tamanho máximo |     2 MB     |

:::caution Atenção
不符合最小或最大文件大小规则的合同，将无法背书，相应的错误信息将通过 webhook 发送。

如果验证未通过，当合作方在收到未偿余额后继续处理提案时，将返回以下错误：

**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"
}
```

文件上传后，所上传文件的键值必须在创建提案的 payload 中（在 *borrower* 字段内）或在对应法定代理人的 *related_parties** 对象内（*"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"
}
```

或者，在提案创建后，可通过以下端点告知：

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
**related_party_key** 在债务创建响应的 **borrower** 对象中返回，用于将文件关联到相关人员（借款人或法定代理人）。

---

## 5 - 模拟转移和/或再融资提案：

:::caution Atenção
对于涉及再融资后找零的提案，需要预先计算找零金额，该金额至少应为所有分期金额现值之和与原始债务余额之差的 5%。可以通过使用第 **5** 条中描述的模拟路由来确定找零金额。

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."
}

```
:::

        **5.1. 带再融资的转移模拟：** 
在录入带再融资的转移提案之前，可以模拟操作的财务条件。

        **5.1.1. 带再融资的转移模拟 - 固定利率：**
与提案录入（3.1.1）类似，可以通过固定转移合同利率进行模拟。

        **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
上述 payload 描述了执行模拟所需的最低数据。
:::

        **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
    }
}

```

        **5.1.2. 带再融资的转移模拟 - 固定释放金额：** 
与提案录入（**3.1.2**）类似，可以通过固定向客户释放的金额进行模拟：

        **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
		}]
	}
}

```

    **5.2. 转移模拟：**
也可以模拟无再融资的转移提案（纯转移）的财务条件，无需采集客户注册数据。

        **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
		}]
	}
}

```
 

--- 

## 6 - 提案正式化：

:::caution 注意
对于涉及再融资后找零的提案，需要预先计算找零金额，根据合同条件，该金额至少应为所有再融资分期金额之和减去所有转移分期金额之和的 5%。否则，请求将收到以下错误：

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."
}

```
:::

        要正式化转移和/或再融资（找零）操作，必须发送提案录入时生成的合同签署证明。

**签署 payload 中必须包含第 4 条中发送的文件相关必填字段。必填字段如下：_ip_address_ 和 _signature_datetime_。**

        **6.1.** 合作方需发起以下调用以签署转移操作：

        **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**    | 当 similarity_score 通过查询 SERPRO 数据库返回时使用。 |
| **tse**       | 当 similarity_score 通过查询 TSE 数据库返回时使用。 |
| **not_found** | 当面部生物识别在任何数据库（SERPRO 或 TSE）中均未找到时使用。 |

        签署完成将以异步方式通知：

        **Webhook**

- WEBHOOK_TYPE credit_transfer.proposal.credit_operation

        *Body:*

**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.** 合作方需发起以下调用以签署再融资操作（找零）：

        **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"
}
```

        签署完成将以异步方式通知：

        **Webhook**

- WEBHOOK_TYPE credit_transfer.proposal.credit_operation

        *Body:*

**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"
	}
}

```

 
--- 
 

## 7 - 转移提案状态机：

    转移提案的状态反映了 CIP 信贷转移中心（CTC）内信贷转移流程所涉及的各个阶段。
以下是转移提案中每个状态的流程说明：

        **7.1. pending_response:**
录入后的提案状态。在此状态下，提案已被 QI 成功接收并发送至 CTC - CIP。

                **6.1.1 rejected:** 
如果提案录入被 CTC - CIP 拒绝，将发送包含拒绝原因的 webhook：

        **Webhook**

- WEBHOOK_TYPE credit_transfer.proposal
- STATUS rejected

        *Body:*

**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:** 
如果提案录入被 CTC - CIP 拒绝，将发送包含拒绝原因的 webhook：

 
| reason                             | description                                                                                                                   | external_code |
|------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|---------------|
| portability_in_progress            | 转移进行中的合同                                                                                       | ECTC0023      |
| portability_finished               | 所指定合同的转移已完成                                                                         | ECTC0028      |
| portability_in_expiration_progress | 不允许转移。合同转移因未完成转移而处于"到期流程"状态 | 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：** CTC - CIP 发送/接受后的提案状态。提案此时正在等待原始债权银行的未偿余额响应。此时将发送包含 CTC - CIP 转移编号的 webhook：

        **Webhook**

- WEBHOOK_TYPE credit_transfer.proposal
- STATUS pending_acceptance

        *Body:*

**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
**"portability_number"** 是 CTC - CIP 内的转移编号，是提案机构和原始债权机构用于识别转移操作的编号。
:::

        一旦原始债权银行响应转移申请，将发送以下 webhook 并通知未偿余额。

    **7.2.1. accepted：** 当原始债权银行返回未偿余额且不保留信贷时的提案状态。将发送包含未偿余额信息的 webhook。
原始债权银行在收到转移提案后，有最多 5 个工作日向承接银行（QI Tech）发送响应。

        **Webhook**

- WEBHOOK_TYPE credit_transfer.proposal
- STATUS accepted

        *Body:*

**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"
		}
	}
}
```

        收到原始债权机构返回的未偿余额信息后，合作方必须在 **5** 个工作日内明确表示是否接受该余额。如果合作方选择接受，则进行如下调用：

:::info
原始债权机构发送未偿余额的截止时间为 10:00。
:::

        收到未偿余额后，如果合作方决定继续推进提案，必须在 **5** 个工作日内接受该余额。接受时，合作方必须在 payload 中提供财务条件和放款账户。

        **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
对于涉及再融资后找零的提案，根据合同的新条件，找零金额至少应为所有再融资分期金额之和减去所有转移分期金额之和的 5%。

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."
}

```
::: 

        合作方可以在此调用中添加新的分期金额或新利率数据（如需更改）：

        **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 附加可选字段
除 `status` 和 `financial` 字段外，提案接受端点还接受以下可选字段：
- **`borrower.document_identification_type`** (string 或 null)：身份证件类型
- **`borrower.document_identification_number`** (string，最多 16 个字符)：身份证件号码
- **`borrower.gender`** (string 或 null)：借款人性别。可接受值：`"male"`、`"female"` 或 `null`
- **`credit_agent`** (对象)：信贷代理人，含 `name`（string，最多 100 个字符）和 `document_number`（string，11 或 14 位数字）
:::

:::danger Atenção!
如果分期金额超过总可用金额（原始合同分期金额 + 福利总可用边际），
将返回以下错误： 
```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"
}

```
收到此错误后，可以重新调用接口，修改分期金额以适配总可用金额。

如果在未偿余额接受截止时间前未调整分期金额，则需要重新录入提案。
:::

        如果合作方决定不继续推进转移提案，则**必须**发起以下调用以告知放弃转移：

        **Request**

- MÉTODO DELETE
- ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY

Testar no Playground

        向 CTC - CIP 发送转移提案取消后，将发送提案取消 webhook：

        **Webhook**

- WEBHOOK_TYPE credit_transfer.proposal
- STATUS canceled

        *Body:*

**body.json**

```json

{
    "webhook_type": "credit_transfer.proposal",
    "proposal_status": "canceled",
    "proposal_key": "\<PROPOSAL-KEY\>",
    "event_datetime": "2022-11-24T15:42:12"
}

```

:::info
未偿余额接受截止时间为 16:30。
无法恢复状态为 "canceled" 的提案。如果提案处于此状态，需要重新录入。
:::
 

        **7.2.2. retained：** 当原始债权银行保留信贷时的提案状态，将发送包含保留信息的 webhook。原始债权银行在收到转移提案后，有最多 2 个工作日发送信贷保留响应。

        **Webhook**

- WEBHOOK_TYPE credit_transfer.proposal
- STATUS retained

        *Body:*

**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"
    }
  }
}
```

### 提案 webhook 字段详情
| 字段                     | 描述                           | 值                          |
|---------------------------|-------------------------------------|----------------------------------|
| reason                    | 提案保留原因列表  | [枚举值](#retention_reason_enumerator) |
 

        **7.3. accepted_by_requester：** 经合作方批准后，提案进入 QI 内部结算流程。

        **7.4. settlement_sent：** 
完成 QI 内部转移提案结算流程后，用于支付未偿余额的资金将发送至原始债权方，并向合作方触发以下 webhook：

        **Webhook**

- WEBHOOK_TYPE credit_transfer.proposal
- STATUS settlement_sent

        *Body:*

**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"
			}
		}
	}
}
```

此时将在 Dataprev 中启动转移操作的背书流程。背书流程将与以下步骤并行进行（第 7.5.、7.5.1. 和 7.5.2. 条）。

 

        **7.5. pending_settlement_confirmation：** 在 QI 收到 CTC - CIP 的资金转移确认信息后，将触发此 webhook，提案将转为此状态。

        **Webhook**

- WEBHOOK_TYPE credit_transfer.proposal
- STATUS pending_settlement_confirmation

        *Body:*

**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
原始债权机构将合同结清确认发送至 CTC - CIP，随后由 CTC - CIP 转发至 QI Tech。

O SLA 转移结清确认的 SLA 为 **2 个工作日**，从发送合同未偿余额支付资金起算。
:::
 
        **7.5.1. paid：** 一旦 QI 收到 CTC - CIP 的合同结清确认，提案将转为 "paid" 状态，并向合作方发送 webhook。

        **Webhook**

- WEBHOOK_TYPE credit_transfer.proposal
- STATUS paid

        *Body:*

**body.json**

```json

{
    "webhook_type": "credit_transfer.proposal",
    "proposal_key": "\<PROPOSAL-KEY\>",
    "proposal_status": "paid",
    "event_datetime": "2022-11-24T15:42:12"
}
```

        在此阶段，如果转移操作的背书已完成，合同将以 "paid" 状态结束；否则，合同将先转为 "pending_collateral_averbation" 状态，等待背书完成后再变为 "paid"。

        **7.5.1.1.** 转移操作背书通知将通过以下 webhook 发送：

        **Webhook**

- WEBHOOK_TYPE credit_transfer.proposal.collateral

        *Body:*

**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:** 
如果原始债权银行拒绝接受合同结清，发送用于结清合同未偿余额的资金将被退还给 QI Tech，提案将转为 "rejected" 状态。

        **Webhook**

- WEBHOOK_TYPE credit_transfer.proposal
- STATUS rejected

        *Body:*

**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."
        }
    }
}
```
 

        如果在此阶段转移操作已在 Dataprev 中背书，再融资操作（找零）将可以启动（第 8 条中描述的流程）。

:::info
无法恢复状态为 "**rejected**" 的提案。始终需要重新录入。
:::

--- 

## 8 - 再融资操作（找零）状态机：
        **8.1** 
当转移操作付款完成时，合作方可以选择是否继续推进再融资操作（找零）。

#### 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.** 要继续推进再融资（找零），合作方需发起以下调用并传递 'Financial' 和 'Disbursement Bank Accounts' 字段：

*此外，可以传递 'purchaser_document_number' 字段以更改操作的受让方。

        **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.** 如果合作方选择不继续推进再融资操作（找零），需发起以下调用以拒绝再融资提案：

**Request**

- MÉTODO DELETE
- ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /refinancing_credit_operation
 

        **8.2. 再融资背书（找零）：** 
一旦合作方选择继续推进再融资操作，可分配边际背书流程将启动。一旦 INSS 可分配边际背书完成，合作方将收到以下 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. 再融资放款（找零）：**

        一旦 INSS 可分配边际完成背书，再融资操作将自动放款。

        **8.3.1.** 如果找零放款成功，将向合作方发送以下 webhook：

        **Webhook**

- WEBHOOK_TYPE credit_transfer.proposal.credit_operation

        *Body:*

**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.** 如果放款失败，合作方将收到以下 webhook：

                **7.3.2.1.** 放款账户失败 webhook

        **Webhook**

- WEBHOOK_TYPE credit_transfer.proposal.credit_operation

        *Body:*

**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.** 再融资操作放款失败 webhook

        **Webhook**

- WEBHOOK_TYPE credit_transfer.proposal.credit_operation

        *Body:*

**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.**
操作放款失败时，可以更改银行数据后重新尝试放款：

        **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"
	}
}

```

## 9 - 查询 CTC - CIP 参与者列表：

        **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\>"
    }
]
 
```

## 10 - 获取最后一次请求的响应

last response 是一种简单直观的方式，用于映射 QI 与 Dataprev 之间通信的响应，可以了解该请求的发送时间及获得的返回结果（通过已列举的枚举值）。

每个枚举值都有详细描述和 Dataprev 参考代码。以下是此端点枚举值的详细信息。

### 成功情况

#### Request - Credit Transfer
ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /CREDIT-OPERATION-TYPE/collateral
MÉTODO GET

#### PATH PARAMETERS credit-operation-type
| Enumerador               					| Descrição                  		|
|-------------------------------------------|--------------------------------|
| refinancing_credit_operation  			| 再融资操作    |
| portability_credit_operation     			| 转移操作      |

#### 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"
}
```

### 请求返回字段详情
| 字段                     | 描述                           | 值                          |
|---------------------------|-------------------------------------|----------------------------------|
| enumerator                | Retorno mapeado do código Dataprev  | [Enumeradores](#dataprev_response_enumerator_success)|
| reservation_method        | Método de averbação da reserva      | portability, new_credit, refinancing|

### 错误情况

#### 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"
  }
}
```

### 失败 webhook 字段详情
| 字段                     | 描述                           | 值                          |
|---------------------------|-------------------------------------|----------------------------------|
| enumerator                | Retorno mapeado do código Dataprev  | [Enumeradores](#dataprev_response_enumerator_errors) |
| reservation_method        | Método de averbação da reserva      | portability, new_credit, refinancing|
## 11 - 最后一次背书尝试的响应 Webhook

如果操作背书失败，将进入重试流程，并发送以下 webhook（详细说明了 Dataprev 返回的错误）。

**Webhook 转移**

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",
      }
    }
  }

  ```

### 失败 webhook 字段详情
| 字段                     | 描述                           | 值                          |
|---------------------------|-------------------------------------|----------------------------------|
| enumerator                | Retorno mapeado do código Dataprev  | [Enumeradores](#dataprev_response_enumerator_errors) |
| reservation_method        | Método de averbação da reserva      | portability, new_credit, refinancing|

## 12 - 查询原始转移数据

可以查询原始银行的转移数据，例如福利编号、开始日期、合同 CET（有效总成本）等信息。

        **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:*

**body.json**

```json
{
    "origin_contract_request_key": "9bb68c89-4b88-400d-9359-99ad8d42a69e",
    "status": "pending_search",
    "status_events": [
        {
            "status": "pending_search"
        }
    ]
}

```

福利编号查询成功时

         **Webhook**

- 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**

- 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"
    }
}

```

## 13. 降低分期金额

此端点允许 降低 信贷转移合同的分期金额。仅当原始合同中还有剩余分期且合同状态为 "disbursed" 时才有效。

        **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:*

**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
    }
```

## 14. 枚举值映射

### Enumeradores Retention Reason {#retention_reason_enumerator}
| Enumerador                               | Descrição                                              |
|------------------------------------------|--------------------------------------------------------|
| **issuer_retention**                     | 客户保留                                    |
| **different_from_original**              | 提案条件与原始合同不符 |
| **issuer_lawsuit**                       | 客户存在诉讼                              |
| **insurance_in_progress**                | 保险理赔进行中                     |
| **collateral_in_execution**              | 担保执行中                                   |
| **contract_not_found**                   | 合同未找到                                |
| **invalid_contract_type**                | 合同类型无效                              |
| **portability_in_progress**              | 转移进行中                             |
| **assigned_contract**                    | 已转让合同                                        |
| **issuer_document_number_invalid**       | CPF 不属于该合同                                  |
| **unrelated_issuer_document_number**     | 提供的 CPF 不是持有人的                       |
| **different_from_original**              | Condições da proposta divergentes do contrato original |
| **issuer_lawsuit**                       | Cliente com ação judicial                              |
| **assigned_without_co_obligation**       | 无共同义务的转让合同                        |
| **insurance_in_progress**                | Indenização de seguro em andamento                     |
| **collateral_in_execution**              | Garantia em Execução                                   |
| **fgts_in_use**                          | FGTS AMORTIZAR 使用中                                  |
| **fgts_funding**                         | FGTS funding                                           |
| **portability_not_requested**            | 客户未申请转移                |
| **wrong_original_financial_institution** | 原始债权机构错误                          |

### Dataprev 背书错误返回表 {#dataprev_response_enumerator_errors}
| Dataprev 代码 | 枚举值                                       | 描述                                                   | 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                           | Teimosinha             |
| HX              | reservation_already_included                     | Reservation already included                                | 确认背书  |
| 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           | Teimosinha             |
| 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 注意！
合同的所有利率和金额在创建预留时进行验证。

当合同长时间未背书时会出现 "invalid_contract_total_amount" 错误，这将影响先前确定的金额。
:::

### 背书成功返回表 {#dataprev_response_enumerator_success}
| Dataprev 代码 | 枚举值               | 描述                               |
|--------|--------------------------|-----------------------------------------|
| 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   |

### 余额查询错误返回表 {#dataprev_balance_errors_enumerators}
| 代码 | 枚举值                            | 描述                                                                       |
|--------|---------------------------------------|---------------------------------------------------------------------------------|
| 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. |

### 福利查询错误返回表 {#dataprev_benefits_errors_enumerators}
| 代码 | 枚举值                            | 描述                                                                       |
|--------|---------------------------------------|---------------------------------------------------------------------------------|
| 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                                |

### 福利状况表 {#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 |

### 福利状态表 {#benefit_status_enumerator}

| 枚举值 | 描述                                           |
|------------|-----------------------------------------------------|
| Elegible   | 符合贷款资格                            |
| Inelegible | 福利不符合贷款资格                |
| Blocked    | 福利符合资格，但贷款被封锁 |

### 封锁类型表 {#block_type_enumerator}

| 枚举值 | 描述                                           |
|------------|-----------------------------------------------------|
| 0          | 无封锁                                        |
| 1          | 被被保险人封锁                             |
| 2          | 因 TBM 被封锁                                   |
| 3          | 在授权时被封锁                              |

### 政治敏感人士类型表 {#politically_exposed_enumerator}

| 枚举值 | 描述                                           |
|------------|-----------------------------------------------------|
| 0          | 非政治敏感人士                    |
| 1          | 政治敏感人士 - 第 1 级              |

### 福利类型表 {#benefit_type_enumerator}

| 代码   | 福利                                   |
| --- | ------------------------------------------------ |
| 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                                      |

## 15. 场景模拟
### 转移

        **15.1.** 未偿余额申请

转移操作签名后，如果客户配置为手动发送，提案将创建为状态 "pending_submission"，只有在调用以下路由后，才会发起未偿余额申请。
如果配置为自动发送，提案将创建为状态 "pending_response"，即已在等待余额响应，无需调用此路由。    

        **Request**

- ENDPOINT /v2/credit_transfer/proposal/PROPOSAL-KEY
- MÉTODO PATCH

        *Payload：*

**payload.json**

```json
{
    "status": "pending_response"
}
```

        **15.2.** CTC 批准

提案必须处于 "pending_response" 状态。

        **Request**

- ENDPOINT /mock/credit_transfer/ctc
- MÉTODO POST

        *Payload：*

**payload.json**

```json
{
    "proposal_key": "CHAVE DA PROPOSTA",
    "event_type": "proposal_creation_accepted"
}
```

        **15.3.** CTC 拒绝

提案必须处于 "pending_response" 状态。

        **Request**

- ENDPOINT /mock/credit_transfer/ctc
- MÉTODO POST

        *Payload：*

**payload.json**

```json
{
    "proposal_key": "CHAVE DA PROPOSTA",
    "event_type": "proposal_creation_refused"
}
```

        **15.4.** 原始银行发送未偿余额

必须先发送 CTC 批准调用（**15.2**）。提案必须处于 "pending_acceptance" 状态。
调用此路由后，将收到 webhook 通知当前债务未偿余额；如要继续操作，需调用第（**7.2.1**）条中的路由 

        **Request**

- ENDPOINT /mock/credit_transfer/ctc
- MÉTODO POST

        *Payload：*

**payload.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
}
```

        **15.5.** 原始银行保留

必须先发送 CTC 批准调用（**15.2**）。提案必须处于 "pending_acceptance" 状态

        **Request**

- ENDPOINT /mock/credit_transfer/ctc
- MÉTODO POST

        *Payload：*

**payload.json**

```json
{
    "proposal_key": "CHAVE DA PROPOSTA",
    "event_type": "proposal_retention"
}
```

        **15.6.** 原始银行退款

只能在提案被接受且转移操作已放款后发送。提案必须处于 
"settlement_sent"、"pending_settlement_confirmation" 或 "paid" 状态。

        **Request**

- ENDPOINT /mock/credit_transfer/str
- MÉTODO POST

        *Payload：*

**payload.json**

```json
{
    "proposal_key": "CHAVE DA PROPOSTA",
    "event_type": "payment_rejected"
}
```

        **15.7.** CTC 付款确认

提案必须已被接受且转移操作已放款。状态必须为 "settlement_sent"。

        **Request**

- ENDPOINT /mock/credit_transfer/ctc
- MÉTODO POST

        *Payload：*

**payload.json**

```json
{
    "proposal_key": "CHAVE DA PROPOSTA",
    "event_type": "settlement_confirmation"
}
```

        **15.8.** 原始银行付款确认

必须在 CTC 付款确认（**15.7**）之后调用。提案必须处于 
"pending_settlement_confirmation" 状态。

        **Request**

- ENDPOINT /mock/credit_transfer/ctc
- MÉTODO POST

        *Payload：*

**payload.json**

```json
{
    "proposal_key": "CHAVE DA PROPOSTA",
    "event_type": "payment_confirmation"
}
```

        **15.9.** 担保背书

提案必须处于 "pending_settlement_confirmation" 或 "paid" 状态，且在 **15.7** 或 **15.8** 之后。

        **Request**

- ENDPOINT /mock/credit_transfer/collateral
- MÉTODO POST

        *Payload：*

**payload.json**

```json
{
    "proposal_key": "CHAVE DA PROPOSTA",
    "credit_operation_type": "portability",
    "collateral_constituted": true
}
```

### 再融资

        **15.10.** 担保背书

提案必须处于 "paid" 或 "pending_settlement_confirmation" 状态，且转移担保已被激活，
再融资必须已被接受。

        **Request**

- ENDPOINT /mock/credit_transfer/collateral
- MÉTODO POST

        *Payload：*

**payload.json**

```json
{
    "proposal_key": "CHAVE DA PROPOSTA",
    "credit_operation_type": "refinancing",
    "collateral_constituted": true
}
```

        **15.11.** 担保背书失败

提案必须处于 "paid" 或 "pending_settlement_confirmation" 状态，且转移担保已被激活，
再融资必须已被接受。

        **Request**

- ENDPOINT /mock/credit_transfer/collateral
- MÉTODO POST

        *Payload：*

**payload.json**

```json
{
    "proposal_key": "CHAVE DA PROPOSTA",
    "credit_operation_type": "refinancing",
    "collateral_constituted": false
}
```

        **15.12.** 放款失败

再融资操作必须已放款。

        **Request**

- ENDPOINT /mock/credit_transfer/disbursement
- MÉTODO POST

        *Payload：*

**payload.json**

```json
{
    "proposal_key": "CHAVE DA PROPOSTA",
    "event_type": "disbursement_failed"
}
```

## 16. 在 QI 向合作方抵扣的转移操作中添加费用

要添加费用，操作必须已背书、已放款且未被转让。

ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /portability_credit_operation/rebate
MÉTODO POST

        **Request**

**payload.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"
}
```

        **Response**

**response.json**

```json
{}
```

## 17. 转移付款收据（STR00047）

转移付款完成后，可以生成交易收据。

ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /receipt_str0047
MÉTODO POST

        **Request**

**payload.json**

```json
{}
```

        **Response**

**response.json**

```json
{
    "proposal_key": "CHAVE DA PROPOSTA",
    "receipt_url": "URL DO RECIBO",
    "receipt_document_key": "CHAVE DO RECIBO"
}
```

---

# Máquinas de Status

URL: /zh-Hans/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](#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"
	}
}

```

---

# Recálculo e Reformalização do Refinanciamento

URL: /zh-Hans/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. |

---

# Fura-fila (priority request)

URL: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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.

**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"
}
```

---

## 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) |

**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` |
:::

---

# 插入文档

URL: /zh-Hans/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

| 字段 | 类型 | 描述
|-|-|-|
| `document_type` * | string | 文档类型（始终为 amendment_term）。|
| `document_b64` * | string | 必须是文件的二进制内容（PDF 格式），以 Base64 编码。

### Response

STATUS 201

```json title='Response Body'
{
    "document_key": "8e515a17-8b4d-49a3-aed6-47c9574e426a"
}
```

---

# 简介

URL: /zh-Hans/documentation/iaas/aditamento_recebiveis/inicio

应收账款补充协议系统是一种允许修改和更新与应收账款相关的现有合同和协议的解决方案。该模块提供以下基本功能：

- 对现有应收账款合同进行变更
- 管理付款条件的修改

本文档提供了如何使用补充协议系统的详细说明，包括其主要功能和流程。您将在此找到以下信息：

- 补充协议流程
- 端点和请求体

要开始使用该系统，请浏览本文档中的可用主题，以便更好地了解补充协议模块的各个方面。

---

# 创建补充协议申请

URL: /zh-Hans/documentation/iaas/aditamento_recebiveis/pedido_aditamento_contrato

---
要提交补充协议申请，需要使用代表基金的唯一标识（FUND_CLASS_KEY，由 Qi Tech 提供）和代表补充协议流水线配置的唯一标识（AMENDMENT_CONFIGURATION_KEY，由 Qi Tech 提供）发起请求。

通过此系统进行的补充协议允许更改合同的付款流程或名义利率，或两者同时更改。也可以指定补充协议将与债务人支付的首付款一起执行。

### 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

| 字段 | 类型 | 描述 | 必填 |
|-|-|-|-|
| `asset_external_id` | string | 被补充合同的唯一标识键。 | 是 |
| `amendment_date` | string | 补充协议执行日期（格式：YYYY-MM-DD） | 是 |
| `amendment_type` | string | 要执行的补充协议类型。请参见 **[补充协议类型枚举](#enumerador-tipo-de-aditamento)** | 是 |
| `down_payment_value` | number | 债务人在补充协议时需支付的首付金额 | 否 |
| `installments` | array | 补充协议后合同的分期付款列表 | 是 |
| `installments[].maturity_date` | string | 分期付款到期日（格式：YYYY-MM-DD） | 是 |
| `installments[].face_value` | number | 分期付款的名义金额 | 是 |
| `installments[].installment_number` | number | 分期付款的序号 | 是 |
| `pre_fixed` | object | 固定利率配置 | 是 |
| `pre_fixed.monthly_rate` | number | 适用的月利率 | 是 |
| `pre_fixed.calendar_base` | string | 计算用历法基准（例如："workdays"） | 是 |

### Response

STATUS 201

```json title='Response Body'
{
    "asset_amendment_key": "a914aac6-93ff-45ee-8574-f4dbaf6c0642",
    "status": "pending_assets_insertion",
}
```

### 补充协议类型枚举 {#enumerador-tipo-de-aditamento}

| 枚举值 | 描述 |
|--------------|---------------|
| **payment_flow** | 仅更改付款流程 |
| **nominal_rate** | 仅更改合同名义利率 |
| **all_contract** | 同时更改付款流程和合同名义利率 |

:::caution **注意**
installments 和 pre_fixed 字段是否存在须根据要执行的补充协议类型，按以下表格要求处理
:::

| 补充协议类型 | installments | pre_fixed |
|------------------- | ------------ | --------- |
| all_contract | 必填 | 必填 |
| pre_fixed | 不得发送 | 必填 |
| payment_flow | 必填 | 不得发送 |

---

# 公共债券交易单

URL: /zh-Hans/documentation/iaas/boletador/boletador_titulos_publicos

## 请求

ENDPOINT /trade_treasury/public/fund_class/{fund_class_key}/operation
METHOD POST

### 路径参数

| 参数 | 类型 | 描述 |
| :---- | :---- | :---- |
| `fund_class_key` | string | 基金的唯一标识符。 |

```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"
}
```

### 请求体属性

| 字段 | 类型 | 必填性 | 描述 |
| :---- | :---- | :---- | :---- |
| `external_id` | string | 可选 | 用于幂等性的外部标识符（UUID）。若未提供则自动生成。最多36个字符。 |
| `operation_date` | string (date) | 必填 | 操作日期，格式 `YYYY-MM-DD`。必须为工作日且等于基金的 `accounting_date`。 |
| `payment_date` | string (date) | 必填 | 结算日期，格式 `YYYY-MM-DD`。必须 `>= operation_date`。非定期操作（`outright_operation`、`buyback_operation`）必须等于 `operation_date`。 |
| `operation_part` | string | 必填 | 基金角色：`assignee`（买方）或 `assignor`（卖方）。 |
| `operation_type` | string | 必填 | 操作类型：`outright_operation`、`buyback_operation`。`buyback_operation` 要求 `operation_part == "assignee"`。 |
| `counterparty` | object | 必填 | 交易对手数据。见下方对象说明。 |
| `treasury_type` | string | 必填 | 债券类型：`lft`、`ltn`、`ntn_b` 或 `ntn_f`。 |
| `unit_price` | number | 必填 | 债券单价。接受任意精度；服务器将按类型向下截断：`buyback_operation` → 8位小数；其他 → 6位小数。 |
| `units` | integer | 必填 | 债券数量（正整数）。 |
| `maturity_date` | string (date) | 必填 | 债券到期日（`YYYY-MM-DD`）。必须严格晚于 `operation_date`。 |
| `yearly_negotiated_rate` | number | 条件性 | 年化协商利率（%）。**`buyback_operation` 必填**。 |
| `return_date` | string (date) | 条件性 | 返还日期（`YYYY-MM-DD`）。**`buyback_operation` 必填**。必须 `> operation_date`。 |

#### `counterparty` 对象

| 字段 | 类型 | 必填性 | 描述 |
| :---- | :---- | :---- | :---- |
| `iselic_number` | string | 必填 | 交易对手的iSELIC编号（8位数字）。 |
| `selic_account_number` | string | 必填 | 交易对手的SELIC账户号码（9位数字）。 |
| `document_number` | string | 必填 | 带标点的交易对手CNPJ（格式 `XX.XXX.XXX/XXXX-XX`）。 |

## 响应

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": "EXAMPLE FUND 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": {}
}
```

### 响应属性

| 字段 | 类型 | 描述 |
| :---- | :---- | :---- |
| `operation_key` | string | QI Tech生成的操作唯一标识符（UUID）。 |
| `external_id` | string | 请求中提供或自动生成的外部标识符。 |
| `fund_class` | object | 与操作关联的基金数据。 |
| `status` | string | 操作的初始状态。 |
| `operation_part` | string | `assignee`（买方）或 `assignor`（卖方）。 |
| `operation_type` | object | `{ enumerator, code }` — 操作类型及对应SELIC代码。 |
| `treasury` | object | `{ enumerator, code }` — 债券类型及对应SELIC代码。 |
| `operation_date` | string | 操作日期（`YYYY-MM-DD`）。 |
| `payment_date` | string | 结算日期（`YYYY-MM-DD`）。 |
| `maturity_date` | string | 债券到期日（`YYYY-MM-DD`）。 |
| `total_operation_value` | decimal | 操作总价值（数量 × 单价）。 |
| `units` | integer | 债券数量。 |
| `unit_price` | number | 债券单价。 |
| `counterparty` | object | 交易对手数据（`iselic_number`、`document_number`、`selic_account_number`）。 |
| `isin_code` | string | 债券ISIN代码。 |
| `issue_date` | string | 债券发行日期（`YYYY-MM-DD`）。 |
| `operation_data` | object | 操作的附加内部元数据。 |

---

# 公共债券列表

URL: /zh-Hans/documentation/iaas/boletador/listagem_titulos_publicos

## 请求

ENDPOINT /trade_treasury/public/fund_class/{fund_class_key}/operations
METHOD GET

### 路径参数

| 参数 | 类型 | 描述 |
| :---- | :---- | :---- |
| `fund_class_key` | string | 基金的唯一标识符。 |

### 查询参数

| 参数 | 类型 | 默认值 | 最大值 | 描述 |
| :---- | :---- | :---- | :---- | :---- |
| `limit` | integer | 100 | 500 | 每页项目数。 |
| `page` | integer | 0 | — | 页码（从0开始）。 |
| `status` | string | — | — | 按操作的精确状态过滤。 |
| `not_status` | string | — | — | 排除特定状态的操作。 |
| `treasury_type` | string | — | — | 按债券类型过滤（`lft`、`ltn`、`ntn_b`、`ntn_f`）。 |
| `operation_type` | string | — | — | 按操作类型过滤（`outright_operation`、`buyback_operation`）。 |
| `operation_date` | string | — | — | 按精确操作日期过滤（`YYYY-MM-DD`）。 |
| `from_operation_date` | string | — | — | 过滤日期 `>=` 指定值（`YYYY-MM-DD`）的操作。 |
| `to_operation_date` | string | — | — | 过滤日期 `<=` 指定值（`YYYY-MM-DD`）的操作。 |
| `maturity_date` | string | — | — | 按精确到期日过滤（`YYYY-MM-DD`）。 |
| `from_maturity_date` | string | — | — | 过滤到期日 `>=` 指定值（`YYYY-MM-DD`）的操作。 |
| `to_maturity_date` | string | — | — | 过滤到期日 `<=` 指定值（`YYYY-MM-DD`）的操作。 |

## 响应

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
}
```

### 响应属性

| 字段 | 类型 | 描述 |
| :---- | :---- | :---- |
| `data` | array | 操作列表。每项包含与单条查询响应相同的字段。 |
| `limit` | integer | 本页返回的项目数。 |
| `page` | integer | 当前页码（从0开始）。 |
| `is_last_page` | boolean | 是否为最后一página。 |

---

# 简介

URL: /zh-Hans/documentation/iaas/boletos/inicio

本节将介绍在**应收账款转让给投资基金**背景下，**发行银行划账单（boletos）**的生态系统运作方式。

## 银行划账单发行结构

在应收账款转让中，银行划账单的发行流程如下：

1. **注册收款账户及生成转让合同**
   - [5.2.4. 转让合同](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato)

2. **银行划账单登记**
   - 银行划账单在转让完成付款后，立即在发行银行进行登记。
   - 必填信息：
     - 转让方标识
     - 付款人（债务人）标识
     - 名义金额
     - 到期日

3. **登记确认**
   - 银行划账单的登记确认在下一个工作日通过银行回执处理完成。

4. **清算**
   - 当付款人支付银行划账单后，系统将自动捕获并更新清算状态。
   - 资金流向基金主账户，构成可用资金。

5. **注销**
   - 如果通过转让方注销或替换方式完成付款，银行划账单将自动注销。

:::warning
为使银行划账单能**自动**发行，**转让合同**必须包含所有必要的收款信息，且系统中必须存在**已正确注册的收款账户**。
:::

如需访问这些服务，请联系团队 [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br)，以便在验证环境（Sandbox）和生产环境中获得相应授权。

---

# Instruções de Boleto

URL: /zh-Hans/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.            |

---

# 获取 CNAB 文件

URL: /zh-Hans/documentation/iaas/boletos/recuperar_arquivo_retorno

---

## 列出 CNAB 文件

返回基金类别下某个 boleto 档案的 CNAB 文件（与银行交换的汇款/回执文件）的分页列表。

### Request

ENDPOINT /bankslip_collection/fund_class/FUND_CLASS_KEY/bankslip_profile/BANKSLIP_PROFILE_KEY/cnab_files
METHOD GET

### Path Params

| 参数 | 描述 |
|------------------------|--------------------------------------------------------------|
| `fund_class_key`       | 基金类别的键。若不存在则返回 `404`（`NotFoundFundClass`）。 |
| `bankslip_profile_key` | boleto 档案的键，必须属于该基金类别。若未找到则返回 `404`（`NotFoundBankslipConfiguration`）。 |

### Query Params

所有参数均为可选。

| 参数 | 类型 | 描述 |
|----------------|--------|--------------------------------------------------------------|
| `initial_date` | date   | 筛选 `cnab_date` 大于或等于该日期的文件（YYYY-MM-DD）。 |
| `final_date`   | date   | 筛选 `cnab_date` 小于或等于该日期的文件（YYYY-MM-DD）。 |
| `cnab_type`    | string | 按文件类型筛选（参见 **[CNAB 类型](#cnab-类型)**）。 |
| `limit`        | int    | 每页条目数，取值范围为 0 到 20。默认值：`10`。 |
| `page`         | int    | 页码（从零开始）。默认值：`0`。 |

当 `is_last_page` 为 `false` 时，请请求下一个 `page` 以获取其余结果。

### 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
}
```

### 分页对象

| 字段 | 类型 | 描述 |
|----------------|---------|--------------------------------------|
| `data`         | array   | **[CNAB File](#cnab-file)** 对象列表 |
| `limit`        | int     | 每页获取的对象数量上限 |
| `page`         | int     | 获取的页码 |
| `is_last_page` | boolean | 指示获取的页面是否为最后一页 |

### CNAB File

| 字段 | 类型 | 描述 |
|--------------------------|--------|----------------------------------------------------------------------------------|
| `cnab_file_key`          | string | CNAB 文件的唯一标识符。 |
| `bankslip_profile`       | object | 关联的 boleto 档案（参见 **[Bankslip Profile](/documentation/iaas/boletos/recuperar_boletos#bankslip-profile)**）。 |
| `cnab_date`              | date   | CNAB 文件的日期。 |
| `type`                   | string | 文件类型（参见 **[CNAB 类型](#cnab-类型)**）。 |
| `status`                 | string | 文件状态（参见 **[CNAB 状态](#cnab-状态)**）。 |
| `download_filename`      | string | 下载文件时使用的文件名。 |
| `url`                    | string | 用于下载文件的预签名 URL，有效期为 **1 小时**。若无法生成则省略。 |
| `external_cnab_file_key` | string | 外部 CNAB 文件的标识符。仅当文件具有该值时出现。 |
| `header`                 | string | 文件的 header。仅当文件具有该值时出现。 |
| `trailer`                | string | 文件的 trailer。仅当文件具有该值时出现。 |
| `number_of_occurrences`  | int    | 文件中的记录数。仅当文件具有该值时出现。 |
| `expectation`            | object | 文件的预期数据。仅当文件具有该值时出现。 |
| `bankslip_expenses`      | array  | **[Bankslip Expense](#bankslip-expense)** 对象列表。仅当文件有关联费用时出现。 |

### Bankslip Expense

| 字段 | 类型 | 描述 |
|------------------------|--------|--------------------|
| `bankslip_expense_key` | string | 费用的唯一标识符。 |
| `type`                 | string | 费用类型。 |
| `number_of_expenses`   | int    | 汇总的费用数量。 |
| `total_value`          | number | 费用总额。 |
| `status`               | string | 费用状态。 |

## CNAB 类型

| 枚举值 | 描述 |
|-----------------------|--------------|
| `return`              | 回执文件 |
| `external_return`     | 外部回执文件 |
| `remittance`          | 汇款文件 |
| `external_remittance` | 外部汇款文件 |

## CNAB 状态

| 枚举值 | 描述 |
|----------------------|----------|
| `created`            | 已创建 |
| `pending_processing` | 待处理 |
| `completed`          | 已完成 |
| `canceled`           | 已取消 |

---

# Recuperação de Boleto e Segunda via

URL: /zh-Hans/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.                          |

---

# 获取银行划账单

URL: /zh-Hans/documentation/iaas/boletos/recuperar_boletos

---

## 银行划账单列表

### Request

ENDPOINT /bankslip_collection/fund_class/FUND_CLASS_KEY/bankslip_profile/BANKSLIP_PROFILE_KEY/bankslips
MÉTODO GET

### Query Params
| 参数 | 描述 |
|------------------------------|--------------------------------------------------------------|
| `limit` | 0 到 100 之间的值，表示每页项目数量。 |
| `page` | 页码（从零开始）。 |
| `borrower_document_number` | 借款人文件编号（仅数字）。 |
| `assignor_document_number` | 转让方文件编号（仅数字）。 |
| `participant_control_number` | 参与者控制编号。 |
| `order_number` | 合同编号。 |
| `our_number` | 银行中的银行划账单编号。 |

### 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
                }
            ]
        },
        {
            "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
                }
            ]
        }
    ],
    "limit": 15,
    "page": 0,
    "is_last_page": true
}
```

### 分页对象

| 字段 | 类型 | 描述 |
|---------------|----------|----------------------------------------------------------------|
| `data` | array | **[Bankslip](#bankslip)** 对象列表 |
| `limit` | int | 每页返回的对象数量上限 |
| `page` | int | 当前返回的页码 |
| `is_last_page` | boolean | 表示当前页是否为最后一页 |

### Bankslip

| 字段 | 类型 | 描述 |
|---------------------------------------|----------|----------------------------------------------------------------------|
| `bankslip_key` | string | 银行划账单的唯一标识。 |
| `external_participant_control_number` | string | 参与者外部控制编号。 |
| `asset_type` | string | 关联的资产类型。 |
| `due_date` | date | 银行划账单到期日。 |
| `face_value` | number | 银行划账单名义金额。 |
| `status` | string | 银行划账单当前状态。 |
| `participant_control_number` | string | 参与者内部控制编号。 |
| `bankslip_configuration` | object | 包含银行划账单配置的对象（见下文）。 |
| `borrower` | object | 表示借款人（付款人）的对象。 |
| `assignor` | object | 表示应收账款转让方的对象。 |
| `occurrences` | array | 与银行划账单相关的事件列表（每个项目为一个对象）。 |

### Bankslip Configuration

| 字段 | 类型 | 描述 |
|--------------------------------------|----------|----------------------------------|
| `bankslip_configuration_key` | string | 银行划账单配置键。 |
| `bankslip_profile` | object | 关联的银行划账单配置文件。 |

---

### Bankslip Profile

| 字段 | 类型 | 描述 |
|--------------------------------------|----------|-------------------------------|
| `bankslip_profile_key` | string | 银行划账单配置文件标识。 |
| `bankslip_profile_code` | string | 配置文件代码。 |
| `bankslip_profile_number` | number | 配置文件编号。 |
| `bankslip_provider` | string | 银行划账单提供商。 |
| `additional_information` | object | 附加信息（见下文）。 |
| `internal_account_key` | string | 关联内部账户标识。 |
| `fund_class` | object | 表示投资基金的对象（见下文）。 |

### Fund Class

| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|----------|---------------------------------------------------|------------|
| `name` | string | 基金类别名称 | 最多 255 |
| `fund_class_key` | string | 基金类别的唯一标识键 | 36 |
| `document_number` | string | 基金类别的 CNPJ | - |

### Borrower

| 字段 | 类型 | 描述 |
|--------------------------------------|----------|-------------------------------|
| `name` | string | 借款人姓名。 |
| `document_number` | string | 文件编号（CPF/CNPJ）。 |
| `person_type` | string | 人员类型。 |
| `address` | object | 借款人地址（见下文）。 |

### Address

| 字段 | 类型 | 描述 |
|--------------------------------------|----------|-------------------------------|
| `street` | string | 街道地址。 |
| `number` | string | 门牌号。 |
| `neighborhood` | string | 社区/街区。 |
| `city` | string | 城市。 |
| `postal_code` | string | 邮政编码。 |
| `uf` | string | 联邦单位（州缩写）。 |
| `country` | string | ISO Alpha-3 格式的国家代码。 |

---

## Assignor（转让方）

| 字段 | 类型 | 描述 |
|--------------------------------------|----------|-------------------|
| `name` | string | 转让方名称。 |
| `document_number` | string | 文件编号（CNPJ）。 |
| `person_type` | string | 人员类型。 |

---

## Occurrences

数组中每个项目是具有以下字段的对象：

| 字段 | 类型 | 描述 |
|--------------------------------------|----------|---------------------------------|
| `occurrence_key` | string | 事件标识。 |
| `status` | string | 事件状态。 |
| `type` | string | 事件类型。 |
| `occurrence_data` | object | 事件附加数据。 |

## 特定银行划账单

### Request

ENDPOINT /bankslip_collection/fund_class/FUND_CLASS_KEY/bankslip_configuration/BANKSLIP_CONFIGURATION_KEY/bankslip/BANKSLIP_KEY
MÉTODO GET

### Response
Response Body

```json title='Response Body'
{
    "bankslip_key": "283bd9f4-7a18-4947-870e-cdb7170be6cb",
    "external_participant_control_number": "0175458470012171954123456",
    "bankslip_configuration": {
        "bankslip_configuration_key": "b3d4a489-a9d1-4afd-b1fc-719a06a1b49a",
        "bankslip_profile": {
            "bankslip_profile_key": "77dac6b1-2744-42d7-a9a1-57384e078e75",
            "bankslip_profile_code": "329-09-0001-1234567",
            "bankslip_profile_number": 9,
            "bankslip_provider": "qi_scd",
            "additional_information": {
                "requester_profile_key": "7c39615a-ae39-44be-b3b3-44b25ade2583"
            },
            "internal_account_key": "545fb51c-1e8e-4019-92dc-cae42eb5e1df",
            "fund_class": {
                "fund_class_key": "48ea2b09-d975-48d5-90e9-180af52441d1",
                "document_number": "21.453.503/0001-00",
                "name": "FUNDO FIDC",
                "manager": {
                    "name": "GESTORA",
                    "manager_key": "d59acd84-e81c-4822-9f34-968a8ccf54bd",
                    "document_number": "12.345.678/0001-01"
                }
            }
        }
    },
    "due_date": "2030-03-03",
    "face_value": 3000.0,
    "status": "registered",
    "participant_control_number": "0175324300089281954563002",
    "borrower": {
        "name": "BORROWER",
        "document_number": "00.000.000/0001-00",
        "person_type": "legal_person",
        "address": {
            "street": "RUA DOS PINHEIROS",
            "number": "250",
            "neighborhood": "SPINHEIROS",
            "city": "SAO PAULO",
            "postal_code": "74015-170"
        }
    },
    "assignor": {
        "name": "CEDENTE LTDA",
        "document_number": "01.001.001/0001-01",
        "person_type": "legal_person"
    },
    "bankslip_type": "simple_collection",
    "order_number": "31234-1",
    "digitable_line": "32990001039000000000101634386701233740000700000",
    "barcode": "39483137400003000000001090000000000161938270",
    "occurrences": [
        {
            "occurrence_key": "187b8700-361d-4df4-ba71-930f79a835a4",
            "status": "succeeded",
            "type": "registration",
            "occurrence_data": null
        }
    ],
    "settlement_instructions": [
        {
            "settlement_instruction_key": "eefbe1c4-bd85-4ba0-9400-4a0e20889dc7",
            "status": "pending_bankslip_payment",
            "issue_date": "2025-02-05",
            "maturity_date": "2030-03-03",
            "face_value": 3000.0,
            "asset_type": "duplicata_servicos",
            "asset_key": "c9168305-334e-47a1-91d6-6448337b5fd1",
            "order_number": "31234-1"
        }
    ],
    "bankslip_url": "https://url.com/c9168305-334e-47a1-91d6-6448337b5fd1_1.pdf"
}
```

---

# 获取 Boleto 档案

URL: /zh-Hans/documentation/iaas/boletos/recuperar_carteiras_cobranca

---

## 列出 boleto 档案

返回基金类别下 boleto 档案的分页列表。仅允许负责该基金类别的管理人（manager）访问。

### Request

ENDPOINT /bankslip_collection/fund_class/FUND_CLASS_KEY/bankslip_profiles
METHOD GET

### Path Params

| 参数 | 描述 |
|------------------|--------------------------------------------------------------|
| `fund_class_key` | 基金类别的键。若不存在则返回 `404`（`NotFoundFundClass`）。 |

### Query Params

所有参数均为可选。

| 参数 | 类型 | 描述 |
|-----------|------|--------------------------------------------------|
| `limit`   | int  | 每页条目数，取值范围为 0 到 50。默认值：`10`。 |
| `page`    | int  | 页码（从零开始）。默认值：`0`。 |

当 `is_last_page` 为 `false` 时，请请求下一个 `page` 以获取其余结果。

### 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
}
```

### 分页对象

| 字段 | 类型 | 描述 |
|-------------------|---------|--------------------------------------------------|
| `data`            | array   | **[Bankslip Profile](#bankslip-profile)** 对象列表 |
| `limit`           | int     | 每页获取的对象数量上限 |
| `page`            | int     | 获取的页码 |
| `is_last_page`    | boolean | 指示获取的页面是否为最后一页 |
| `elapsed_time_ms` | number  | 服务器端查询执行时间（毫秒） |

### Bankslip Profile

| 字段 | 类型 | 描述 |
|---------------------------|--------|------------------------------------------------------------------------------|
| `bankslip_profile_key`    | string | boleto 档案的标识符。 |
| `bankslip_profile_code`   | string | 档案代码。 |
| `bankslip_profile_number` | number | 档案编号。 |
| `bankslip_provider`       | string | boleto 提供方。 |
| `additional_information`  | object | 档案的附加信息。 |
| `internal_account_key`    | string | 关联内部账户的标识符。 |
| `fund_class`              | object | 表示基金类别的对象（参见 **[Fund Class](/documentation/iaas/boletos/recuperar_boletos#fund-class)**）。 |
| `total_value`             | number | 档案的未结总额。仅在档案的定期余额计算完成后出现。 |
| `total_overdue_value`     | number | 档案的逾期总额。仅在档案的定期余额计算完成后出现。 |

---

# 获取 Boleto 配置

URL: /zh-Hans/documentation/iaas/boletos/recuperar_configuracoes_boleto

---

## 列出 boleto 配置

返回基金类别下某个 boleto 档案的 boleto 配置的分页列表。仅允许负责该基金类别的管理人（manager）访问。

### Request

ENDPOINT /bankslip_collection/fund_class/FUND_CLASS_KEY/bankslip_profile/BANKSLIP_PROFILE_KEY/bankslip_configurations
METHOD GET

### Path Params

| 参数 | 描述 |
|------------------------|--------------------------------------------------------------|
| `fund_class_key`       | 基金类别的键。若不存在则返回 `404`（`NotFoundFundClass`）。 |
| `bankslip_profile_key` | boleto 档案的键，必须属于该基金类别。若未找到则返回 `404`（`NotFoundBankslipProfile`）。 |

### Query Params

所有参数均为可选。

| 参数 | 类型 | 描述 |
|---------------|--------|--------------------------------------------------------------|
| `issuer_type` | string | 按发行方类型筛选（参见 **[发行方类型](#发行方类型)**）。未知值将返回 `InvalidValueForEntity` 错误。 |
| `limit`       | int    | 每页条目数，取值范围为 0 到 30。默认值：`10`。 |
| `page`        | int    | 页码（从零开始）。默认值：`0`。 |

当 `is_last_page` 为 `false` 时，请请求下一个 `page` 以获取其余结果。

### 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
}
```

### 分页对象

| 字段 | 类型 | 描述 |
|-------------------|---------|--------------------------------------------------------|
| `data`            | array   | **[Bankslip Configuration](#bankslip-configuration)** 对象列表 |
| `limit`           | int     | 每页获取的对象数量上限 |
| `page`            | int     | 获取的页码 |
| `is_last_page`    | boolean | 指示获取的页面是否为最后一页 |
| `elapsed_time_ms` | number  | 服务器端查询执行时间（毫秒） |

### Bankslip Configuration

| 字段 | 类型 | 描述 |
|------------------------------|--------|------------------------------------------------------------------------------|
| `bankslip_configuration_key` | string | boleto 配置的唯一标识符。 |
| `bankslip_profile`           | object | 关联的 boleto 档案（参见 **[Bankslip Profile](/documentation/iaas/boletos/recuperar_boletos#bankslip-profile)**）。 |
| `bankslip_issuer_type`       | string | boleto 发行方类型（参见 **[发行方类型](#发行方类型)**）。 |
| `delay`                      | int    | 为 boleto 签发配置的延迟。 |
| `our_number_range`           | object | 分配给该配置的 "nosso número" 号段（参见 **[Our Number Range](#our-number-range)**）。仅当配置分配了号段时出现。 |

### Our Number Range

| 字段 | 类型 | 描述 |
|----------------------------|------|----------------------------|
| `our_number_range_initial` | int  | "nosso número" 号段的起始值。 |
| `our_number_range_final`   | int  | "nosso número" 号段的结束值。 |

## 发行方类型

| 枚举值 | 描述 |
|--------------|--------|
| `internal`   | 内部   |
| `manager`    | 管理人 |
| `consultant` | 顾问   |

---

# Webhooks

URL: /zh-Hans/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"
    }
}
```

---

# 投资组合 - 审批

URL: /zh-Hans/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"
}

```

### "new_status" 枚举值

| 枚举值 | 描述 |
|--------------------------|--------|
| `confirmed` | 审批通过投资组合 |
| `reproved` | 拒绝审批投资组合 |

---

# 投资组合 - 下载

URL: /zh-Hans/documentation/iaas/composicao_carteira/baixar_carteira

## 简介

此资源旨在以同步方式下载基于**Composition**的报告。支持的报告格式如下：

- **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 注意
要下载投资组合，其状态必须为 **confirmed（已确认）**，否则响应将返回 **400**。

:::

---

# 简介

URL: /zh-Hans/documentation/iaas/composicao_carteira/inicio

本节将介绍如何通过 API 消费投资组合数据。每天，所有由 QI CTVM 管理的投资基金的投资组合都通过此 API 提供，其中包含构成当日基金单位净值的信息。

在基金关账处理及随之而来的投资组合发布过程中，我们首先生成**验证组合**，一旦审批通过，便进入**最终组合**的发布阶段。

两者的主要区别在于：验证组合在被动处理之前生成，这包括摊销、申购和赎回操作；而最终组合已将这些变动纳入考量。资产、费用、核对及现金信息在两个组合之间始终保持一致。实际上，两者的区别在于：待配额赎回的"应付款"或待配额申购的"应收款"，均已配额化并影响发行系列的配额数量，但不改变已公布的配额值。

:::warning
在批准**验证组合**之前，务必对其进行所有必要的审查和验证，因为一旦批准，系统将进行被动处理，随即发布最终组合。在此阶段，由于被动处理已完成，可能已有赎回和摊销完成了清算。
:::

如需访问这些服务，请联系团队 [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br)，以便在验证环境（Sandbox）和生产环境中获得相应授权。

---

# 投资组合 - 获取

URL: /zh-Hans/documentation/iaas/composicao_carteira/recuperar_carteira

---

## 投资组合列表

### Request

ENDPOINT /composition/fund_class/FUND_CLASS_KEY/compositions
MÉTODO GET

### Query Params
| 参数 | 描述 |
|------------------|-----------------------------------------------------------------------------------------------------|
| `not_status` | 过滤结果，排除指定状态的组合。 |
| `status` | 过滤结果，仅返回指定状态的组合。 |
| `reference_date` | 查询组合的参考日期，格式为 `YYYY-MM-DD`。 |
| `type` | 要过滤的组合类型 pre_quota/final_quota。 |
| `start_date` | 查询范围的开始日期，若提供 `end_date` 则必填。格式：`YYYY-MM-DD`。 |
| `end_date` | 查询范围的结束日期，若提供 `start_date` 则必填。格式：`YYYY-MM-DD`。 |

:::warning 注意
    按日期过滤有两种方式：
- 通过 *query param* 字段 *reference_date* 查询 特定日期 。
- 通过 *query param* 字段 *start_date* 和 *end_date* 查询 时间段 。
:::

```json title='Response Body'
{
    "data": [
        {
            "composition_key": "f2208257-1489-4937-8862-031bca34016f",
            "status": "confirmed",
            "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",
            "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
}

```

### 分页对象

| 字段 | 类型 | 描述 |
|---------------|--------|----------------------------------------------------------------|
| `data` | array | **[Composition](#composition)** 对象列表 |
| `limit` | int | 每页返回的对象数量上限 |
| `page` | int | 当前返回的页码 |
| `is_last_page` | boolean | 表示当前页是否为最后一页 |

### Composition

| 字段 | 类型 | 描述 |
|--------------------------|--------|-------------------------------------------------|
| `composition_key` | string | 投资组合的唯一标识键 |
| `status` | string | 该投资组合的状态 |
| `type` | string | 该投资组合的类型，pre_quota/final_quota |
| `composition_date` | string | 投资组合的参考日期 |
| `fund_class` | object | **[Fund Class](#fund_class)** 对象 |

### Fund Class

| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|----------|---------------------------------------------------|------------|
| `name` | string | 基金类别名称 | 最多 255 |
| `fund_class_key` | string | 基金类别的唯一标识键 | 36 |
| `document_number` | string | 基金类别的 CNPJ | - |

---

## 投资组合详情

### 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",
    "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
            },
            {
                "reference_date": "2024-11-25", 
                "quota_value": 1.7568068,
                "di_benchmark_quota_value": 1.76049545
            }
        ]
      }
    ]
}
```

### 完整 Composition 字段

| 字段 | 类型 | 描述 |
|--------------------------|--------|-------------------------------------------------------------|
| `composition_key` | string | 投资组合的唯一标识键 |
| `status` | string | 该投资组合的状态 |
| `type` | string | 该投资组合的类型，pre_quota/final_quota |
| `composition_date` | string | 投资组合的参考日期 |
| `fund_class` | object | **[Fund Class](#fund_class)** 对象 |
| `issuance_series` | array | **[Issuance Series](#issuance_series)** 对象列表 |
| `assets` | array | **[Assets](#composition)** 对象列表 |
| `consolidated_assets` | array | **[Consolidated Assets](#composition)** 对象列表 |
| `receivables` | array | **[Receivables](#composition)** 对象列表 |
| `payables` | array | **[Payables](#composition)** 对象列表 |
| `cash_accounts` | array | **[Cash Accounts](#composition)** 对象列表 |

### Issuance Serie

| 字段 | 类型 | 描述 |
|--------------------------|--------|-------------------------------------------------------------|
| `issuance_serie_key` | string | 发行系列的唯一标识键 |
| `name` | string | 该系列名称 |
| `gross_net_worth` | float | 该系列的总净资产 |
| `net_net_worth` | float | 该系列的净净资产 |
| `gross_quota_value` | float | 总配额价值 |
| `net_quota_value` | float | 净配额价值 |
| `number_of_quotas` | float | 总配额数量 |
| `profitabilities` | array | **[Profitability](#profitability)** 对象列表 |

### Profitability

| 字段 | 类型 | 描述 |
|-----------------------------|--------|----------------------------------------------------------------------|
| `reference_date` | string | 分析绩效的参考日期 |
| `quota_value` | float | 该参考日期时的系列配额价值 |
| `di_benchmark_quota_value` | float | 若参考配额以 100% DI 运行至今的模拟配额价值 |

### Assets

| 字段 | 类型 | 描述 |
|---------------------------------|---------|-------------------------------------------------------|
| `asset_key` | string | 资产的唯一标识键 |
| `asset_type` | string | 资产类型 |
| `purchase_date` | string | 资产购入日期 |
| `total_purchase_value` | string | 资产的总购入价值 |
| `bad_debt_percentage` | string | 已应用的坏账准备比例 |
| `bad_debt_value` | integer | 考虑的坏账准备总值 - 以分为单位的整数 |
| `overdue_accounting_value` | integer | 资产逾期金额 - 以分为单位的整数 |
| `current_accounting_value` | integer | 资产总金额 - 以分为单位的整数 |
| `current_fair_accounting_value` | integer | 资产总公允价值 - 以分为单位的整数 |

### Consolidated Assets

| 字段 | 类型 | 描述 |
|---------------------------------|---------|----------------------------------------------------------------------|
| `asset_type` | string | 资产类型 |
| `total_units` | string | 该类型合并资产的总数量 |
| `bad_debt_value` | integer | 考虑的坏账准备总值 - 以分为单位的整数 |
| `overdue_accounting_value` | integer | 资产逾期金额 - 以分为单位的整数 |
| `current_accounting_value` | integer | 资产总金额 - 以分为单位的整数 |
| `current_fair_accounting_value` | integer | 分析绩效的参考日期 |

### Receivables

| 字段 | 类型 | 描述 |
|-----------------------------|--------|----------------------------------------------------------------------|
| `origin_key` | string | 产生此应收款项的资源的唯一标识键 |
| `origin_type` | string | 产生此应收款项的资源类型 |
| `description` | string | 项目描述 |
| `total_value` | float | 应收总金额 |
| `recognized_value` | float | 已计提的金额 |
| `start_date` | string | 计提开始日期 |
| `end_date` | string | 计提结束日期 |
| `payment_date` | string | 清算日期 |

### Payables

| 字段 | 类型 | 描述 |
|-----------------------------|--------|----------------------------------------------------------------------|
| `origin_key` | string | 产生此应付款项的资源的唯一标识键 |
| `origin_type` | string | 产生此应付款项的资源类型 |
| `description` | string | 项目描述 |
| `total_value` | float | 应付总金额 |
| `recognized_value` | float | 已计提的金额 |
| `start_date` | string | 计提开始日期 |
| `end_date` | string | 计提结束日期 |
| `payment_date` | string | 清算日期 |

### Cash Accounts

| 字段 | 类型 | 描述 |
|-----------------------------|---------|-------------------------------------------------------------------|
| `account_key` | string | 账户的唯一标识键 |
| `balance` | integer | 账户余额 - 以分为单位的整数 |
| `unconcilied_cash_in` | integer | 该账户待对账的收入金额 - 以分为单位的整数 |
| `unconcilied_cash_out` | integer | 该账户待对账的支出金额 - 以分为单位的整数 |
| `account_branch` | string | 账户支行 |
| `account_digit` | string | 账户校验位 |
| `account_number` | string | 账户号码 |
| `accounting_identification` | integer | 该账户的会计标识 |
| `financial_institution` | object | **[Financial Institution](#financial_institution)** 对象 |

### Financial Institution

| 字段 | 类型 | 描述 |
|-----------------------------|--------|-----------------------|
| `code` | string | 金融机构 COMPE 代码 |
| `ispb` | string | 金融机构 ISPB |
| `name` | string | 金融机构名称 |

---

# 按基金类别查询金融申购

URL: /zh-Hans/documentation/iaas/cotas_de_fundo/consulta_paginada_aplicacoes_financeiras

:::warning 注意
此资源仅适用于担任**基金经理**角色的集成方。
:::

### Request

ENDPOINT /trade_fund_quota/fund_class/FUND_CLASS_KEY/financial_applications
MÉTODO GET

#### Query Params

| 参数 | 类型 | 描述 |
| ---------------------------------- | ------ | --------------------------------------------- |
| `quotation_date` | date | 申购的配额日期 |
| `financial_application_status` | string | 按特定状态过滤申购 |
| `not_financial_application_status` | string | 排除特定状态的申购 |
| `document_number` | string | 被投资基金类别的 CNPJ |

### Response

STATUS 200

案例 01：返回一个申购

```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
| 字段 | 类型 | 描述 |
|---------------|--------|------------------------------------------------------------------------------|
| `data` | array | **[Financial Application](#financial_application)** 对象列表 |
| `limit` | int | 每页返回的对象数量上限 |
| `page` | int | 当前返回的页码 |
| `is_last_page` | boolean | 表示当前页是否为最后一页 |

### Financial Application

| 字段 | 类型 | 描述 |
| ------------------------------------ | ------ | ----------------------------------------------- |
| amount | float | 申购金额 |
| financial_application_key | string | 金融申购的唯一标识键 |
| asset_key | string | 相关资产的标识键 |
| quotation_date | string | 配额日期（YYYY-MM-DD） |
| status | string | 申购状态 |
| external_financial_application_key | string | 金融申购的外部标识 |
| issuance_serie | JSON | **[Issuance Serie](#issuance-serie)** 对象 |
| fund_class | JSON | **[Fund Class](#fund-class)** 对象 |

### Issuance Serie

| 字段 | 类型 | 描述 |
| ----------------------------- | ------ | ----------------------------------------------------- |
| issuance_serie_key | string | 发行系列的唯一标识键 |
| name | string | 发行系列名称 |
| subclass_name | string | 子类名称（例如：SUBORDINADA） |
| serie | int | 系列编号 |
| quota_calculation_method | string | 配额计算方法（例如：quota_value） |
| internal_code | string | 系列内部代码 |
| fund_class_name | string | 与系列关联的基金类别名称 |
| fund_class_short_name | string | 基金类别的简短名称 |
| fund_class_document_number | string | 基金类别的 CNPJ |
| minimum_share_capital | float | 最低申购金额 |
| investment_category | string | 投资类别（例如：multi_market） |
| payment_type | string | 付款类型（例如：transfer） |
| account_data | JSON | **[Account Data](#account-data)** 对象 |
| last_updated_date | string | 最后更新日期（YYYY-MM-DD） |
| administrator | JSON | **[Administrator](#administrator)** 对象 |
| operation_periods | JSON | **[Operation Periods](#operation-periods)** 对象 |
| isin_code | string | 系列的 ISIN 代码 |

### Administrator

| 字段 | 类型 | 描述 |
| ------------------ | ------ | ---------------------------- |
| administrator_key | string | 管理员的唯一标识键 |
| name | string | 管理员名称 |
| document_number | string | 管理员的 CNPJ |

### Operation Periods

| 字段 | 类型 | 描述 |
| ---------------------- | ---- | -------------------------------------------------------------------------------------- |
| redemption_request | JSON | 赎回的**[配额与付款](#quotation-and-payment)**周期对象 |
| amortization_request | JSON | 摊销的**[配额与付款](#quotation-and-payment)**周期对象 |
| financial_application | JSON | 申购的**[配额与付款](#quotation-and-payment)**周期对象 |

### Quotation and Payment

| 字段 | 类型 | 描述 |
| -------------- | ------ | ------------------------------------------------ |
| days | int | 天数 |
| type | string | 计算类型（例如：fixed、until） |
| calendar_base | string | 历法基准（例如：workdays、calendar_365） |

### Account Data

| 字段 | 类型 | 描述 |
| ---------------------------- | ------ | ----------------------------------------------------------------- |
| account_digit | string | 银行账户校验位 |
| account_branch | string | 银行支行号 |
| account_number | string | 银行账户号码 |
| financial_institution_code | string | 金融机构代码 |
| financial_institution_ispb | string | 金融机构 ISPB（巴西支付系统） |

### Fund Class

| 字段 | 类型 | 描述 |
| ---------------- | ------ | ----------------------------------------- |
| fund_class_key | string | 基金类别的唯一标识键 |
| name | string | 基金类别全名 |
| short_name | string | 基金类别简称 |
| document_number | string | 基金类别的 CNPJ |
| accounting_date | string | 最新会计日期 |
| distributor | JSON | **[Distributor](#distributor)** 对象 |
| manager | JSON | **[Manager](#manager)** 对象 |

### Distributor

| 字段 | 类型 | 描述 |
| ---------------- | ------ | --------------------------- |
| name | string | 分销商名称 |
| distributor_key | string | 分销商的唯一标识键 |
| document_number | string | 分销商的 CNPJ |

### Manager

| 字段 | 类型 | 描述 |
| ---------------- | ------ | --------------------------------- |
| manager_key | string | 基金经理的唯一标识键 |
| manager_name | string | 基金类别的基金经理名称 |
| document_number | string | 基金经理的 CNPJ |

---

# 按基金类别查询赎回

URL: /zh-Hans/documentation/iaas/cotas_de_fundo/consulta_paginada_resgates

:::warning 注意
此资源仅适用于担任基金经理角色的集成方。
:::

### Request

ENDPOINT /trade_fund_quota/fund_class/FUND_CLASS_KEY/redemption_requests
MÉTODO GET

#### Query Params

| 参数 | 类型 | 描述 |
| ------------------------------- | ------ | ------------------------------------------- |
| `quotation_date` | date | 赎回的配额日期 |
| `redemption_request_status` | string | 按特定状态过滤赎回 |
| `not_redemption_request_status` | string | 排除特定状态的赎回 |
| `document_number` | string | 被投资基金类别的 CNPJ |

### Response

STATUS 200

案例 01：返回一个赎回

```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
| 字段 | 类型 | 描述 |
| -------------- | ------- | ----------------------------------------------------------------- |
| `data` | array | **[Redemption Request](#redemption-request)** 对象列表 |
| `limit` | int | 每页返回的对象数量上限 |
| `page` | int | 当前返回的页码 |
| `is_last_page` | boolean | 表示当前页是否为最后一页 |

### Redemption Request

| 字段 | 类型 | 描述 |
| ---------------------------------- | ------ | ----------------------------------------------- |
| redemption_request_key | string | 赎回申请的唯一标识键 |
| external_redemption_request_key | string | 外部控制标识键（可选） |
| status | string | 赎回状态（例如：confirmed） |
| quotation_date | string | 赎回配额日期 |
| payment_date | string | 赎回付款日期 |
| amount | float | 赎回金额 |
| issuance_serie | JSON | **[Issuance Serie](#issuance-serie)** 对象 |
| fund_class | JSON | **[Fund Class](#fund-class)** 对象 |

### Issuance Serie

| 字段 | 类型 | 描述 |
| ----------------------------- | ------ | ----------------------------------------------------- |
| issuance_serie_key | string | 发行系列的唯一标识键 |
| name | string | 发行系列名称 |
| subclass_name | string | 子类名称（例如：SUBORDINADA） |
| serie | int | 系列编号 |
| quota_calculation_method | string | 配额计算方法（例如：quota_value） |
| internal_code | string | 系列内部代码 |
| fund_class_name | string | 与系列关联的基金类别名称 |
| fund_class_short_name | string | 基金类别的简短名称 |
| fund_class_document_number | string | 基金类别的 CNPJ |
| minimum_share_capital | float | 最低申购金额 |
| investment_category | string | 投资类别（例如：multi_market） |
| payment_type | string | 付款类型（例如：transfer） |
| account_data | JSON | **[Account Data](#account-data)** 对象 |
| last_updated_date | string | 最后更新日期（YYYY-MM-DD） |
| administrator | JSON | **[Administrator](#administrator)** 对象 |
| operation_periods | JSON | **[Operation Periods](#operation-periods)** 对象 |
| isin_code | string | 系列的 ISIN 代码 |

### Administrator

| 字段 | 类型 | 描述 |
| ------------------ | ------ | ---------------------------- |
| administrator_key | string | 管理员的唯一标识键 |
| name | string | 管理员名称 |
| document_number | string | 管理员的 CNPJ |

### Operation Periods

| 字段 | 类型 | 描述 |
| ---------------------- | ---- | -------------------------------------------------------------------------------------- |
| redemption_request | JSON | 赎回的**[配额与付款](#quotation-and-payment)**周期对象 |
| amortization_request | JSON | 摊销的**[配额与付款](#quotation-and-payment)**周期对象 |
| financial_application | JSON | 申购的**[配额与付款](#quotation-and-payment)**周期对象 |

### Quotation and Payment

| 字段 | 类型 | 描述 |
| -------------- | ------ | ------------------------------------------------ |
| days | int | 天数 |
| type | string | 计算类型（例如：fixed、until） |
| calendar_base | string | 历法基准（例如：workdays、calendar_365） |

### Account Data

| 字段 | 类型 | 描述 |
| ---------------------------- | ------ | ----------------------------------------------------------------- |
| account_digit | string | 银行账户校验位 |
| account_branch | string | 银行支行号 |
| account_number | string | 银行账户号码 |
| financial_institution_code | string | 金融机构代码 |
| financial_institution_ispb | string | 金融机构 ISPB（巴西支付系统） |

### Fund Class

| 字段 | 类型 | 描述 |
| ---------------- | ------ | ----------------------------------------- |
| fund_class_key | string | 基金类别的唯一标识键 |
| name | string | 基金类别全名 |
| short_name | string | 基金类别简称 |
| document_number | string | 基金类别的 CNPJ |
| accounting_date | string | 最新会计日期 |
| distributor | JSON | **[Distributor](#distributor)** 对象 |
| manager | JSON | **[Manager](#manager)** 对象 |

### Distributor

| 字段 | 类型 | 描述 |
| ---------------- | ------ | --------------------------- |
| name | string | 分销商名称 |
| distributor_key | string | 分销商的唯一标识键 |
| document_number | string | 分销商的 CNPJ |

### Manager

| 字段 | 类型 | 描述 |
| ---------------- | ------ | --------------------------------- |
| manager_key | string | 基金经理的唯一标识键 |
| manager_name | string | 基金类别的基金经理名称 |
| document_number | string | 基金经理的 CNPJ |

---

# 查询发行系列

URL: /zh-Hans/documentation/iaas/cotas_de_fundo/consulta_paginada_series_de_emissao

:::warning 注意
此资源仅适用于担任**基金经理**角色的集成方。
:::

### Request

ENDPOINT /trade_fund_quota/issuance_series
MÉTODO GET

#### Query Params

| 参数 | 类型 | 描述 |
| ---------------------------- | ------ | ---------------------------------- |
| `fund_class_document_number` | string | 基金的 CNPJ（00.000.000/0001-00） |

### Response

STATUS 200

案例 01：返回一个系列

```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
| 字段 | 类型 | 描述 |
|---------------|--------|------------------------------------------------------------------------------|
| `data` | array | **[Issuance Serie](#issuance_serie)** 对象列表 |
| `limit` | int | 每页返回的对象数量上限 |
| `page` | int | 当前返回的页码 |
| `is_last_page` | boolean | 表示当前页是否为最后一页 |

### Issuance Serie

| 字段 | 类型 | 描述 |
| ----------------------------- | ------ | ----------------------------------------------------- |
| issuance_serie_key | string | 发行系列的唯一标识键 |
| name | string | 发行系列名称 |
| subclass_name | string | 子类名称（例如：SUBORDINADA） |
| serie | int | 系列编号 |
| quota_calculation_method | string | 配额计算方法（例如：quota_value） |
| internal_code | string | 系列内部代码 |
| fund_class_name | string | 与系列关联的基金类别名称 |
| fund_class_short_name | string | 基金类别的简短名称 |
| fund_class_document_number | string | 基金类别的 CNPJ |
| minimum_share_capital | float | 最低申购金额 |
| investment_category | string | 投资类别（例如：multi_market） |
| payment_type | string | 付款类型（例如：transfer） |
| account_data | JSON | **[Account Data](#account-data)** 对象 |
| last_updated_date | string | 最后更新日期（YYYY-MM-DD） |
| administrator | JSON | **[Administrator](#administrator)** 对象 |
| operation_periods | JSON | **[Operation Periods](#operation-periods)** 对象 |
| isin_code | string | 系列的 ISIN 代码 |

### Administrator

| 字段 | 类型 | 描述 |
| ------------------ | ------ | ---------------------------- |
| administrator_key | string | 管理员的唯一标识键 |
| name | string | 管理员名称 |
| document_number | string | 管理员的 CNPJ |

### Operation Periods

| 字段 | 类型 | 描述 |
| ---------------------- | ---- | -------------------------------------------------------------------------------------- |
| redemption_request | JSON | 赎回的**[配额与付款](#quotation-and-payment)**周期对象 |
| amortization_request | JSON | 摊销的**[配额与付款](#quotation-and-payment)**周期对象 |
| financial_application | JSON | 申购的**[配额与付款](#quotation-and-payment)**周期对象 |

### Quotation and Payment

| 字段 | 类型 | 描述 |
| -------------- | ------ | ------------------------------------------------ |
| days | int | 天数 |
| type | string | 计算类型（例如：fixed、until） |
| calendar_base | string | 历法基准（例如：workdays、calendar_365） |

### Account Data

| 字段 | 类型 | 描述 |
| ---------------------------- | ------ | ----------------------------------------------------------------- |
| account_digit | string | 银行账户校验位 |
| account_branch | string | 银行支行号 |
| account_number | string | 银行账户号码 |
| financial_institution_code | string | 金融机构代码 |
| financial_institution_ispb | string | 金融机构 ISPB（巴西支付系统） |

---

# 简介

URL: /zh-Hans/documentation/iaas/cotas_de_fundo/inicio

基金份额系统是一种允许买卖和查询其他基金份额的解决方案。该模块提供以下基本功能：

- 管理对其他基金的申购和赎回
- 创建操作

本文档提供了如何使用基金份额系统的详细说明，包括其主要功能和流程。您将在此找到以下信息：

- 与其他基金份额相关的买入、卖出及查询
- 端点和请求体

要开始使用该系统，请浏览本文档中的可用主题，以便更好地了解基金份额模块的各个方面。

---

# 创建金融申购

URL: /zh-Hans/documentation/iaas/cotas_de_fundo/operacao_aplicacoes_financeiras

---
:::warning 注意
此资源仅适用于担任基金经理角色的集成方。
:::

### 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 **注意**
当操作涉及 "payment_type" 为 "automatic_debit"（通常为清零基金）的系列时，必须发送 source_account_key。

此操作不会实际产生申购，仅创建预期记录并将资金转至您名下的账户，以便后续完成操作。

您可以通过以下端点获取此键：[`获取账户信息`](/documentation/iaas/visibildade_de_caixa/get_accounts)
其中 source_account_key 即为您希望进行申购的机构的 account_key。

否则请勿发送此字段。
:::

### Body params
| 字段 | 类型 | 描述 | 必填 |
| -------------------- | ------ | ------------------------------------------------ | ----------- |
| `issuance_serie_key` | string | 发行系列的唯一标识键 | 是 |
| `amount` | float | 申购金额 | 是 |
| `source_account_key` | string | 资金目标银行账户的标识键 | 否 |
| `quotation_date` | string | 配额日期，格式为 `YYYY-MM-DD` | 否 |
| `payment_method` | string | 付款方式（`wire_transfer`、`pix`） | 否 |

### 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"
    }
}
}
```

# 审批金融申购

---

### 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
| 字段 | 类型 | 描述 |
| -------- | ------ | -------------------------------------------------------------------- |
| `status` | string | 赎回申请的新状态。请参见下方允许的值。 |

### 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"}
}
}
```

# 取消金融申购

---

### Request

ENDPOINT /trade_fund_quota/fund_class/FUND_CLASS_KEY/financial_application/FINANCIAL_APPLICATION_KEY/cancel
MÉTODO PUT
STATUS 202

:::note **注意**
只有当申购申请处于以下状态之一时，才能取消：
 - pending_manager_approval
 - pending_distributor_approval

否则您将收到错误代码：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"}
}
}
```

---

# 创建赎回申请

URL: /zh-Hans/documentation/iaas/cotas_de_fundo/operacao_resgates

---
:::warning 注意
此资源仅适用于担任基金经理角色的集成方。
:::

### 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 **注意**
当操作涉及 "payment_type" 为 "automatic_debit"（通常为清零基金）的系列时，必须发送 source_account_key。

此操作不会实际产生赎回，仅创建预期记录并将资金转至您名下的账户，以便后续完成操作。

您可以通过以下端点获取此键：[`获取账户信息`](/documentation/iaas/visibildade_de_caixa/get_accounts)
其中 source_account_key 即为您希望进行赎回的机构的 account_key。

否则请勿发送此字段。
:::

### Body params
| 字段 | 类型 | 描述 | 必填 |
| -------------------- | ------- | ------------------------------------------------------------ | ----------- |
| `issuance_serie_key` | string | 发行系列的唯一标识键 | 是 |
| `external_id` | string | 赎回申请的唯一外部标识 | 是 |
| `amount` | float | 赎回总金额（若 `redeem_all` 为 `true` 则忽略） | 否 |
| `source_account_key` | string | 基金类别的来源银行账户标识键 | 否 |
| `redeem_all` | boolean | 表示是否为全额赎回 | 否 |

### 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"
    }
  }
}
```

# 审批赎回申请

---

### 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
| 字段 | 类型 | 描述 |
| -------- | ------ | -------------------------------------------------------------------- |
| `status` | string | 赎回申请的新状态。请参见下方允许的值。 |

### 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,
    "fund_class_name": "Fund Class Name",
    "fund_class_short_name": "Fund Class Short Name",
    "fund_class_document_number": "00.000.000/0000-00"
  },
  "fund_class": {
    "fund_class_key": "UUID",
    "name": "Fund Class Name",
    "document_number": "00.000.000/0000-00"
  }
}
```

# 取消赎回申请

---

### Request

ENDPOINT /trade_fund_quota/fund_class/FUND_CLASS_KEY/redemption_request/REDEMPTION_REQUEST_KEY/cancel
MÉTODO PUT
STATUS 202

:::note **注意**
只有当赎回申请处于以下状态之一时，才能取消：
 - pending_manager_approval
 - pending_distributor_approval

否则您将收到错误代码：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,
    "fund_class_name": "Fund Class Name",
    "fund_class_document_number": "00.000.000/0000-00"
  },
  "fund_class": {
    "fund_class_key": "UUID",
    "name": "Fund Class Name",
    "document_number": "00.000.000/0000-00"
  }
}
```

---

# Consulta de despesas consolidadas

URL: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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 |

---

# 发行 - 整合认购

URL: /zh-Hans/documentation/iaas/emissoes/cadastrar_boleta

---

## 整合认购

使用以下端点，可以开始对某一发行进行整合认购。

### 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"
   }
  }
}

```

### 定义

#### 买入操作

| 字段 | 类型 | 描述 | 必填 |
| ------------------------------| ------ | ------------------------------------------------ | ----------- |
| `security_external_id` | string | 资产的外部标识 | 是* |
| `bookkeeper_document_number` | string | 记账员的 CNPJ 编号 | 是* |
| `security_key` | string | 资产的内部标识键 | 是* |
| `unit_price` | float | 整合认购时的单价 | 是 |
| `number_of_units` | float | 购买的单位数量 | 是 |
| `external_id` | string | 买入操作的外部标识 | 是 |
| `integralization_date` | string | 整合认购日期 | 是 |
| `payment` | dict | 用于清算的[付款](#付款)对象 | 是 |

:::note ⚠️ **重要** ( * )
结构化资产的标识可通过以下两种方式之一进行：

1. 提供 `security_key` 字段**(内部标识键)**；**或**
2. **同时**提供 `security_external_id` 和 `bookkeeper_document_number` 字段。

请求体中必须存在**至少一种标识方式**。若两者均存在，将优先使用内部标识键。
:::

##### 付款

| 字段 | 类型 | 描述 | 必填 |
| ---------------------------- | ------ | --------------------------------------------------- | ----------- |
| `target_account` | string | 用于清算的[银行账户](#银行账户)对象 | 是 |

##### 银行账户

| 字段 | 类型 | 描述 | 必填 |
| ---------------------------- | ------ | --------------------------------------------------- | ----------- |
| `account_branch` | string | 银行账户支行 | 是 |
| `account_digit` | string | 账户校验位 | 是 |
| `account_number` | string | 银行账户号码 | 是 |
| `financial_institution_code` | string | 金融机构代码 | 是 |
| `financial_institution_ispb` | string | 金融机构 ISPB 代码 | 是 |

### 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",
}
```

---

# 资产注册 - 发行

URL: /zh-Hans/documentation/iaas/emissoes/cadastro_ativo

---

## 创建 - 商业票据

使用以下端点，可以在结构化资产管理系统中注册一个新票据。

注册的资产初始状态为 **pre_operational**，以便提交与该资产相关的文件。这样可以预先注册资产，只有在正式手续完成后才启用其操作，详情见下一节。

以下列出了各字段的说明及其必填要求和类型。

### 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"
    }
}

```

## 定义

### 资产对象（请求体）

| 字段 | 类型 | 描述 | 必填 |
| ------------------------------| ------ | ------------------------------------------------ | ----------- |
| `asset_type` | string | 确定[资产类型](#资产类型枚举)的枚举值 | 是 |
| `external_id` | string | 资产的外部标识；用于访问实体的键 | 是 |
| `b3_code` | string | 资产的 Cetip 代码 | 否 |
| `isin_code` | string | ISIN 代码（国际证券识别码） | 否 |
| `ipoc_code` | string | 资产的 IPOC 代码 | 否 |
| `allowed_managers` | list | 有权在发行中操作的基金经理 CNPJ 列表 | 否 |
| `allowed_consultants` | list | 有权在发行中操作的顾问 CNPJ 列表 | 否 |
| `issuer_document_number` | string | 发行人的 CNPJ 或 CPF 编号 | 是 |
| `bookkeeper_document_number` | string | 记账员的 CNPJ 编号 | 是 |
| `number_of_units` | float | 单位数量 | 是 |
| `issue_unit_price` | float | 发行时的单价 | 是 |
| `issue_value` | float | 发行时的资产价值 | 是 |
| `principal_unit_price` | float | 发行时资产的本金单价 | 是 |
| `issue_date` | string | 发行日期，格式为 `YYYY-MM-DD` | 是 |
| `disbursement_date` | string | 放款日期，格式为 `YYYY-MM-DD` | 是 |
| `amortization_type` | string | [摊销类型](#摊销类型枚举)的枚举值 | 是 |
| `contract_number` | string | 合同编号 | 是 |
| `maturity_date` | string | 资产到期日 | 是 |
| `installments` | dict | [分期付款](#分期付款对象)对象 | 是 |
| `delay` | dict | [逾期](#逾期对象)对象 | 是 |
| `pre_fixed` | dict | [固定利率](#固定利率对象)对象 | 是 |
| `post_fixed` | dict | [浮动利率](#浮动利率对象)对象 | 否 |

#### 资产类型枚举

| 枚举值 | 描述 |
|--------------|---------------|
| **commercial_paper** | 商业票据类资产 |
| **debenture** | 债券类资产 |
| **cri** | CRI 类资产 |
| **cra** | CRA 类资产 |

#### 摊销类型枚举

| 枚举值 | 描述 |
|--------------|---------------|
| **sac** | SAC 摊销类型 |
| **price** | Price 摊销类型 |

#### 分期付款对象

| 字段 | 类型 | 描述 | 必填 |
| ------------------------------- | ------ | -------------------------------------------| ----------- |
| `installment_number` | int | 分期编号 | 是 |
| `maturity_date` | string | 到期日，格式为 `YYYY-MM-DD` | 是 |
| `principal_unit_price` | float | 资产的本金单价 | 是 |
| `face_unit_price` | float | 资产的面值单价 | 是 |
| `amortization_percentage` | float | 摊销百分比 | 否 |

#### 逾期对象

| 字段 | 类型 | 描述 | 必填 |
|-|-|-|-|
| `fine` | object | 到期罚款对象。请参见**[逾期罚款对象](#逾期罚款对象)**。 | 是 |
| `interest` | object | 逾期利息对象。请参见**[逾期利息对象](#逾期利息对象)**。 | 是 |

#### 逾期罚款对象

| 字段 | 类型 | 描述 | 必填 |
|-|-|-|-|
| `fine_type` | string | 罚款类型。 | 是 |
| `percentage_value` | number | 若罚款类型为 `percentage`，则为罚款金额。取值范围：0 至 1（对应 0% 至 100%） | 是 |
| `amount` | number | 若罚款类型为 `fixed`，则为罚款金额。 | 是 |

##### 罚款类型枚举

| 枚举值 | 描述 |
|----------------|-------------------------------------------|
| **percentage** | 按分期金额的百分比罚款 |
| **fixed** | 固定罚款金额 |

#### 逾期利息对象

| 字段 | 类型 | 描述 | 必填 |
|-|-|-|-|
| `method` * | string | 请参见**[逾期利息方法枚举](#逾期利息方法枚举)**。 | 是 |
| `pre_fixed` * | object | 请参见**[固定利率对象](#固定利率对象)**。 | 是 |

##### 逾期利息方法枚举

| 枚举值 | 描述 |
|--------------|-----------------------------|
| **compound** | 复利逾期利息 |
| **simple** | 单利逾期利息 |

#### 固定利率对象

| 字段 | 类型 | 描述 | 必填 |
|-|-|-|-|
| `calendar_base` * | string | 所用计算基准。 | 枚举值 |
| `monthly_rate` * | number | 合同月利率。1% 使用 0.01 | 最多 8 位小数 |

#### 浮动利率对象

| 字段 | 类型 | 描述 | 必填 |
|---------------|--------|-----------------------------------------------------|-------------|
| rate | int | 适用的固定利率 | 是 |
| indexer | string | 调整参考指数（di、ipca） | 是 |
| calendar_base | string | 所用历法类型 | 是 |

#### Lag 对象

| 字段 | 类型 | 描述 | 必填 |
|-----------|--------|------------------------------------------------|-------------|
| amount | int | 滞后单位数量 | 是 |
| reference | string | 滞后时间单位 | 是 |

#### 计算基准枚举

| 枚举值 | 描述 |
|--------------|---------------|
| **daily** | 逾期的日计算值 |
| **monthly** | 逾期的月计算值 |

#### 逾期参考枚举

| 枚举值 | 描述 |
|--------------|---------------|
| **workdays** | 工作日（252）计算基准 |
| **calendar_365** | 365 天计算基准 |
| **calendar_360** | 360 天计算基准 |

### Response

STATUS 201

```json title='Response Body'
{
    "security_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "status": "pre_operational",
}
```

---

# 发行确认

URL: /zh-Hans/documentation/iaas/emissoes/confirmacao_emissao

## 确认 - 商业票据

完成所有正式手续并在资产中注册相关文件后，即可审批该资产，表明其已准备好进行后续操作。

值得注意的是，买入操作可以在预运营资产上发起，但在资产发行确认之前，这些操作无法进行清算。

### Request

ENDPOINT /security/security/EXTERNAL_ID/confirm
MÉTODO PUT

```json title="Request Body"
{
 "bookkeeper_document_number": "00.000.000/0000-00"
}

```

| 字段 | 类型 | 描述 | 必填 |
| ------------------------------| ------ | ---------------------------------------------------- | ----------- |
| `bookkeeper_document_number` | string | 用于标识发行的记账员 CNPJ | 是 |

#### 定义

### Response

STATUS 202

```json title='Response Body'
{
    "security_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "status": "active",
}
```

---

# 简介

URL: /zh-Hans/documentation/iaas/emissoes/inicio

发行生态系统负责商业票据、债券、CRI 和 CRA 等资产的创建、买卖及付款。可用功能包括：

- 注册新的预运营资产；
- 确认发行；
- 创建买卖交易单；

本文档提供了如何使用发行系统的详细说明，包括其主要功能和流程。

要开始使用该系统，请浏览本文档中的可用主题，以便更好地了解基金份额模块的各个方面。

---

# Apontamentos de Compliance

URL: /zh-Hans/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. |

---

# 注册更新

URL: /zh-Hans/documentation/iaas/homologacao_cedente/cadastro/atualizacao_de_cadastro

基金经理有责任根据公司的实际情况保持转让方数据的更新。这一承诺极为重要，既能保持反洗钱分析的最新状态，也能更新签署人组，签署人组会不断变化并会过期，因此需要进行新的分析。此外，每 2 年会自动生成一次新的分析，以确保定期更新。

:::warning 注意
基金经理有责任保持转让方数据的更新，并反映公司的实际情况。
:::

更新注册时，无论更改了哪个字段，都将生成新的分析，该分析将根据所做的更改要求新的文件。分析有顺序编号，可能会多次失败，直到最终获得合规团队的批准。更改只有在分析成功完成后才会生效。如果关联方发生更改，将进行转让方签署人组的验证阶段。需要注意的是，如果关联方或担保人**未被发送**，将被视为**已删除**。

:::info
如果分析正在进行中，且发送了注册更新，最后一次未完成的分析将自动关闭并被拒绝，原因为"assignor_update"。
:::

---

## 法人转让方注册更新

### 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"
        }
      ]
    }
  ]
}
```

---

### 转让方定义

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `annual_revenues` | number | 转让方的年营收声明。 | - |
| `email` | string | 转让方的电子邮件地址。 | 1 至 255 |
| `is_in_national_financial_system` | boolean | 表示转让方是否为 SFN 成员。 | - |
| `phone` | object | 转让方电话信息对象。 | 请参见**[电话定义](#definição-de-telefone)**。 |
| `address` | object | 转让方地址信息对象。 | 请参见**[地址定义](#definição-de-endereço)**。 |
| `related_parties` | array | 公司关联方列表。 | 请参见**[关联方定义](#definição-de-parte-relacionada)**。 |
| `guarantors` | array | 转让方担保人列表。 | 请参见**[担保人定义](#definição-de-avalista)**。 |

如果不想更改某个字段，只需在请求中不发送该字段。对于列表，如 `related_parties` 和 `guarantors`，如果发送了空列表，或之前列表中存在但新列表中未包含的某方，将被视为删除处理。

### 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": []
      }
    ],
    "documents": [],
    "analysis_data": {}
  }
}
```

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `assignor_registry_key` | string | 注册标识符。 | 36 |
| `status` | string | 注册状态。 | 请参见**[注册状态枚举](#assignor-registry-status)**。 |
| `name` | string | 转让方名称。 | 1 至 255 |
| `document_number` | string | 转让方文件。 | 14 至 18 |
| `last_analysis` | object | 审查对象。 | 请参见**[审查定义](#definição-de-análise)**。 |

:::info
重要的是存储 `analysis_key` 和 `analysis_related_party_key`，它们将用于提交转让方和关联方的文件。
:::

---

:::caution 注意！
更新转让方注册时，将生成新的注册分析，产生新的 `analysis_key` 和新的 `analysis_related_party_key`。注册只有在此新分析获得批准后才会正式更新。
:::

:::caution 重要！
无法更新转让方的基本数据，如**文件编号**和**人员类型**。可更改的注册数据包括：
- 名称/公司名称；
- 电子邮件；
- 地址；
- 电话；
- 营收；
- SFN 参与状态；
- 关联方（现有关联方的添加和更改）；
- 担保人（现有担保人的添加和更改）；
:::

---
## 定义

### 地址定义

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `street` * | string | 街道名称。 | 1 至 255 |
| `number` * | string | 门牌号。 | 1 至 4 |
| `neighborhood` * | string | 社区/街区。 | 1 至 255 |
| `city` * | string | 城市。 | 1 至 255 |
| `uf` * | string | 州缩写。 | 2 |
| `complement` | string | 地址补充信息。 | 1 至 255 |
| `postal_code` * | string | 邮政编码。 | 9（格式：XXXXX-XXX） |
| `country` * | string | 国家（缩写）。 | 3 |

*必填字段。

---

### 电话定义

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `international_dial_code` * | string | 国际拨号代码。 | 1 至 3 |
| `area_code` * | string | 区号。 | 2 |
| `number` * | string | 电话号码。 | 8 至 9 |

*必填字段。

---

### 关联方定义

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `name` * | string | 关联方名称。 | 1 至 255 |
| `document_number` ** | string | 受益人文件编号（CPF）。 | 14 至 18 |
| `passport_number` ** | string | 外国受益人文件编号。 | 8 至 9 |
| `related_party_type` * | string | 关联方的关联类型。 | 请参见**[关联方类型枚举](#related-party-type)**。 |
| `nationality` * | string | 受益人的来源国。 | 3，按 ISO 3166-1 alpha-3 |
| `direct_beneficiary` * | boolean | 与转让方直接或间接关联的受益人。 | 1 至 255 |
| `is_representative` * | boolean | 表示关联方是否为转让方的签署代表。 | 1 至 255 |
| `company_registry_number` *** | string | 若非直接与转让方关联，关联的公司。 | 1 至 255 |
| `company_country` *** | string | 受益人与转让方之间中介公司所在国。 | 3，按 ISO 3166-1 alpha-3 |
| `address` | object | 代表地址信息对象。 | 请参见**[地址定义](#definição-de-endereço)**。 |
| `email` **** | string | 代表的电子邮件地址。 | 1 至 255 |
| `phone` | object | 代表电话信息对象。 | 请参见**[电话定义](#definição-de-telefone)**。 |
| `marital_status` | string | 关联方婚姻状况。 | 请参见**[婚姻状况枚举](#marital-status)**。 |
| `property_system` | string | 财产分离制度。 | 请参见**[财产制度枚举](#property-system)**。 |
| `profession` | string | 关联方职业。 | 1 至 255。 |

*必填字段。
**巴西人需要 document_number，外国人需要 passport_number。
***若关联方与转让方非直接关联，则为必填。
****仅签署代表必填。

---

### 审查定义

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `analysis_key` * | string | 审查标识符。 | 36 |
| `analysis_number` * | integer | 审查的顺序编号。 | - |
| `status` * | string | 审查状态。 | 请参见**[审查状态枚举](#analysis-status)**。 |
| `analysis_related_parties` * | array | 审查的关联方。 | 请参见**[审查关联方定义](#definição-de-partes-relacionadas-de-análise)**。 |
| `documents` * | array | 审查的文件。 | 请参见**[文件定义](#definição-de-documentos)**。 |
| `analysis_data` * | object | 生成该审查的请求负载。 | - |
| `analysis_datetime` * | string | 审查创建的日期时间对象。 | - |
| `reproval_reason` | string | 审查拒绝原因的枚举值。 | 请参见**[拒绝原因枚举](#analysis-reproval-reason)**。 |
| `reproval_details` | string | 审查拒绝详情的自由字段。 | - |

*必填字段。

---

### 担保人定义

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `name` * | string | 担保人名称。 | 3 至 255 |
| `document_number` * | string | 担保人文件编号。 | 14 至 18 |
| `person_type` * | string | 担保人的人员类型（自然人或法人）。 | - |
| `email` * | string | 担保人的电子邮件地址。 | 1 至 255 |
| `nationality` | string | 担保人的来源国。 | 3，按 ISO 3166-1 alpha-3 |
| `phone` | object | 担保人电话信息对象。 | 请参见**[电话定义](#definição-de-telefone)**。 |
| `address` | object | 担保人地址信息对象。 | 请参见**[地址定义](#definição-de-endereço)**。 |
| `guarantor_representatives` | array | 担保人的签署代表 - 仅适用于法人担保人。 | 请参见**[担保人代表定义](#definição-de-representante-do-avalista)**。 |
| `marital_status` | string | 担保人婚姻状况。 | 请参见**[婚姻状况枚举](#marital-status)**。 |
| `property_system` | string | 财产分离制度。 | 请参见**[财产制度枚举](#property-system)**。 |
| `profession` | string | 担保人职业。 | 1 至 255。 |

*必填字段。

担保人代表仅应为法人担保人发送。

:::warning 注意
担保人及其代表也将被添加到生成的分析中，需要根据其人员类型发送标准文件。他们也将经过合规流程，可能会产生问题点。
:::

---

### 担保人代表定义

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `name` * | string | 代表名称。 | 3 至 255 |
| `document_number` * | string | 担保人代表的文件编号 - 必须为自然人。 | 14 |
| `email` * | string | 担保人代表的电子邮件地址。 | 1 至 255 |
| `nationality` | string | 担保人代表的来源国。 | 3，按 ISO 3166-1 alpha-3 |
| `address` | object | 担保人代表地址信息对象。 | 请参见**[地址定义](#definição-de-endereço)**。 |
| `phone` | object | 担保人代表电话信息对象。 | 请参见**[电话定义](#definição-de-telefone)**。 |
| `marital_status` | string | 担保人代表婚姻状况。 | 请参见**[婚姻状况枚举](#marital-status)**。 |
| `property_system` | string | 财产分离制度。 | 请参见**[财产制度枚举](#property-system)**。 |
| `profession` | string | 担保人代表职业。 | 1 至 255。 |

---

### 文件定义

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `document_key` * | string | 文件标识符。 | 36 |
| `document_type` * | string | 文件类型。 | 请参见**[文件类型枚举](#document-type)**。 |
| `status` | string | 文件状态。 | 请参见**[文件状态枚举](#document-status)**。 |
| `observation` | string | 发送的备注。 | - |

*必填字段。

---

### 审查关联方定义

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `analysis_representative_key` * | string | 代表标识符。 | 36 |
| `document_number` * | string | 代表文件编号。 | 14 至 18 |
| `name` | string | 受益人名称。 | 1 至 255 |
| `documents` * | 枚举值 | 代表审查的文件。 | 请参见**[文件定义](#definição-de-documentos)**。 |

*必填字段。

---

# 枚举值

### Assignor Registry Status

| 枚举值 | 描述 |
| -------------------------- | ----------------- |
| **pending_registry** | 待注册 |
| **registered** | 已注册 |

---

### Analysis Status

| 枚举值 | 描述 |
| ----------------------- | --------------------- |
| **pending_documents** | 待提交文件 |
| **sent_to_analysis** | 已发送审查 |
| **pending_internal_validation** | 文件验证中 |
| **in_manual_analysis** | 合规手动审查中 |
| **approved** | 已批准 |
| **reproved** | 已拒绝 |

---

### Related Party Type

| 枚举值 | 描述 |
| ----------------------- | ------------- |
| **president** | 总裁 |
| **partner** | 合伙人 |
| **administrator** | 管理人 |
| **director** | 董事 |
| **manager** | 经理 |
| **attorney** | 代理人 |

---

### Document Status

| 枚举值 | 描述 |
| ----------------------- | ------------- |
| **created** | 已创建 |
| **valid** | 有效 |
| **invalid** | 无效 |
| **canceled** | 已取消 |
| **accepted** | 已接受，但未验证 |

---

### Document Type

| 枚举值 | 描述 |
| ---------------------------- | -------------------------- |
| **cnh** | 驾驶执照。 |
| **rg_back** | 身份证背面。 |
| **rg_front** | 身份证正面。 |
| **passport** | 护照 - 仅限外国人。 |
| **national_migration_registry** | 国家移民登记。 |
| **cin_digital** | 国家数字身份证。 |
| **social_contract** | 社会合同/公司章程。 |
| **cnpj_card** | CNPJ 卡。 |
| **commercial_board_certificate** | 商业局简化证书。 |
| **board_election_record** | 现任董事会选举记录。 |
| **power_of_attorney** | 授权委托书 - 若代表为代理人则为必填。 |
| **marital_power_of_attorney** | 婚姻授权委托书 - 仅适用于配偶。 |
| **compliance_statement** | 合规意见书。 |
| **financial_statement** | 财务报表。 |
| **credit_report** | 信贷记录/意见书。 |
| **manager_statement** | 基金经理意见书/表格。 |
| **visit_report** | 访问报告。 |
| **proof_of_residence** | 居住证明。 |
| **credit_agency_consulation** | 信用保护机构查询。 |
| **annual_revenues_declaration** | 年营收声明。 |
| **financial_institutions_declaration** | 银行关系声明。 |
| **additional_document** | 附加文件 - 自由格式。 |

---

### Analysis Reproval Reason

| 枚举值 | 描述 |
|--------------|---------------|
| **assignor_update** | 因后续注册更新而取消的分析 |
| **insuficient_documents** | 未提交证明授权所需的最少文件 |
| **compliance_reproval** | 合规团队分析拒绝关联 |
| **unidentified_related_parties** | 已提交关联方，但关联关系未得到证明 |
| **invalid_documents** | 文件无效/过期 |
| **missing_related_parties** | 未提交必要的关联方 |

---

### Marital Status

| 枚举值 | 描述 |
|--------------|---------------|
| **single** | 单身 |
| **married** | 已婚 |
| **widower** | 丧偶 |
| **divorced** | 离婚 |
| **separated** | 分居 |
| **stable_union** | 稳定伴侣关系 |

---

### Property System

| 枚举值 | 描述 |
| --------------------------------- | -------------------------------------- |
| **total_communion_of_goods** | 完全财产共有 |
| **partial_communion_of_goods** | 部分财产共有 |
| **total_separation_of_goods** | 完全财产分离 |
| **final_participation_of_acquisitions** | 婚后财产最终参与 |
| **compulsory_separation_of_goods** | 强制财产分离 |

---

# Definição de Assinantes

URL: /zh-Hans/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` ativo 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 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)**. |

### 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": "active",
      "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
}
```

### 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](#definição-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](#definição-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](#definição-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. |
| **active** | Conjunto vigente e utilizado nas assinaturas. |
| **inactive** | Conjunto substituído por uma versão mais recente ou desativado. |

---

# 提交审查

URL: /zh-Hans/documentation/iaas/homologacao_cedente/cadastro/disparo_da_analise

附上所有文件后，需触发审查，将所有数据发送至我们的反欺诈系统进行合规分析。如被拒绝，需重新进行审查；如获批准，将进行代表的内部验证，并建立转让方签署人结构，最终开始与该转让方的操作，并可创建转让方与基金之间的主合同。

---
### 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

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `analysis_status` * | string | 要发送的审查新状态（必须等于 **sent_to_analysis**）。 | 1 至 50 |

*必填字段。

### 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 注意！
审查应在附上所有相关文件后才正式提交。一旦提交审查，将无法再附加新文件。
:::

---

# 提交注册

URL: /zh-Hans/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro

在转让方注册的第一阶段，需要提交转让方的数据，如下所定义。
需要注意的是，仅提交数据并不能创建可运营的转让方，只有在文件审查成功完成后，转让方才会被激活。

对于法人实体（强制）和自然人（可选），可以注册关联方，代表与转让方相关的最终受益人。

:::info 信息
最终受益人定义为在公司或集团中具有重大影响力、拥有决策权或在股权结构中持有重大参股的个人或个人组成的群体。就注册目的而言，应考虑在公司或其所属集团中持股超过 15% 的任何关联方，或在没有如此重大参股的情况下，按降序排列的前三大关联方。
:::

如果相关受益人是另一家公司，则应指定其最终受益人，标记为间接受益人。此外，参与操作的代理人、管理人和董事也被视为关联方，他们将成为转让方的签署代表。

签署代表是负责跟踪和签署我们系统向转让方发送文件的关联方，需要提供关联关系的证明，对于公司而言，通过股权结构、董事或授权委托书证明。无法注册非代理人的关联方作为自然人转让方。此外，需要指明被视为最终受益人的关联方是否与转让方直接或间接关联。

:::info 信息
在验证环境中，审批规则如下：CPF/CNPJ 以 1 开头：自动拒绝；CPF/CNPJ 以 8 开头：待手动验证；其余自动批准。
:::
---
## 转让方注册

### 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",
      "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"
        }
      ]
    }
  ]
}
```

---

### 转让方定义

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `name` * | string | 转让方名称。 | 1 至 255 |
| `document_number` * | string | 转让方文件编号（CNPJ）。 | 14 至 18 |
| `annual_revenues` * | number | 转让方的年营收声明（整数）。 | 最小值为 1 |
| `person_type` * | string | 转让方的人员类型（自然人或法人）。 | - |
| `email` * | string | 转让方的电子邮件地址。 | 1 至 255 |
| `is_in_national_financial_system` * | boolean | 表示转让方是否为 SFN 成员。 | - |
| `phone` | object | 转让方电话信息对象。 | 请参见**[电话定义](#definição-de-telefone)**。 |
| `address` * | object | 转让方地址信息对象。 | 请参见**[地址定义](#definição-de-endereço)**。 |
| `related_parties` * | array | 公司关联方列表。 | 请参见**[关联方定义](#definição-de-parte-relacionada)**。 |
| `accounts` * | array | 转让方还款账户列表。 | 请参见**[账户定义](#definição-de-conta)**。 |
| `guarantors` * | array | 转让方担保人列表。 | 请参见**[担保人定义](#definição-de-avalista)**。 |

*必填字段。

### 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": []
      }
    ],
    "documents": [],
    "analysis_data": {}
  }
}
```

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `assignor_registry_key` | string | 注册标识符。 | 36 |
| `status` | string | 注册状态。 | 请参见**[注册状态枚举](#assignor-registry-status)**。 |
| `name` | string | 转让方名称。 | 1 至 255 |
| `document_number` | string | 转让方文件。 | 14 至 18 |
| `last_analysis` | object | 审查对象。 | 请参见**[审查定义](#definição-de-análise)**。 |

:::info
重要的是存储 `assignor_registry_key`，因为它将用于其他多个流程，以及将用于提交转让方和关联方文件的 `analysis_key` 和 `analysis_related_party_key`。
:::

:::info
在审查结构中，担保人或担保人的代表也通过 `analysis_related_party` 表示。值得注意的是，每个 `document_number` 只有一个，因此，如果同一个人既是担保人又是转让方的关联方，只会生成一个 `analysis_related_party`，具有一个 `analysis_related_party_key`，同时适用于关联方和担保人。
:::

:::info
自然人的代表仅限于可代其签署的代理人。
:::

---

## 定义

### 地址定义

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `street` * | string | 街道名称。 | 1 至 255 |
| `number` * | string | 门牌号。 | 1 至 4 |
| `neighborhood` * | string | 社区/街区。 | 1 至 255 |
| `city` * | string | 城市。 | 1 至 255 |
| `uf` * | string | 州缩写。 | 2 |
| `complement` | string | 地址补充信息。 | 1 至 255 |
| `postal_code` * | string | 邮政编码。 | 9（格式：XXXXX-XXX） |
| `country` * | string | 国家（缩写）。 | 3，按 ISO 3166-1 alpha-3 |

*必填字段。

---

### 电话定义

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `international_dial_code` * | string | 国际拨号代码。 | 1 至 3 |
| `area_code` * | string | 区号。 | 2 |
| `number` * | string | 电话号码。 | 8 至 9 |

*必填字段。

---

### 关联方定义

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `name` * | string | 关联方名称。 | 1 至 255 |
| `document_number` ** | string | 受益人文件编号（CPF）。 | 14 至 18 |
| `passport_number` ** | string | 外国受益人文件编号。 | 8 至 9 |
| `related_party_type` * | string | 关联方的关联类型。 | 请参见**[关联方类型枚举](#related-party-type)**。 |
| `nationality` * | string | 受益人的来源国。 | 3，按 ISO 3166-1 alpha-3 |
| `direct_beneficiary` * | boolean | 与转让方直接或间接关联的受益人。 | - |
| `is_representative` * | boolean | 表示关联方是否为转让方的签署代表。 | - |
| `company_registry_number` *** | string | 若非直接与转让方关联，关联的公司。 | 1 至 255 |
| `company_country` *** | string | 受益人与转让方之间中介公司所在国。 | 3，按 ISO 3166-1 alpha-3 |
| `address` | object | 代表地址信息对象。 | 请参见**[地址定义](#definição-de-endereço)**。 |
| `email` **** | string | 代表的电子邮件地址。 | 1 至 255 |
| `phone` | object | 代表电话信息对象。 | 请参见**[电话定义](#definição-de-telefone)**。 |
| `marital_status` | string | 关联方婚姻状况。 | 请参见**[婚姻状况枚举](#marital-status)**。 |
| `property_system` | string | 财产分离制度。 | 请参见**[财产制度枚举](#property-system)**。 |
| `profession` | string | 关联方职业。 | 1 至 255。 |

*必填字段。
**巴西人需要 document_number，外国人需要 passport_number。
***若关联方与转让方非直接关联，则为必填。
****仅签署代表必填。

---

### 担保人定义

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `name` * | string | 担保人名称。 | 3 - 255 |
| `document_number` * | string | 担保人文件编号。 | 14 至 18 |
| `person_type` * | string | 担保人的人员类型（自然人或法人）。 | - |
| `email` * | string | 担保人的电子邮件地址。 | 1 至 255 |
| `nationality` | string | 担保人的来源国。 | 3，按 ISO 3166-1 alpha-3 |
| `phone` | object | 担保人电话信息对象。 | 请参见**[电话定义](#definição-de-telefone)**。 |
| `address` | object | 担保人地址信息对象。 | 请参见**[地址定义](#definição-de-endereço)**。 |
| `guarantor_representatives` | array | 担保人的签署代表 - 仅适用于法人担保人。 | 请参见**[担保人代表定义](#definição-de-representante-do-avalista)**。 |
| `marital_status` | string | 担保人婚姻状况。 | 请参见**[婚姻状况枚举](#marital-status)**。 |
| `property_system` | string | 财产分离制度。 | 请参见**[财产制度枚举](#property-system)**。 |
| `profession` | string | 担保人职业。 | 1 至 255。 |

*必填字段。

# 枚举值

### Assignor Registry Status

| 枚举值 | 描述 |
| -------------------------- | ----------------- |
| **pending_registry** | 待注册 |
| **registered** | 已注册 |

---

### Analysis Status

| 枚举值 | 描述 |
| ----------------------- | --------------------- |
| **pending_documents** | 待提交文件 |
| **sent_to_analysis** | 已发送审查 |
| **pending_internal_validation** | 文件验证中 |
| **in_manual_analysis** | 合规手动审查中 |
| **approved** | 已批准 |
| **reproved** | 已拒绝 |

---

### Related Party Type

| 枚举值 | 描述 |
| ----------------------- | ------------- |
| **president** | 总裁 |
| **partner** | 合伙人 |
| **administrator** | 管理人 |
| **director** | 董事 |
| **manager** | 经理 |
| **attorney** | 代理人 |

---

### Marital Status
| 枚举值 | 描述 |
|--------------|---------------|
| **single** | 单身 |
| **married** | 已婚 |
| **widower** | 丧偶 |
| **divorced** | 离婚 |
| **separated** | 分居 |
| **stable_union** | 稳定伴侣关系 |

---

### Property System

| 枚举值 | 描述 |
| --------------------------------- | -------------------------------------- |
| **total_communion_of_goods** | 完全财产共有 |
| **partial_communion_of_goods** | 部分财产共有 |
| **total_separation_of_goods** | 完全财产分离 |
| **final_participation_of_acquisitions** | 婚后财产最终参与 |
| **compulsory_separation_of_goods** | 强制财产分离 |

---

# 文件提交

URL: /zh-Hans/documentation/iaas/homologacao_cedente/cadastro/envio_de_documentos

提交转让方注册信息后，需提交相关文件。为此，使用文件审查结构，无论是在创建还是修改时，都会生成审查并需要提交相应文件。管理公司有责任审查将与其管理基金合作的转让方的运营，未来在创建主合同时，需要签署管理公司声明，证明其已完成《第三方资源管理行政与管理规则和程序手册》要求的全部分析，该手册要求管理公司负责分析和更新转让方注册信息。

---

## 转让方文件

### 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",
}
```

## 文件对象

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `document_type` * | string | 文件类型。 | 请参见**[文件类型](#document-type)**。 |
| `document_b64` * | string | 必须是 PDF 格式文件的二进制内容，以 Base64 编码。 | - |
| `observation` | string | 描述上传文件的自由格式字段。 | 1 - 255 |

*必填字段。

### 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
在注册更新的情况下，只有在转让方**特有信息**发生更新时，才需要在审查中提交特定的转让方文件。
:::

## 关联方文件

### 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
在注册更新的情况下，只有在转让方关联方发生新增或更新时，才需要在审查中提交关联方文件。
:::

:::caution 注意！
如果文件以错误类型上传或质量不佳，可能会返回状态 **accepted**（表示质量存疑）或 **invalid**（无效），此时需要重新正确上传。
:::

## 取消文件提交

除 additional_document 类型外，审查中每种类型只允许一个状态为 "valid" 的文件。如因某种原因需要替换已有效文件，需先取消该文件。

### Request

ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/related_party/ANALYSIS_RELATED_PARTY_KEY/document/DOCUMENT_KEY
MÉTODO PUT

或

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"
}
```

---

### 转让方/担保人标准文件

| 人员类型 | *document_type* | 描述 | 必填要求 |
|----------------|-------------------|------------|--------------|
| 自然人 | cnh | 驾驶执照 | * |
| 自然人 | cin_digital | 国家身份证（电子版） | * |
| 自然人 | rg_back | 身份证（背面） | * |
| 自然人 | rg_front | 身份证（正面） | * |
| 法人 | social_contract | 公司章程 | 始终必填 |
| 法人 | commercial_board_certificate | 商业委员会简化证明书 | 可选，但对日期超过 3 年的公司章程为必填 |
| 法人 | board_election_record | 董事会选举记录（如适用） | 用于证明关联关系 |

*对于所有自然人，身份证正反面、驾驶执照和国家身份证中仅需提供一种。

### 关联方/代表标准文件

| 人员类型 | *document_type* | 描述 | 必填要求 |
|----------------|-------------------|------------|--------------|
| 自然人 | cnh | 驾驶执照 | * |
| 自然人 | cin_digital | 国家身份证（电子版） | * |
| 自然人 | rg_back | 身份证（背面） | * |
| 自然人 | rg_front | 身份证（正面） | * |
| 自然人 | power_of_attorney | 自然人或法人授权委托书 - 代表为代理人时必填 | 用于证明关联关系 |

*对于所有自然人，身份证正反面、驾驶执照和国家身份证中仅需提供一种。

:::warning 注意
部分文件类型会经过 OCR 工具进行数据提取和验证。应始终关注文件提交的返回结果，该结果会同步返回 OCR 验证状态 - valid/accepted/invalid。
:::

## 文件类型

### Document Type

| 枚举值 | 描述 |
| ---------------------------- | -------------------------- |
| **cnh** | 驾驶执照 |
| **rg_back** | 身份证背面 |
| **rg_front** | 身份证正面 |
| **passport** | 护照 - 仅限外国人 |
| **national_migration_registry** | 全国移民登记证 |
| **cin_digital** | 国家身份证（电子版） |
| **social_contract** | 公司章程/公司协议 |
| **cnpj_card** | CNPJ 卡 |
| **commercial_board_certificate** | 商业委员会简化证明书 |
| **board_election_record** | 现任董事会选举记录 |
| **power_of_attorney** | 授权委托书 - 代表为代理人时必填 |
| **marital_power_of_attorney** | 配偶授权委托书 - 仅限配偶使用 |
| **compliance_statement** | 合规意见书 |
| **financial_statement** | 财务报表 |
| **credit_report** | 信贷报告/意见书 |
| **manager_statement** | 基金经理意见书/档案 |
| **visit_report** | 访问报告 |
| **proof_of_residence** | 居住证明 |
| **credit_agency_consulation** | 信用保护机构查询 |
| **annual_revenues_declaration** | 营收声明 |
| **financial_institutions_declaration** | 银行关系声明 |
| **additional_document** | 附加文件 - 自由格式 |

### Document Status

| 枚举值 | 描述 |
| ----------------------- | ------------- |
| **created** | 已创建 |
| **valid** | 有效 |
| **invalid** | 无效 |
| **canceled** | 已取消 |
| **accepted** | 已接受但未验证 |

---

# 分支机构注册

URL: /zh-Hans/documentation/iaas/homologacao_cedente/cadastro/filiais

要启用分支机构，可以遵循两种操作流程：

1. **完整流程（从零开始）：** 完整注册分支机构，涵盖地址和营收数据直至法定代表人和担保人信息。在此流程中，启用过程遵循文档中之前介绍的标准流程，经过文件审批和授权验证。此流程需要新的转让合同才能有效启用转让方在基金中的操作。
2. **简化流程（关联注册）：** 本页介绍的此流程将分支机构注册视为与预先注册的总公司的关联。在此流程中，仅提交基本数据并创建新的 `assignor_registry_key`，但代表和担保人等数据必须从总公司的审查中复用。

:::info
如果分支机构已作为转让方注册，也可以将其关联到总公司。在这种情况下，之前的文件、代表和担保人信息将被废弃，分支机构将继承总公司的数据。
:::

## 简化激活流程的优势

分支机构简化激活流程有两大主要优势：

* **付款选项：** 与分支机构进行转让操作时，总公司的账户也将成为付款选项。
* **配置复制：** 总公司的所有转让配置将在审批后自动复制到分支机构，无需合同签署步骤。要获取新密钥，建议使用分页的转让配置 GET 请求（主题 5.3.1.2.），以 `assignment_contract_key`、`asset_type` 和 `assignor_document_number` 等参数，以总公司签订的合同为参考。

:::warning 注意
简化的分支机构流程要求总公司签订的主合同中包含以下条款才能使用：

> 鉴于转让方声明并保证，如适用，其作为总公司对所有分支机构拥有完全法律代表权，包括为与受让方签订和执行所有转让所需的所有行为。转让方认可并承担其分支机构因与受让方进行转让而产生的所有义务的连带和无限责任，放弃就授权不足或自主性的任何主张。
:::

---

## 创建新分支机构

尽管总公司的反洗钱审查已完成，分支机构的首次审查（关联审查）始终会经历外部数据查询和验证阶段，需要等待自动发送的审查批准或拒绝的 Webhook 通知。

### Request

ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/branch
MÉTODO POST

:::info
请求中发送的 `assignor_registry_key` 必须属于转让方的**总公司**，且总公司必须已启用。
:::

```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
        }
    ]
}
```

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `document_number` * | string | 转让方文件编号（CNPJ）。 | 14 至 18 |
| `annual_revenues` * | number | 转让方的年营收声明（整数）。 | 最小值为 1 |
| `email` * | string | 转让方的电子邮件地址。 | 1 至 255 |
| `phone` | object | 转让方电话信息对象。 | 请参见**[电话定义](#定义-de-电话)**。 |
| `address` * | object | 转让方地址信息对象。 | 请参见**[地址定义](#定义-de-地址)**。 |
| `accounts` * | array | 转让方还款账户列表。 | 请参见**[账户定义](#定义-de-账户)**。 |

*必填字段。

### 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": []
      }
    ],
    "documents": [
      {
        "document_key": "5530af20-f52e-4a2e-b0f3-732e8121f4b3",
        "document_type": "social_contract",
        "status": "valid",
      }
    ],
    "analysis_data": {}
  }
}
```

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `assignor_registry_key` | string | 注册标识符。 | 36 |
| `status` | string | 注册状态。 | 请参见**[注册状态枚举](#assignor-registry-status)**。 |
| `name` | string | 转让方名称。 | 1 至 255 |
| `document_number` | string | 转让方文件。 | 14 至 18 |
| `last_analysis` | object | 审查对象。 | 请参见**[审查定义](#定义-de-审查)**。 |

:::info
所有代表、担保人和文件信息将自动从总公司的注册中复制。但是，发送的账户必须属于分支机构所有，否则未来的转账将失败。
:::

:::info
重要的是存储 assignor_registry_key，因为它将用于其他多个流程，以及 analysis_key 和 analysis_related_party_key。
:::

---

## 将现有分支机构关联到总公司

如果分支机构和总公司已以不同注册存在，可以强制将两者关联。在此流程中，分支机构中不在创建请求体中的所有信息将被总公司的信息替换。

### Request

ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/branch
MÉTODO PUT

:::info
请求中发送的 `assignor_registry_key` 必须属于转让方的**总公司**，且总公司必须已启用。
:::

```json title='Request Body'
{
    "branch_assignor_registry_key": "9c130814-1aa5-4dcb-b6af-c4abdfca2947",
}
```

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `branch_assignor_registry_key` * | string | 注册标识符。 | 36 |

*必填字段。

### 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"
  }
}
```

---

# 转让方账户

URL: /zh-Hans/documentation/iaas/homologacao_cedente/cadastro/manutencao_de_contas

在转让方注册时，必须为转让方提供至少一个转让还款账户。在基金经理审批转让阶段，可以指定该转让方的任何已注册账户进行还款。需要注意的是，如果转让方与基金之间的操作发起人是顾问，账户维护将由咨询方而非基金经理负责。

与代表、地址等注册数据不同，修改转让方账户不会创建新的审查，因此变更立即生效。对于还款账户，账户持有人必须是转让方本人，账户所有者的文件编号将默认为转让方的编号。

:::warning 注意
填写账户数据时务必谨慎。如果账户无效，转让付款将无法进行，整个操作将被取消。
:::

---

## 添加备选账户

### 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
}
```

## 账户对象

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `account_number` * | string | 账户号码。 | 3-20 |
| `account_digit` * | string | 账户校验位。 | 1 |
| `account_branch` * | string | 账户支行。 | 4 |
| `account_type` * | string | 账户类型。 | - |
| `financial_institution_code` * | string | 账户银行代码。 | 3 |
| `default_account` * | boolean | 默认还款账户。 | - |

*必填字段。

### 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
如果新账户以 "default_account" 为 true 发送，旧的默认还款账户将变为非默认账户，新发布的账户将成为默认还款账户。
:::

## 账户更新

无法修改账户数据。如需更改，必须停用错误账户并创建具有有效数据的新账户。

要更改默认还款账户，只需指定新账户，旧账户将自动更改。无法将账户设置为非默认还款账户，必须始终指定新的默认账户。

### Request

ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/account/ACCOUNT_KEY
MÉTODO PUT

```json title='Request Body'
{
    "status": "active",
    "default_account": true,
}
```

## 账户对象

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `status` | string | 账户新状态。 | 请参见**[账户状态枚举](#account-status)**。 |
| `default_account` | boolean | 默认还款账户。 | - |

*必填字段（无）。

### 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
如果更新以 "default_account" 为 true 发送，旧的默认还款账户将变为非默认账户，新发布的账户将成为默认还款账户。无法停用默认账户，或将非活跃账户设置为默认账户。
:::

# 枚举值

### Account Status

| 枚举值 | 描述 |
| -------------------------- | ----------------- |
| **active** | 账户活跃，可作为还款选项。 |
| **inactive** | 账户不活跃，不可用于还款。 |

---

# Webhooks

URL: /zh-Hans/documentation/iaas/homologacao_cedente/cadastro/webhooks_analise

---
## 审查 Webhooks
---

#### 转至合规

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"
}
```

#### 文件审查中

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"
}
```

#### 已批准

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"
}
```

#### 已拒绝

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"
}
```

## 注册 Webhooks
---

#### 转让方已激活

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"
}
```

#### 转让方已过期

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"
}
```

---

# 审查查询

URL: /zh-Hans/documentation/iaas/homologacao_cedente/consulta/consulta_de_analise

---
## 按标识键查询审查

### 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_data": {}
}
```

---

## 分页查询审查列表

### Request

ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analyses
MÉTODO GET

### Path params

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `limit` | integer | 对象数量限制 | - |
| `page` | integer | 请求页码 | - |

### 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": []
          }
        ],
      }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": true,
}
```

---

# 转让方查询

URL: /zh-Hans/documentation/iaas/homologacao_cedente/consulta/consulta_de_cedente

---

## 按标识键查询转让方

### 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"
    }
  ],
  "last_analysis": {
    "analysis_key": "d7805a05-98a7-486b-a440-807f1d3d5691",
    "analysis_number": 1,
    "status": "pending_documents",
    "analysis_related_parties": [],
    "documents": [],
    "analysis_data": {}
  }
}
```

### 转让方对象

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `assignor_registry_key` | string | 注册标识符。 | 36 |
| `name` * | string | 转让方名称。 | 1 至 255 |
| `document_number` * | string | 转让方文件编号（CNPJ）。 | 14 至 18 |
| `status` | 枚举值 | 注册状态。 | 14 至 18 |
| `annual_revenues` * | number | 转让方的年营收声明（整数）。 | 最小值为 1 |
| `person_type` * | string | 转让方的人员类型（自然人或法人）。 | - |
| `email` * | string | 转让方的电子邮件地址。 | 1 至 255 |
| `is_in_national_financial_system` * | boolean | 表示转让方是否为 SFN 成员。 | - |
| `phone` | object | 转让方电话信息对象。 | 请参见**[电话定义](#definição-de-telefone)**。 |
| `address` * | object | 转让方地址信息对象。 | 请参见**[地址定义](#definição-de-endereço)**。 |
| `related_parties` * | array | 公司关联方列表。 | 请参见**[关联方定义](#definição-de-parte-relacionada)**。 |
| `accounts` * | array | 转让方还款账户列表。 | 请参见**[账户定义](#definição-de-conta)**。 |
| `guarantors` * | array | 转让方担保人列表。 | 请参见**[担保人定义](#definição-de-avalista)**。 |

---

## 分页查询转让方列表

### Request

ENDPOINT /assignor_registry/assignor_registries
MÉTODO GET

### Path params

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `name` | string | 转让方名称 | 1-255 |
| `document_number` | string | 转让方文件编号 | 1-18 |
| `assignor_registry_status` | string | 转让方状态 | 1-255 |
| `analysis_status` | string | 最新审查状态 | 1-255 |
| `limit` | integer | 对象数量限制 | - |
| `page` | integer | 请求页码 | - |

### 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,
      "last_analysis": {
        "analysis_key": "d7805a05-98a7-486b-a440-807f1d3d5691",
        "analysis_number": 1,
        "status": "pending_documents"
      }
    }
  ],
  "limit": 10,
  "page": 0,
  "is_last_page": true
}
```

---

## 查询转让方签署人

### Request

ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/signers
MÉTODO GET

---

### Response

```json title='Response Body'
{
  "signer_groups": [
    {
      "signers": [
        {
          "name": "Natália Nascimento",
          "document_number": "883.512.866-80",
          "email": "natalia.nascimento@yopmail.com",
          "is_required_signer": true,
        },
        {
          "name": "Roberto Carlos",
          "document_number": "802.834.257-41",
          "email": "roberto.carlos@yopmail.com",
          "is_required_signer": true,
        }
      ],
      "minimum_required_signers": 2,
      "expiration": "2025-10-20"
    }
  ]
}
```

### 签署人组对象

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `signers` | array | 组内签署人标识。 | - |
| `minimum_required_signers` | number | 将文件视为已签署所需的最少签署人数。 | - |
| `expiration` | date | 签署人组的到期日（可选）。 | 10（格式：YYYY-MM-DD） |

签署人组在内部根据提交文件的审查以及代表与转让方之间经证明的关联关系构建。

---

# 查询文件

URL: /zh-Hans/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

| 参数 | 描述 |
|------------------------------|--------------------------------------|
| `assignment_contract_key` | 转让合同的标识键 |
| `document_key` | 文件的标识键 |

### 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"
}
```

:::info 说明
download_url 字段提供了文件最新版本的签名下载 URL，即如果文件已签署，则提供已签署版本的 URL。该 URL 会过期，不应用于非实时查询。
:::

### 附件文件定义

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `document_key` * | string | 文件的唯一标识键。 | 36 |
| `document_type` * | string | 文件类型。 | -- |
| `status` * | string | 文件状态。 | 请参见**[文件状态枚举](#attached-document-status)**。 |
| `document_template_key` | string | 生成文件的模板的唯一标识键。 | 36 |
| `required_parties` | array | 签署该文件的各方列表。 | -- |
| `download_url` | string | PDF 下载 URL。 | -- |

# 枚举值

### Attached Document Status

| 枚举值 | 描述 |
| ----------------------- | --------------------- |
| **pending_generate** | 待生成文件 |
| **approved** | 文件已生成 |
| **signed** | 文件已签署 |

---

# 合同管理

URL: /zh-Hans/documentation/iaas/homologacao_cedente/contrato_de_cessao/manutencao_do_contrato

---

根据流程，可能需要进行多次调用才能完成合同流程。

---

# 基金经理审批

---

如果合同由咨询方提出，在文件生成后，需要基金经理审批，才能将合同发送签署。

### 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

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `status` * | string | 基金经理的决定。denied 或 approved | -- |
| `denial_reason` | string | 拒绝原因说明。 | 1 至 500 |

*必填字段

### Response

STATUS 202

---

# 手动发送签署

---

如果模板配置为手动发送签署，可以将具有相同基金经理、转让方和担保人的多个合同归入同一批次签署。

### Request

ENDPOINT /assignment_contract/signature_batch
MÉTODO POST

```json title='Request Body'
{
    "assignment_contract_keys": ["assignment_contract_key", "assignment_contract_key"],
}
```

#### Body Params

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `assignment_contract_keys` * | array | 要在同一批次中发送的合同列表 | -- |

*必填字段

### Response

STATUS 202

---

# 取消合同

---

在任何阶段，除已签署的合同外，都可以取消合同。如合同处于签署中，签署事件也将被取消。

### Request

ENDPOINT /assignment_contract/assignment_contract/ASSIGNMENT_CONTRACT_KEY
MÉTODO PUT

```json title='Request Body'
{
    "status": "canceled"
}
```

#### Body Params

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `status` * | string | canceled | -- |

*必填字段

### Response

STATUS 202

---

# 转让合同

URL: /zh-Hans/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato

---

此流程在投资基金与转让方之间生成转让合同并发送签署。要生成合同，需要持有由 QI CTVM 团队提供的基金的 fund_class_key，以及同样由团队提供的 assignment_contract_template_key，该密钥定义合同参数，如共同义务、必要的转让文件、条款等。

在合同结构中，存在产品，例如标识某种资产类型的转让配置、回购等。将发送两份文件进行签署：合同本身，涉及所有相关方，如转让方、管理公司、担保人等；以及管理公司声明，仅由管理公司签署，证明已履行 CVM、Anbima 和中央银行规定的关于转让方操作的所有规范和要求，包括风险分析、反洗钱等，可在相应门户查询。

合同流程可变：可配置文件生成后立即发送签署，或等待手动发送。此外，如果合同由顾问提出，需要基金经理审批后才能发送签署。最后，如果转让方注册尚未完成，或正在更新，需要等待最新审查完成后才能发送签署。如果审查被拒绝，合同也将被取消。

双方签署两份文件后，产品将处于待激活状态，配置转让流水线可能需要几分钟，最终将可以使用各产品的转让配置密钥 `assignment_configuration_key` 在基金与转让方之间进行转让。

可选地，可以为基金与转让方之间的操作定义担保人，前提是合同模板允许。担保人必须预先与转让方一起注册，合同中仅通过文件编号指示。需要注意，还款账户在转让方注册中定义。

整个合同签署流程由我们的认证机构 CertifiQI 完成，以提供更大的便利性和简便性。由于此资源，签署和后续转让方激活的跟踪是自动进行的。

### 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

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `fund_class_key` * | string | 基金的唯一标识键。在基金创建时生成，由 QI CTVM 团队提供。 | UUID 键 |
| `assignment_contract_template_key` * | string | 合同模板的唯一标识键。同样由 QI CTVM 团队提供。 | UUID 键 |
| `assignor_document_number` * | string | 转让方的文件编号。 | CPF 或 CNPJ |
| `credit_limit` | number | 合同的信贷额度。 | - |
| `external_id` | string | 合同的外部标识，通常为合同编号。 | 1 至 255 |
| `observation` | string | 备注。用于任何注释的自由字段。 | 1 至 500 |
| `guarantors` | array | 操作的担保人。 | 请参见**[担保人定义](#definição-de-avalista)**。 |

*必填字段

:::warning 注意
担保人必须在转让方注册和此阶段都进行指定，这一点非常重要。如果仅在注册中指定，而不在合同中指定，担保人将不会签署文件。如果仅在合同中指定，而不在注册中指定，将返回错误。
:::

---

### 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
保存 `assignment_contract_key` 极为重要，因为它将用于将来表征合同生成的转让配置，特别是通过主题 5.2.2.6 的分支机构流程生成的配置。可以按照主题 5.3.1.2 的 GET 请求获取生成的配置。
:::

### 转让合同定义

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `assignment_contract_key` * | string | 合同的唯一标识键。 | 36 |
| `fund_class` * | object | 基金对象 | -- |
| `assignor` * | object | 转让方对象。 | -- |
| `consultant` | object | 顾问对象。仅当顾问为合同的一方时。 | -- |
| `assignment_contract_template` * | object | 合同模板对象。 | -- |
| `attached_documents` * | array | 附件文件列表。 | 请参见**[附件文件定义](#definição-de-documento-anexo)**。 |
| `products` * | array | 合同下的产品列表。 | 请参见**[产品定义](#definição-de-produto)**。 |
| `proposal_agent` * | string | 合同提议代理类型。 | -- |
| `status` * | string | 合同状态。 | 请参见**[转让合同状态枚举](#assignmnt-contract-status)**。 |
| `credit_limit` | number | 发送的信贷额度。 | -- |
| `external_id` | string | 合同的外部标识，通常为合同编号。 | 1 至 255 |
| `case_number` | string | 案例编号，每个基金唯一。 | -- |
| `denial_reason` | string | 基金经理拒绝的详情。 | 1 至 255 |
| `observation` | string | 发送的备注。 | 1 至 500 |
| `creation_datetime` | string | 合同创建的日期时间。 | -- |

### 附件文件定义

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `document_key` * | string | 文件的唯一标识键。 | 36 |
| `document_type` * | string | 文件类型。 | -- |
| `status` * | string | 文件状态。 | 请参见**[文件状态枚举](#attached-document-status)**。 |
| `document_template_key` | string | 生成文件的模板的唯一标识键。 | 36 |
| `required_parties` | array | 签署该文件的各方列表。 | -- |

### 产品定义

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `product_key` * | string | 产品的唯一标识键。 | 36 |
| `assignment_configuration_key` * | string | 转让配置的唯一标识键。 | 36 |
| `asset_type` * | string | 资产类型。 | -- |
| `status` * | string | 产品状态。 | -- |

### 担保人定义

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `name` * | string | 担保人名称。 | 1 至 255 |
| `document_number` * | string | CPF 或 CNPJ。 | 14 至 18 |

*必填字段

:::warning 注意
如前所述，担保人必须预先与特定转让方一起注册。
:::

# 枚举值

### Assignment Contract Status

| 枚举值 | 描述 |
| ----------------------- | --------------------- |
| **pending_document** | 待生成文件 |
| **sending_to_signature** | 正在发送签署 |
| **pending_signature** | 可供各方签署 |
| **signed** | 已签署 |
| **pending_manager_approval** | 待基金经理审批 |
| **denied** | 被基金经理分析拒绝 |
| **pending_signature_submission** | 待手动发送签署 |
| **pending_assignor_registry_release** | 待关联转让方注册完成（注册或更新中） |
| **canceled** | 已取消 |

### Attached Document Status

| 枚举值 | 描述 |
| ----------------------- | --------------------- |
| **pending_generate** | 待生成文件 |
| **approved** | 文件已生成 |
| **signed** | 文件已签署 |

---

# 获取合同

URL: /zh-Hans/documentation/iaas/homologacao_cedente/contrato_de_cessao/recuperacao_de_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"
    }
```

### 转让合同定义

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `assignment_contract_key` * | string | 合同的唯一标识键。 | 36 |
| `fund_class` * | object | 基金对象 | -- |
| `assignor` * | object | 转让方对象。 | -- |
| `consultant` | object | 顾问对象（仅当顾问为合同的一方时）。 | -- |
| `assignment_contract_template` * | object | 合同模板对象。 | -- |
| `attached_documents` * | array | 附件文件列表。 | 请参见**[附件文件定义](#definição-de-documento-anexo)**。 |
| `products` * | array | 合同下的产品列表。 | 请参见**[产品定义](#definição-de-produto)**。 |
| `proposal_agent` * | string | 合同提议代理类型。 | -- |
| `status` * | string | 合同状态。 | 请参见**[转让合同状态枚举](#assignmnt-contract-status)**。 |
| `credit_limit` | number | 发送的信贷额度。 | -- |
| `external_id` | string | 合同的外部标识（通常为合同编号）。 | 1 至 255 |
| `case_number` | string | 案例编号，每个基金唯一。 | -- |
| `denial_reason` | string | 基金经理拒绝的详情。 | 1 至 255 |
| `observation` | string | 发送的备注。 | 1 至 500 |
| `signature_batch_key` | string | 签署批次标识符。 | 36 |
| `creation_datetime` | string | 合同创建的日期时间。 | -- |

### 附件文件定义

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `document_key` * | string | 文件的唯一标识键。 | 36 |
| `document_type` * | string | 文件类型。 | -- |
| `status` * | string | 文件状态。 | 请参见**[文件状态枚举](#attached-document-status)**。 |
| `document_template_key` | string | 生成文件的模板的唯一标识键。 | 36 |
| `required_parties` | array | 签署该文件的各方列表。 | -- |

### 产品定义

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `product_key` * | string | 产品的唯一标识键。 | 36 |
| `assignment_configuration_key` * | string | 转让配置标识键，用于资产购买流水线。 | 36 |
| `asset_type` * | string | 资产类型。 | -- |
| `status` * | string | 产品状态。 | -- |

---
# 转让合同列表
---

### Request

ENDPOINT /assignment_contract/assignment_contracts
MÉTODO GET

### Query Params

| 参数 | 描述 |
|-----------------------------|---------------------------------------------------------------------------|
| `assignor_document_number` | 转让方文件 |
| `fund_class_document_number` | 基金文件 |
| `fund_class_key` | 基金的唯一标识符（UUID） |
| `status` | 转让状态 |
| `case_number` | 案例编号 |
| `start_date` | 开始日期 |
| `end_date` | 结束日期 |

### 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"
      },
      "assignor": {
        "assignor_key": "UUID",
        "document_number": "00.000.000/0000-00",
        "name": "SAMPLE ASSIGNOR NAME"
      },
      "status": "pending_document",
      "products": [
        {
          "product_key": "UUID",
          "assignment_configuration_key": "UUID",
          "asset_type": "ccb",
          "status": "pending_signature"
        }
      ]
    }
  ],
  "limit": 10,
  "page": 0,
  "is_last_page": true
}
```

# 枚举值

### Assignment Contract Status

| 枚举值 | 描述 |
| ----------------------- | --------------------- |
| **pending_document** | 待生成文件 |
| **sending_to_signature** | 正在发送签署 |
| **pending_signature** | 可供各方签署 |
| **signed** | 已签署 |
| **pending_manager_approval** | 待基金经理审批 |
| **denied** | 被基金经理分析拒绝 |
| **pending_signature_submission** | 待手动发送签署 |
| **pending_assignor_registry_release** | 待关联转让方注册完成（注册或更新中） |
| **canceled** | 已取消 |

### Attached Document Status

| 枚举值 | 描述 |
| ----------------------- | --------------------- |
| **pending_generate** | 待生成文件 |
| **approved** | 文件已生成 |
| **signed** | 文件已签署 |

---

# 合同 Webhooks

URL: /zh-Hans/documentation/iaas/homologacao_cedente/contrato_de_cessao/webhooks_contrato

---

#### 待基金经理审批

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"
}
```

#### 待发送签署

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"
}
```

#### 待转让方注册完成

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"
}
```

#### 被基金经理拒绝

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"
}
```

#### 合同已发送签署

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"
}
```

#### 已签署

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"
}
```

#### 合同已取消

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

---
#### 产品已激活

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"
}
```

#### 产品激活中

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"
}
```

---

# 简介

URL: /zh-Hans/documentation/iaas/homologacao_cedente/inicio

转让方注册是任何购买信用权益的基金开始运营的关键环节。本节将说明整个流程，从首次信息提交到开通转让流水线以发送资产。

如需访问后续章节中讨论的服务，请联系团队 [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br)，以便在验证环境（Sandbox）和生产环境中获得相应授权。

需要注意的是，要有效激活一个转让方，需要使用两个不同的系统：

1. 在我们数据库中注册转让方，仅需执行一次；

2. 在转让方与基金之间签订转让合同；

对于这两个系统，基金经理和顾问均可作为代理人，根据业务发展在转让方与基金之间提出注册和合同。

### 转让方注册

在此阶段，需要提交转让方及其代表和最终受益人的所有信息。提交后，转让方将以"待注册"状态创建，并生成首次分析，需提交必要文件以验证注册信息。最后，在附上所有必要文件后，需触发分析提交，即将分析发送至验证流程，该分析将经历反欺诈和反洗钱审查。

对于法人实体，分析所需文件包括：公司章程（最新版本）、商业委员会简化证明书以及现任董事选举记录。此外，还需提交公司最终受益人的文件，用于反洗钱、反腐败和反恐融资合规。对于自然人转让方，仅需身份证明文件即可进行分析。

两种情况均需要注册代理人的责任声明，确认已按照 CVM 和 AMBIMA 规范收集了所有文件，包括营收证明、合规文件等。

一旦首次分析获批，注册将进入内部验证阶段，团队将验证收到的信息并在签署人验证后继续处理。生效后，转让方将可进行后续操作。此时，如已配置，我们将发送 Webhook 通知分析已获批，也可通过基金经理门户追踪已注册的转让方。

### 转让方更新

如需更新注册信息，需重新提交所有转让方信息及所需变更。提交后，将生成新的分析，需附上必要文件以确保更新有效性。最后，在附上所有必要文件后，需触发分析提交，即将新分析发送至验证流程。

需要注意的是，需要提交的文件仅限于变更实体的文件，无论是新增代表还是修改公司注册数据。

一旦新分析获批，转让方的新注册数据将正式更新。此时，如已配置，我们将发送 Webhook 通知分析已获批。需要注意，转让方的注册更新不会阻止与其进行新的操作。

### 转让合同签订

为正式确立转让方与基金之间的关系，需要签署转让合同，该合同规范资产出售事宜。我们提供 API 以自动化此流程。

该流程包括基于模板发起签订申请，系统将自动创建合同并发送签署。合同签署完成后，模板中定义的产品将可供激活。客户选择要激活的产品并指定还款账户后，将通过产品激活返回生成的转让配置密钥，该标识符将在后续资产买卖流程中使用。

---

# SFTP 集成

URL: /zh-Hans/documentation/iaas/integracao_sftp/inicio

SFTP（安全文件传输协议）是 QI CTVM 提供基金报告 下载 的渠道。各报告模型、每个文件的逐列布局以及可下载的示例，请参阅 [DTVM 报告文档](/documentation/iaas/relatorios_dtvm/)。

集成时，建议使用实现该协议的库和客户端，例如 Python 的 `paramiko`、命令行的 `sftp`，或任何标准 SFTP 客户端。

:::info 权限开放
如需申请访问权限，请联系 [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br)。权限先在同质化环境（Sandbox）开放，随后在生产环境开放。
:::

## 认证方式

访问认证使用 **SSH 公钥**，不使用密码。您生成密钥对，自行保管私钥，只需将公钥发送给我们，我们会将其登记到您的 SFTP 用户下。

| 提供方          | 提供内容                                                         |
| --------------- | ---------------------------------------------------------------- |
| **您**          | 公钥（`.pub` 文件），OpenSSH 格式                                |
| **QI CTVM**     | `HOSTNAME`、`PORT`（22）和 `USERNAME`，以及主机<em>指纹</em>      |

:::danger 切勿发送您的私钥
QI Tech 的任何团队都不会索要您的私钥。如果有人索要——无论通过邮件、工单还是其他任何渠道——那都不是我们。第 3 步中的 1Password 共享仅用于**公钥**（`sftp_qitech.pub`）。

如果私钥已经发送给他人或作为附件上传过，请视其为已泄露：请重新生成密钥对，并将新的公钥发送给我们。
:::

## 1. 生成密钥对

请生成**专用于 SFTP** 的密钥对。不要重用签发 JWT 令牌的密钥：它们是不同系统的凭证，生命周期不同——轮换其中一个就会被迫轮换另一个，而任何一侧泄露都会同时影响两者。

请将 `company-name` 替换为贵公司的名称，例如 `sftp-acme`。该文本仅是密钥中的注释，用于帮助我们识别该密钥。

**Linux / macOS**

```bash
mkdir -p ~/.ssh && chmod 700 ~/.ssh
ssh-keygen -t ed25519 -C "sftp-company-name" -f ~/.ssh/sftp_qitech
```

**Windows (PowerShell)**

```powershell
New-Item -ItemType Directory -Force "$env:USERPROFILE\.ssh" | Out-Null
ssh-keygen -t ed25519 -C "sftp-company-name" -f "$env:USERPROFILE\.ssh\sftp_qitech"
```

**Windows (cmd)**

```batch
if not exist "%USERPROFILE%\.ssh" mkdir "%USERPROFILE%\.ssh"
ssh-keygen -t ed25519 -C "sftp-company-name" -f "%USERPROFILE%\.ssh\sftp_qitech"
```

**Windows (WSL)**

```bash
mkdir -p ~/.ssh && chmod 700 ~/.ssh
ssh-keygen -t ed25519 -C "sftp-company-name" -f ~/.ssh/sftp_qitech
```

在 WSL 中请使用 Linux 路径（`~/.ssh`）。密钥保存在 WSL 的文件系统中，而不是 Windows 的用户目录中。

:::caution 请复制与您所用程序对应的那个标签页中的命令
每个标签页都按对应程序能识别的写法给出文件夹路径，因此这些命令不能互换使用。如果把某个标签页的命令放到另一个程序中运行，会出现 `No such file or directory`，并且不会生成任何密钥——这时只需回到正确的标签页重新复制命令即可。

在 Windows 上，如果不确定该用哪一个，请使用 **PowerShell**：它是 Windows 终端默认打开的程序。
:::

该命令会询问 口令（passphrase） ，并生成两个文件：

| 文件               | 说明                                       |
| ------------------ | ------------------------------------------ |
| `sftp_qitech`      | **私钥。** 切勿发送，切勿共享。            |
| `sftp_qitech.pub`  | **公钥。** 这是您需要发送给我们的文件。    |

关于 口令 ：

- **自动化集成**（由您的服务下载报告）：留空即可（在两次提示时直接按 Enter），并在存放私钥的位置对其加以保护，例如访问受限的密钥管理服务。如果口令必须在运行时对进程可用，它并不会带来实质性的保护。
- **由人工使用**：请设置口令。

`ssh-keygen` 生成的私钥权限默认仅限当前用户。如果您将该文件复制到另一台机器，请恢复其权限——SSH 客户端会拒绝其他用户可读的私钥：

```bash
chmod 600 ~/.ssh/sftp_qitech
```

## 2. 检查公钥格式

`.pub` 文件的内容是**单独一行**，以密钥类型开头，以注释结尾：

```
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIE1wA3uBEFYG+Yi7zIw7/YUJJ4fBB0MUZsvUVaqyyv6M sftp-acme
```

发送给我们之前，请先检查该文件：

```bash
ssh-keygen -lf ~/.ssh/sftp_qitech.pub
```

预期输出为密钥的 指纹 ，格式形如 `256 SHA256:... sftp-acme (ED25519)`。如果命令返回 `is not a public key file`，说明文件已损坏，或者它不是 OpenSSH 公钥。

### 如果您的密钥是 PEM/X.509 格式

以 `-----BEGIN PUBLIC KEY-----` 开头的密钥属于 PEM/X.509 格式，即 OpenSSL 的标准格式。该格式**无法登记到 SFTP**：服务器要求单行的 OpenSSH 格式。

如果该密钥已经专用于 SFTP，您无需重新生成，只需转换格式：

- **您仍有对应的私钥。** 适用于任意类型的密钥：

  ```bash
  ssh-keygen -y -f 私钥路径
  ```

- **您只有 PEM 格式的公钥。** 适用于 RSA 密钥：

  ```bash
  ssh-keygen -i -m PKCS8 -f 公钥路径.pem
  ```

两个命令都会将 OpenSSH 格式的密钥输出到标准输出。转换不会保留原有注释；如有需要，可在行尾追加 `sftp-company-name`。

## 3. 发送公钥

请通过 **1Password** 发送公钥，并将该条目共享给集成团队。这是我们接收密钥的渠道：它能完整保留您生成的内容，并使发送来源可被验证——任何能够在传输过程中替换您公钥的人，都将获得对您 SFTP 目录的访问权限。

1. 在 1Password 中创建一个条目，并将 `sftp_qitech.pub` 文件的内容**以纯文本形式粘贴进去，保持单独一行，不要换行**。
2. 附上密钥的 指纹 ——即上一步 `ssh-keygen -lf` 的输出。我们会将其与收到的密钥指纹进行比对，确认密钥在传输过程中未被篡改。
3. 将该条目共享给集成团队，并通过 [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) 告知我们已完成共享。

:::caution 请勿以 `.docx` 或 `.pdf` 附件发送密钥
这些程序的自动格式化会替换字符（把 `+` 替换为破折号，把直引号替换为弯引号）并插入换行。任何这类改动都会使密钥失效，而错误只会在连接时才暴露出来。
:::

公钥登记完成后，我们会确认权限开放，并向您提供 `HOSTNAME`、`USERNAME` 以及主机 指纹 。

## 4. 连接 SFTP

### 首次连接时请核对主机密钥

首次连接时，客户端会询问您是否信任该服务器。请勿不加核对就接受：将显示的 指纹 与集成团队提供的指纹进行比对。正是这一比对，才能防止其他服务器冒充我们的服务器。

```bash
ssh-keyscan -t ed25519 <hostname> > qitech_host_key
ssh-keygen -lf qitech_host_key          # 与 QI CTVM 提供的指纹进行比对
cat qitech_host_key >> ~/.ssh/known_hosts
```

核对完成后，`known_hosts` 即成为客户端的比对依据，出现不同主机密钥的连接会被自动拒绝。

### 连接凭证

| 凭证              | 来源                          |
| ----------------- | ----------------------------- |
| `HOSTNAME`        | 服务器地址，由 QI CTVM 提供   |
| `PORT`            | 22                            |
| `USERNAME`        | 用户名，由 QI CTVM 提供       |
| **私钥**          | 您自己生成的 `sftp_qitech`    |

:::caution 注意
这些凭证可直接访问贵方基金的报告，不得与他人共享。
:::

### 代码示例

**Python**

```python
import paramiko

HOSTNAME = "sftp.example.com"             # 由 QI CTVM 提供
PORT = 22
USERNAME = "username"                     # 由 QI CTVM 提供
PRIVATE_KEY = "/path/to/sftp_qitech"      # 您自己生成的私钥
KNOWN_HOSTS = "/path/to/known_hosts"      # 其中已包含核对过的 QI CTVM 主机密钥

client = paramiko.SSHClient()
client.load_host_keys(KNOWN_HOSTS)

# 如果主机密钥与预期不符，则拒绝连接。
# 请勿使用 AutoAddPolicy：它会不加验证地接受任何服务器。
client.set_missing_host_key_policy(paramiko.RejectPolicy())

client.connect(
    hostname=HOSTNAME,
    port=PORT,
    username=USERNAME,
    key_filename=PRIVATE_KEY,  # paramiko 会根据文件识别密钥类型
    look_for_keys=False,
    allow_agent=False,
    timeout=30,
)

try:
    with client.open_sftp() as sftp:
        # 列出可用文件
        for name in sftp.listdir("/"):
            print(name)

        # 下载文件
        sftp.get("remote/path/file.csv", "local/path/file.csv")
finally:
    client.close()
```

## 5. 下载文件

文件名由 基金的简称 、 报告模型 以及 YYYY-MM-DD 格式的 参考日期 组成：

- `example_name_assets_wallet_composition_2026-07-29.csv`

各报告模型、每个文件的逐列布局以及可下载的示例，请参阅 [DTVM 报告文档](/documentation/iaas/relatorios_dtvm/)。

:::info 说明
所提供的 SFTP 服务仅供 下载 文件使用；不允许进行 上传 。
:::

## 密钥的轮换与吊销

如需更换密钥，请重新生成密钥对，并按第 1 至第 3 步通过 1Password 将新的公钥发送给我们。我们会登记新密钥，并在移除旧密钥后通知您，使切换过程不产生服务中断窗口。

如果怀疑私钥已泄露，请通过同一联系方式通知集成团队：我们会先立即吊销旧密钥的访问权限，再登记新密钥。

---

# Webhook 接收

URL: /zh-Hans/documentation/iaas/introducao/autenticacao_webhooks

Webhook 签名采用对称密钥加密策略，即 QI CTVM 与集成合作方共享同一密钥。在配置 Webhook 时，我们将生成并提供一个 *Signature Key*。每个来自 QI 系统的请求都会携带一个 SIGNATURE 请求头，该请求头为使用该密钥签名的 JWT。编码算法为 HS256。

以下是使用 Python 进行签名解码的示例：
```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)
```

除了验证签名外，我们还建议集成合作方验证我们的 IP，因为我们所有的请求都来自同一个 IP，具体如下：

|环境|IP            |
|--------|--------------|
|生产环境|54.205.166.229|
|Sandbox |52.72.221.4   |

:::danger 注意！
QI CTVM 的 Webhook 不应以严格方式进行映射。
我们的 API 返回的 Webhook payload 中可能会包含额外字段。
:::

---

# 简介

URL: /zh-Hans/documentation/iaas/introducao/inicio

QI CTVM 是一家金融机构，提供投资基金的管理和托管服务。我们拥有一系列基于 REST API 的服务，为整个运营流程带来全新体验，旨在简化操作、实现自动化，并为相关各方提供完全透明的服务。

本文档旨在描述操作任何投资基金所需的流程、接口端点及数据结构。

注：如在任何阶段遇到疑问，请通过 [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) 联系我们，并详细说明您的问题，我们将为您提供协助。

## 访问权限角色

在我们的系统中，用户通过其在 QI CTVM 结构中承担的角色来识别。我们共有 5 种主要角色：
1. 基金管理人；
2. 资产发起人；
3. 转让人；
4. 投资者；
5. 分销商；

每种角色都有专属的集成接口端点，并提供相应的路由；

如需创建访问权限角色以使用我们的 API，请通过 [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) 联系我们的团队。

## 环境（Host）

QI CTVM 提供两种环境：SANDBOX 和生产环境。两种环境的代码和行为完全相同，但 SANDBOX 环境中的货币金额为虚拟数据，而生产环境会执行真实的金融交易。

Sandbox 环境专为开发者完成集成测试而创建，准备好进入生产环境时，只需更新生产环境参数的环境变量即可。

| 角色         | 环境     | Host                                           |
|----------------|----------|------------------------------------------------|
| 基金管理人       | Sandbox  | https://manager-api.sandbox.qidtvm.com.br/     |
| 资产发起人   | Sandbox  | https://originator-api.sandbox.qidtvm.com.br/  |
| 转让人       | Sandbox  | https://assignor-api.sandbox.qidtvm.com.br/    |
| 投资者   | Sandbox  | https://investor-api.sandbox.qidtvm.com.br/    |
| 分销商 | sandbox  | https://distributor-api.sandbox.qidtvm.com.br/ |
| 顾问    | sandbox  | https://consultant-api.sandbox.qidtvm.com.br/  |
| 基金管理人       | 生产环境 | https://manager-api.qidtvm.com.br/             |
| 转让人       | 生产环境 | https://assignor-api.qidtvm.com.br/            |
| 资产发起人   | 生产环境 | https://originator-api.qidtvm.com.br/          |
| 投资者   | 生产环境 | https://investor-api.qidtvm.com.br/            |
| 分销商 | 生产环境 | https://distributor-api.qidtvm.com.br/         |
| 顾问    | 生产环境 | https://consultant-api.qidtvm.com.br/          |
| 公开        | 生产环境 | https://api.qidtvm.com.br/                     |

:::danger 重要提示！
不得在 QI Tech 的 Sandbox 环境中使用真实的自然人或法人数据。
:::

---

# 端点包

URL: /zh-Hans/documentation/iaas/introducao/pacote_endpoints

为了简化与 QI Tech 生态系统的集成体验，我们提供了一个完整的端点包，包含所有可用端点，并已按文件夹结构进行整理。

我们的目标是使集成过程更加敏捷、清晰和规范——减少初始工作量，确保您在实施过程中能够立即访问所有必要资源。

该包集中提供：

- 每种产品的全部可用端点列表；

- 按主题组织的结构，与文档保持一致；

一个统一的参考点，避免分散查询或遗漏重要信息。

通过提供该文件夹，我们致力于确保集成合作方拥有一条 更简单、更快速、更结构化 的路径来启动与 QI Tech 的集成实施，体现我们对清晰性、安全性和技术效率的承诺。

### [📦 下载完整 Python 包](/downloads/integracao_python_iaas.zip)

---

# 测试端点

URL: /zh-Hans/documentation/iaas/introducao/teste_de_autenticacao/endpoints_de_teste

## GET 方法

### Request

ENDPOINT /authentication_test
MÉTODO GET

### Response

STATUS 200

Response Body

```json
{
  "success": "Congrats!"
}
```

## 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!"
}

```

---

# 认证测试

URL: /zh-Hans/documentation/iaas/introducao/teste_de_autenticacao/

### 1. 简介

本节将说明请求的构建方式，以便被我们的系统接受。首先，需要在请求头的 API-CLIENT-KEY 中放入 QI CTVM 团队提供的 Api Key。然后，需要使用集成合作方的私钥创建 AUTHORIZATION 请求头进行签名；

以下将通过 Python 示例，逐步说明 AUTHORIZATION 的创建过程。

### 2. 导入库
本 Python 示例使用 5 个库来完成认证过程。

```python
from datetime import datetime
import json
from jose import jwt
from hashlib import md5
import requests
```

### 3. 插入私钥和集成密钥
```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. 定义变量
定义每个请求特有的方法、端点和内容变量（本例中，我们使用 "POST" 方法访问 "/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"}
```

### 5. 构建基础签名字典
```python title="Dicionário base"

dict_to_sign = {"timestamp": today_str, "method": method, "uri": endpoint}

```

#### 5.1. 如有必要，添加内容
对于含有 _body_ 的请求，需要添加该内容的字节 md5。由于我们系统中的所有请求均通过 JSON 传输，可以使用以下方式：

```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. 对请求头进行加密
使用 JWT 库进行加密（本代码示例中，我们在 JavaScript 中使用 jsonwebtoken 作为 jwt）

```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. 组装最终请求头

```python
headers = {"API-CLIENT-KEY": api_key, "AUTHORIZATION": encoded_header_token}
```

```python title="Definindo url final"
url = f"{base_url}{endpoint}"
```

### 发送请求

```python
resp = requests.post(url=url, headers=headers, json=body)
print(resp.json())
```

---

# 密钥交换

URL: /zh-Hans/documentation/iaas/introducao/troca_de_chaves

## 1. 签名请求

我们所有 API 的请求必须使用 **HTTPs** 协议，采用 **TLS 1.2 或 1.3**，并包含两个请求头：

1. API-CLIENT-KEY：由我们集成团队提供的密钥，用于标识特定的集成；
2. AUTHORIZATION：请求签名，须按照本手册中的说明进行；

QI CTVM 标准采用非对称密钥方案，其中存在两种不同的密钥：用于签名的 私钥 和用于读取的 公钥 。集成合作方需使用私钥，按照 JWT 标准进行签名。
集成合作方负责生成密钥对，并将公钥提供给 QI CTVM 团队，以便我们验证其请求。

:::caution **注意**
私钥仅供集成合作方专用，必须妥善保管。QI CTVM 在任何情况下都不会要求您与我们共享私钥。
:::
## 2. 生成密钥对

要在 UNIX 计算机上生成私钥，请执行：

```bash
$ ssh-keygen -t ecdsa -b 521 -m PEM -f private.key
```

然后从该私钥生成公钥。

```bash
$ openssl ec -in private.key -pubout -outform PEM -out public.key.pub
```

生成的公钥（public.key.pub 文件）须发送给 QI Tech 团队，并等待集成配置完成；

# 说明视频

---

# Início

URL: /zh-Hans/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 quatro fluxos, organizados de acordo com o tipo de investidor e o canal pelo qual ele 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`
Fundo de Investimento
veículos com CNPJ próprio (FIMs, FIAs, FIDCs e demais classes) que aplicam recursos em nome de seus cotistas `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`) fazem o cadastro de seus cotistas

### 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: /zh-Hans/documentation/iaas/investidor/cadastro/atualizacao_cadastral



---

# atualizar_status_grupo_assinantes

URL: /zh-Hans/documentation/iaas/investidor/cadastro/atualizar_status_grupo_assinantes



---

# busca_informacoes_de_uma_analise_cadastral_do_investidor

URL: /zh-Hans/documentation/iaas/investidor/cadastro/busca_informacoes_de_uma_analise_cadastral_do_investidor



---

# busca_informacoes_do_investidor

URL: /zh-Hans/documentation/iaas/investidor/cadastro/busca_informacoes_do_investidor



---

# buscar_documentos_para_assinatura

URL: /zh-Hans/documentation/iaas/investidor/cadastro/buscar_documentos_para_assinatura



---

# 分页查询投资者数据

URL: /zh-Hans/documentation/iaas/investidor/cadastro/buscar_investidores_paginado

---

### Introduction
此功能允许通过可选筛选条件（证件号码、状态和姓名）列出投资者，并支持分页。

### Input / Output

无请求体。筛选条件通过 *query string* 传递，全部为可选。

***输出***将返回符合所提供筛选条件的投资者列表。

### Request

ENDPOINT `/investor_registry/investors`
MÉTODO `GET`
STATUS `200`

### Query Params

所有参数均为**可选**。

| Param             | 类型   | 默认值 | 描述                                                      |
|-------------------|--------|:------:|-----------------------------------------------------------|
| `document_number` | string | `None` | 按完整证件号码筛选                                        |
| `status`          | string | `None` | 按状态筛选                                                |
| `name`            | string | `None` | 按姓名筛选                                                |
| `limit`           | int    | `100`  | 每页条数（最小 `0`，最大 `500`）                          |
| `page`            | int    | `0`    | 页码；偏移量按 `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

| 字段 | 类型 | 描述 |
|----------------|---------|--------------------------------------------------------------------|
| `data`         | array   | **[Investor](#investor)** 对象列表                                 |
| `limit`        | int     | 查询中使用的每页条数                                               |
| `page`         | int     | 返回的页码                                                         |
| `is_last_page` | boolean | 是否为结果的最后一页                                               |

### Investor {#investor}

| 字段 | 类型 | 描述 |
|-----------------|--------|----------------------------------------------------|
| `investor_key`  | string | 投资者的唯一标识键                                 |
| `name`          | string | 投资者姓名（或公司名称）                           |
| `status`        | string | 投资者的当前状态                                   |
| `person_type`   | string | 人员类型（`natural_person` 或 `legal_person`）     |
| `email`         | string | 投资者的联系邮箱                                   |
| `phone`         | string | 投资者的联系电话                                   |
| `distributor`   | object | **Distributor** 对象                               |

### Distributor {#distributor}

| 字段 | 类型 | 描述 |
|--------------------------|--------|--------------------------------------------------|
| `distributor_key`        | string | 分销商的唯一标识键                               |
| `name`                   | string | 分销商名称                                       |
| `document_number`        | string | 分销商的 CNPJ                                     |
| `registry_configuration` | object | 分销商的注册配置                                 |

---

# consultar_analise_em_andamento

URL: /zh-Hans/documentation/iaas/investidor/cadastro/consultar_analise_em_andamento



---

# atualizar_status_conta_bancaria

URL: /zh-Hans/documentation/iaas/investidor/cadastro/contas_bancarias/atualizar_status_conta_bancaria



---

# definir_conta_principal

URL: /zh-Hans/documentation/iaas/investidor/cadastro/contas_bancarias/definir_conta_principal



---

# enviar_contas_bancarias

URL: /zh-Hans/documentation/iaas/investidor/cadastro/contas_bancarias/enviar_contas_bancarias



---

# 创建投资者/投资者分析

URL: /zh-Hans/documentation/iaas/investidor/cadastro/criar_investidor

---

### 简介
本资源旨在向我们提供启动投资者**注册分析**所需的基本数据。
**注册分析**有2种类型：**自然人**和**法人**。法人又有***子类型***，用于区分注册过程中所需的信息。

:::info 信息
在同质化环境中，我们有如下规则：以1开头的 CPF/CNPJ：自动拒绝；以8开头的 CPF/CNPJ：待人工验证；其余自动批准。
:::

### 注册流程

法人投资者注册遵循以下步骤：

1. **创建投资者** - 初始创建投资者和注册分析
2. **发送注册数据** - 法人具体数据
3. **发送地址** - 地址信息
4. **发送净资产** - 净资产数据
5. **发送银行账户** - 银行账户信息
6. **发送适配度** - 适配度问卷（零售投资者必须）
7. **发送签署人组** - 定义签署人组
8. **发送投资者文件** - 上传必要文件
9. **创建关联方** - 注册合伙人、董事、管理员等
10. **发送关联方文件** - 上传关联方文件
11. **发送分析** - 提交注册分析
12. **签署文件** - 批准后签署文件

### 输入/输出：
每种**注册分析**类型需要不同的***输入***数据集，以下是启动每种流程的示例。

作为***输出***，将返回 ***investor_key*** 和 ***investor_analysis_key***。***investor_analysis_key*** 用于标识创建的**注册分析**。
***investor_key*** 用于标识**注册分析**所属的**投资者**。

因此，一个 ***investor_key***（投资者）可以关联一个或多个 ***investor_analysis_key***（注册分析）。

***investor_key*** 和 ***investor_analysis_key*** 都将用于与**投资者**或**注册分析**交互的其他端点。

### Request

ENDPOINT `/investor_registry/v2/investor`
MÉTODO `POST`
STATUS `201`

### Request body
```json title='Request Body'
{
    "name": "string",
    "document_number": "xx.xxx.xxx/xxxx-xx",
    "person_type": "legal_person | natural_person",
    "person_sub_type": "regular | fund_class",
    "external_distribution_key": "campo livre",
    "email": "string",
    "phone": {
	    "international_dial_code": "+xx",
	    "area_code": "xx",
	    "number": "xxxxxxxxxx"
    }
}

```

:::warning 注意
必填字段根据 **person_type** 有所不同。

- 如果是 **natural_person**（自然人）：
    - **name**、**document_number**、**person_type**、**email** 和 **phone** 为必填字段

- 如果是 **legal_person**（法人）：
    - **name**、**document_number**、**person_type** 为必填字段

- 如果是 **nominee**（PCO）：
    - **name**、**person_type**、**external_distribution_key** 为必填字段

:::

:::info 信息
**registry_user** 是代表将填写投资者注册数据的用户的实体。
对于**自然人**，投资者本人填写其注册数据。
:::

情况02：注册法人

```json title='Request Body'
{
  "name": "Fundo XPTO", 
  "document_number": "12.456.789/0001-00", 
  "person_type": "legal_person",
  "person_sub_type": "regular",
  "registry_user": {
    "name": "José da Silva", 
    "document_number": "123.456.789-00",
    "email": "example@example.com",
    "phone": {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "1234567890"
    },
  }
}
```

### Body params
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `name` | string | 投资者姓名 | 1-255 | 是 |
| `document_number` | string | CPF 或 CNPJ | 13-18 | 是 |
| `person_type` | string | **[Person Type](#person_type)** 枚举值 | - | 是 |
| `person_sub_type` | string | **[Person Sub Type](#person_sub_type)** 枚举值 | - | 是 |
| `email` | string | 电子邮件 | 1-255 | 否 |
| `phone` | JSON | **[Phone](#phone)** 对象 | - | 否 |
| `registry_user` | JSON | **[Registry User](#registry_user)** 对象 | - | 否 |

### Phone
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `international_dial_code` | string | 国际区号 | 1-3 | 是 |
| `area_code` | string | 地区区号 | 2 | 是 |
| `number` | string | 电话号码 | 8-9 | 是 |

### Registry User
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `name` | string | 注册用户姓名 | 1-255 | 是 |
| `document_number` | string | CPF | 13 | 是 |
| `person_type` | string | **[Person Type](#person_type)** 枚举值 | - | 是 |
| `email` | string | 电子邮件 | 1-255 | 是 |
| `phone` | JSON | **[Phone](#phone)** 对象 | - | 是 |

### Person Type
| 枚举值 | 描述 |
|-----------------------------------|------------------------------------------------------------------------------|
| `natural_person` | 自然人 |
| `legal_person` | 法人 |

### Person Sub Type
| 枚举值 | 描述 |
|-----------------------------------|------------------------------------------------------------------------------|
| `regular` | - |
| `fund_class` | 投资基金 |

### Response
```json title='Response Body'
{
    "investor_key": "UUID",
    "investor_analysis_key": "UUID"
}
```

---

# definir_grupo_assinantes_padrao

URL: /zh-Hans/documentation/iaas/investidor/cadastro/definir_grupo_assinantes_padrao



---

# enviar_cadastro_para_analise

URL: /zh-Hans/documentation/iaas/investidor/cadastro/enviar_cadastro_para_analise



---

# enviar_dados_cadastrais

URL: /zh-Hans/documentation/iaas/investidor/cadastro/enviar_dados_cadastrais



---

# enviar_endereco

URL: /zh-Hans/documentation/iaas/investidor/cadastro/enviar_endereco



---

# enviar_grupos_assinantes

URL: /zh-Hans/documentation/iaas/investidor/cadastro/enviar_grupos_assinantes



---

# enviar_investor_document

URL: /zh-Hans/documentation/iaas/investidor/cadastro/enviar_investor_document



---

# enviar_patrimonio

URL: /zh-Hans/documentation/iaas/investidor/cadastro/enviar_patrimonio



---

# consultar_feedback

URL: /zh-Hans/documentation/iaas/investidor/cadastro/feedback/consultar_feedback



---

# enviar_mensagem_feedback

URL: /zh-Hans/documentation/iaas/investidor/cadastro/feedback/enviar_mensagem_feedback



---

# listar_feedbacks

URL: /zh-Hans/documentation/iaas/investidor/cadastro/feedback/listar_feedbacks



---

# Introdução

URL: /zh-Hans/documentation/iaas/investidor/cadastro/introducao

Esta seção reúne os fluxos de cadastro de investidores que não se enquadram nas categorias específicas — **Carteira Administrada**, **Fundo de Investimento** ou **Distribuição Externa** —, cobrindo pessoas físicas e jurídicas em geral, como é o caso de um consultor (`consultant-integration`) ou gestor (`manager-integration`) estar cadastrando um investidor.

O cadastro contempla o envio de dados cadastrais, endereço, patrimônio, contas bancárias, suitability, grupos de assinantes, partes relacionadas e, quando aplicável, *investor owner*, até o disparo da análise cadastral pela QI Tech.

Importante ressaltar que nesses casos a assinatura é sempre executada exclusivamente pelo investidor ou representante legal identificado durante a análise.

### 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 (não exigido para fundos de investimento)
↓
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

Nas subseções a seguir veremos cada uma das etapas necessárias para concluir esses cadastros.

---

# criar_parte_relacionada

URL: /zh-Hans/documentation/iaas/investidor/cadastro/related_party/criar_parte_relacionada



---

# enviar_documento_parte_relacionada

URL: /zh-Hans/documentation/iaas/investidor/cadastro/related_party/enviar_documento_parte_relacionada



---

# consultar_formulario_suitability

URL: /zh-Hans/documentation/iaas/investidor/cadastro/suitability/consultar_formulario_suitability



---

# enviar_suitability

URL: /zh-Hans/documentation/iaas/investidor/cadastro/suitability/enviar_suitability



---

# atualizacao_cadastral

URL: /zh-Hans/documentation/iaas/investidor/carteira_administrada/atualizacao_cadastral



---

# atualizar_status_grupo_assinantes

URL: /zh-Hans/documentation/iaas/investidor/carteira_administrada/atualizar_status_grupo_assinantes



---

# busca_informacoes_de_uma_analise_cadastral_do_investidor

URL: /zh-Hans/documentation/iaas/investidor/carteira_administrada/busca_informacoes_de_uma_analise_cadastral_do_investidor



---

# busca_informacoes_do_investidor

URL: /zh-Hans/documentation/iaas/investidor/carteira_administrada/busca_informacoes_do_investidor



---

# buscar_documentos_para_assinatura

URL: /zh-Hans/documentation/iaas/investidor/carteira_administrada/buscar_documentos_para_assinatura



---

# consultar_analise_em_andamento

URL: /zh-Hans/documentation/iaas/investidor/carteira_administrada/consultar_analise_em_andamento



---

# atualizar_status_conta_bancaria

URL: /zh-Hans/documentation/iaas/investidor/carteira_administrada/contas_bancarias/atualizar_status_conta_bancaria



---

# definir_conta_principal

URL: /zh-Hans/documentation/iaas/investidor/carteira_administrada/contas_bancarias/definir_conta_principal



---

# enviar_contas_bancarias

URL: /zh-Hans/documentation/iaas/investidor/carteira_administrada/contas_bancarias/enviar_contas_bancarias



---

# 创建投资者/投资者分析

URL: /zh-Hans/documentation/iaas/investidor/carteira_administrada/criar_investidor

---

### 简介
本资源旨在向我们提供启动投资者**注册分析**所需的基本数据。
**注册分析**有2种类型：**自然人**和**法人**。法人又有***子类型***，用于区分注册过程中所需的信息。

:::info 信息
在同质化环境中，我们有如下规则：以1开头的 CPF/CNPJ：自动拒绝；以8开头的 CPF/CNPJ：待人工验证；其余自动批准。
:::

### 注册流程

法人投资者注册遵循以下步骤：

1. **创建投资者** - 初始创建投资者和注册分析
2. **发送注册数据** - 法人具体数据
3. **发送地址** - 地址信息
4. **发送净资产** - 净资产数据
5. **发送银行账户** - 银行账户信息
6. **发送适配度** - 适配度问卷（零售投资者必须）
7. **发送签署人组** - 定义签署人组
8. **发送投资者文件** - 上传必要文件
9. **创建关联方** - 注册合伙人、董事、管理员等
10. **发送关联方文件** - 上传关联方文件
11. **发送分析** - 提交注册分析
12. **签署文件** - 批准后签署文件

### 输入/输出：
每种**注册分析**类型需要不同的***输入***数据集，以下是启动每种流程的示例。

作为***输出***，将返回 ***investor_key*** 和 ***investor_analysis_key***。***investor_analysis_key*** 用于标识创建的**注册分析**。
***investor_key*** 用于标识**注册分析**所属的**投资者**。

因此，一个 ***investor_key***（投资者）可以关联一个或多个 ***investor_analysis_key***（注册分析）。

***investor_key*** 和 ***investor_analysis_key*** 都将用于与**投资者**或**注册分析**交互的其他端点。

### Request

ENDPOINT `/investor_registry/v2/investor`
MÉTODO `POST`
STATUS `201`

### Request body
```json title='Request Body'
{
    "name": "string",
    "document_number": "xx.xxx.xxx/xxxx-xx",
    "person_type": "legal_person | natural_person",
    "person_sub_type": "regular | fund_class",
    "external_distribution_key": "campo livre",
    "email": "string",
    "phone": {
	    "international_dial_code": "+xx",
	    "area_code": "xx",
	    "number": "xxxxxxxxxx"
    }
}

```

:::warning 注意
必填字段根据 **person_type** 有所不同。

- 如果是 **natural_person**（自然人）：
    - **name**、**document_number**、**person_type**、**email** 和 **phone** 为必填字段

- 如果是 **legal_person**（法人）：
    - **name**、**document_number**、**person_type** 为必填字段

- 如果是 **nominee**（PCO）：
    - **name**、**person_type**、**external_distribution_key** 为必填字段

:::

:::info 信息
**registry_user** 是代表将填写投资者注册数据的用户的实体。
对于**自然人**，投资者本人填写其注册数据。
:::

情况02：注册法人

```json title='Request Body'
{
  "name": "Fundo XPTO", 
  "document_number": "12.456.789/0001-00", 
  "person_type": "legal_person",
  "person_sub_type": "regular",
  "registry_user": {
    "name": "José da Silva", 
    "document_number": "123.456.789-00",
    "email": "example@example.com",
    "phone": {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "1234567890"
    },
  }
}
```

### Body params
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `name` | string | 投资者姓名 | 1-255 | 是 |
| `document_number` | string | CPF 或 CNPJ | 13-18 | 是 |
| `person_type` | string | **[Person Type](#person_type)** 枚举值 | - | 是 |
| `person_sub_type` | string | **[Person Sub Type](#person_sub_type)** 枚举值 | - | 是 |
| `email` | string | 电子邮件 | 1-255 | 否 |
| `phone` | JSON | **[Phone](#phone)** 对象 | - | 否 |
| `registry_user` | JSON | **[Registry User](#registry_user)** 对象 | - | 否 |

### Phone
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `international_dial_code` | string | 国际区号 | 1-3 | 是 |
| `area_code` | string | 地区区号 | 2 | 是 |
| `number` | string | 电话号码 | 8-9 | 是 |

### Registry User
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `name` | string | 注册用户姓名 | 1-255 | 是 |
| `document_number` | string | CPF | 13 | 是 |
| `person_type` | string | **[Person Type](#person_type)** 枚举值 | - | 是 |
| `email` | string | 电子邮件 | 1-255 | 是 |
| `phone` | JSON | **[Phone](#phone)** 对象 | - | 是 |

### Person Type
| 枚举值 | 描述 |
|-----------------------------------|------------------------------------------------------------------------------|
| `natural_person` | 自然人 |
| `legal_person` | 法人 |

### Person Sub Type
| 枚举值 | 描述 |
|-----------------------------------|------------------------------------------------------------------------------|
| `regular` | - |
| `fund_class` | 投资基金 |

### Response
```json title='Response Body'
{
    "investor_key": "UUID",
    "investor_analysis_key": "UUID"
}
```

---

# definir_grupo_assinantes_padrao

URL: /zh-Hans/documentation/iaas/investidor/carteira_administrada/definir_grupo_assinantes_padrao



---

# enviar_cadastro_para_analise

URL: /zh-Hans/documentation/iaas/investidor/carteira_administrada/enviar_cadastro_para_analise



---

# enviar_dados_cadastrais

URL: /zh-Hans/documentation/iaas/investidor/carteira_administrada/enviar_dados_cadastrais



---

# enviar_endereco

URL: /zh-Hans/documentation/iaas/investidor/carteira_administrada/enviar_endereco



---

# enviar_grupos_assinantes

URL: /zh-Hans/documentation/iaas/investidor/carteira_administrada/enviar_grupos_assinantes



---

# enviar_investor_document

URL: /zh-Hans/documentation/iaas/investidor/carteira_administrada/enviar_investor_document



---

# enviar_patrimonio

URL: /zh-Hans/documentation/iaas/investidor/carteira_administrada/enviar_patrimonio



---

# consultar_feedback

URL: /zh-Hans/documentation/iaas/investidor/carteira_administrada/feedback/consultar_feedback



---

# enviar_mensagem_feedback

URL: /zh-Hans/documentation/iaas/investidor/carteira_administrada/feedback/enviar_mensagem_feedback



---

# listar_feedbacks

URL: /zh-Hans/documentation/iaas/investidor/carteira_administrada/feedback/listar_feedbacks



---

# Introdução

URL: /zh-Hans/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: /zh-Hans/documentation/iaas/investidor/carteira_administrada/investor_owner/enviar_documento_investor_owner



---

# criar_parte_relacionada

URL: /zh-Hans/documentation/iaas/investidor/carteira_administrada/related_party/criar_parte_relacionada



---

# enviar_documento_parte_relacionada

URL: /zh-Hans/documentation/iaas/investidor/carteira_administrada/related_party/enviar_documento_parte_relacionada



---

# consultar_formulario_suitability

URL: /zh-Hans/documentation/iaas/investidor/carteira_administrada/suitability/consultar_formulario_suitability



---

# enviar_suitability

URL: /zh-Hans/documentation/iaas/investidor/carteira_administrada/suitability/enviar_suitability



---

# Assinar Documento

URL: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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.

---

# 查询投资者信息

URL: /zh-Hans/documentation/iaas/investidor/compartilhado/busca_informacoes_de_uma_analise_cadastral_do_investidor

---

### 简介
本资源旨在提供**投资者**的**注册分析**数据。

### 输入/输出：
本资源没有作为***输入***的***body***，只需在 *path* 中传递**投资者**标识键（*investor_key*）。

作为***输出***，将返回我们系统中该投资者每项数据的表示。以下是示例。

### Request

ENDPOINT `/investor_registry/v2/investor/{investor_key}/investor_analysis/{investor_analysis_key}`
MÉTODO `GET`
STATUS `200`

### Responses

情况01：法人投资者注册分析 - 投资基金

```json
{
   "investor_analysis_key":"faf54393-178c-41ae-8318-94b65c575c7d",
   "name":"Sample Investor Name",
   "document_number":"05.112.864/0001-19",
   "analysis_datetime":"2025-04-29 12:07:55.059999",
   "status":"approved",
   "agent_key":"e53230ad-670d-4410-a3f3-5a179eb53be0",
   "registry_user":[
      {
         "registry_user_key":"91d5dbbf-a54b-4aa1-86c9-a6fe39140c20",
         "name":"Sample Investor Name",
         "document_number":"05.112.864/0001-19",
         "email":"05112864000119@email.com.br",
         "phone":{
            "number":"123456789",
            "area_code":"11",
            "international_dial_code":"055"
         }
      }
   ],
   "bank_accounts":[
      {
         "main_account":true,
         "account_digit":"8",
         "account_branch":"2152",
         "account_number":"43473205725488",
         "financial_institution_code":"349"
      }
   ],
   "representatives_analyses":[
      {
         "representative_analysis_key":"b41e936c-7001-4727-aa1d-58bea16a0f36",
         "name":"Sample",
         "document_number":"069.800.621-66",
         "status":"pending_documents",
         "documents":[
            
         ],
         "powers":[
            "investor_registry.read_investor_user",
            "investor_registry.update_investor_analysis",
            "investor_registry.create_investor",
            "investor_registry.read_investor_analyses",
            "quota_distributor.generate_report",
            "quota_distributor.read_investor_positions"
         ]
      }
   ],
   "status_events":[
      {
         "status":"pending_registry_data",
         "event_datetime":"2025-04-29 12:07:55.065287"
      },
      {
         "status":"pending_documents",
         "event_datetime":"2025-04-29 12:07:55.065287"
      },
      {
         "status":"approved",
         "event_datetime":"2025-04-29 12:07:55.065287"
      }
   ],
   "email":"05112864000119@email.com.br",
   "phone":{
      "number":"123456789",
      "area_code":"11",
      "international_dial_code":"055"
   },
   "address":{
      "uf":"SP",
      "city":"São Paulo",
      "number":"123",
      "street":"Sample",
      "country":"BRA",
      "complement":"Sample",
      "postal_code":"00000-000",
      "neighborhood":"Sample"
   },
   "net_worth":{
      "salary":0,
      "real_state":0,
      "other_incomes":0,
      "movable_assets":0,
      "resource_origin":"I have a lot of money, bro",
      "total_net_worth":0,
      "total_financial_applications":0
   },
   "person_type":"legal_person",
   "person_sub_type": "fund_class",
   "legal_person":{
      "name": "Sample Fundo",
      "foundation_date": "2025-04-25",
      "activity_code": "6470-1-01",
      "fund_class": {
        "cvm_code": "480274",
        "giin_code": "1ZT8DV.99999.SL.076",
        "administrator": {
            "name": "Sample DTVM",
            "document_number": "07.228.314/0001-95"
        },
        "manager": {
            "name": "Sample Gestora",
            "document_number": "77.784.920/0001-72"
        },
        "exclusive_investor": {
            "name": "Sample Investor",
            "document_number": "240.610.880-50"
        },
        "selic_account": "4298-6",
        "cetip_account": "3T6O05700-3"
      }
  },
   "representatives":[
      {
         "name":"Sample",
         "type":"administrator",
         "powers":[
            "investor_registry.read_investor_user",
            "investor_registry.update_investor_analysis",
            "investor_registry.create_investor",
            "investor_registry.read_investor_analyses",
            "quota_distributor.generate_report",
            "quota_distributor.read_investor_positions"
         ],
         "document_number":"069.800.621-66"
      }
   ],
   }
```

### Investor Analysis
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------|------- |------------------------------------------------------------------|------------|
| `investor_analysis_key` | string | 注册分析唯一标识键 | 36 |
| `name` | string | 投资者姓名 | 最多255 |
| `document_number` | string | 投资者 CPF / CNPJ | 14或18 |
| `analysis_datetime` | string | 注册分析创建的日期和时间 | - |
| `status` | string | 注册分析状态枚举值 | - |
| `agent_key` | string | 发起注册的代理人唯一标识键 | 36 |
| `email` | string | 投资者电子邮件 | 最多255 |
| `person_type` | string | 投资者自然人或法人枚举值 | - |
| `distributor` | JSON | **[Distributor](#distributor)** 对象 | - |
| `status_events` | array | **[Status Event](#status_event)** 对象列表 | - |

### Person Type
| 枚举值 | 描述 |
|--------------------------|-----------------------|
| `natural_person` | 自然人 |
| `legal_person` | 法人 |

### Distributor
| 字段 | 类型 | 描述 | 字符数 |
|--------------------------|----------|---------------------------------------------------|------------|
| `name` | string | 分销商名称 | 最多255 |
| `distributor_key` | string | 分销商唯一标识键 | - |
| `document_number` | string | 分销商 CPF/CNPJ | 14或18 |

### Investor Analysis
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|----------|----------------------------------------------------------------|------------|
| `investor_analysis_key` | string | 投资者注册分析唯一标识键 | 36 |
| `analysis_datetime` | string | 注册分析创建的日期和时间 | - |
| `status` | string | 注册分析状态枚举值 | - |
| `registry_user` | JSON | **[Registry User](#registry_user)** 对象 | - |

### Registry User
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|----------|----------------------------------------------------------------|------------|
| `registry_user_key` | string | 注册用户唯一标识键 | 36 |
| `kc_user_id` | string | KeyCloak 中用户的唯一标识键 | - |
| `name` | string | 分销商名称 | 最多255 |
| `document_number` | string | 分销商 CPF/CNPJ | 14或18 |
| `phone` | JSON | **[Phone](#phone)** 对象 | - |

### Phone
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------------|----------|-------------------------------------|--------------|
| `international_dial_code` | string | 国际区号 | 1-3 |
| `area_code` | string | 地区区号 | 2 |
| `number` | string | 电话号码 | 8-9 |

### Investor Analysis Status
| 枚举值 | 描述 |
|--------------------------|-----------------------------|
| `pending_registry_data` | 待注册数据 |
| `pending_documents` | 待文件 |
| `sent_to_analysis` | 已发送分析 |
| `in_manual_analysis` | 人工分析中 |
| `approved` | 已批准 |
| `reproved` | 已拒绝 |

### Status Event 
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|----------|------------------------------------------------------------|------------|
| `status` | string | Investor Status 枚举值 | - |
| `event_datetime` | string | 状态更新执行的日期和时间 | - |

---

# 查询投资者信息

URL: /zh-Hans/documentation/iaas/investidor/compartilhado/busca_informacoes_do_investidor

---

### 简介
本资源旨在提供**投资者**的数据。

### 输入/输出：
本资源没有作为***输入***的***body***，只需在 *path* 中传递**投资者**标识键（*investor_key*）。

作为***输出***，将返回我们系统中该投资者每项数据的表示。以下是示例。

### Request

ENDPOINT `/investor_registry/v2/investor/{investor_key}`
MÉTODO `GET`
STATUS `200`

### Responses

情况01：法人投资者 - 投资基金

```json
{
   "investor_key":"UUID",
   "name":"Sample Investor Name",
   "document_number":"000.000.000-00",
   "status":"pending_analysis",
   "email":"sample@mail.com.br",
   "person_type":"natural_person",
   "phone":{
      "number":"123456789",
      "area_code":"11",
      "international_dial_code":"055"
   },
   "distributor":{
      "distributor_key":"UUID",
      "name":"Sample Distributor Name",
      "document_number":"00.000.000/0000-00"
   },
   "analyses":[
      {
         "investor_analysis_key":"308af5df-38ff-4b38-941e-aadc6e4804f8",
         "analysis_datetime":"2024-11-25 13:42:40.003782",
         "status":"pending_registry_data"
      }
   ],
   "document_batches":[
      {
         "document_batch_key":"308af5df-38ff-4b38-941e-aadc6e4804f8",
         "status":"creating_documents | pending_signer_groups | send_to_signature | pending_signature",
         "documents":[
            {
               "investor_document_key":"UUID",
               "type":" cnh | rg | rg_back | rg_front | proof_of_residence | cnpj_card | financial_statements | power_of_attorney | billing_statement | social_contract |qualified_investor_term | professional_investor_term | natural_person_registry_form | legal_person_registry_form ",
               "status":"generated"
            }
         ]
      }
   ],
   "status_events":[
      {
         "status":"pending_analysis",
         "event_datetime":"2024-11-25 13:42:40.013357"
      }
   ],
}
```

情况02：法人投资者待注册分析

```json
{
   "investor_key":"UUID",
   "name":"Sample Investor Name",
   "document_number":"00.000.000/0000-00 | 000.000.000-00",
   "status":"pending_analysis",
   "person_type":"legal_person",
   "distributor":{
      "distributor_key":"UUID",
      "name":"Sample Distributor Name",
      "document_number":"00.000.000/0000-00"
   },
   "email":"sample@mail.com.br",
   "phone":{
      "number":"123456789",
      "area_code":"11",
      "international_dial_code":"055"
   },
   "analyses":[
      {
         "investor_analysis_key":"UUID",
         "agent_key":"UUID",
         "analysis_datetime":"2024-11-25 13:08:25.649543",
         "status":"pending_registry_data",
         "registry_user":{
            "registry_user_key":"UUID",
            "kc_user_id":"UUID",
            "name":"Sample Investor Name",
            "document_number":"000.000.000-00",
            "email":"sample@email.com.br",
            "phone":{
               "number":"123456789",
               "area_code":"11",
               "international_dial_code":"055"
            }
         }
      }
   ],
   "document_batches":[
      {
         "document_batch_key":"308af5df-38ff-4b38-941e-aadc6e4804f8",
         "status":"creating_documents | send_to_signature | pending_signature",
         "documents":[
            {
               "investor_document_key":"UUID",
               "type":" cnh | rg | rg_back | rg_front | proof_of_residence | cnpj_card | financial_statements | power_of_attorney | billing_statement | social_contract |qualified_investor_term | professional_investor_term | natural_person_registry_form | legal_person_registry_form ",
               "status":"sent_to_generate | generated"
            }
         ]
      }
   ],
   "status_events":[
      {
         "status":"pending_analysis",
         "event_datetime":"2024-11-25 13:08:25.673902"
      }
   ],
}
```

### Investor
| 字段 | 类型 | 描述 | 字符数 |
|--------------------|------- |---------------------------------------------------------------------------------|------------|
| `investor_key` | string | 投资者唯一标识键 | 36 |
| `name` | string | 投资者姓名 | 最多255 |
| `document_number` | string | 投资者 CPF / CNPJ | 14或18 |
| `email` | string | 投资者电子邮件 | - |
| `phone` | string | **[Phone](#phone)** 对象 | - |
| `status` | string | 投资者注册状态枚举值 | - |
| `person_type` | string | 投资者自然人或法人枚举值 | - |
| `distributor` | JSON | **[Distributor](#distributor)** 对象 | - |
| `analyses` | array | **[Investor Analysis](#analysis)** 对象列表 | - |
| `document_batches` | array | **[Document Batch](#document_batch)** 对象列表 | - |
| `status_events` | array | **[Status Event](#status_event)** 对象列表 | - |

### Phone
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------------|----------|-------------------------------------|--------------|
| `international_dial_code` | string | 国际区号 | 1-3 |
| `area_code` | string | 地区区号 | 2 |
| `number` | string | 电话号码 | 8-9 |

### Investor Status
| 枚举值 | 描述 |
|--------------------------|-----------------------|
| `pending_analysis` | 待分析 |
| `pending_documents` | 待文件 |
| `pending_update` | 待更新 |
| `registered` | 已注册 |

### Person Type
| 枚举值 | 描述 |
|--------------------------|-----------------------|
| `natural_person` | 自然人 |
| `legal_person` | 法人 |

### Distributor
| 字段 | 类型 | 描述 | 字符数 |
|--------------------------|----------|---------------------------------------------------|------------|
| `name` | string | 分销商名称 | 最多255 |
| `distributor_key` | string | 分销商唯一标识键 | - |
| `document_number` | string | 分销商 CPF/CNPJ | 14或18 |

### Investor Analysis
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|----------|----------------------------------------------------------------|------------|
| `investor_analysis_key` | string | 投资者注册分析唯一标识键 | 36 |
| `analysis_datetime` | string | 注册分析创建的日期和时间 | - |
| `status` | string | 注册分析状态枚举值 | - |
| `registry_user` | JSON | **[Registry User](#registry_user)** 对象 | - |

### Document Batch
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|----------|-----------------------------------------------------------------|------------|
| `document_batch_key` | string | 文件批次唯一标识键 | 36 |
| `status` | string | 文件批次状态枚举值 | - |
| `documents` | Array | **[Investor Document](#investor_document)** 对象列表 | - |

### Investor Document
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|----------|----------------------------------------------------------------|------------|
| `investor_document_key` | string | 投资者文件唯一标识键 | 36 |
| `type` | string | 投资者文件类型枚举值 | - |
| `status` | string | 投资者文件状态枚举值 | - |

### Registry User
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|----------|----------------------------------------------------------------|------------|
| `registry_user_key` | string | 注册用户唯一标识键 | 36 |
| `kc_user_id` | string | KeyCloak 中用户的唯一标识键 | - |
| `name` | string | 分销商名称 | 最多255 |
| `document_number` | string | 分销商 CPF/CNPJ | 14或18 |
| `phone` | JSON | **[Phone](#phone)** 对象 | - |

### Investor Analysis Status
| 枚举值 | 描述 |
|--------------------------|-----------------------------|
| `pending_registry_data` | 待注册数据 |
| `pending_documents` | 待文件 |
| `sent_to_analysis` | 已发送分析 |
| `in_manual_analysis` | 人工分析中 |
| `approved` | 已批准 |
| `reproved` | 已拒绝 |

### Document Batch Status
| 枚举值 | 描述 |
|--------------------------|-----------------------------|
| `creating_documents` | 创建文件中 |
| `send_to_signature` | 已发送签署 |
| `pending_signature` | 待签署 |

### Document Type
| 枚举值 | 描述 |
|--------------------------------|----------------------------------------|
| `cnh` | CNH |
| `rg` | RG |
| `rg_back` | RG - 背面 |
| `rg_front` | RG - 正面 |
| `proof_of_residence` | 居住证明 |
| `cnpj_card` | CNPJ 卡 |
| `financial_statements` | 财务报表 |
| `power_of_attorney` | 授权书 |
| `billing_statement` | 收入证明 |
| `social_contract` | 章程合同 |
| `qualified_investor_term` | 合格投资者声明 |
| `professional_investor_term` | 专业投资者声明 |
| `natural_person_registry_form` | 注册表 - 自然人 |
| `legal_person_registry_form` | 注册表 - 法人 |

### Investor Document Status
| 枚举值 | 描述 |
|--------------------|----------------------------------------|
| `sent_to_generate` | 已发送生成 |
| `generated` | 已生成 |

### Status Event 
| 字段 | 类型 | 描述 | 字符数 |
|------------------- |----------|------------------------------------------------------------|------------|
| `status` | string | Investor Status 枚举值 | - |
| `event_datetime` | string | 状态更新执行的日期和时间 | - |

---

# 发送已签署文件

URL: /zh-Hans/documentation/iaas/investidor/compartilhado/buscar_documentos_para_assinatura

---
### 简介
本资源旨在向我们发送与**注册分析**已批准的**投资者**注册正式化相关的**文件**签署证明。文件有3种类型：**注册表**、**合格投资者声明**和**专业投资者声明**。

### 输入/输出：
作为***输入***，需发送**文件类型**、**签署类型**以及根据签署方式所需的验证内容。请参见以下示例。

作为***输出***，将返回 ***investor_document_key***。***investor_document_key*** 用于标识已发送的**文件**。

### Request

ENDPOINT `/investor_registry/v2/investor/{investor_key}/investor_analysis/{investor_analysis_key}/document_batch`
MÉTODO `GET`
STATUS `200`

### 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": "professional_investor_term",
      "status": "generated",
      "signature_method": "certifiqi"
    },
    {
      "investor_document_key": "UUID",
      "document_type": "legal_person_registry_form",
      "status": "generated",
      "signature_method": "certifiqi"
    }
  ]
}
```

---

# Consultar Análise em Andamento

URL: /zh-Hans/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**.

---

# 添加银行账户

URL: /zh-Hans/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
| 字段                             | 类型     | 描述                                                                    | 字符数   | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `financial_institution_code`                            | string   | 金融机构代码                                                           |   1  - 4   |    是      |
| `account_number`                 | string   | 账号                                                                  |   1 - 20    |    是      |
| `account_digit`                     | string   | 账号校验位                                |      1       |    是      |
| `account_branch`                           | string   | 支行号                                                                       |   1  - 4   |    是      |

### Response
```json title='Response Body'
{
    "bank_account_key": "UUID"
}
```

### 可处理错误
| 错误代码                             | 含义     |
|------------------------------------|-----------------|
"IVR000077" | 该账户已为该投资者注册 |

---

# 更新银行账户

URL: /zh-Hans/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 注意
    更新银行账户有三种方式：
- 将 *status* 更新为 inactive ，停用该账户。
- 将 *status* 更新为 active ，重新激活该账户。
- 使用 *main_account* 属性更新主账户设置，将该账户设为投资者的主账户。

    如果同时发送两个参数，将返回错误。
:::

### Body params
| 字段                             | 类型     | 描述                                                                    | 字符数   | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `status`                            | string   | 账户新状态                                                           |   1 - 20   |    否      |
| `main_account`                            | bool   | 设置该账户是否为投资者的主账户 |   -   |    否      |

---

# Atualizar Status da Conta Bancária

URL: /zh-Hans/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.

---

# 查询银行账户

URL: /zh-Hans/documentation/iaas/investidor/compartilhado/contas_bancarias/buscar_contas_bancarias

---

### Request

ENDPOINT /investor/investor/INVESTOR_KEY/bank_accounts
MÉTODO GET
STATUS 200

### Query params
| 字段                             | 类型     | 描述                                                                    | 选项   | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `status`                            | string   | 账户新状态                                                           |   "active" 或 "inactive"   |    否      |
| `main_account`                            | bool   | 设置该账户是否为投资者的主账户 |   True 或 False   |    否      |

### 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: /zh-Hans/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: /zh-Hans/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á retornada a conta criada, incluindo a chave `bank_account_key` gerada.

### 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
A conta bancária criada é retornada no corpo, incluindo `external_bank_account_key` e `status`.

---

# Criar investidor

URL: /zh-Hans/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).

Existem 3 tipos principais de investidor, definidos pelo campo **`person_type`**: **pessoa física** (`natural_person`) e **pessoa jurídica** (`legal_person`). 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.

:::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",
    "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 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` e `registry_user`
:::

:::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`)                                       |   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)                           |

### Response
```json title='Response Body'
{
    "investor_key": "UUID",
    "investor_analysis_key": "UUID"
}
```

---

# Definir Grupo de Assinantes Padrão

URL: /zh-Hans/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.

---

# 发送投资者注册进行分析

URL: /zh-Hans/documentation/iaas/investidor/compartilhado/enviar_cadastro_para_analise

---
### 简介
本资源旨在将已在**发送注册数据**步骤中填写数据的**注册分析**发送进行验证。

:::warning 注意
**注册分析**以异步方式进行。建议集成接收我们发送的 ***webhooks*** 以更新*状态*变化。
:::

### 输入/输出：
本资源没有作为***输入***的请求体。只需按以下描述的格式发送请求。

作为***输出***，将返回 ***investor_analysis_key***。***investor_analysis_key*** 用于标识已更新的**注册分析**。

### Request

ENDPOINT `/investor_registry/v2/investor/{investor_analysis_key}/investor_analysis/{investor_analysis_key}/submit`
MÉTODO `PUT`
STATUS `202`

### Response
```json title='Response Body'
{
    "investor_analysis_key": "UUID"
}
```

---

# 发送投资者注册数据

URL: /zh-Hans/documentation/iaas/investidor/compartilhado/enviar_dados_cadastrais

---
### 简介
本资源旨在向我们提供与人员类型相关的注册数据，这些数据将构成投资者的**注册分析**。

### 输入/输出：
作为***输入***，需根据投资者类型（`natural_person` 或 `legal_person`）发送相应的注册数据。

作为***输出***，将返回 ***investor_key*** 和 ***investor_analysis_key***。

### Request

ENDPOINT `/investor_registry/v2/investor/{investor_key}/investor_analysis/{investor_analysis_key}/registry_data`
MÉTODO `PUT`
STATUS `202`

### Request body

示例：发送自然人注册数据

```json title='Request Body'
{
    "name": "João da Silva",
    "email": "joao.silva@example.com",
    "phone": {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "1234567890"
    },
    "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"
        }
    }
}
```

示例：发送法人注册数据

```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"
    }
}
```

### Body params
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `name` | string | 投资者姓名 | 1-255 | 是 |
| `email` | string | 投资者电子邮件 | 1-255 | 是 |
| `phone` | object | **[Phone](#phone)** 对象 | - | 是 |
| `natural_person` | object | **[Natural Person](#natural-person)** 对象（自然人必填） | - | 是* |
| `legal_person` | object | **[Legal Person](#legal-person)** 对象（法人必填） | - | 是* |

\* 当 `person_type` 为 `natural_person` 时，`natural_person` 为必填。当 `person_type` 为 `legal_person` 时，`legal_person` 为必填。

### Natural Person {#natural-person}
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `birthdate` | string | 出生日期（格式：YYYY-MM-DD） | 10 | 是 |
| `gender` | string | 性别。**[Gender](#gender)** 枚举值 | 1-6 | 否 |
| `mother_name` | string | 母亲全名 | 1-255 | 是 |
| `nationality` | string | 国籍 | 1-255 | 是 |
| `place_of_birth` | object | **[Place of Birth](#place-of-birth)** 对象 | - | 是 |
| `marital_status` | string | 婚姻状态 | 1-255 | 是 |
| `spouse` | object | **[Spouse](#spouse)** 对象 | - | 否 |
| `profession` | string | 职业 | 1-255 | 是 |
| `occupation` | string | 职位 | 1-255 | 是 |
| `occupation_company` | object | **[Occupation Company](#occupation-company)** 对象 | - | 否 |

### Gender {#gender}
| 枚举值 | 描述 |
|-----------------------------------|------------------------------------------------------------------------------|
| `male` | 男 |
| `female` | 女 |

### Place of Birth {#place-of-birth}
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `country` | string | 国家 | - | 否 |
| `uf` | string | 州 (UF) | - | 否 |
| `city` | string | 城市 | - | 否 |

### Spouse {#spouse}
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `name` | string | 配偶全名 | 1-255 | 是 |
| `document_number` | string | 配偶 CPF 或 CNPJ | 14 | 是 |

### Occupation Company {#occupation-company}
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `name` | string | 公司名称 | 1-255 | 是 |
| `document_number` | string | 公司 CNPJ | 18 | 是 |

### Legal Person {#legal-person}
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `legal_name` | string | 公司注册名称 | 1-255 | 是 |
| `constitution_date` | string | 公司成立日期（格式：YYYY-MM-DD） | 10 | 是 |

### Phone {#phone}
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `international_dial_code` | string | 国际区号 | 1-3 | 是 |
| `area_code` | string | 地区区号 | 2 | 是 |
| `number` | string | 电话号码 | 8-9 | 是 |

### Response
```json title='Response Body'
{
    "investor_key": "UUID",
    "investor_analysis_key": "UUID"
}
```

---

---

# Enviar Documento Assinado

URL: /zh-Hans/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"
}
```

---

# 发送投资者注册数据

URL: /zh-Hans/documentation/iaas/investidor/compartilhado/enviar_endereco

---
### 简介
本资源旨在向我们提供构成投资者**注册分析**的注册数据。

### 输入/输出：
注册数据根据**创建投资者**步骤中传递的数据有所变化。以下是每种变体应发送的数据示例。

作为***输出***，将返回 ***investor_key*** 和 ***investor_analysis_key***。***investor_analysis_key*** 用于标识已更新的**注册分析**。
***investor_key*** 用于标识**注册分析**所属的**投资者**。

### Request

ENDPOINT `/investor_registry/v2/investor/{investor_key}/investor_analysis/{investor_analysis_key}/address`
MÉTODO `PUT`
STATUS `202`

示例

```json title='Request Body'
{
        "street": "Sample",
        "number": "000",
        "neighborhood": "Sample",
        "city": "Sample",
        "postal_code": "00000-000",
        "uf": "SP",
        "country": "BRA",
        "complement": "sample",
    }
```

### Body Params
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `street` | string | 街道 | 1-255 | 是 |
| `number` | string | 门牌号 | 1-10 | 是 |
| `neighborhood` | string | 社区 | 1-255 | 是 |
| `city` | string | 城市 | 1-255 | 是 |
| `postal_code` | string | 邮政编码 | 9 | 是 |
| `uf` | string | 州。例如：SP / CE / MG | 2 | 是 |
| `country` | string | 国家。例如：BRA / EUA / ARG | 3 | 是 |
| `complement` | string | 补充信息 | 1-255 | 否 |

### Response
```json title='Response Body'
{
    "investor_key": "UUID",
    "investor_analysis_key": "UUID"
}
```

---

# Enviar Grupo de Assinantes

URL: /zh-Hans/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.
:::

### 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: /zh-Hans/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.
:::

### 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, com sua `document_key` (também referida como `external_investor_analysis_document_key`).

### 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}
| Enumerador                     | Descrição                                            | Extensões      |
|--------------------------------|------------------------------------------------------|----------------|
| `cnh`                          | CNH                                                  | `pdf`, `jpeg`  |
| `rg`                           | RG (frente e verso em arquivo único)                 | `pdf`, `jpeg`  |
| `rg_front`                     | RG — frente                                          | `pdf`, `jpeg`  |
| `rg_back`                      | RG — verso                                           | `pdf`, `jpeg`  |
| `proof_of_residence`           | Comprovante de residência                            | `pdf`, `jpeg`  |
| `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`  |
| `investor_qualification_proof` | Comprovação de qualificação                          | `pdf`, `jpeg`  |
| `power_of_attorney`            | Procuração                                           | `pdf`, `jpeg`  |
| `billing_statement`            | Fatura / extrato                                     | `pdf`, `jpeg`  |
| `fund_prospectus`              | Regulamento do fundo de investimento                 | `pdf`, `jpeg`  |

### Documentos Obrigatórios

#### Pessoa Física (`natural_person`)
| Documento                                  | Descrição                          |
|--------------------------------------------|------------------------------------|
| `cnh` ou (`rg_front` + `rg_back`) ou `rg`  | Documento de identificação         |
| `proof_of_residence`                       | Comprovante de residência          |

#### Pessoa Jurídica regular (`legal_person` / `investor_sub_type: default`)
| Documento                       | Quando enviar                                |
|---------------------------------|----------------------------------------------|
| `financial_statements`          | Todos                                        |
| `social_contract`               | Quando aplicável                             |
| `company_statute`               | Quando aplicável                             |
| `board_election_record`         | Quando aplicável                             |
| `investor_qualification_proof`  | Investidor qualificado / profissional        |

#### Pessoa Jurídica — Fundo de Investimento (`investor_sub_type: fund_class`)
| Documento                | Descrição                                           |
|--------------------------|-----------------------------------------------------|
| `cnpj_card`              | Cartão CNPJ do fundo                                |
| `financial_statements`   | Demonstrações financeiras                           |
| `fund_prospectus`        | Regulamento do fundo                                |

### Response
O documento criado é retornado no corpo da resposta, incluindo a chave `document_key` (também referenciada como `external_investor_analysis_document_key`) e o `status` inicial (`valid`, `invalid` ou `in_manual_analysis`).

---

# Enviar Patrimônio do Investidor

URL: /zh-Hans/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 Investidor `fund_class`
Para fundos de investimento, o patrimônio é calculado **automaticamente** a partir dos dados públicos da CVM ao enviar a análise para validação. O envio desta etapa não é necessário para esse subtipo.
:::

### 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: /zh-Hans/documentation/iaas/investidor/compartilhado/feedback/consultar_feedback

---
### Introdução
Este recurso retorna a representação detalhada de um único **feedback** identificado por `feedback_key`.

### Request

ENDPOINT `/investor_registry/investor/{investor_key}/feedback/{feedback_key}`
MÉTODO `GET`
STATUS `200`

### Response

```json
{
  "feedback_key": "UUID",
  "status": "open",
  "origin_type": "investor_analysis_document",
  "origin_key": "UUID",
  "messages": [
    {
      "message": "Por favor, reenvie o comprovante de residência.",
      "sender_type": "backoffice",
      "created_at": "2025-04-29T12:07:55Z"
    },
    {
      "message": "Comprovante reenviado.",
      "sender_type": "agent",
      "created_at": "2025-04-29T15:10:00Z"
    }
  ]
}
```

---

# Enviar Mensagem em Feedback

URL: /zh-Hans/documentation/iaas/investidor/compartilhado/feedback/enviar_mensagem_feedback

---
### Introdução
Este recurso adiciona uma nova **mensagem** a um feedback existente — ou cria o feedback caso ele ainda não exista para a entidade de origem informada (`origin_type` + `origin_key`).

### Request

ENDPOINT `/investor_registry/investor/{investor_key}/feedback/{feedback_key}/message`
MÉTODO `PUT`
STATUS `201`

### Request body
```json title='Request Body'
{
    "message": "Estamos providenciando o documento solicitado.",
    "origin_type": "investor_analysis_document",
    "origin_key": "UUID"
}
```

### Body params
| Campo         | Tipo   | Descrição                                                                  | Caracteres | Obrigatório |
|---------------|--------|----------------------------------------------------------------------------|------------|-------------|
| `message`     | string | Conteúdo da mensagem                                                       |  1 - 1000  |    Sim      |
| `origin_type` | string | Tipo da entidade à qual o feedback se refere                               |   1 - 50   |    Sim      |
| `origin_key`  | string | Chave da entidade de origem (UUID)                                         |     36     |    Sim      |

### Response
O feedback atualizado é retornado no corpo da resposta.

---

# Listar Feedbacks

URL: /zh-Hans/documentation/iaas/investidor/compartilhado/feedback/listar_feedbacks

---
### Introdução
Este recurso lista os **feedbacks** trocados em torno de uma entidade da análise cadastral. Feedbacks são utilizados para comunicação assíncrona com o backoffice (ex.: pendências de documento, comentários do compliance).

### Request

ENDPOINT `/investor_registry/investor/{investor_key}/feedbacks`
MÉTODO `GET`
STATUS `200`

### Query params
| Campo         | Tipo    | Descrição                                                                                  | Obrigatório |
|---------------|---------|--------------------------------------------------------------------------------------------|-------------|
| `origin_type` | string  | Tipo da entidade de origem (ex.: `investor_analysis`, `investor_analysis_document`)        |    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      |

### Response

```json
{
  "data": [
    {
      "feedback_key": "UUID",
      "status": "open",
      "messages": [
        {
          "message": "Por favor, reenvie o comprovante de residência com data atualizada.",
          "sender_type": "backoffice",
          "created_at": "2025-04-29T12:07:55Z"
        }
      ],
      "origin_type": "investor_analysis_document",
      "origin_key": "UUID"
    }
  ],
  "page": 0,
  "limit": 100,
  "is_last_page": true
}
```

---

# Criar Investor Owner

URL: /zh-Hans/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: /zh-Hans/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.

---

# 创建关联方

URL: /zh-Hans/documentation/iaas/investidor/compartilhado/related_party/criar_parte_relacionada

---

### 简介
本资源旨在识别与法人投资者相关的最终受益人（自然人）和控制人，如合伙人、董事、管理员等。

:::warning 注意
- 必须创建**至少一个**关联方
- **至少一个**关联方必须具有 `legal_representative: true`
- 对于法人关联方，`related_party_type` 必须为 `parent_company`
- 此端点需多次调用，每个关联方调用一次
:::

:::info 关于最终受益人
*最终受益人是最终行使公司控制权或重大影响力的自然人，特别是直接或间接持有15%或以上股份、担任管理职位或代表公司履行法律目的的人。*

*请提供直接或间接持有15%或以上股权的自然人及管理员的数据。如果没有合伙人/股东单独持有等于或超过15%的股份，则请发送持有最大百分比股份的3位控制人的信息。*
:::

### 输入/输出：
作为***输入***，需发送关联方数据。

作为***输出***，将返回 ***related_party_key*** 和所创建关联方的详情。

### Request

ENDPOINT `/investor_registry/v2/investor/{investor_key}/investor_analysis/{investor_analysis_key}/related_party`
MÉTODO `POST`
STATUS `201`

### 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,
    "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"
    }
}
```

示例：母公司（法人）

```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
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `name` | string | 关联方姓名 | 1 - 255 | 是 |
| `document_number` | string | CPF 或 CNPJ | 1 - 18 | 是 |
| `person_type` | string | **[Person Type](#person-type-related-party)** 枚举值 | - | 是 |
| `related_party_type` | string | **[Related Party Type](#related-party-type)** 枚举值 | - | 是 |
| `resident` | boolean | 定义是否为巴西居民 | - | 是 |
| `legal_representative` | boolean | 定义是否为法定代表人 | - | 是 |
| `direct_beneficiary` | boolean | 定义是否为直接受益人 | - | 是 |
| `address` | object | **[Address](#address)** 对象 | - | 是 |
| `participation_percentage` | number | 持股比例（0 到 1） | - | 是 |
| `email` | string | 电子邮件 | 1 - 100 | 否 |
| `phone` | object | **[Phone](#phone)** 对象 | - | 否 |
| `monthly_income` | number | 月收入 | - | 否 |
| `expiration_date` | string | 过期日期（格式：YYYY-MM-DD） | 10 | 否 |

### Person Type (Related Party) {#person-type-related-party}
| 枚举值 | 描述 |
|-----------------------------------|------------------------------------------------------------------------------|
| `natural_person` | 自然人 |
| `legal_person` | 法人 |

### Related Party Type {#related-party-type}
| 枚举值 | 描述 |
|-----------------------------------|------------------------------------------------------------------------------|
| `president` | 董事长 |
| `partner` | 合伙人 |
| `administrator` | 管理员 |
| `director` | 董事 |
| `manager` | 经理 |
| `attorney` | 代理人 |
| `parent_company` | 母公司（仅限法人） |
| `asset_custodian` | 资产托管人 |

### Address {#address}
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `postal_code` | string | 邮政编码 | 9 | 是 |
| `street` | string | 街道 | 1 - 255 | 否 |
| `number` | string | 门牌号 | 1 - 10 | 否 |
| `neighborhood` | string | 社区 | 1 - 255 | 否 |
| `city` | string | 城市 | 1 - 255 | 否 |
| `uf` | string | 州 | 2 | 否 |
| `country` | string | 国家 | 3 | 否 |
| `complement` | string | 补充信息 | 1 - 255 | 否 |

### Phone {#phone}
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `international_dial_code` | string | 国际区号 | 1 - 3 | 是 |
| `area_code` | string | 地区区号 | 2 | 是 |
| `number` | string | 电话号码 | 8 - 9 | 是 |

### 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": {...}
}
```

---

# 发送关联方文件

URL: /zh-Hans/documentation/iaas/investidor/compartilhado/related_party/enviar_documento_parte_relacionada

---

### 简介
本资源旨在上传每个已创建关联方的必要文件。

:::warning 注意
- 此端点需为**每个**已创建且为**自然人**的关联方调用
- 关联方必须处于**"active"**状态才能接收文件
- 对于自然人：必须发送身份证件（cnh 或 rg）
- 对于 attorney（代理人）类型：必须发送 power_of_attorney（授权书）
:::

### 输入/输出：
作为***输入***，需发送 base64 编码的文件、文件类型和文件扩展名。

作为***输出***，将返回标识已发送文件的 ***related_party_document_key***。

### Request

ENDPOINT `/investor_registry/v2/investor/{investor_key}/investor_analysis/{investor_analysis_key}/related_party/{related_party_key}/document`
MÉTODO `POST`
STATUS `201`

### Request body

示例：身份证件 (CNH)

```json title='Request Body'
{
    "type": "cnh",
    "document_b64": "base64_encoded_document_content",
    "file_extension": "pdf"
}
```

示例：RG（正面和背面）

```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"
}
```

示例：授权书（适用于 attorney 类型）

```json title='Request Body'
{
    "type": "power_of_attorney",
    "document_b64": "base64_encoded_document_content",
    "file_extension": "pdf"
}
```

### Body params
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `type` | string | 文件类型 | 1 - 50 | 是 |
| `document_b64` | string | 文件 Base 64 编码 | - | 是 |
| `file_extension` | string | 文件扩展名（pdf、png、jpeg） | 1 - 10 | 是 |

### Document Type (Related Party)
| 枚举值 | 描述 | 支持的扩展名 | 必填对象 |
|-----------------------------------|-----------------------------|-----------------------------|-------------------------------------|
| `cnh` | CNH | pdf, jpeg | 自然人（二选一） |
| `rg` | RG | pdf, jpeg | 自然人（二选一） |
| `rg_back` | RG 背面 | pdf, jpeg | 自然人（与 rg_front 配合） |
| `rg_front` | RG 正面 | pdf, jpeg | 自然人（与 rg_back 配合） |
| `power_of_attorney` | 授权书 | pdf, jpeg | attorney 类型 |

### 必要文件
| 文件 | 描述 | 关联方类型 |
|-----------------------------------|------------------------------------------------------------|-----------------------------------------|
| `cnh` 或 (`rg_front` + `rg_back`) | 身份证件 | 自然人 |
| `power_of_attorney` | 授权书 | attorney 类型 |

### Response
```json title='Response Body'
{
    "related_party_document_key": "UUID",
    "status": "valid | invalid | in_manual_analysis"
}
```

:::info 信息
文件上传后将自动进行验证。状态可能为：
- `valid`：文件有效
- `invalid`：文件无效
- `in_manual_analysis`：人工分析中

对于无效文件，可以使用 `force=true` 参数强制发送。但是，使用此标志时，文件将必然提交进行人工审核。
:::

---

# Consultar Formulário Suitability

URL: /zh-Hans/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: /zh-Hans/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.
:::

### 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: /zh-Hans/documentation/iaas/investidor/distribuicao_externa/assinar_documento



---

# atualizacao_cadastral

URL: /zh-Hans/documentation/iaas/investidor/distribuicao_externa/atualizacao_cadastral



---

# atualizar_status_grupo_assinantes

URL: /zh-Hans/documentation/iaas/investidor/distribuicao_externa/atualizar_status_grupo_assinantes



---

# busca_informacoes_de_uma_analise_cadastral_do_investidor

URL: /zh-Hans/documentation/iaas/investidor/distribuicao_externa/busca_informacoes_de_uma_analise_cadastral_do_investidor



---

# busca_informacoes_do_investidor

URL: /zh-Hans/documentation/iaas/investidor/distribuicao_externa/busca_informacoes_do_investidor



---

# buscar_documentos_para_assinatura

URL: /zh-Hans/documentation/iaas/investidor/distribuicao_externa/buscar_documentos_para_assinatura



---

# consultar_analise_em_andamento

URL: /zh-Hans/documentation/iaas/investidor/distribuicao_externa/consultar_analise_em_andamento



---

# atualizar_status_conta_bancaria

URL: /zh-Hans/documentation/iaas/investidor/distribuicao_externa/contas_bancarias/atualizar_status_conta_bancaria



---

# definir_conta_principal

URL: /zh-Hans/documentation/iaas/investidor/distribuicao_externa/contas_bancarias/definir_conta_principal



---

# enviar_contas_bancarias

URL: /zh-Hans/documentation/iaas/investidor/distribuicao_externa/contas_bancarias/enviar_contas_bancarias



---

# 创建投资者/投资者分析

URL: /zh-Hans/documentation/iaas/investidor/distribuicao_externa/criar_investidor

---

### 简介
本资源旨在向我们提供启动投资者**注册分析**所需的基本数据。
**注册分析**有2种类型：**自然人**和**法人**。法人又有***子类型***，用于区分注册过程中所需的信息。

:::info 信息
在同质化环境中，我们有如下规则：以1开头的 CPF/CNPJ：自动拒绝；以8开头的 CPF/CNPJ：待人工验证；其余自动批准。
:::

### 注册流程

法人投资者注册遵循以下步骤：

1. **创建投资者** - 初始创建投资者和注册分析
2. **发送注册数据** - 法人具体数据
3. **发送地址** - 地址信息
4. **发送净资产** - 净资产数据
5. **发送银行账户** - 银行账户信息
6. **发送适配度** - 适配度问卷（零售投资者必须）
7. **发送签署人组** - 定义签署人组
8. **发送投资者文件** - 上传必要文件
9. **创建关联方** - 注册合伙人、董事、管理员等
10. **发送关联方文件** - 上传关联方文件
11. **发送分析** - 提交注册分析
12. **签署文件** - 批准后签署文件

### 输入/输出：
每种**注册分析**类型需要不同的***输入***数据集，以下是启动每种流程的示例。

作为***输出***，将返回 ***investor_key*** 和 ***investor_analysis_key***。***investor_analysis_key*** 用于标识创建的**注册分析**。
***investor_key*** 用于标识**注册分析**所属的**投资者**。

因此，一个 ***investor_key***（投资者）可以关联一个或多个 ***investor_analysis_key***（注册分析）。

***investor_key*** 和 ***investor_analysis_key*** 都将用于与**投资者**或**注册分析**交互的其他端点。

### Request

ENDPOINT `/investor_registry/v2/investor`
MÉTODO `POST`
STATUS `201`

### Request body
```json title='Request Body'
{
    "name": "string",
    "document_number": "xx.xxx.xxx/xxxx-xx",
    "person_type": "legal_person | natural_person",
    "person_sub_type": "regular | fund_class",
    "external_distribution_key": "campo livre",
    "email": "string",
    "phone": {
	    "international_dial_code": "+xx",
	    "area_code": "xx",
	    "number": "xxxxxxxxxx"
    }
}

```

:::warning 注意
必填字段根据 **person_type** 有所不同。

- 如果是 **natural_person**（自然人）：
    - **name**、**document_number**、**person_type**、**email** 和 **phone** 为必填字段

- 如果是 **legal_person**（法人）：
    - **name**、**document_number**、**person_type** 为必填字段

- 如果是 **nominee**（PCO）：
    - **name**、**person_type**、**external_distribution_key** 为必填字段

:::

:::info 信息
**registry_user** 是代表将填写投资者注册数据的用户的实体。
对于**自然人**，投资者本人填写其注册数据。
:::

情况02：注册法人

```json title='Request Body'
{
  "name": "Fundo XPTO", 
  "document_number": "12.456.789/0001-00", 
  "person_type": "legal_person",
  "person_sub_type": "regular",
  "registry_user": {
    "name": "José da Silva", 
    "document_number": "123.456.789-00",
    "email": "example@example.com",
    "phone": {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "1234567890"
    },
  }
}
```

### Body params
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `name` | string | 投资者姓名 | 1-255 | 是 |
| `document_number` | string | CPF 或 CNPJ | 13-18 | 是 |
| `person_type` | string | **[Person Type](#person_type)** 枚举值 | - | 是 |
| `person_sub_type` | string | **[Person Sub Type](#person_sub_type)** 枚举值 | - | 是 |
| `email` | string | 电子邮件 | 1-255 | 否 |
| `phone` | JSON | **[Phone](#phone)** 对象 | - | 否 |
| `registry_user` | JSON | **[Registry User](#registry_user)** 对象 | - | 否 |

### Phone
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `international_dial_code` | string | 国际区号 | 1-3 | 是 |
| `area_code` | string | 地区区号 | 2 | 是 |
| `number` | string | 电话号码 | 8-9 | 是 |

### Registry User
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `name` | string | 注册用户姓名 | 1-255 | 是 |
| `document_number` | string | CPF | 13 | 是 |
| `person_type` | string | **[Person Type](#person_type)** 枚举值 | - | 是 |
| `email` | string | 电子邮件 | 1-255 | 是 |
| `phone` | JSON | **[Phone](#phone)** 对象 | - | 是 |

### Person Type
| 枚举值 | 描述 |
|-----------------------------------|------------------------------------------------------------------------------|
| `natural_person` | 自然人 |
| `legal_person` | 法人 |

### Person Sub Type
| 枚举值 | 描述 |
|-----------------------------------|------------------------------------------------------------------------------|
| `regular` | - |
| `fund_class` | 投资基金 |

### Response
```json title='Response Body'
{
    "investor_key": "UUID",
    "investor_analysis_key": "UUID"
}
```

---

# definir_grupo_assinantes_padrao

URL: /zh-Hans/documentation/iaas/investidor/distribuicao_externa/definir_grupo_assinantes_padrao



---

# enviar_cadastro_para_analise

URL: /zh-Hans/documentation/iaas/investidor/distribuicao_externa/enviar_cadastro_para_analise



---

# 发送投资者注册数据

URL: /zh-Hans/documentation/iaas/investidor/distribuicao_externa/enviar_dados_cadastrais

---
### 简介
本资源旨在向我们提供与人员类型相关的注册数据，这些数据将构成投资者的**注册分析**。

### 输入/输出：
作为***输入***，需根据投资者类型（`natural_person` 或 `legal_person`）发送相应的注册数据。

作为***输出***，将返回 ***investor_key*** 和 ***investor_analysis_key***。

### Request

ENDPOINT `/investor_registry/v2/investor/{investor_key}/investor_analysis/{investor_analysis_key}/registry_data`
MÉTODO `PUT`
STATUS `202`

### Request body

示例：发送自然人注册数据

```json title='Request Body'
{
    "name": "João da Silva",
    "email": "joao.silva@example.com",
    "phone": {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "1234567890"
    },
    "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"
        }
    }
}
```

示例：发送法人注册数据

```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"
    }
}
```

### Body params
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `name` | string | 投资者姓名 | 1-255 | 是 |
| `email` | string | 投资者电子邮件 | 1-255 | 是 |
| `phone` | object | **[Phone](#phone)** 对象 | - | 是 |
| `natural_person` | object | **[Natural Person](#natural-person)** 对象（自然人必填） | - | 是* |
| `legal_person` | object | **[Legal Person](#legal-person)** 对象（法人必填） | - | 是* |

\* 当 `person_type` 为 `natural_person` 时，`natural_person` 为必填。当 `person_type` 为 `legal_person` 时，`legal_person` 为必填。

### Natural Person {#natural-person}
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `birthdate` | string | 出生日期（格式：YYYY-MM-DD） | 10 | 是 |
| `gender` | string | 性别。**[Gender](#gender)** 枚举值 | 1-6 | 否 |
| `mother_name` | string | 母亲全名 | 1-255 | 是 |
| `nationality` | string | 国籍 | 1-255 | 是 |
| `place_of_birth` | object | **[Place of Birth](#place-of-birth)** 对象 | - | 是 |
| `marital_status` | string | 婚姻状态 | 1-255 | 是 |
| `spouse` | object | **[Spouse](#spouse)** 对象 | - | 否 |
| `profession` | string | 职业 | 1-255 | 是 |
| `occupation` | string | 职位 | 1-255 | 是 |
| `occupation_company` | object | **[Occupation Company](#occupation-company)** 对象 | - | 否 |

### Gender {#gender}
| 枚举值 | 描述 |
|-----------------------------------|------------------------------------------------------------------------------|
| `male` | 男 |
| `female` | 女 |

### Place of Birth {#place-of-birth}
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `country` | string | 国家 | - | 否 |
| `uf` | string | 州 (UF) | - | 否 |
| `city` | string | 城市 | - | 否 |

### Spouse {#spouse}
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `name` | string | 配偶全名 | 1-255 | 是 |
| `document_number` | string | 配偶 CPF 或 CNPJ | 14 | 是 |

### Occupation Company {#occupation-company}
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `name` | string | 公司名称 | 1-255 | 是 |
| `document_number` | string | 公司 CNPJ | 18 | 是 |

### Legal Person {#legal-person}
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `legal_name` | string | 公司注册名称 | 1-255 | 是 |
| `constitution_date` | string | 公司成立日期（格式：YYYY-MM-DD） | 10 | 是 |

### Phone {#phone}
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `international_dial_code` | string | 国际区号 | 1-3 | 是 |
| `area_code` | string | 地区区号 | 2 | 是 |
| `number` | string | 电话号码 | 8-9 | 是 |

### Response
```json title='Response Body'
{
    "investor_key": "UUID",
    "investor_analysis_key": "UUID"
}
```

---

---

# enviar_documento_assinado

URL: /zh-Hans/documentation/iaas/investidor/distribuicao_externa/enviar_documento_assinado



---

# enviar_endereco

URL: /zh-Hans/documentation/iaas/investidor/distribuicao_externa/enviar_endereco



---

# enviar_grupos_assinantes

URL: /zh-Hans/documentation/iaas/investidor/distribuicao_externa/enviar_grupos_assinantes



---

# 发送投资者文件

URL: /zh-Hans/documentation/iaas/investidor/distribuicao_externa/enviar_investor_document

---

### 简介
本资源旨在上传投资者的必要文件。

### 输入/输出：
作为***输入***，需发送 base64 编码的文件、文件类型和文件扩展名。

作为***输出***，将返回标识已发送文件的 ***document_key***。

:::warning 注意
此端点需多次调用，每个必要文件调用一次。必要文件根据投资者类型（自然人或法人）以及投资者类别（零售、合格或专业）而有所不同。
:::

### Request

ENDPOINT `/investor_registry/v2/investor/{investor_key}/investor_analysis/{investor_analysis_key}/document`
MÉTODO `POST`
STATUS `201`

### Request body

示例：身份证件 - 自然人 (CNH)

```json title='Request Body'
{
    "type": "cnh",
    "document_b64": "base64_encoded_document_content",
    "file_extension": "pdf",
    "document_data": {
        "document_type": "CNH",
        "issuer_entity": "DETRAN"
    }
}
```

示例：身份证件 - 自然人 (RG)

```json title='Request Body - Frente'
{
    "type": "rg_front",
    "document_b64": "base64_encoded_document_content",
    "file_extension": "pdf",
    "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": "pdf"
}
```

示例：CNPJ 卡 - 法人

```json title='Request Body'
{
    "type": "cnpj_card",
    "document_b64": "base64_encoded_document_content",
    "file_extension": "pdf",
    "document_data": {
        "document_type": "CNPJ",
        "issuer_entity": "RFB"
    }
}
```

示例：财务报表 - 法人

```json title='Request Body'
{
    "type": "financial_statements",
    "document_b64": "base64_encoded_document_content",
    "file_extension": "pdf"
}
```

示例：居住证明

```json title='Request Body'
{
    "type": "proof_of_residence",
    "document_b64": "base64_encoded_document_content",
    "file_extension": "pdf"
}
```

### Body params
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `type` | string | 身份证件类型 | 1-50 | 是 |
| `document_b64` | string | 文件 Base 64 编码 | - | 是 |
| `file_extension` | string | 文件扩展名（pdf、png、jpeg） | 1-10 | 是 |
| `document_data` | object | 包含文件识别信息的对象 | - | 否 |

### Document Type {#document-type}
| 枚举值 | 描述 | 支持的扩展名 |
|-----------------------------------|------------------------------------------------------------------------------|-----------------------------|
| `cnh` | CNH | pdf, jpeg |
| `rg` | RG | pdf, jpeg |
| `rg_back` | RG 背面 | pdf, jpeg |
| `rg_front` | RG 正面 | pdf, jpeg |
| `proof_of_residence` | 居住证明 | pdf, jpeg |
| `cnpj_card` | CNPJ 卡 | pdf, jpeg |
| `social_contract` | 章程合同 | pdf, jpeg |
| `company_statute` | 公司章程 | pdf, jpeg |
| `board_election_record` | 董事选举记录 | pdf, jpeg |
| `financial_statements` | 财务报表 | pdf, jpeg |
| `investor_qualification_proof` | 资质证明 | pdf, jpeg |
| `power_of_attorney` | 授权书 | pdf, jpeg |
| `billing_statement` | 账单/对账单 | pdf, jpeg |
| `fund_prospectus` | 投资基金章程 | pdf, jpeg |

### 必要文件

#### 自然人 (Natural Person)
| 文件 | 描述 | 必填对象 |
|-----------------------------------|------------------------------------------------------------------------------|-------------------------------------|
| `cnh` 或 (`rg_front` + `rg_back`) 或 `rg` | 投资者身份证件 | 所有自然人投资者 |
| `proof_of_residence` | 居住证明 | 所有自然人投资者 |

#### 法人 - 普通 (Legal Person - Regular)
| 文件 | 描述 | 必填对象 |
|-----------------------------------|------------------------------------------------------------------------------|-------------------------------------|
| `financial_statements` | 公司财务报表 | 所有 |
| `social_contract` | 公司章程合同 | 适用时 |
| `company_statute` | 公司章程 | 适用时 |
| `board_of_election_records` | 选举记录 | 适用时 |
| `investor_qualification_proof` | 合格投资者资质证明 | 合格投资者 |

#### 法人 - 投资基金 (Legal Person - Fund Class)
| 文件 | 描述 | 必填对象 |
|-----------------------------------|------------------------------------------------------------------------------|-------------------------------------|
| `cnpj_card` | 证明基金存在的文件 | 所有 |
| `financial_statements` | 财务报表 | 所有 |
| `fund_prospectus` | 投资基金章程 | 所有 |

### Response
```json title='Response Body'
{
    "document_key": "UUID"
}
```

---

# enviar_patrimonio

URL: /zh-Hans/documentation/iaas/investidor/distribuicao_externa/enviar_patrimonio



---

# Enviar Resposta Suitability

URL: /zh-Hans/documentation/iaas/investidor/distribuicao_externa/enviar_suitability

---
### Introdução
Este recurso tem como objetivo enviar a categoria suitability definida para o 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.
:::

### Request

ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/suitability`
MÉTODO `PUT`
STATUS `202`

Exemplo

```json title='Request Body'
{
   "profile": "bold"
}
```

### Body Params
| Campo               | Tipo     | Descrição                                            | Caracteres   | Obrigatório |
|---------------------|----------|------------------------------------------------------|--------------|-------------|
| `profile`              | string   | **[categoria suitability cadastrador](#profile)**                          |   1 - 255    |    Sim      |

### Profile {#profile}
| Enumerador          | Descrição                                            |
|---------------------|------------------------------------------------------|
| `bold`    | Arrojado                                        |
| `moderate`      | Moderado                                      |
| `conservative`           | Conservador            |

### Response
A análise cadastral atualizada é retornada no corpo da resposta.

---

# consultar_feedback

URL: /zh-Hans/documentation/iaas/investidor/distribuicao_externa/feedback/consultar_feedback



---

# enviar_mensagem_feedback

URL: /zh-Hans/documentation/iaas/investidor/distribuicao_externa/feedback/enviar_mensagem_feedback



---

# listar_feedbacks

URL: /zh-Hans/documentation/iaas/investidor/distribuicao_externa/feedback/listar_feedbacks



---

# Introdução

URL: /zh-Hans/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: /zh-Hans/documentation/iaas/investidor/distribuicao_externa/investor_owner/criar_investor_owner



---

# enviar_documento_investor_owner

URL: /zh-Hans/documentation/iaas/investidor/distribuicao_externa/investor_owner/enviar_documento_investor_owner



---

# criar_parte_relacionada

URL: /zh-Hans/documentation/iaas/investidor/distribuicao_externa/related_party/criar_parte_relacionada



---

# enviar_documento_parte_relacionada

URL: /zh-Hans/documentation/iaas/investidor/distribuicao_externa/related_party/enviar_documento_parte_relacionada



---

# atualizacao_cadastral

URL: /zh-Hans/documentation/iaas/investidor/fundo_de_investimento/atualizacao_cadastral



---

# busca_informacoes_de_uma_analise_cadastral_do_investidor

URL: /zh-Hans/documentation/iaas/investidor/fundo_de_investimento/busca_informacoes_de_uma_analise_cadastral_do_investidor



---

# busca_informacoes_do_investidor

URL: /zh-Hans/documentation/iaas/investidor/fundo_de_investimento/busca_informacoes_do_investidor



---

# buscar_documentos_para_assinatura

URL: /zh-Hans/documentation/iaas/investidor/fundo_de_investimento/buscar_documentos_para_assinatura



---

# atualizar_status_conta_bancaria

URL: /zh-Hans/documentation/iaas/investidor/fundo_de_investimento/contas_bancarias/atualizar_status_conta_bancaria



---

# definir_conta_principal

URL: /zh-Hans/documentation/iaas/investidor/fundo_de_investimento/contas_bancarias/definir_conta_principal



---

# enviar_contas_bancarias

URL: /zh-Hans/documentation/iaas/investidor/fundo_de_investimento/contas_bancarias/enviar_contas_bancarias



---

# 创建投资者/投资者分析

URL: /zh-Hans/documentation/iaas/investidor/fundo_de_investimento/criar_investidor

---

### 简介
本资源旨在向我们提供启动投资者**注册分析**所需的基本数据。
**注册分析**有2种类型：**自然人**和**法人**。法人又有***子类型***，用于区分注册过程中所需的信息。

:::info 信息
在同质化环境中，我们有如下规则：以1开头的 CPF/CNPJ：自动拒绝；以8开头的 CPF/CNPJ：待人工验证；其余自动批准。
:::

### 注册流程

法人投资者注册遵循以下步骤：

1. **创建投资者** - 初始创建投资者和注册分析
2. **发送注册数据** - 法人具体数据
3. **发送地址** - 地址信息
4. **发送净资产** - 净资产数据
5. **发送银行账户** - 银行账户信息
6. **发送适配度** - 适配度问卷（零售投资者必须）
7. **发送签署人组** - 定义签署人组
8. **发送投资者文件** - 上传必要文件
9. **创建关联方** - 注册合伙人、董事、管理员等
10. **发送关联方文件** - 上传关联方文件
11. **发送分析** - 提交注册分析
12. **签署文件** - 批准后签署文件

### 输入/输出：
每种**注册分析**类型需要不同的***输入***数据集，以下是启动每种流程的示例。

作为***输出***，将返回 ***investor_key*** 和 ***investor_analysis_key***。***investor_analysis_key*** 用于标识创建的**注册分析**。
***investor_key*** 用于标识**注册分析**所属的**投资者**。

因此，一个 ***investor_key***（投资者）可以关联一个或多个 ***investor_analysis_key***（注册分析）。

***investor_key*** 和 ***investor_analysis_key*** 都将用于与**投资者**或**注册分析**交互的其他端点。

### Request

ENDPOINT `/investor_registry/v2/investor`
MÉTODO `POST`
STATUS `201`

### Request body
```json title='Request Body'
{
    "name": "string",
    "document_number": "xx.xxx.xxx/xxxx-xx",
    "person_type": "legal_person | natural_person",
    "person_sub_type": "regular | fund_class",
    "external_distribution_key": "campo livre",
    "email": "string",
    "phone": {
	    "international_dial_code": "+xx",
	    "area_code": "xx",
	    "number": "xxxxxxxxxx"
    }
}

```

:::warning 注意
必填字段根据 **person_type** 有所不同。

- 如果是 **natural_person**（自然人）：
    - **name**、**document_number**、**person_type**、**email** 和 **phone** 为必填字段

- 如果是 **legal_person**（法人）：
    - **name**、**document_number**、**person_type** 为必填字段

- 如果是 **nominee**（PCO）：
    - **name**、**person_type**、**external_distribution_key** 为必填字段

:::

:::info 信息
**registry_user** 是代表将填写投资者注册数据的用户的实体。
对于**自然人**，投资者本人填写其注册数据。
:::

情况02：注册法人

```json title='Request Body'
{
  "name": "Fundo XPTO", 
  "document_number": "12.456.789/0001-00", 
  "person_type": "legal_person",
  "person_sub_type": "regular",
  "registry_user": {
    "name": "José da Silva", 
    "document_number": "123.456.789-00",
    "email": "example@example.com",
    "phone": {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "1234567890"
    },
  }
}
```

### Body params
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `name` | string | 投资者姓名 | 1-255 | 是 |
| `document_number` | string | CPF 或 CNPJ | 13-18 | 是 |
| `person_type` | string | **[Person Type](#person_type)** 枚举值 | - | 是 |
| `person_sub_type` | string | **[Person Sub Type](#person_sub_type)** 枚举值 | - | 是 |
| `email` | string | 电子邮件 | 1-255 | 否 |
| `phone` | JSON | **[Phone](#phone)** 对象 | - | 否 |
| `registry_user` | JSON | **[Registry User](#registry_user)** 对象 | - | 否 |

### Phone
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `international_dial_code` | string | 国际区号 | 1-3 | 是 |
| `area_code` | string | 地区区号 | 2 | 是 |
| `number` | string | 电话号码 | 8-9 | 是 |

### Registry User
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `name` | string | 注册用户姓名 | 1-255 | 是 |
| `document_number` | string | CPF | 13 | 是 |
| `person_type` | string | **[Person Type](#person_type)** 枚举值 | - | 是 |
| `email` | string | 电子邮件 | 1-255 | 是 |
| `phone` | JSON | **[Phone](#phone)** 对象 | - | 是 |

### Person Type
| 枚举值 | 描述 |
|-----------------------------------|------------------------------------------------------------------------------|
| `natural_person` | 自然人 |
| `legal_person` | 法人 |

### Person Sub Type
| 枚举值 | 描述 |
|-----------------------------------|------------------------------------------------------------------------------|
| `regular` | - |
| `fund_class` | 投资基金 |

### Response
```json title='Response Body'
{
    "investor_key": "UUID",
    "investor_analysis_key": "UUID"
}
```

---

# enviar_cadastro_para_analise

URL: /zh-Hans/documentation/iaas/investidor/fundo_de_investimento/enviar_cadastro_para_analise



---

# 发送投资者注册数据

URL: /zh-Hans/documentation/iaas/investidor/fundo_de_investimento/enviar_dados_cadastrais

---
### 简介
本资源旨在向我们提供与人员类型相关的注册数据，这些数据将构成投资者的**注册分析**。

### 输入/输出：
作为***输入***，需根据投资者类型（`natural_person` 或 `legal_person`）发送相应的注册数据。

作为***输出***，将返回 ***investor_key*** 和 ***investor_analysis_key***。

### Request

ENDPOINT `/investor_registry/v2/investor/{investor_key}/investor_analysis/{investor_analysis_key}/registry_data`
MÉTODO `PUT`
STATUS `202`

### Request body

示例：发送自然人注册数据

```json title='Request Body'
{
    "name": "João da Silva",
    "email": "joao.silva@example.com",
    "phone": {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "1234567890"
    },
    "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"
        }
    }
}
```

示例：发送法人注册数据

```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"
    }
}
```

### Body params
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `name` | string | 投资者姓名 | 1-255 | 是 |
| `email` | string | 投资者电子邮件 | 1-255 | 是 |
| `phone` | object | **[Phone](#phone)** 对象 | - | 是 |
| `natural_person` | object | **[Natural Person](#natural-person)** 对象（自然人必填） | - | 是* |
| `legal_person` | object | **[Legal Person](#legal-person)** 对象（法人必填） | - | 是* |

\* 当 `person_type` 为 `natural_person` 时，`natural_person` 为必填。当 `person_type` 为 `legal_person` 时，`legal_person` 为必填。

### Natural Person {#natural-person}
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `birthdate` | string | 出生日期（格式：YYYY-MM-DD） | 10 | 是 |
| `gender` | string | 性别。**[Gender](#gender)** 枚举值 | 1-6 | 否 |
| `mother_name` | string | 母亲全名 | 1-255 | 是 |
| `nationality` | string | 国籍 | 1-255 | 是 |
| `place_of_birth` | object | **[Place of Birth](#place-of-birth)** 对象 | - | 是 |
| `marital_status` | string | 婚姻状态 | 1-255 | 是 |
| `spouse` | object | **[Spouse](#spouse)** 对象 | - | 否 |
| `profession` | string | 职业 | 1-255 | 是 |
| `occupation` | string | 职位 | 1-255 | 是 |
| `occupation_company` | object | **[Occupation Company](#occupation-company)** 对象 | - | 否 |

### Gender {#gender}
| 枚举值 | 描述 |
|-----------------------------------|------------------------------------------------------------------------------|
| `male` | 男 |
| `female` | 女 |

### Place of Birth {#place-of-birth}
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `country` | string | 国家 | - | 否 |
| `uf` | string | 州 (UF) | - | 否 |
| `city` | string | 城市 | - | 否 |

### Spouse {#spouse}
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `name` | string | 配偶全名 | 1-255 | 是 |
| `document_number` | string | 配偶 CPF 或 CNPJ | 14 | 是 |

### Occupation Company {#occupation-company}
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `name` | string | 公司名称 | 1-255 | 是 |
| `document_number` | string | 公司 CNPJ | 18 | 是 |

### Legal Person {#legal-person}
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `legal_name` | string | 公司注册名称 | 1-255 | 是 |
| `constitution_date` | string | 公司成立日期（格式：YYYY-MM-DD） | 10 | 是 |

### Phone {#phone}
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `international_dial_code` | string | 国际区号 | 1-3 | 是 |
| `area_code` | string | 地区区号 | 2 | 是 |
| `number` | string | 电话号码 | 8-9 | 是 |

### Response
```json title='Response Body'
{
    "investor_key": "UUID",
    "investor_analysis_key": "UUID"
}
```

---

---

# consultar_feedback

URL: /zh-Hans/documentation/iaas/investidor/fundo_de_investimento/feedback/consultar_feedback



---

# enviar_mensagem_feedback

URL: /zh-Hans/documentation/iaas/investidor/fundo_de_investimento/feedback/enviar_mensagem_feedback



---

# listar_feedbacks

URL: /zh-Hans/documentation/iaas/investidor/fundo_de_investimento/feedback/listar_feedbacks



---

# Introdução

URL: /zh-Hans/documentation/iaas/investidor/fundo_de_investimento/introducao

Esta seção descreve o fluxo de cadastro de investidores do tipo **Fundo de Investimento** — veículos com CNPJ próprio (FIMs, FIAs, FIDCs e demais classes) que aplicam recursos em nome de seus cotistas.

Por se tratar de um veículo, o cadastro contempla os dados do fundo, do seu *investor owner* (administrador/gestor responsável) e das demais entidades exigidas pela análise cadastral. O envio de `suitability` **não** é necessário para este tipo de investidor.

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 ou administradora é 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 fundos enquanto investidores.

Um ponto muito importante é que apenas gestoras e administradoras que estiverem com seus cadastros atualizados podem realizar o cadastro de fundos de investimento. 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 do fundo de investimento
↓
3. Enviar Contas Bancárias
contas para movimentação
↓
4. Criar Partes Relacionadas
investidores exclusivos (quando aplicável)
↓
5. Enviar Documentos das Partes Relacionadas
documentos de cada investidor exclusivo
↓
6. Enviar para Análise
submissão da análise cadastral para validação
↓
7. 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 um Fundo de Investimento e disparar a análise cadastral pela QI Tech.

---

# criar_parte_relacionada

URL: /zh-Hans/documentation/iaas/investidor/fundo_de_investimento/related_party/criar_parte_relacionada



---

# enviar_documento_parte_relacionada

URL: /zh-Hans/documentation/iaas/investidor/fundo_de_investimento/related_party/enviar_documento_parte_relacionada



---

# 获取投资者持仓信息

URL: /zh-Hans/documentation/iaas/investidor/informacoes_posicao_investidor

---

### Request

ENDPOINT /quota/investor/INVESTOR_KEY/investor_positions
MÉTODO GET

### Query Params

| 参数                    | 描述                                                                            |
|------------------------------|--------------------------------------------------------------------------------------|
| `issuance_serie_key`         | 发行系列唯一标识键                                     |
| `only_above_zero`            | 仅返回份额数量大于零的当前持仓                                   |
| `fund_class_document_number` | 基金 CNPJ                                                                        |

### Responses

STATUS 200

案例 01：投资者仅持有一个单一份额系列的持仓

```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
}
```

案例 02：投资者仅持有一个优先份额系列的持仓

```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
}
```

案例 03：投资者持有两个系列的持仓，一个优先份额和一个次级份额

```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
}
```

### 响应字段

| 字段         | 类型   | 描述                                                      |
|---------------|--------|----------------------------------------------------------------|
| `data`        | array  | **[Investor Position](#investor_position)** 对象列表|
| `limit`       | int    | 每页返回的对象数量限制                       |
| `page`        | int    | 当前返回的页码                                    |
| `is_last_page`| boolean| 表示当前页是否为最后一页        |

### Investor Position
| 字段                    | 类型   | 描述                                             |
|--------------------------|--------|-------------------------------------------------------|
| `investor`               | JSON   | **[Investor](#investor)** 对象                   |
| `total_net_worth`        | float  | 投资者持仓净资产总值           |
| `total_number_of_quotas` | float  | 投资者持仓份额总数              |
| `issuance_serie`         | JSON   | **[Issuance Serie](#issuance_serie)** 对象       |
| `investor_position_key`  | JSON   | 投资者持仓唯一标识键 |

### Investor
| 字段                    | 类型     | 描述                                         | 字符数 |
|--------------------------|----------|---------------------------------------------------|------------|
| `name`                   | string   | 投资者姓名                                | 最多 255    |
| `investor_key`           | string   | 投资者唯一标识键        | 36         |
| `document_number`        | string   | 投资者 CPF/CNPJ                            | 14 或 18   |
| `person_type`            | string   | 自然人 / 法人 / 基金类别 | 最多 50     |
| `investor_sub_type`      | string   | 默认 / 金融机构                  | 最多 50     |
| `distributor`            | JSON     | **[Distributor](#distributor)** 对象         |     -      |             
| `account_data`           | JSON     | **[Account Data](#account_data)** 对象       |     -      |

### Distributor
| 字段                    | 类型     | 描述                                         | 字符数 |
|--------------------------|----------|---------------------------------------------------|------------|
| `name`                   | string   | 分销商名称                              | 最多 255    |
| `distributor_key`        | string   | 分销商唯一标识键      |     -      |             
| `document_number`        | string   | 分销商 CPF/CNPJ                          | 14 或 18   |
| `account_data`           | JSON     | **[Account Data](#account_data)** 对象       |     -      |

### Account Data
| 字段                        | 类型     | 描述                                                                   |
|------------------------------|----------|-----------------------------------------------------------------------------|
| `account_digit`              | string   | 银行账号校验位                                                    |
| `account_branch`             | string   | 银行账户支行号                                             |             
| `account_number`             | string   | 银行账号                                                        |
| `financial_institution_code` | string   | 金融机构代码                                            |
| `financial_institution_ispb` | string   | 金融机构在巴西支付系统中的标识符  |

### Issuance Serie
| 字段                         | 类型     | 描述                                         | 字符数 |
|-------------------------------|----------|---------------------------------------------------|------------|
| `name`                        | string   | 发行系列名称                          | 最多 255    |
| `issuance_serie_key`          | string   | 发行系列唯一标识键  | 36         |
| `cetip_code`                  | string   | 发行系列在 CETIP 中的资产代码    | 10         |             
| `start_date`                  | string   | 发行系列起始日期                | 10         |
| `maturity_date`               | string   | 发行系列到期日期            | 10         |
| `original_quota_value`        | float    | 原始份额价值                            | -          |
| `remuneration_type`           | string   | 收益曲线 / 残差                    | 最多 50     |
| `investment_category`         | string   | FIDC / 多市场                               | 最多 50     |
| `condominum_type`             | string   | 开放式 / 封闭式                                  | 最多 50     |
| `tax_classification`          | string   | 短期 / 长期                         | 最多 50     |
| `investment_restriction_type` | string   | 无限制 / 合格投资者 / 专业投资者        | 最多 50     |
| `minimum_share_capital`       | float    | 最低申购金额                       | -          |
| `accounting_date`             | string   | 发行系列会计日期                 | 10         |
| `sub_class`                   | JSON     | **[Sub Class](#sub_class)** 对象             | -          |

### Sub Class 
| 字段                         | 类型     | 描述                                         | 字符数 |
|-------------------------------|----------|---------------------------------------------------|------------|
| `name`                        | string   | 子类名称                                | 最多 255    |
| `sub_class_key`               | string   | 子类唯一标识键        | 36         |
| `subordination_level`         | int      | 子类从属层级               | -          |             
| `fund_class`                  | JSON     | **[Fund Class](#fund_class)** 对象           | -          |

### Fund Class 
| 字段                         | 类型     | 描述                                         | 字符数 |
|-------------------------------|----------|---------------------------------------------------|------------|
| `name`                        | string   | 基金类别名称                           | 最多 255    |
| `fund_class_key`              | string   | 基金类别唯一标识键   | 36         |
| `document_number`             | string   | 基金类别 CNPJ                           | -          |

---

# 简介

URL: /zh-Hans/documentation/iaas/investidor/inicio

本节将介绍用于查询投资者相关信息的可用工具。

如需访问这些服务，请联系团队 [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br)，以便在同质化环境（Sandbox）和生产环境中完成相应的权限开放。

### 投资者持仓信息

通过此工具可获取投资者投资持仓信息列表，详见：[5.8.2 投资者持仓信息](/documentation/iaas/investidor/informacoes_posicao_investidor)。

### 认购公告信息

通过此工具可获取投资者认购公告信息列表，详见：[5.8.4 认购公告信息](/documentation/iaas/passivo/controle_de_oferta/informacoes_boletins_de_subscricao)。

---

# 插入清算记录

URL: /zh-Hans/documentation/iaas/liquidacao_ativos/ativos/

---

### Request

ENDPOINT /settlement/fund_class/FUND_CLASS_KEY/payment_batch/EXTERNAL_ID/settlement
MÉTODO POST

:::info **信息**

清算和资产回购均通过此端点执行。区分两者的字段为 `collection_origin_type`。如果是清算，使用的枚举值为 "borrower" ；如果是回购，则使用 "assignor" 。
:::

```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"
}
```
:::caution **注意**

字段 `asset_external_id` 和 `contract_number` 是系统中资产的标识符，必须传入其中**一个**，但**不能**同时传入两者。
:::

#### Body Params
`必填字段` *
| 字段                       | 类型   | 描述                                                                     | 字符数      |
|-----------------------------|--------|------------------------------------------------------------------------------|------------|
| `asset_type` *              | string | 指定要传入的资产类型                                                         | 最多 255   |
| `total_value` *             | float  | 资产付款总值（保留两位小数）                                                 | 最多 24    |
| `external_id` *             | string | 集成合作伙伴系统中清算记录的唯一标识键                                       | 最多 50    |
| `settlement_type` *         | string | 指定要传入的清算类型                                                         | 最多 50    |
| `collection_origin_type` *  | string | 确定操作是清算还是回购                                                       | 枚举值     |
| `contract_number`           | string | 与资产相关的合同编号                                                         | 最多 50    |
| `asset_external_id`         | string | 转让时提供的资产在合作伙伴系统中的唯一标识键                                 | 最多 50    |
| `if_code`                   | string | 金融工具代码（B3）                                                           | 最多 50    |
| `participant_control_number`| string | 转让时提供的参与者控制编号                                                   | 最多 50    |
| `installment_number`        | int    | 待付款分期编号                                                               | 最多 24    |
| `installment_maturity_date` | string | 待付款分期的到期日                                                           | ISO 8601   |
| `collection_date`           | string | 付款日期（此字段供集成方控制使用）                                           | ISO 8601   |

:::info **信息**

请求体中的 `external_id` 字段指的是**清算记录**的标识符，而端点中的 `EXTERNAL_ID` 字段指的是**批次**的标识符。
:::

### 资产类型
| 枚举值                | 描述                                          |
|-----------------------|---------------------------------------------|
| `ccb`                 | 银行信用凭证                                  |
| `cce`                 | 出口信用凭证                                  |
| `structured_ccb`      | 结构化银行信用凭证                            |
| `structured_cce`      | 结构化出口信用凭证                            |
| `structured_nce`      | 结构化出口信用票据                            |
| `structured_cci`      | 结构化不动产信用凭证                          |
| `duplicata_mercantil` | 商业汇票                                      |
| `duplicata_servicos`  | 服务汇票                                      |
| `discounted_contract` | 合同                                          |

### 清算类型
| 枚举值                    | 描述                                                                                               |
|---------------------------|----------------------------------------------------------------------------------------------------|
| `asset_settlement`        | 资产全额清算                                                                                       |
| `asset_amortization`      | 资产摊销（宽限期）                                                                                 |
| `fine_payment`            | 资产利息或罚息支付                                                                                 |
| `installment_settlement`  | 分期清算（此时需传入 `installment_number` 字段）                                                   |
| `installment_amortization`| 分期摊销（此时需传入 `installment_number` 字段）                                                   |
| `installment_fine_payment`| 分期利息或罚息支付（此时需传入 `installment_number` 字段）                                         |
| `gloss`                   | 分期冲销（此时需传入 `installment_number` 字段）                                                   |

### collection_origin_type 类型
| 枚举值                    | 描述                                                                                               |
|---------------------------|----------------------------------------------------------------------------------------------------|
| `borrower`                | 操作为清算时使用                                                                                   |
| `assignor`                | 操作为回购时使用                                                                                   |

### Response

STATUS 201

```json title='Request Body'
{
    "status": "validated", 
    "total_value": 130.50,
    "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
    "installment_number": 1,
    "type":"installment_settlement",
    "settlement_result":0.0,
    "assets":[
        {
            "asset_key": "f34e9437-d025-41ab-bb53-6b94e10fd361",
            "number_of_units": 1,
            "present_value": 1250.00,
            "installment_face_value":130.50
        }
    ]
}
```

### 可能的错误

STATUS 404

Response Body

```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

Response Body

```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"
}

```
---

---

# 删除清算记录

URL: /zh-Hans/documentation/iaas/liquidacao_ativos/ativos/remocao_liquidacoes

---

### Request

ENDPOINT /settlement/fund_class/FUND_CLASS_KEY/payment_batch/EXTERNAL_ID/settlement/SETTLEMENT_EXTERNAL_ID
MÉTODO PUT

```json title='Request Body'
{
    "status": "discarded", 
}
```

:::info **信息**

请求端点中的 `SETTLEMENT_EXTERNAL_ID` 字段指的是**清算记录**的标识符，而 `EXTERNAL_ID` 字段指的是**批次**的标识符。
:::

### Response

STATUS 200

```json title='Request Body'
{ 
    "external_id": "6299b801-a272-4b5a-a766-70ceb8e273a8",
    "status": "discarded"
}
```

### 可能的错误

STATUS 404

Response Body

```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

Response Body

```json
{
  "title": "Invalid status",
  "description": "The status given: {status} is not suported.",
  "translation": "O status: {status} não possui suporte.",
  "code": "SET000026"
}

```
---

STATUS 400

Response Body

```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

Response Body

```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

URL: /zh-Hans/documentation/iaas/liquidacao_ativos/ativos/webhook

---
#### 清算完成

STATUS Settled

```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",
    },
    "webhook_type":"settlement.settlement_status_change",
    "webhook_datetime":"2024-04-23T15:08:30Z"
}
```

---

# Fluxo de liquidação de ativos

URL: /zh-Hans/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).
:::

---

# 简介

URL: /zh-Hans/documentation/iaas/liquidacao_ativos/inicio

本节将介绍相关 API，这些 API 用于实现由 QI CTVM 管理的投资基金的资产清算流程。需要特别说明的是，国债或债券等资产的清算流程不适用于此上下文。

如需访问这些服务，请联系团队 [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br)，以便在沙盒（Homologação）环境和生产环境中获得相应权限。

执行资产清算需要以下步骤：

1. 创建付款批次；
2. 插入待付款的资产；
3. 关闭付款批次；

## 清算流程

下图展示了主路径、分支以及每个步骤产生的状态。将鼠标悬停在节点上可查看端点，点击可打开该步骤的文档。

<FlowDiagram
  columns={3}
  labels={{ you: '集成方', qitech: 'QI Tech', manager: '基金管理人', docs: '查看文档' }}
  nodes={[
    { id: 'criacao', row: 1, col: 2, actor: 'you', num: 1,
      title: '创建付款批次',
      status: 'pending_settlements_insertion',
      desc: '所有将被一起处理的清算记录的容器，由唯一的 external_id 标识。',
      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: '插入清算记录',
      status: '清算：validated',
      desc: '每条清算记录一次请求，需提供资产类型、金额、清算方式和标识符。',
      endpoint: { method: 'POST', path: '.../payment_batch/{external_id}/settlement' },
      href: '/documentation/iaas/liquidacao_ativos/ativos' },

    { id: 'remocao', row: 2, col: 3, actor: 'you', tag: '可选',
      title: '移除某条清算记录',
      status: '清算：discarded',
      desc: '丢弃误插入的清算记录。仅在批次尚未关闭时可执行。',
      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: '关闭批次',
      desc: '设置 batch_status。批次中至少需要插入一条清算记录。',
      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: '批次已丢弃',
      status: 'discarded',
      desc: '不处理任何清算记录，也不产生任何资金变动。流程终止。' },

    { id: 'pago', row: 4, col: 2, actor: 'qitech',
      title: '批次付款已确认',
      status: 'paid',
      desc: 'QI Tech 确认付款。从该事件起，各条清算记录开始被处理。',
      href: '/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook' },

    { id: 'processa', row: 5, col: 2, actor: 'qitech',
      title: '逐条处理清算记录',
      status: '清算：settled',
      desc: '每条清算记录都会在基金投资组合中完成对账，并通过 webhook 单独发送通知。',
      href: '/documentation/iaas/liquidacao_ativos/ativos/webhook' },

    { id: 'conciliada', row: 6, col: 2, actor: 'qitech', tone: 'ok',
      title: '基金投资组合已对账',
      status: 'completed',
      desc: '所有清算记录均已达到最终状态，批次周期结束。',
      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 完整流程
如需了解每一次状态流转、webhook 载荷以及异常路径，请参阅[资产清算流程](/documentation/iaas/liquidacao_ativos/fluxo_liquidacao)。
:::

# 创建批次
在此步骤中，需要生成一个付款批次密钥，该密钥将用于在清算过程中标识批次。此密钥将在创建批次时发送，之后即可进入下一步骤。
:::caution **注意**

每个批次在已注册的基金中必须拥有**唯一密钥**。
:::

# 插入资产
在此步骤中，清算相关资产将逐一发送，并附带其待清算金额、资产类型、清算方式以及资产标识符等信息，格式详情请参见 [5.4.3.1 资产](ativos/ativos.md)。

# 关闭批次
最后，插入所有资产后，需要使用批次密钥关闭付款批次。此后，付款批次的清算处理将在内部启动，并最终通过 webhook 指示流程完成。

:::info **信息**

现金对账和资产组合更新将由 API 自动完成。
:::

---

# 创建付款批次

URL: /zh-Hans/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao

---

### 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": "PAGAMENOS - ABC - 2025-01-01",
    "account": {
        "account_number":"123456",
        "account_digit":"0",
        "account_branch": "0001",
        "financial_institution_code": "329",
    },
}
```

### Body Params
`必填字段 * `
| 字段                     | 类型   | 描述                                                                    | 字符数     |
|--------------------------|--------|-----------------------------------------------------------------------------|------------|
| `external_id` *          | string | 集成合作伙伴系统中此批次的唯一标识键。                                      | 最多 50    |
| `account_key`            | string | 用于标识清算入账账户的字段                                                  | 36         |
| `account`                | JSON   | 用于标识清算入账账户的字段                                                  | -          |
| `description`            | string | 清算批次描述                                                                | 255        |
| `reference_date`         | string | 清算参考日期。                                                              | ISO 8601   |
| `end_to_end_id`          | string | 清算金融对手方的 PIX 标识符。                                               | 32         |
| `source_document_number` | string | 清算金融对手方的文件号码。                                                  | 14 - 18    |

:::caution **注意**

`account` 和 `account_key` 字段均非必填，但若未作为参数传入，清算将在基金主账户中生成。两者不应同时传入。账户信息必须属于该基金旗下的账户。
:::

### Account
| 字段                         | 类型   | 描述                     | 字符数     |
|------------------------------|--------|----------------------------------|------------|
| `account_number`             | string | 账号                             | 最多 50    |
| `account_digit`              | string | 账号校验位                       | 1          |
| `account_branch`             | string | 账户支行                         | 最多 50    |
| `financial_institution_code` | string | 金融机构代码                     | 3          |

### Response

STATUS 201

```json title='Response Body'
{
    "external_id": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "status": "pending_settlements_insertion",
    "description": "Lote de Pagamento - 2024-01-01 - 41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad",
    "payment_batch_key": "63f0dbec-e9c4-4943-929e-1d47b9edbb0b",
    "reference_date": "2024-01-01",
}
```

### 可能的错误

STATUS 404

Response Body

```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 400

Response Body

```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 409

Response Body

```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 404

Response Body

```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"
}

```

---

# 关闭付款批次的插入

URL: /zh-Hans/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento

---

### Request

ENDPOINT /settlement/fund_class/FUND_CLASS_KEY/payment_batch/EXTERNAL_ID
MÉTODO PUT

```json title='Request Body'
{
    "batch_status": "pending_payment",
}
```
### Body Params
#### `必填字段` *
| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `batch_status` * | string | 指定要传入的状态 | 最多 50 |
### 状态
| 枚举值 | 描述|
|---|---|
| `pending_payment`| 待付款|
| `discarded` | 已丢弃|
### Response

STATUS 200

```json title='Response Body'
{
    "external_id": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "status": "pending_payment",
}
```

### 可能的错误

STATUS 404

Response Body

```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

Response Body

```json
{
  "title": "Invalid status",
  "description": "The status given: {status} is not suported.",
  "translation": "O status: {status} não possui suporte.",
  "code": "SET000026"
}

```
---

STATUS 400

Response Body

```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"
}

```
---

---

# 清算批次列表

URL: /zh-Hans/documentation/iaas/liquidacao_ativos/lote_pagamento/listagem

---

### Request

ENDPOINT /settlement/fund_class/FUND_CLASS_KEY/payment_batchs
MÉTODO GET

### 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 RECEBÍVEIS",
                "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": "discarded",
            "external_id": "5910209c-9cb5-4569-9069-f2dbc8060434",
            "reference_date": "2025-08-08",
            "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e"
        },
        {
            "description": "AJUSTE LOTE DE LIQUIDAÇÃO 06/08",
            "fund_class": {
                "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS RECEBÍVEIS",
                "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": "5e9f645d-10e1-4ecc-9154-e8d81bb54e72",
            "status": "completed",
            "external_id": "214b237b-3453-40cb-a07a-d9f57065a1bd",
            "reference_date": "2025-08-06",
            "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e",
            "total_value": 143.18
        }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": false
}
```

---

# 产品 Webhooks

URL: /zh-Hans/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook

---
#### 付款批次已付款

STATUS Paid

```json title='Webhook Body'
{
    "data":{
        "external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78",
        "status": "paid"
    },
    "webhook_type":"settlement.payment_batch_status_change",
    "webhook_datetime":"2024-04-23T15:08:30Z"  
}
```

---

# 资产 - 信贷业务

URL: /zh-Hans/documentation/iaas/negociacao_recebiveis/asset/criacao_co

---
## 创建 - CCB

### Request

ENDPOINT /trade_receivables/BASE_URL/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"
          }
      ],
    }
}

```

## 定义

### 资产对象（Request Body）

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `asset_type` * | string | 资产类型。 | 最多 50 |
| `total_purchase_value` * | number | 资产采购总价。即受让方实际支付的金额。 | 保留 2 位小数 |
| `premiums` | list of objects | 销售中涉及的溢价列表。此信息仅供后续查看，不用于任何后续计算。参见 **[溢价对象](#溢价对象)**。 | - |
| `credit_operation` * | object | 参见 **[信贷业务对象](#信贷业务对象)**。 | - |

### 溢价对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `premium_type` | string | 溢价类型。参见 **[溢价类型枚举值](#溢价类型枚举值)**。 | enumerator |
| `total_value` | number | 该溢价的总金额。 | 保留 2 位小数 |

#### 溢价类型枚举值

| 枚举值       | 描述          |
|--------------|---------------|
| **spread**   | 与信贷发起和发行相关的利差 |

### 信贷业务对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `external_id` * | string | 集成合作伙伴系统中此资产的唯一标识键。 | 最多 50 |
| `originator_document_number` * | string | 促成此信贷业务的发起人/顾问的标识文件号。 | 格式化 CPF 或 CNPJ |
| `principal_value` * | number | 此业务的未偿还本金总额。 | 最多 8 位小数 |
| `contract` * | object | 参见 **[合同对象](#合同对象)**。 | - |
| `borrower` * | object | 参见 **[借款人对象](#借款人对象)**。 | - |
| `amortization_type` * | string | 业务计算中使用的摊销类型。参见 **[摊销类型枚举值](#摊销类型枚举值)** | enumerator |
| `interest_rate_type` * | string | 业务的利率类型。参见 **[利率类型枚举值](#利率类型枚举值)** | enumerator |
| `pre_fixed` * | object | 含固定利率部分计算信息的对象。参见 **[固定利率对象](#固定利率对象)**。 | - |
| `installments` * | list of objects | 业务分期列表。参见 **[分期对象](#分期对象)**。 | - |
| `modality_code` | string | 标识与资产相关联的金融业务类别或类型的标识符。 | 4 |
| `consignee` | object | 参见 **[代扣对象](#代扣对象)**。 | - |
| `collaterals` | list of objects | 担保品列表。参见 **[担保品对象](#担保品对象)**。 | - |

:::caution **注意**
信贷业务的 `external_id` 字段对于不同资产必须唯一，不应与批次标识符 `EXTERNAL_ID` 混淆。
:::

#### 摊销类型枚举值

| 枚举值       | 描述          |
|--------------|---------------|
| **sac**   | SAC 类型摊销 |
| **price**   | Price 类型摊销 |

#### 利率类型枚举值

| 枚举值       | 描述          |
|--------------|---------------|
| **pre_fixed**   | 固定利率业务 |
| **post_fixed**   | 浮动利率业务 |

### 借款人对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `name` * | string | 借款人姓名。 | 最多 255 |
| `document_number` * | string | 借款人标识文件号。 | CPF 或 CNPJ |
| `person_type` * | string | 人员类型。参见 **[人员类型枚举值](#人员类型枚举值)**。 | enumerator |
| `email` | string | 借款人电子邮箱。 | 最多 255 |
| `address` * | object | 参见 **[地址对象](#地址对象)**。 | - |
| `phone` | object | 参见 **[电话对象](#电话对象)**。 | - |

#### 人员类型枚举值

| 枚举值       | 描述          |
|--------------|---------------|
| **natural_person** | 自然人。参见 **[自然人对象](#自然人对象)**。 |
| **legal_person**   | 法人。参见 **[法人对象](#法人对象)**。 |

### 地址对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `street` * | string | 如无完整信息，可将汇总信息填入此字段。 | 最多 255 |
| `number` | string | 门牌号。 | 最多 40 |
| `neighborhood` | string | 街区/社区。 | 最多 255 |
| `city` | string | 城市。 | 最多 255 |
| `uf`  | string | 州/省。 | 2 个字符 |
| `complement`  | string | 补充地址。 | 最多 255 |
| `postal_code` * | string | 邮政编码。 | 9 个字符 |
| `country`  | string | 国家。 | 3 个字符 |

### 电话对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `area_code` * | string | 区号。 | 2 |
| `number` * | string | 电话号码。 | 9 |

### 合同对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `number` * | string | 合同编号。 | 最多 50 |
| `disbursement_date` * | string | 放款日期。 | 格式化日期 |
| `issue_date` * | string | 发行日期。 | 格式化日期 |
| `signature_date` | string | 合同签署日期。 | 格式化日期 |
| `issue_value` * | number | 合同发行价值。 | 保留 2 位小数 |

### 固定利率对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `calendar_base` * | string | 使用的计算基础。参见 **[计算基础枚举值](#计算基础枚举值)**。 | enumerator |
| `monthly_rate` * | number | 合同的月利率。1% 使用 0.01 | 最多 8 位小数 |

#### 计算基础枚举值

| 枚举值       | 描述          |
|--------------|---------------|
| **workdays** | 以工作日为计算基础（252天） |
| **calendar_365**   | 以 365 天为计算基础 |
| **calendar_360**   | 以 360 天为计算基础 |

### 自然人对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `birthdate`  | string | 出生日期。 | 格式化日期 |
| `gender` | string | 参见 **[性别枚举值](#性别枚举值)**。 | enumerator |
| `mother_name` | string | 母亲姓名。 | 最多 255 |

#### 性别枚举值

| 枚举值       | 描述          |
|--------------|---------------|
| **male** | 男性。 |
| **female**   | 女性。 |

### 法人对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `foundation_date`  | string | 成立日期。 | 格式化日期 |
| `activity_code` * | string | 经营活动代码。 | 格式：11.11-1-11 |
| `annual_revenues` | integer | 年收入。 | - |
| `representatives` | object | 参见 **[法人对象](#法人对象)**。 | enumerator |

### 分期对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `maturity_date` * | string | 分期到期日。 | 格式化日期 |
| `installment_number` * | number | 分期编号。 | 整数 |
| `face_value` | number | 面值。 | 最多 8 位小数 |
| `principal_value` | number | 到期日预期摊还的本金。 | 最多 8 位小数 |

### 逾期对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `fine` * | object | 到期罚款对象。参见 **[逾期罚款对象](#逾期罚款对象)**。 | - |
| `interest` * | object | 逾期利息对象。参见 **[逾期利息对象](#逾期利息对象)**。 | - |

#### 逾期罚款对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `fine_type` * | string | 参见 **[罚款类型枚举值](#罚款类型枚举值)**。 | enumerator |
| `percentage_value` | number | 罚款金额（当罚款类型为 `percentage` 时）。计量单位：0 至 1，对应 0 至 100% | 最多 2 位小数 |
| `amount` | number | 罚款金额（当罚款类型为 `fixed` 时）。 | 最多 2 位小数 |

##### 罚款类型枚举值

| 枚举值         | 描述                                     |
|----------------|------------------------------------------|
| **percentage** | 按分期金额的百分比计算的罚款             |
| **fixed**      | 固定罚款金额                             |

#### 逾期利息对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `method` * | string | 参见 **[逾期利息计算方法枚举值](#逾期利息计算方法枚举值)**。 | enumerator |
| `pre_fixed` * | object | 参见 **[固定利率对象](#固定利率对象)**。 | - |

##### 逾期利息计算方法枚举值

| 枚举值       | 描述                     |
|--------------|--------------------------|
| **compound** | 复利逾期利息             |
| **simple**   | 单利逾期利息             |

### 代扣对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `name` * | string | 代扣实体名称。 | 最多 255 |
| `document_number` * | string | 代扣实体标识文件号。 | CPF 或 CNPJ |
| `consignee_type` * | string | 代扣类型。参见 **[代扣类型枚举值](#代扣类型枚举值)**。 | enumerator |

##### 代扣类型枚举值

| 枚举值       | 描述               |
|--------------|--------------------|
| **public**   | 公共代扣           |
| **private**  | 私人代扣           |
| **inss**     | INSS 代扣          |

### 担保品对象

| 字段                | 描述                                                                              |
|---------------------|----------------------------------------------------------------------------------------|
| `collateral_type` * | 担保品类型。参见 **[担保品类型枚举值](#担保品类型枚举值)** |

##### 担保品类型枚举值

| 枚举值              | 描述                                                               |
|---------------------|--------------------------------------------------------------------|
| **fgts**            | FGTS 担保。参见 **[FGTS 对象](#fgts-对象)**                        |
| **social_security** | INSS 担保。参见 **[INSS 对象](#inss-对象)**                        |
| **home_equity**     | 不动产担保。参见 **[不动产对象](#不动产对象)**                     |

### FGTS 对象

| 字段                | 描述             |
|---------------------|----------------------|
| `protocol_number` * | 协议编号。           |
| `status` *          | 状态。               |

### INSS 对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `benefit_number` * | string | 福利编号。 | - |
| `benefit_type` * | string | 福利类型。 | - |
| `status` * | string | 状态。 | - |

### 不动产对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `enterprise_name` * | string | 项目名称。 | - |
| `registration_number` * | string | 不动产登记编号。 | - |
| `enterprise_document_number` | string | 与项目相关联的标识文件号。 | CPF 或 CNPJ |
| `collateral_properties` * | list object | 不动产属性列表。参见 **[不动产属性对象](#不动产属性对象)**。 | - |

### 不动产属性对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `address` * | object | 不动产地址。参见 **[地址对象](#地址对象)**。 | - |
| `total_collateral_value` * | number | 不动产价值。 | 最多 8 位小数 |

### Response

STATUS 201

```json title='Response Body'
{
    "asset_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "status": "pending_eligibility",
}
```

### 可能的错误

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"
}

```

---

# Criação de Ativo — CTE

URL: /zh-Hans/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.

---

# 资产 - 信贷业务

URL: /zh-Hans/documentation/iaas/negociacao_recebiveis/asset/criacao_discounted_contract

---
## 创建 - 合同

### Request

ENDPOINT /trade_receivables/BASE_URL/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"
      }
    }
}

```

## 定义

### 资产对象（Request Body）

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `asset_type` * | string | 资产类型。 | 最多 50 |
| `total_purchase_value` * | number | 资产采购总价。即受让方实际支付的金额。 | 保留 2 位小数 |
| `discounted_credit_right` * | object | 参见 **[信用权利对象](#信用权利对象)**。 | - |

### 信用权利对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `external_id` * | string | 集成合作伙伴系统中此批次的唯一标识键。 | 最多 50 个字符 |
| `originator_document_number` * | string | 促成此信贷业务的发起人/顾问的标识文件号。 | 格式化 CPF 或 CNPJ |
| `maturity_date` * | string | 分期到期日。 | 格式化日期 |
| `order_number` * | string | 订单编号。 | 最多 45 |
| `face_value` * | number | 面值。 | 最多 8 位小数 |
| `borrower` * | object | 参见 **[借款人对象](#借款人对象)**。 | - |
| `contract` * | object | 参见 **[合同对象](#合同对象)**。 | - |

### 借款人对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `name` * | string | 借款人姓名。 | 最多 255 |
| `document_number` * | string | 借款人标识文件号。 | CPF 或 CNPJ |
| `person_type` * | string | 人员类型。参见 **[人员类型枚举值](#人员类型枚举值)**。 | enumerator |
| `email` | string | 借款人电子邮箱。 | 最多 255 |
| `address` * | object | 参见 **[地址对象](#地址对象)**。 | - |
| `phone` | object | 参见 **[电话对象](#电话对象)**。 | - |

#### 人员类型枚举值

| 枚举值       | 描述          |
|--------------|---------------|
| **natural_person** | 自然人。参见 **[自然人对象](#自然人对象)**。 |
| **legal_person**   | 法人。参见 **[法人对象](#法人对象)**。 |

### 地址对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `street` * | string | 如无完整信息，可将汇总信息填入此字段。 | 最多 255 |
| `number` | string | 门牌号。 | 最多 40 |
| `neighborhood` | string | 街区/社区。 | 最多 255 |
| `city` | string | 城市。 | 最多 255 |
| `uf`  | string | 州/省。 | 2 个字符 |
| `complement`  | string | 补充地址。 | 最多 255 |
| `postal_code` * | string | 邮政编码。 | 9 个字符 |
| `country`  | string | 国家。 | 3 个字符 |

### 自然人对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `birthdate`  | string | 出生日期。 | 格式化日期 |
| `gender` | string | 参见 **[性别枚举值](#性别枚举值)**。 | enumerator |
| `mother_name` | string | 母亲姓名。 | 最多 255 |

#### 性别枚举值

| 枚举值       | 描述          |
|--------------|---------------|
| **male** | 男性。 |
| **female**   | 女性。 |

### 法人对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `foundation_date`  | string | 成立日期。 | 格式化日期 |
| `activity_code` | string | 经营活动代码。 | - |
| `annual_revenues` | integer | 年收入。 | - |
| `representatives` | object | 参见 **[法人对象](#法人对象)**。 | enumerator |

### 代表人对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `name` | string | 代表人姓名。 | 最多 255 |
| `document_number` | string | 代表人标识文件号。 | CPF 或 CNPJ |
| `email` | string | 代表人电子邮箱。 | 最多 255 |
| `phone` | object | 参见 **[电话对象](#电话对象)**。 | enumerator |
| `address` | object | 参见 **[地址对象](#地址对象)**。 | enumerator |
| `person_type` | string | 参见 **[人员类型枚举值](#人员类型枚举值)**。 | enumerator |
| `representative_type` | string | 代表人类型。 | 最多 50 |

### 电话对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `international_dial_code`  | string | 国际区号。 | 最多 3 |
| `area_code`  | string | 区号。 | 2 位数字 |
| `number` | string | 号码。 | 最多 10 |

### 合同对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `number_of_installments` * | integer | 分期数量。 | - |
| `total_face_value` * | number | 合同面值。 | 保留 2 位小数 |
| `number` * | string | 合同编号。 | 最多 50 |
| `issue_date` * | string | 发行日期。 | 格式化日期 |

### Response

STATUS 201

```json title='Response Body'
{
    "asset_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "status": "pending_eligibility",
}
```

---

# 资产 - 信贷业务

URL: /zh-Hans/documentation/iaas/negociacao_recebiveis/asset/criacao_duplicata

---
## 创建 - 商业汇票

### Request

ENDPOINT /trade_receivables/BASE_URL/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"
        }       
    }
}

```

## 定义

### 资产对象（Request Body）

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `asset_type` * | string | 资产类型。 | 最多 50 |
| `total_purchase_value` * | number | 资产采购总价。即受让方实际支付的金额。 | 保留 2 位小数 |
| `discounted_credit_right` * | object | 参见 **[信用权利对象](#信用权利对象)**。 | - |

### 信用权利对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `external_id` * | string | 集成合作伙伴系统中此批次的唯一标识键。 | 最多 50 个字符 |
| `originator_document_number` * | string | 促成此信贷业务的发起人/顾问的标识文件号。 | 格式化 CPF 或 CNPJ |
| `maturity_date` * | string | 分期到期日。 | 格式化日期 |
| `order_number` * | string | 订单编号。 | 最多 45 |
| `face_value` * | number | 面值。 | 最多 8 位小数 |
| `borrower` * | object | 参见 **[借款人对象](#借款人对象)**。 | - |
| `participant_control_number` | string | 集成合作伙伴系统中的参与者控制编号。 | 50 个字母数字字符 |
| `bankslip` | object | 参见 **[银行票据对象](#银行票据对象)**。 | - |
| `delay` | object | 参见 **[逾期对象](#逾期对象)**。 | - |
| `invoice` * | object | 参见 **[发票对象](#发票对象)**。 | - |

### 借款人对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `name` * | string | 借款人姓名。 | 最多 255 |
| `document_number` * | string | 借款人标识文件号。 | CPF 或 CNPJ |
| `person_type` * | string | 人员类型。参见 **[人员类型枚举值](#人员类型枚举值)**。 | enumerator |
| `email` | string | 借款人电子邮箱。 | 最多 255 |
| `address` * | object | 参见 **[地址对象](#地址对象)**。 | - |
| `phone` | object | 参见 **[电话对象](#电话对象)**。 | - |

#### 人员类型枚举值

| 枚举值       | 描述          |
|--------------|---------------|
| **natural_person** | 自然人。参见 **[自然人对象](#自然人对象)**。 |
| **legal_person**   | 法人。参见 **[法人对象](#法人对象)**。 |

### 地址对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `street` * | string | 如无完整信息，可将汇总信息填入此字段。 | 最多 255 |
| `number` | string | 门牌号。 | 最多 40 |
| `neighborhood` | string | 街区/社区。 | 最多 255 |
| `city` | string | 城市。 | 最多 255 |
| `uf`  | string | 州/省。 | 2 个字符 |
| `complement`  | string | 补充地址。 | 最多 255 |
| `postal_code` * | string | 邮政编码。 | 9 个字符 |
| `country`  | string | 国家。 | 3 个字符 |

### 自然人对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `birthdate`  | string | 出生日期。 | 格式化日期 |
| `gender` | string | 参见 **[性别枚举值](#性别枚举值)**。 | enumerator |
| `mother_name` | string | 母亲姓名。 | 最多 255 |

#### 性别枚举值

| 枚举值       | 描述          |
|--------------|---------------|
| **male** | 男性。 |
| **female**   | 女性。 |

### 法人对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `foundation_date`  | string | 成立日期。 | 格式化日期 |
| `activity_code` | string | 经营活动代码。 | - |
| `annual_revenues` | integer | 年收入。 | - |
| `representatives` | object | 参见 **[法人对象](#法人对象)**。 | enumerator |

### 代表人对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `name` | string | 代表人姓名。 | 最多 255 |
| `document_number` | string | 代表人标识文件号。 | CPF 或 CNPJ |
| `email` | string | 代表人电子邮箱。 | 最多 255 |
| `phone` | object | 参见 **[电话对象](#电话对象)**。 | enumerator |
| `address` | object | 参见 **[地址对象](#地址对象)**。 | enumerator |
| `person_type` | string | 参见 **[人员类型枚举值](#人员类型枚举值)**。 | enumerator |
| `representative_type` | string | 代表人类型。 | 最多 50 |

### 电话对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `international_dial_code`  | string | 国际区号。 | 最多 3 |
| `area_code`  | string | 区号。 | 2 位数字 |
| `number` | string | 号码。 | 最多 10 |

### 银行票据对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `our_number` | object | 包含"我方编号"数据的对象。仅适用于由客户开具我方编号的情况。参见 **[我方编号对象](#我方编号对象)**。 | - |

#### 我方编号对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `number` | number | 我方编号。用于有登记收款的银行编号。 | 1 至 11 位数字字符 |
| `digit` | string | 我方编号的自校验位。 | 1 位字母数字字符 |

### 逾期对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `fine` | object | 到期罚款对象。参见 **[逾期罚款对象](#逾期罚款对象)**。 | - |
| `interest` | object | 逾期利息对象。参见 **[逾期利息对象](#逾期利息对象)**。 | - |

#### 逾期罚款对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `fine_type` | string | 参见 **[罚款类型枚举值](#罚款类型枚举值)**。 | enumerator |
| `percentage_value` | number | 罚款金额（当罚款类型为 `percentage` 时）。计量单位：0 至 1，对应 0 至 100% | 最多 2 位小数 |
| `amount` | number | 罚款金额（当罚款类型为 `fixed` 时）。 | 最多 2 位小数 |

##### 罚款类型枚举值

| 枚举值       | 描述          |
|--------------|---------------|
| **percentage**   | 按分期金额的百分比计算的罚款 |
| **fixed**   | 固定罚款金额 |

#### 逾期利息对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `method` * | string | 参见 **[逾期利息计算方法枚举值](#逾期利息计算方法枚举值)**。 | enumerator |
| `pre_fixed` * | object | 参见 **[固定利率对象](#固定利率对象)**。 | - |

##### 逾期利息计算方法枚举值

| 枚举值       | 描述          |
|--------------|---------------|
| **compound**   | 复利逾期利息 |
| **pre_fixed**   | 单利逾期利息 |

### 发票对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `access_key` * | string | 发票编号。 | 44 个字符 |
| `total_value` | number | 总值。 | 保留 2 位小数 |
| `serie` * | string | 序列号。 | 最多 3 |
| `number` * | string | 发票号码。 | 最多 50 |
| `issue_date` * | string | 发行日期。 | 格式化日期 |

### Response

STATUS 201

```json title='Response Body'
{
    "asset_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "status": "pending_eligibility",
}
```

---

# 插入待回购资产

URL: /zh-Hans/documentation/iaas/negociacao_recebiveis/asset/criacao_repurchased_asset

### Request

ENDPOINT /trade_receivables/BASE_URL/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
}
```

#### Body Params

| 字段 | 类型 | 描述
|-|-|-|
| `asset_type` * | string | 资产类型。
| `external_id` * | string | 待回购资产的外部标识符。
| `assignor_document_number` * | string | 待回购资产的转让方文件号。
| `repurchase_value` * | number | 资产回购价值。

### 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",
    "current_value": 120.02
}
```

---

# 插入文件

URL: /zh-Hans/documentation/iaas/negociacao_recebiveis/asset/documents

### Request

ENDPOINT /trade_receivables/BASE_URL/assignment/EXTERNAL_ID/asset/ASSET_EXTERNAL_ID/document
MÉTODO POST

```json title='Request Body'
{
    "document_type":"ccb",
    "document_b64": "aGVsbG8gd29ybGQgaWYgeW91IGRlY29kZWQgbWUsIGJlIGNhcmVmdWwuIEl0IG11c3QgYmUgYSBQREYgRmlsZSBvdGhlcndpc2UgSSB3aWxsIHJhaXNlIGFuIEVycm9yLg=="
}
```

#### Body Params

| 字段 | 类型 | 描述
|-|-|-|
| `document_b64` * | string | 必须是以 Base64 编码的 PDF 格式文件二进制内容。

### Response

STATUS 201

```json title='Response Body'
{
    "document_key": "8e515a17-8b4d-49a3-aed6-47c9574e426a"
}
```

### 可能的错误

STATUS 404

Response Body

```json
{
  "title": "Asset not found",
  "description": "Asset not found",
  "translation": "Ativo não foi encontrado",
  "code": "TRC000020"
}

```

---

STATUS 400

Response Body

```json
{
  "title": "Invalid documents",
  "description": "Required documents type are invalid",
  "translation": "Tipo de Documentos requeridos sao inválidos",
  "code": "TRC000032"
}

```

---

STATUS 400

Response Body

```json
{
  "title": "Invalid document type",
  "description": "Invalid document type",
  "translation": "Tipo de documento invalido",
  "code": "TRC000033"
}

```

---

STATUS 400

Response Body

```json
{
  "title": "Invalid document format",
  "description": "Invalid document format",
  "translation": "Formato do documento invalido",
  "code": "TRC000034"
}

```

---

# 查询批次中的资产

URL: /zh-Hans/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos

---
## 查询资产

### Request

ENDPOINT /trade_receivables/fund_class/FUND_CLASS_KEY/assignment/EXTERNAL_ID/assets
MÉTODO GET

### Response 
Response Body

```json
{
   "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",
         "discounted_credit_right":{
            "delay":{
               "fine":{
                  "fine_type":"percentage",
                  "percentage_value":0.0
               },
               "interest":{
                  "method":"pre_fixed",
                  "pre_fixed":{
                     "daily_rate":0.0,
                     "calendar_base":"calendar_360"
                  }
               }
            },
            "invoice":{
               "serie":"123",
               "number":"958431587",
               "access_key":"69037229347091328617032722238810300308237163",
               "issue_date":"2023-10-10",
               "total_value":1450.02
            },
            "bankslip":{
               "our_number":{
                  "digit":"P",
                  "number":"15948261594"
               }
            },
            "borrower":{
               "name":"Borrower Teste",
               "email":"Borrower@yopmail.com",
               "phone":{
                  "number":"36360268",
                  "area_code":"11"
               },
               "address":{
                  "uf":"SP",
                  "city":"São Paulo",
                  "number":"215",
                  "street":"Gilberto Sabino",
                  "country":"BRA",
                  "postal_code":"05425-020",
                  "neighborhood":"Pinheiros"
               },
               "person_type":"natural_person",
               "natural_person":{
                  "birthdate":"2001-01-05",
                  "mother_name":"Lívia Santos"
               },
               "document_number":"805.359.140-08"
            },
            "face_value":1450.02,
            "external_id":"e292656f-f7fb-44dc-96f3-667c36c88442",
            "person_type":"natural_person",
            "order_number":"18923619954796912",
            "maturity_date":"2050-12-10",
            "originator_document_number":"53.020.654/0001-43",
            "participant_control_number":"ICX841HWCPUGU4U101XPLDW8D",
            "originator":{
               "originator_key":"e172cfd3-716c-40a4-a5ec-5739a83cbbf8",
               "document_number":"53.020.654/0001-43",
               "name":"Originador de testes"
            }
         },
         "duration":9177,
         "denied_by": "document", 
         "denial_reason": "Invalid documents"
      }
   ],
   "limit":10,
   "page":0,
   "is_last_page":true
}
```

---

## 查询特定资产

### Request

ENDPOINT /trade_receivables/BASE_URL/assignment/EXTERNAL_ID/asset/ASSET_EXTERNAL_ID
MÉTODO GET

### Response 
Response Body

```json
{
   "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",
   "discounted_credit_right":{
      "delay":{
         "fine":{
            "fine_type":"percentage",
            "percentage_value":0.0
         },
         "interest":{
            "method":"pre_fixed",
            "pre_fixed":{
               "daily_rate":0.0,
               "calendar_base":"calendar_360"
            }
         }
      },
      "invoice":{
         "serie":"123",
         "number":"958431587",
         "access_key":"69037229347091328617032722238810300308237163",
         "issue_date":"2023-10-10",
         "total_value":1250.02
      },
      "bankslip":{
         "our_number":{
            "digit":"P",
            "number":"15948261594"
         }
      },
      "borrower":{
         "name":"Borrower",
         "email":"borrower@yopmail.com",
         "phone":{
            "number":"36360268",
            "area_code":"11"
         },
         "address":{
            "uf":"SP",
            "city":"São Paulo",
            "number":"215",
            "street":"Gilberto Sabino",
            "country":"BRA",
            "postal_code":"05425-020",
            "neighborhood":"Pinheiros"
         },
         "person_type":"natural_person",
         "natural_person":{
            "birthdate":"2001-01-05",
            "mother_name":"Lívia Santos"
         },
         "document_number":"805.359.140-08"
      },
      "face_value":1450.02,
      "external_id":"acfbc329-4e67-40ea-bd8d-5debdaebe144",
      "person_type":"natural_person",
      "order_number":"18923619954796912",
      "maturity_date":"2050-12-10",
      "originator_document_number":"53.020.654/0001-43",
      "participant_control_number":"ICX841HWCPUGU4U101XPLDW8D",
      "originator":{
         "originator_key":"e172cfd3-716c-40a4-a5ec-5739a83cbbf8",
         "document_number":"53.020.654/0001-43",
         "name":"Originador de testes"
      }
   },
   "duration":9184,
   "denied_by":"document",
   "denial_reason":"Invalid documents"
}
```

---

# 从批次中移除资产

URL: /zh-Hans/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos

---

要从批次中移除资产，该批次必须处于待管理员审批状态。在此状态下，需要执行以下3个步骤。

* 开放批次
* 移除资产
* 关闭批次

要执行第一步，请发送以下请求：

### Request

ENDPOINT /trade_receivables/BASE_URL/assignment/EXTERNAL_ID
MÉTODO PUT

```json title='Request Body'
{
    "assignment_status":"pending_assets_insertion"
}
```

#### Body Params

| 字段 | 类型 | 描述
|-|-|-|
| `assignment_status` * | string | 批次状态。

### 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
}
```

此后批次已开放，可以移除资产。要移除资产，请对每个待移除的资产发送以下请求。

### Request

ENDPOINT /trade_receivables/BASE_URL/assignment/EXTERNAL_ID/asset/ASSET_EXTERNAL_ID
MÉTODO PUT

```json title='Request Body'
{
    "asset_status":"denied"
}
```

#### Body Params

| 字段 | 类型 | 描述
|-|-|-|
| `asset_status` * | string | 资产状态。

### Response

STATUS 200

```json title='Response Body'
{
    "external_id": "9eec85be-97c9-41e0-88b3-b17a39869b36",
    "status": "denied"
}
```

最后，按照以下结构重新关闭批次：

### Request

ENDPOINT /trade_receivables/BASE_URL/assignment/EXTERNAL_ID
MÉTODO PUT

```json title='Request Body'
{
    "assignment_status":"completed_assets_insertion"
}
```

#### Body Params

| 字段 | 类型 | 描述
|-|-|-|
| `assignment_status` * | string | 批次状态。

### 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
}
```
这样，批次将重新进入管理员审批流程，并正常继续后续步骤。

### 可能的错误

STATUS 404

Response Body

```json
{
  "title": "Asset not found",
  "description": "Asset not found",
  "translation": "Ativo não foi encontrado",
  "code": "TRC000020"
}

```

---

STATUS 404

Response Body

```json
{
  "title": "Cant deny this asset.",
  "description": "This asset cant be denied.",
  "translation": "Esse ativo não pode ser negado",
  "code": "TRC000086"
}

```

---

STATUS 404

Response Body

```json
{
  "title": "Invalid assignment status",
  "description": "Assignment is not in a valid status for this operation",
  "translation": "O lote não esstá em um status valido para essa operação",
  "code": "TRC000087"
}

```

---

# Webhooks

URL: /zh-Hans/documentation/iaas/negociacao_recebiveis/asset/webhooks

---
#### 在资格审核中被拒绝

STATUS Denied by Eligibility

```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",
    },
    "webhook_type":"trade_receivables.asset_status_change",
    "webhook_datetime":"2024-04-23T15:08:30Z"
}
```

#### 通过资格审核并等待文件

STATUS Pending documentation

```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",
    },
    "webhook_type":"trade_receivables.asset_status_change",
    "webhook_datetime":"2024-04-23T15:08:30Z"
}
```

#### 资产已丢弃

STATUS Discarded

```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",
    },
    "webhook_type":"trade_receivables.asset_status_change",
    "webhook_datetime":"2024-04-23T15:08:30Z"
}
```

#### 资产创建 Webhook

STATUS Pending documentation

```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",
        "asset_payload": {
   "premiums":[
      {
         "total_value":1.2,
         "premium_type":"spread"
      }
   ],
   "asset_type":"ccb",
   "deductions":[
      
   ],
   "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"
}
```

---

# 管理员审批

URL: /zh-Hans/documentation/iaas/negociacao_recebiveis/assignment/aprovacao

:::info 致管理员
需要特别说明的是，该路由仅对管理员开放。如果未集成，可以通过门户网站执行此操作。
:::

### Request

ENDPOINT /trade_receivables/BASE_URL/assignment/EXTERNAL_ID
MÉTODO PUT

```json title='Request Body'
{
    "assignment_status": "approved",
    "disbursement_account_key": "764746ce-a530-4a71-af66-3f7c879627df"
}
```
#### Body Params
| 字段 | 类型 | 描述 | 字符数 |
|----------------------------|--------|-------------------------------------------------------------------------|------------|
| `assignment_status` * | string | 批次状态 | 最多50 |
| `disbursement_account_key` | string | 在转让人同质化中注册的拨付账户的唯一键 | 36 |

#### Assignment Status 枚举值
| 枚举值 | 描述 |
|--------------|----------------------|
| **approved** | 用于审批批次 |
| **reproved** | 用于拒绝批次 |

### Response

STATUS 201

```json title='Response Body'
{
    "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "status": "approved",
}
```

### 可能的错误

STATUS 400

Response Body

```json
{
  "title": "Assignment not found",
  "description": "Assignment not found",
  "translation": "Cessão não foi encontrada",
  "code": "TRC000018"
}

```
---

STATUS 400

Response Body

```json
{
  "title": "Invalid operation",
  "description": "This assignment can not receive 'dinied' status",
  "translation": "Esse lote não pode receber o status 'denied'",
  "code": "TRC000024"
}

```
---

---

# 创建转让/替代批次

URL: /zh-Hans/documentation/iaas/negociacao_recebiveis/assignment/criacao

---

### Request

ENDPOINT /trade_receivables/BASE_URL/assignment
MÉTODO POST

```json title='Request Body'
{
	"external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
    "assignment_date": "2024-04-01"
}
```

#### Body Params

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `external_id` * | string | 集成合作伙伴系统中该批次的唯一标识键。 | 最多50 |
| `assignment_date` *| string | 转让日期 | YYYY-MM-DD

### Response

STATUS 201

```json title='Response Body'
{
    "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "status": "pending_assets_insertion",
}
```

### 可能的错误

STATUS 404

Response Body

```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

Response Body

```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

Response Body

```json
{
  "title": "Assignment Configuration is not active.",
  "description": "Assignment Configuration is not active.",
  "translation": "A configuração de cessão não está ativa.",
  "code": "TRC000014"
}

```
---

STATUS 400

Response Body

```json
{
  "title": "Already Exists This External Id",
  "description": "Already Exists This External Id",
  "translation": "Ja existe lote com esse external_id",
  "code": "TRC000041"
}

```

---

# 转让文件

URL: /zh-Hans/documentation/iaas/negociacao_recebiveis/assignment/documento_da_cessao

---

### Request

ENDPOINT /trade_receivables/BASE_URL/assignment/ASSIGNMENT_EXTERNAL_ID/assignment_term_link
MÉTODO GET

### Path Params

| 参数 | 描述 |
|---------------------------------|------------------------------------|
| `fund_class_key` | 基金的唯一键 |
| `assignment_configuration_key` | 转让配置键 |
| `assignment_external_id` | 批次的外部键 |

### Response 
情况01：返回文件

```json
{
   "assignment_term_url":"URL do termo não assinado",
   "signed_assignment_term_url":"URL do termo assinado"
}
```

:::info 说明
如果文件尚未签署，signed_assignment_term_url 字段可能为 None
:::

---

# 结束资产插入

URL: /zh-Hans/documentation/iaas/negociacao_recebiveis/assignment/fechamento

### Request

ENDPOINT /trade_receivables/BASE_URL/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",
}
```

### 可能的错误

STATUS 400

Response Body

```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"
}

```
---

---

# 转让批次列表

URL: /zh-Hans/documentation/iaas/negociacao_recebiveis/assignment/listagem

---

### Request

ENDPOINT /trade_receivables/fund_class/FUND_CLASS_KEY/assignments
MÉTODO GET

### Query Params

| 参数 | 描述 |
|------------------------------|--------------------------------------------------------------------------------------|
| `date` | 日期 (YYYY-MM-DD) |
| `status` | 转让状态 |
| `not_in_status` | 要从搜索中排除的状态列表 |
| `in_status` | 要包含在搜索中的状态列表 |

### Response 
情况01：返回一个批次

```json
{
  "data": [
    {
      "assignment_key": "UUID",
      "external_id": "ID EXTERNO",
      "name": "IDENTIFICADOR DA CESSÃO",
      "assignment_configuration": {
        "assignment_configuration_key": "UUID",
        "validation_configuration_key": "UUID",
        "assignment_configuration_name": "NOME DA CONFIGURAÇÃO",
        "assignment_contract_key": "UUID",
        "registry_type": "internal_registry | external_registry",
        "asset_type": "duplicata_mercantil | duplicata_servico | ccb",
        "fund_class": {
          "fund_class_key": "UUID",
          "name": "SAMPLE FUND NAME",
          "document_number": "00.000.000/0000-00",
          "accounting_date": "YYYY-MM-DD",
          "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"
        },
        "consultant_decision_type": "automatic_approval | manual_approval",
        "consultant": {
          "consultant_key": "UUID",
          "document_number": "00.000.000/0000-00",
          "name": "SAMPLE CONSULTANT NAME"
        }
      },
      "assignment_number": "01234567",
      "assignment_date": "YYYY-MM-DD",
      "status": "pending | completed | canceled",
      "assignment_term_key": "UUID",
      "disbursement": {
        "target_account": {
          "owner": {
            "document_number": "00.000.000/0000-00"
          },
          "status": "active | inactive",
          "account_key": "UUID",
          "account_type": "checking_account",
          "account_digit": "4",
          "account_branch": "001",
          "account_number": "12345",
          "default_account": true,
          "financial_institution_code": "000",
          "financial_institution_ispb": "00000000"
        }
      },
      "assignment_total_value": 0.00,
      "assignment_irr": 0.0000
    }
  ],
  "limit": 10,
  "page": 0,
  "is_last_page": false
}
```

<!--

STATUS 200

```json title='Response Body'

```-->

---

# 获取转让批次

URL: /zh-Hans/documentation/iaas/negociacao_recebiveis/assignment/recuperacao

---

### Request

ENDPOINT /trade_receivables/BASE_URL/assignment/EXTERNAL_ID
MÉTODO GET

### Response

STATUS 200

```json title='Response Body'
{
    "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "status": "pending_assets_insertion",
}
```

---

# 如何创建转让？

URL: /zh-Hans/documentation/iaas/negociacao_recebiveis/assignment/video_cessao

---

## 🎥 视频 - 如何通过 Python 创建转让？

在视频中，我们介绍了创建转让的完整流程步骤。以下是文档中的具体步骤。

### [第1步 - 创建批次](/documentation/iaas/negociacao_recebiveis/assignment/criacao)

### [第2步 - 插入资产](/documentation/iaas/negociacao_recebiveis/asset/criacao_co)

### [第3步 - 发送文件](/documentation/iaas/negociacao_recebiveis/asset/documents)

### [第4步 - 关闭批次](/documentation/iaas/negociacao_recebiveis/assignment/fechamento)

---

# Webhooks

URL: /zh-Hans/documentation/iaas/negociacao_recebiveis/assignment/webhooks

---

#### 在资格审核中被拒绝

STATUS Denied

```json title='Webhook Body'
{
    "data":{
        "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "assignment_new_status": "denied",
    },
    "webhook_type":"trade_receivables.assignment_status_change",
    "webhook_datetime":"2024-04-23T15:08:30Z"
    
}
```

#### 待管理员审批（通过资格审核）

STATUS Pending Manager Approval

```json title='Webhook Body'
{
    "data":{
        "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "assignment_new_status": "pending_manager_approval",
    },
    "webhook_type":"trade_receivables.assignment_status_change",
    "webhook_datetime":"2024-04-23T15:08:30Z"
}
```

#### 待签署转让协议

STATUS Pending Assignment Term Signature

```json title='Webhook Body'
{ 
    "data":{
        "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "assignment_new_status": "pending_assignment_term_signature",
    },
    "webhook_type":"trade_receivables.assignment_status_change",
    "webhook_datetime":"2024-04-23T15:08:30Z"
}
```

#### 待支付

STATUS Pending Payment

```json title='Webhook Body'
{
    "data":{
        "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "assignment_new_status": "pending_payment",
   },
   "webhook_type":"trade_receivables.assignment_status_change",
   "webhook_datetime":"2024-04-23T15:08:30Z"
}
```

#### 已完成

STATUS Completed

```json title='Webhook Body'
{
   "data":{
        "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "assignment_new_status": "completed",
   },
   "webhook_type":"trade_receivables.assignment_status_change",
   "webhook_datetime":"2024-04-23T15:08:30Z"

}
```

#### 已丢弃

STATUS Discarded

```json title='Webhook Body'
{
   "data":{
        "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "assignment_new_status": "discarded",
   },
   "webhook_type":"trade_receivables.assignment_status_change",
   "webhook_datetime":"2024-04-23T15:08:30Z"

}
```

---

# Fluxo de Cessão

URL: /zh-Hans/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 ou contrato descontado). 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 →

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).
:::

---

# 简介

URL: /zh-Hans/documentation/iaas/negociacao_recebiveis/inicio

本节将介绍一系列 API，这些 API 用于实现将信用权利转让给 QI CTVM 管理的投资基金的流程。需要特别说明的是，购买国库券或公司债券等其他资产的流程不适用于此场景。

要访问这些服务，请联系团队 [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br)，以便在沙盒（同质化）环境和生产环境中完成相应的授权配置。

有关该产品的详细工作原理，请访问我们的[信用权利转让手册](/documentation/iaas/negociacao_recebiveis/manual_api)。建议将其与此处提供的路由结合阅读，以便集成合作伙伴更好地理解产品，并相应地设计更合适的服务。

## 转让流程

下图展示了主路径、分支以及每个步骤产生的状态。将鼠标悬停在节点上可查看端点，点击可打开该步骤的文档。

<FlowDiagram
  columns={3}
  labels={{ you: '集成方', qitech: 'QI Tech', manager: '基金管理人', docs: '查看文档' }}
  nodes={[
    { id: 'criacao', row: 1, col: 2, actor: 'you', num: 1,
      title: '创建批次',
      status: 'pending_assets_insertion',
      desc: '所有将转让给基金的资产的容器，由唯一的 external_id 标识。',
      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: '插入资产',
      status: '资产：pending_eligibility',
      desc: '每个资产一次请求，需提供操作信息、分期数据和债务人信息。',
      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: '提交文件',
      desc: '只有在提交完产品所要求的全部文件后，资产才会继续流转。',
      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: '关闭插入',
      status: 'completed_assets_insertion',
      desc: '表示所有资产已插入完毕，并将批次释放进入合格性审核。',
      endpoint: { method: 'PUT', path: '.../assignment/{assignment_external_id}' },
      href: '/documentation/iaas/negociacao_recebiveis/assignment/fechamento' },

    { id: 'elegibilidade', row: 5, col: 2, actor: 'qitech',
      title: '资产与批次的合格性审核',
      desc: '先逐个审核资产，再审核整个批次。被拒的资产不会留在批次中。',
      href: '/documentation/iaas/negociacao_recebiveis/asset/webhooks' },

    { id: 'reprovado', row: 6, col: 1, actor: 'qitech', tone: 'end',
      title: '被拒',
      status: 'denied',
      desc: '资产或批次未通过合格性审核，或基金管理人拒绝了该批次。流程终止。' },

    { id: 'aprovacao', row: 6, col: 2, actor: 'manager', tag: '视配置而定', num: 5,
      title: '顾问和/或管理人审批',
      status: 'pending_manager_approval',
      desc: '仅当转让配置要求时才为人工步骤。否则审批自动完成，集成方无需任何操作。',
      endpoint: { method: 'PUT', path: '.../assignment/{assignment_external_id}' },
      href: '/documentation/iaas/negociacao_recebiveis/assignment/aprovacao' },

    { id: 'termo', row: 7, col: 2, actor: 'qitech',
      title: '生成并签署转让条款',
      status: 'pending_assignment_term_signature',
      desc: '批次获批后，转让条款将被生成并由各方签署。',
      href: '/documentation/iaas/negociacao_recebiveis/assignment/webhooks' },

    { id: 'pagamento', row: 8, col: 2, actor: 'qitech',
      title: '向转让方付款',
      status: 'pending_payment',
      desc: '转让款项将支付给转让方。',
      href: '/documentation/iaas/negociacao_recebiveis/assignment/webhooks' },

    { id: 'encarteirado', row: 9, col: 2, actor: 'qitech', tone: 'ok',
      title: '资产纳入基金投资组合',
      status: 'completed',
      desc: '资产进入基金投资组合，批次周期结束。',
      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: '自动', via: 'right', dashed: true },
    { from: 'aprovacao', to: 'reprovado', tone: 'end' },
    { from: 'aprovacao', to: 'termo', label: '批准', tone: 'ok' },
    { from: 'termo', to: 'pagamento', label: 'webhook' },
    { from: 'pagamento', to: 'encarteirado', label: 'webhook' },
  ]}
/>

:::tip 完整流程
如需了解每一次状态流转、webhook 载荷以及异常路径，请参阅[转让流程](/documentation/iaas/negociacao_recebiveis/fluxo_cessao)。
:::

## 转让批次
创建转让批次需要遵循3个步骤。
* 创建批次
* 插入将被购买的资产
* 关闭批次

## 替代批次
创建替代批次需要遵循4个步骤。
* 创建批次
* 插入将被回购的资产
* 插入将被购买的资产
* 关闭批次

转让和替代流程之间的区别仅在于插入将被回购资产的步骤。

---

# 转让配置列表

URL: /zh-Hans/documentation/iaas/negociacao_recebiveis/listagem

---

### Request

ENDPOINT /trade_receivables/fund_class/FUND_CLASS_KEY/assignment_configurations
MÉTODO GET

### Path Params

| 参数 | 描述 |
|---------------------|-------------------------|
| `fund_class_key` | 基金的唯一键 |

### Query Params

| 参数 | 描述 |
|---------------------|-------------------------|
| `assignment_contract_key` | 生成该配置的合同唯一标识键 |
| `asset_type` | 资产类型 |
| `assignor_document_number` | 转让人的 CPF/CNPJ |

### Response 
情况01：返回一个配置

```json
{
  "data": [
    {
      "assignment_configuration_key": "UUID",
      "assignment_configuration_name": "NOME DA CONFIGURAÇÃO",
      "assignment_contract_key": "UUID",
      "registry_type": "internal_registry | external_registry",
      "asset_type": "duplicata_mercantil | duplicata_servico | ccb",
      "fund_class": {
        "fund_class_key": "UUID",
        "name": "SAMPLE FUND NAME",
        "document_number": "00.000.000/0000-00",
        "accounting_date": "YYYY-MM-DD",
        "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"
      },
      "consultant_decision_type": "automatic_approval | manual_approval",
      "consultant": {
        "consultant_key": "UUID",
        "document_number": "00.000.000/0000-00",
        "name": "SAMPLE CONSULTANT NAME"
      }
    }
  ],
  "limit": 10,
  "page": 0,
  "is_last_page": true
}
```

---

# 信用权利转让手册

URL: /zh-Hans/documentation/iaas/negociacao_recebiveis/manual_api

本手册描述了向 QI CTVM 管理的基金转让信用权利所涉及的步骤。此外，还解释了产品的业务规则以及集成合作伙伴需要注意的主要事项，以便实现更快速、更高效的集成。

## 前提条件

1. 已签订转让合同，并已激活相应产品（参见**[转让人同质化](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato)** API）；

2. 只有基金管理员、合同中的转让人以及关联的发起人才能访问此服务。

3. 已存储基金受让人的唯一标识键（ fund_class_key ）以及转让配置的唯一标识键（ assignment_configuration_key ）。

```python
BASE_URL = "/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}"
```

:::info
_**BASE_URL**_ 是本 API 所有端点使用的路径。
:::

## 状态流程

转让流程有两个主要实体，其状态机之间存在关联。一方面是批次，称为 assignment ；另一方面是资产，称为 asset 。对于批次，其流程如下：

```mermaid
graph TB
LA[pending_assets_insertion] --> |Encerrar Inserção| LB[completed_assets_insertion]
LB --> |Todos Ativos Pré Aprovados ou Descartados| LC[pending_eligibility]
LC --> |Não aceito| LZ[discarded]
LC --> |Aceito| LD[pending_manager_approval]
LD --> |Gestor reprovou| LZ
LD --> |Gestor aprovou| LE[pending_assignment_term_signature]
LE --> |Termo Assinado| LG[pending_payment]
LG --> |Pagamento| LH[pending_assets_wallet_inclusion]
LH --> |Todos Ativos Encarteirados| LI[completed]
```

对于资产，流程如下：

```mermaid
graph TB
LA[pending_eligibility] --> |Aceito| LB[pending_documentation]
LA --> |Não aceito| LZ[discarded]
LB --> |Documentos Inseridos| LC[pre_approved]
LC --> |Gestor aprovou| LE[pending_formalization]
LE --> |Pagamento| LH[sending_to_wallet]
LH --> |Encarteirado| LI[completed]
```

## 集成摘要

总结而言，要完成资产入库，需遵循以下步骤：

1. 创建批次；
2. 插入资产；
3. 结束资产插入；
4. 资产资格审核 Webhook；
6. 发送文件；
7. 批次资格审核 Webhook；
8. 管理员审批；
9. 签署转让协议；
10. 转让支付；
11. 资产入库；

## 1 - 创建批次

**[创建批次](/documentation/iaas/negociacao_recebiveis/assignment/criacao)**仅需要集成合作伙伴系统生成的唯一标识符。该标识符将用于 Webhook 回调和其他功能路由（如下文所述）。

此标识符必须是唯一的，QI CTVM 系统不允许合作伙伴重复发送同一批次。

## 2 - 插入资产

插入资产是整个集成中最精细的过程。本节将解释资产创建所涉及的业务规则，包括与类型无关的规则以及特定类型的规则。

对于理解此 API，理解资产价值和资产购买价值的概念非常重要。为此，我们使用以下符号：

**[A]** 为资产购买价值，在对象根部提供，表示基金应为该资产支付的金额。

**[B]** 为操作溢价的总和。可通过将所提供的所有 premiums 中的 total_values 求和得出。

**[C]** 为操作折扣的总和。可通过将所提供的所有 deductions 中的 total_values 求和得出。

**[D]** 为资产价值，可通过以下公式推导：

:::tip 关系
[D] = [A] - [B] + [C]
:::

### 2.1 - 与资产类型无关的规则

#### 2.1.1 - 资产类型与转让配置的兼容性

每个转让配置对应唯一的资产类型。同一批次中永远不可能混合 CCB 和应收票据。激活产品生成的 assignment_configuration_key 包含特定资产类型，在给定配置中只接受该类型。
如果违反此规则，将返回以下错误：

Response Body
STATUS 400

```json title='Response Body'
{
    "code": "TRC000025"
}
```

#### 2.1.2 - 向已完成批次插入

如果尝试将资产插入已关闭的批次，集成合作伙伴将收到以下错误：

Response Body
STATUS 400

```json title='Response Body'
{
    "code": "TRC000022"
}
```

#### 2.1.3 - 邮政编码验证

操作借款人地址对象的邮政编码必须有效。因此，如果提供了不存在的邮政编码，请求将不被接受，并返回以下错误：

Response Body
STATUS 404

```json title='Response Body'
{
    "code": "TRC000070"
}
```

#### 2.1.4 - External ID 唯一性

同一资产不能被合作伙伴转让两次。因此，如果该资产已存在于我们的数据库中且未被丢弃，将引发以下错误：

Response Body
STATUS 409

```json title='Response Body'
{
    "code": "TRC000054"
}
```

### 2.2 - 信贷操作规则

信贷操作是指那些源自借款人承诺的资产，借款人按一定利率借款，并按照特定流程履行还款承诺。因此，这些资产始终有未偿本金和会增加该价值的利率。创建信贷操作所需的数据结构可在**[此页面](/documentation/iaas/negociacao_recebiveis/asset/criacao_co)**找到。

#### 2.2.1 - 资产价值与未偿本金不符

对于信贷操作，资产价值必须始终大于或等于未偿本金（信贷操作对象的 principal_value 字段）。与此业务规则相关的错误为：

Response Body
STATUS 409

```json title='Response Body'
{
    "code": "TRC000054"
}
```

#### 2.2.2 - 发行价值与未偿本金不符

合同的发行价值必须始终大于或等于未偿本金。与此业务规则相关的错误为：

Response Body
STATUS 409

```json title='Response Body'
{
    "code": "TRC000054"
}
```

#### 2.2.3 - 分期付款顺序

信贷操作的所有分期付款必须按到期日（ maturity_date ）升序排列，且编号（ installment_number ）连续。因此，如果流程从第1期开始，下一期必须是第2期，然后是第3期，以此类推。

与这些规则相关的错误分别为：

Response Body
STATUS 409

```json title='Response Body'
{
    "code": "TRC000054"
}
```

Response Body
STATUS 409

```json title='Response Body'
{
    "code": "TRC000054"
}
```

#### 2.2.4 - 固定利率和浮动利率对象

根据操作的利率类型（ interest_rate_type ），需要提供固定和/或浮动利率对象。如果利率类型为固定利率，则**只**需要提供固定利率对象；而对于浮动利率，浮动利率对象为**必填项**，固定利率对象为**可选项**。例如，如果操作

<!-- #### 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 - 结束资产插入

在批次的所有资产创建完成后，合作伙伴可以命令**[结束资产插入](/documentation/iaas/negociacao_recebiveis/assignment/fechamento)**。这一步骤很重要，以便 QI CTVM 系统知道从此时起，当所有资产都经过资格审核并提供了所有文件后，可以对整个批次进行资格审核。

:::info
无需等待所有资产的 Webhook。当不再需要插入资产时，可以执行此命令。
:::

## 4 - 资产资格审核 Webhook

随着资产被基金资格规则逐一分析，系统将逐个返回 **[Webhooks](/documentation/iaas/negociacao_recebiveis/asset/webhooks)**。这些 Webhooks 将通过合作伙伴在创建时提供的资产唯一标识符进行标识。

分析结果只有两种可能：资产**通过**或**被拒绝**。如果是前者，资产将继续其流程，等待文件插入；否则，它将进入已丢弃状态，不会进入后续步骤。

## 5 - 发送文件

当某一资产通过资格审核后，合作伙伴可以继续**[插入产品所需的文件](/documentation/iaas/negociacao_recebiveis/asset/documents)**。每个所需文件需要发送一个请求。内容将通过二进制文件的 Base64 编码传输，从而可以通过 JSON 完成，与我们系统的所有其他 API 一致。

注意，要执行此请求，除了文件的二进制内容外，还需要提供该文件的文档类型。只有提交了所有所需文件，资产才会继续流程。当这一切发生时，资产将进入预审批（ pre_approved ）状态。

:::warning 注意
所需文件取决于产品类型和基金章程。这可以通过获取转让合同的产品来获取，该产品已激活以获取该批次的 assignment_configuration_key 。
::: 

:::info
无需已命令结束资产插入。如果想将发送文件的逻辑与接收 Webhook 关联，这完全可行且推荐。
:::

## 6 - 批次资格审核 Webhook

一旦某个已结束资产插入的批次，且其所有资产都已被丢弃或预批准，它将进行整个批次的资格审核分析。即使所有资产都已被批准，整个批次也可能导致基金出现某种不合规情况。因此需要第二步进行资格审核。

与资产类似，资格审核可能产生两种结果：批准或拒绝。结果将通过 **[Webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks)** 通知，但这次以批次的 external_id 标识。

如果批次被拒绝，它将被丢弃，流程结束。否则，它将进入管理员分析和审批阶段。

## 7 - 管理员审批

管理员审批必须通过**[特定请求](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao)**或通过我们的**[门户](https://manager-dash.qidtvm.com.br/)**来完成。如果批次被拒绝，它将被丢弃，流程结束。否则，系统将生成转让协议并发送签署，将批次置于 pending_assignment_term_signature 状态，直到所有相关方签署文件。

## 8 - 签署转让协议

一旦签署，我们会发送一个 **[Webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks)**，通知协议已签署并应继续进行支付，因此进入 pending_payment 状态。

## 9 - 转让支付

此时，系统向转让人支付转让总金额，即所有未丢弃资产的 total_purchase_value 之和，支付到产品激活时提供的账户。一旦付款确认，我们发送一个 **[Webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks)**，资产开始入库。

## 10 - 资产入库

最后，一旦所有资产都被妥善入库，批次将变为 completed ，从此时起，集成合作伙伴可以完全确认所有资产已妥善存入基金的库存中。

---

# Listagem de Solicitações de Amortização

URL: /zh-Hans/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`

| 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 |

---

# 分页查询金融申请

URL: /zh-Hans/documentation/iaas/passivo/aplicacao_financeira/busca_paginada_aplicacoes_financeiras

---

### Requests

按份额持有人查询：此端点将返回某份额持有人的所有金融申请
ENDPOINT /quota/investor/INVESTOR_KEY/financial_applications
MÉTODO GET
STATUS 200
按基金查询：此端点将返回某基金的所有金融申请
ENDPOINT /quota/fund_class/FUND_CLASS_KEY/financial_applications
MÉTODO GET
STATUS 200

### Query Params

| 参数 | 描述 |
|------------------|--------------------------------------------------------------------------------------|
| `quotation_date` | 申请的报价日期 |
| `status` | 所需的 **[Financial Application Status](#financial_application_status)** 列表 |
| `application_from_datetime` | 仅返回申请日期时间大于或等于所提供值的金融申请。 |
| `application_to_datetime` | 仅返回申请日期时间小于或等于所提供值的金融申请。 |

### Responses

情况01：查询成功

```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
| 字段 | 类型 | 描述 |
|---------------|--------|------------------------------------------------------------------------------|
| `data` | array | **[Financial Application](#financial_application)** 对象列表 |
| `limit` | int | 每页返回的对象数量限制 |
| `page` | int | 返回的页码 |
| `is_last_page`| boolean| 指示返回的页面是否为最后一页的信息 |

### Financial Application
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|----------|---------------------------------------------------------------------------------|------------|
| `external_id` | string | 外部标识符 | 最多100 |
| `financial_application_key` | string | 金融申请的唯一标识键 | 36 |
| `share_capital` | float | 投资金额 | - |
| `investor_position` | JSON | **[Investor Position](#investor_position)** 对象 | - |
| `original_principal_value` | float | 每单位原始本金价值 | - |
| `current_principal_value` | float | 每单位当前本金价值 | - |
| `original_number_of_units` | float | 原始份额数量 | - |
| `current_number_of_units` | float | 当前份额数量 | - |
| `quotation_date` | string | 报价日期 | - |
| `application_datetime` | string | 金融申请创建日期 | - |
| `status` | string | **[Financial Application Status](#financial_application_status)** 枚举值 | - |
| `status_events` | array | **[Status Event](#status_event)** 对象列表 | - |
| `capital_returns` | array | **[Capital Return](#capital_return)** 对象列表 | - |

### Financial Application Status
| 枚举值 | 描述 |
|--------------------------|-------------------------------------------------|
| `pending_payment` | 待支付 |
| `pending_quote` | 待报价 |
| `quoted` | 已报价 |
| `settled` | 已完全摊销 |
| `redeemed` | 已完全赎回 |
| `canceled` | 已取消 |

### Investor Position
| 字段 | 类型 | 描述 |
|--------------------------|--------|-------------------------------------------------------|
| `investor` | JSON | **[Investor](#investor)** 对象 |
| `total_net_worth` | float | 投资者持仓净资产 |
| `total_number_of_quotas` | float | 投资者持仓份额数量 |
| `issuance_serie` | JSON | **[Issuance Serie](#issuance_serie)** 对象 |
| `investor_position_key` | JSON | 投资者持仓唯一标识键 |

### Investor
| 字段 | 类型 | 描述 | 字符数 |
|--------------------------|----------|---------------------------------------------------|------------|
| `name` | string | 投资者姓名 | 最多255 |
| `investor_key` | string | 投资者唯一标识键 | 36 |
| `document_number` | string | 投资者 CPF/CNPJ | 14或18 |
| `person_type` | string | 自然人 / 法人 / 基金类别 | 最多50 |
| `distributor` | JSON | **[Distributor](#distributor)** 对象 | - |
| `account_data` | JSON | **[Account Data](#account_data)** 对象 | - |

### Distributor
| 字段 | 类型 | 描述 | 字符数 |
|--------------------------|----------|---------------------------------------------------|------------|
| `name` | string | 分销商名称 | 最多255 |
| `distributor_key` | string | 分销商唯一标识键 | - |
| `document_number` | string | 分销商 CPF/CNPJ | 14或18 |
| `account_data` | JSON | **[Account Data](#account_data)** 对象 | - |

### Account Data
| 字段 | 类型 | 描述 |
|------------------------------|----------|-----------------------------------------------------------------------------|
| `account_digit` | string | 银行账户校验位 |
| `account_branch` | string | 银行账户支行编号 |
| `account_number` | string | 银行账户号码 |
| `financial_institution_code` | string | 金融机构代码 |
| `financial_institution_ispb` | string | 金融机构在巴西支付系统中的标识符 |

### Issuance Serie
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|----------|---------------------------------------------------|------------|
| `name` | string | 发行系列名称 | 最多255 |
| `issuance_serie_key` | string | 发行系列唯一标识键 | 36 |
| `cetip_code` | string | 发行系列在 CETIP 中作为资产的代码 | 10 |
| `start_date` | string | 发行系列开始日期 | 10 |
| `maturity_date` | string | 发行系列到期日期 | 10 |
| `original_quota_value` | float | 原始份额价值 | - |
| `remuneration_type` | string | 收益曲线 / 残差 | 最多50 |
| `investment_category` | string | FIDC / 多市场 | 最多50 |
| `condominum_type` | string | 开放式 / 封闭式 | 最多50 |
| `tax_classification` | string | 短期 / 长期 | 最多50 |
| `investment_restriction_type` | string | 无限制 / 合格投资者 / 专业投资者 | 最多50 |
| `minimum_share_capital` | float | 最低投资金额 | - |
| `accounting_date` | string | 发行系列记账日期 | 10 |
| `sub_class` | JSON | **[Sub Class](#sub_class)** 对象 | - |

### Sub Class 
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|----------|---------------------------------------------------|------------|
| `name` | string | 子类别名称 | 最多255 |
| `sub_class_key` | string | 子类别唯一标识键 | 36 |
| `subordination_level` | int | 子类别从属级别 | - |
| `fund_class` | JSON | **[Fund Class](#fund_class)** 对象 | - |

### Fund Class 
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|----------|---------------------------------------------------|------------|
| `name` | string | 基金类别名称 | 最多255 |
| `fund_class_key` | string | 基金类别唯一标识键 | 36 |
| `document_number` | string | 基金类别 CNPJ | - |

### Capital Return
| 字段 | 类型 | 描述 |
|---------------------------|----------|----------------------------------------------------------------|
| `capital_return_key` | string | 资本回报唯一标识键 |
| `origin_key` | string | 资本回报来源唯一标识键 |
| `net_value` | float | 资本回报净值 |
| `iof_value` | float | 资本回报 IOF 金额 |
| `ir_value` | float | 资本回报 IR 金额 |
| `payment_date` | string | 资本回报支付日期 |
| `capital_return_date` | string | 资本回报创建日期 |
| `status` | string | 发送至管理员 / 待支付 / 已支付 |
| `capital_return_type` | string | 摊销 / 赎回申请 / Come-cotas |
| `number_of_units` | float | 资本回报份额数量 |

---

# 金融申请结算分页查询

URL: /zh-Hans/documentation/iaas/passivo/aplicacao_financeira/busca_paginada_fechamento_das_aplicacoes_financeiras

---

### Requests

按基金类别查询
ENDPOINT /quota/fund_class/FUND_CLASS_KEY/financial_application_closings
MÉTODO GET
STATUS 200

#### Query Params

| 参数 | 描述 |
|--------------------|--------------------------------------------------------------------------------------|
| `accounting_date`  | 特定记账结算日期（格式 `yyyy-mm-dd`） |
| `from_date`        | 期间开始日期（格式 `yyyy-mm-dd`） |
| `to_date`          | 期间结束日期（格式 `yyyy-mm-dd`） |
| `limit`            | 每页返回的对象数量限制（最小 `0`，最大 `75`，默认 `75`） |
| `page`             | 返回的页码（最小 `0`，默认 `0`） |

:::warning 注意
必须发送 `accounting_date` **或** `from_date` 与 `to_date` 的组合。如果未发送其中任何一个参数，资源将返回必填参数缺失的错误。
:::

按投资者和金融申请查询
ENDPOINT /quota/investor/INVESTOR_KEY/financial_application/FINANCIAL_APPLICATION_KEY/financial_application_closings
MÉTODO GET
STATUS 200

#### Query Params

| 参数 | 描述 |
|--------------------------------------|--------------------------------------------------------------------------------------|
| `last_financial_application_closing` | 布尔值。当为 `true` 时，仅返回该申请的最新结算。默认：`false`。 |
| `limit`                              | 每页返回的对象数量限制（最小 `0`，最大 `500`，默认 `50`） |
| `page`                               | 返回的页码（最小 `0`，默认 `0`） |

### Responses

情况01：查询成功

```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 **注意**
`financial_application` 对象中以下字段为**条件性**字段——仅在底层数据存在时才会返回：

- `redemptions[]`、`amortizations[]`、`status_events[]`、`reserved_taxable_yields[]`：列表为空时省略。
- `original_number_of_quotas`（及其同级 `original_number_of_quotas_str`）、`current_principal_value`、`acquisition_cost`、`current_number_of_quotas`、`quotation_date`：在申请的报价处理后填充。
- `payment_method`、`financial_application_type`、`external_id`：每个申请可选——在创建或后续更新时提供时返回。

外层（`data`、`limit`、`page`、`is_last_page`）以及 **[Financial Application Closing](#financial-application-closing)** 对象的字段在响应中始终存在。
:::

### Page
| 字段 | 类型 | 描述 |
|---------------|--------|------------------------------------------------------------------------------|
| `data` | array | **[Financial Application Closing](#financial-application-closing)** 对象列表 |
| `limit` | int | 每页返回的对象数量限制 |
| `page` | int | 返回的页码 |
| `is_last_page`| boolean| 指示返回的页面是否为最后一页的信息 |

### Financial Application Closing
| 字段 | 类型 | 描述 |
|-------------------------|----------|---------------------------------------------------------------|
| `financial_application` | JSON | **[Financial Application](#financial-application)** 对象 |
| `total_value` | float | 申请结算总价值 |
| `number_of_quotas` | float | 结算相关份额数量 |
| `principal_value` | float | 结算相关本金价值 |
| `acquisition_cost` | float | 结算相关份额的购置成本 |
| `yield_value` | float | 毛收益价值 |
| `ir_value` | float | IR 金额 |
| `iof_value` | float | IOF 金额 |
| `taxable_yield_value` | float | 应税收益价值 |
| `accounting_date` | string | 申请结算相关记账日期 |

### Financial Application
| 字段 | 类型 | 描述 |
|------------------------------------|----------|---------------------------------------------------------------------------------|
| `financial_application_key` | string | 金融申请唯一标识键 |
| `share_capital` | float | 投资金额 |
| `status` | string | **[Financial Application Status](#financial-application-status)** 枚举值 |
| `investor` | JSON | **[Investor](#investor)** 对象 |
| `issuance_serie` | JSON | **[Issuance Serie](#issuance-serie)** 对象 |
| `redemptions` | array | **[Redemption](#redemption)** 对象列表 *（条件性）* |
| `amortizations` | array | **[Amortization](#amortization)** 对象列表 *（条件性）* |
| `status_events` | array | **[Status Event](#status-event)** 对象列表 *（条件性）* |
| `reserved_taxable_yields` | array | **[Reserved Taxable Yield](#reserved-taxable-yield)** 对象列表 *（条件性）* |
| `financial_application_type` | string | 金融申请类型 *（条件性）* |
| `original_number_of_quotas` | float | 原始份额数量 *（条件性）* |
| `original_number_of_quotas_str` | string | 原始份额数量的高精度字符串版本 *（条件性）* |
| `current_principal_value` | float | 每单位当前本金价值 *（条件性）* |
| `acquisition_cost` | float | 申请份额的购置成本 *（条件性）* |
| `current_number_of_quotas` | float | 当前份额数量 *（条件性）* |
| `payment_method` | string | 支付方式（`regular`、`cetip`、`b3`） *（条件性）* |
| `quotation_date` | string | 报价日期 *（条件性）* |
| `external_id` | string | 外部标识符 *（条件性）* |

### Financial Application Status
| 枚举值 | 描述 |
|-------------------|----------------------------|
| `pending_payment` | 待支付 |
| `pending_quote` | 待报价 |
| `quoted` | 已报价 |
| `settled` | 已完全摊销 |
| `redeemed` | 已完全赎回 |
| `canceled` | 已取消 |

### Investor
| 字段 | 类型 | 描述 |
|-----------------------------|----------|------------------------------------------------------|
| `investor_key` | string | 投资者唯一标识键 |
| `name` | string | 投资者姓名 |
| `person_type` | string | `natural_person` / `legal_person` / `fund_class` |
| `distributor` | JSON | **[Distributor](#distributor)** 对象 |
| `document_number` | string | 投资者 CPF/CNPJ *（条件性）* |
| `external_id` | string | 投资者外部标识符 *（条件性）* |
| `external_distribution_key` | string | 外部分销键 *（条件性）* |

### Distributor
| 字段 | 类型 | 描述 |
|--------------------------|----------|---------------------------------------------------|
| `distributor_key` | string | 分销商唯一标识键 |
| `name` | string | 分销商名称 |
| `document_number` | string | 分销商 CNPJ |
| `account_data` | JSON | 分销商银行账户数据对象 |

### Issuance Serie
| 字段 | 类型 | 描述 |
|----------------------------------|----------|----------------------------------------------------------------------------------------------|
| `issuance_serie_key` | string | 发行系列唯一标识键 |
| `name` | string | 发行系列名称 |
| `serie` | string | 系列标识符 |
| `internal_code` | string | 系列内部代码 |
| `status` | string | 发行系列状态枚举值 |
| `original_quota_value` | float | 原始份额价值 |
| `current_quota_value` | float | 当前份额价值（由 `current_net_worth` / `current_number_of_quotas` 计算） |
| `current_number_of_quotas` | float | 当前流通份额数量 |
| `current_net_worth` | float | 当前净资产 |
| `current_principal_value` | float | 当前本金价值 |
| `performance_fee_current_value` | float | 当前业绩费 |
| `minimum_share_capital` | float | 最低投资金额 |
| `remuneration_type` | string | 收益类型（枚举值） |
| `interest_rate_type` | string | 利率类型（枚举值） |
| `processing_method` | string | 系列处理方法（枚举值） |
| `operation_period_configuration` | JSON | 运营期配置 |
| `sub_class` | JSON | **[Sub Class](#sub-class)** 对象 |
| `pre_fixed` | JSON | 预固定配置 *（条件性）* |
| `post_fixed` | JSON | 后固定配置 *（条件性）* |
| `isin_code` | string | ISIN 代码 *（条件性）* |
| `external_id` | string | 发行系列外部标识符 *（条件性）* |
| `specific_interest_rate_data` | JSON | 特定利率数据 *（条件性）* |

### Sub Class
| 字段 | 类型 | 描述 |
|------------------------|----------|---------------------------------------------------|
| `sub_class_key` | string | 子类别唯一标识键 |
| `name` | string | 子类别名称 |
| `subordination_level` | int | 子类别从属级别 |
| `fund_class` | JSON | **[Fund Class](#fund-class)** 对象 |

### Fund Class
| 字段 | 类型 | 描述 |
|--------------------------------|----------|---------------------------------------------------|
| `fund_class_key` | string | 基金类别唯一标识键 |
| `name` | string | 基金类别名称 |
| `short_name` | string | 基金类别简称 |
| `document_number` | string | 基金类别 CNPJ |
| `accounting_date` | string | 基金类别记账日期 |
| `sub_type` | string | 基金类别子类型（枚举值） |
| `tax_classification_id` | string | 税务分类（枚举值） |
| `condominum_type_id` | string | 集合形式（枚举值） |
| `investment_category_id` | string | 投资类别（枚举值） |
| `prevent_payment` | boolean | 阻止支付标志 |
| `integralization_account_key` | string | 缴款账户键 |
| `manager` | JSON | **[Manager](#manager)** 对象 |

### Manager
| 字段 | 类型 | 描述 |
|---------------------|----------|---------------------------------------------|
| `manager_key` | string | 管理人唯一标识键 |
| `manager_name` | string | 管理人姓名 |
| `document_number` | string | 管理人 CNPJ |

---

# 通过键查询金融申请

URL: /zh-Hans/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
 

情况01：查询成功

```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
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|----------|---------------------------------------------------------------------------------|------------|
| `external_id` | string | 外部标识符 | 最多100 |
| `financial_application_key` | string | 金融申请唯一标识键 | 36 |
| `share_capital` | float | 投资金额 | - |
| `investor_position` | JSON | **[Investor Position](#investor_position)** 对象 | - |
| `original_principal_value` | float | 每单位原始本金价值 | - |
| `current_principal_value` | float | 每单位当前本金价值 | - |
| `original_number_of_units` | float | 原始份额数量 | - |
| `current_number_of_units` | float | 当前份额数量 | - |
| `quotation_date` | string | 报价日期 | - |
| `status` | string | **[Financial Application Status](#financial_application_status)** 枚举值 | - |
| `status_events` | array | **[Status Event](#status_event)** 对象列表 | - |
| `capital_returns` | array | **[Capital Return](#capital_return)** 对象列表 | - |

### Financial Application Status
| 枚举值 | 描述 |
|--------------------------|-------------------------------------------------|
| `pending_payment` | 待支付 |
| `pending_quote` | 待报价 |
| `quoted` | 已报价 |
| `settled` | 已完全摊销 |
| `redeemed` | 已完全赎回 |
| `canceled` | 已取消 |

### Investor Position
| 字段 | 类型 | 描述 |
|--------------------------|--------|-------------------------------------------------------|
| `investor` | JSON | **[Investor](#investor)** 对象 |
| `total_net_worth` | float | 投资者持仓净资产 |
| `total_number_of_quotas` | float | 投资者持仓份额数量 |
| `issuance_serie` | JSON | **[Issuance Serie](#issuance_serie)** 对象 |
| `investor_position_key` | JSON | 投资者持仓唯一标识键 |

### Investor
| 字段 | 类型 | 描述 | 字符数 |
|--------------------------|----------|---------------------------------------------------|------------|
| `name` | string | 投资者姓名 | 最多255 |
| `investor_key` | string | 投资者唯一标识键 | 36 |
| `document_number` | string | 投资者 CPF/CNPJ | 14或18 |
| `person_type` | string | 自然人 / 法人 / 基金类别 | 最多50 |
| `distributor` | JSON | **[Distributor](#distributor)** 对象 | - |
| `account_data` | JSON | **[Account Data](#account_data)** 对象 | - |

### Distributor
| 字段 | 类型 | 描述 | 字符数 |
|--------------------------|----------|---------------------------------------------------|------------|
| `name` | string | 分销商名称 | 最多255 |
| `distributor_key` | string | 分销商唯一标识键 | - |
| `document_number` | string | 分销商 CPF/CNPJ | 14或18 |
| `account_data` | JSON | **[Account Data](#account_data)** 对象 | - |

### Account Data
| 字段 | 类型 | 描述 |
|------------------------------|----------|-----------------------------------------------------------------------------|
| `account_digit` | string | 银行账户校验位 |
| `account_branch` | string | 银行账户支行编号 |
| `account_number` | string | 银行账户号码 |
| `financial_institution_code` | string | 金融机构代码 |
| `financial_institution_ispb` | string | 金融机构在巴西支付系统中的标识符 |

### Issuance Serie
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|----------|---------------------------------------------------|------------|
| `name` | string | 发行系列名称 | 最多255 |
| `issuance_serie_key` | string | 发行系列唯一标识键 | 36 |
| `cetip_code` | string | 发行系列在 CETIP 中作为资产的代码 | 10 |
| `start_date` | string | 发行系列开始日期 | 10 |
| `maturity_date` | string | 发行系列到期日期 | 10 |
| `original_quota_value` | float | 原始份额价值 | - |
| `remuneration_type` | string | 收益曲线 / 残差 | 最多50 |
| `investment_category` | string | FIDC / 多市场 | 最多50 |
| `condominum_type` | string | 开放式 / 封闭式 | 最多50 |
| `tax_classification` | string | 短期 / 长期 | 最多50 |
| `investment_restriction_type` | string | 无限制 / 合格投资者 / 专业投资者 | 最多50 |
| `minimum_share_capital` | float | 最低投资金额 | - |
| `accounting_date` | string | 发行系列记账日期 | 10 |
| `sub_class` | JSON | **[Sub Class](#sub_class)** 对象 | - |

### Sub Class 
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|----------|---------------------------------------------------|------------|
| `name` | string | 子类别名称 | 最多255 |
| `sub_class_key` | string | 子类别唯一标识键 | 36 |
| `subordination_level` | int | 子类别从属级别 | - |
| `fund_class` | JSON | **[Fund Class](#fund_class)** 对象 | - |

### Fund Class 
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|----------|---------------------------------------------------|------------|
| `name` | string | 基金类别名称 | 最多255 |
| `fund_class_key` | string | 基金类别唯一标识键 | 36 |
| `document_number` | string | 基金类别 CNPJ | - |

### Capital Return
| 字段 | 类型 | 描述 |
|---------------------------|----------|----------------------------------------------------------------|
| `capital_return_key` | string | 资本回报唯一标识键 |
| `origin_key` | string | 资本回报来源唯一标识键 |
| `net_value` | float | 资本回报净值 |
| `iof_value` | float | 资本回报 IOF 金额 |
| `ir_value` | float | 资本回报 IR 金额 |
| `payment_date` | string | 资本回报支付日期 |
| `capital_return_date` | string | 资本回报创建日期 |
| `status` | string | 发送至管理员 / 待支付 / 已支付 |
| `capital_return_type` | string | 摊销 / 赎回申请 / Come-cotas |
| `number_of_units` | float | 资本回报份额数量 |

---

# 创建金融申请

URL: /zh-Hans/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"
}
```

:::note **必填字段**
- issuance_serie_key 
- shared_capital
:::

:::caution **注意**
**payment_method** 和 **central_depositary** 为可选字段，如果未发送，将使用默认选项。

- 这将在未来版本中被废弃，届时这些字段将成为必填项
:::
### Body params
| 字段 | 类型 | 描述 |
|-----------------------------------|----------|--------------------------------------------------------------------------------------------------------------------------|
| `issuance_serie_key` | string | 发行系列唯一标识键 |
| `share_capital` | float | 金融申请金额 |
| `payment_method` | string | 支付方式。预期值：<br />• regular: Pix 或 TED **(默认)**<br />• cetip: 通过 Cetip |
| `central_depositary` | string | 托管类型。预期值：<br />• unregistered: 无登记机构<br />• cetip: 在 Cetip 登记 **(默认)** |

### Response
```json title='Response Body'
{
    "financial_application_key": "UUID"
}
```

---

# 手动批准份额锁定

URL: /zh-Hans/documentation/iaas/passivo/bloqueio_de_cotas/aprovar_bloqueio_pendente_aprovacao

---

### 简介
本资源旨在详细说明锁定的手动审批流程。

:::warning 注意
只有当锁定金额超过总净资产价值的 **3.8%** 时，份额锁定才会进入待手动审批状态。

:::

### 审批

ENDPOINT quota_lock/investor/INVESTOR_KEY/quota_lock/QUOTA_LOCk_KEY/pending_manual_approval/approve
MÉTODO PUT
STATUS 204

### 拒绝

ENDPOINT quota_lock/investor/INVESTOR_KEY/quota_lock/QUOTA_LOCk_KEY/pending_manual_approval/reprove
MÉTODO PUT
STATUS 204

---

# 查询份额锁定

URL: /zh-Hans/documentation/iaas/passivo/bloqueio_de_cotas/consulta_de_bloqueio_de_cotas

---

### 简介
本资源旨在详细说明**投资者**的某个**份额锁定**请求的信息。

### 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
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------|------- |------------------------------------------------------------------------|------------|
| `quota_lock_key` | string | 份额锁定唯一标识符 | 36 |
| `status` | string | 份额锁定状态枚举值 | 最多255 |
| `type` | string | 份额锁定类型枚举值 | 最多255 |
| `original_locked_quotas` | float | 原始锁定份额数量 | - |
| `current_locked_quotas` | float | 当前锁定份额数量 | - |
| `original_locked_value` | float | 原始锁定价值 | - |
| `current_locked_value` | float | 当前锁定价值 | - |
| `collateral` | JSON | **[担保](#collateral)** 对象 | - |
| `investor_positions_locks` | Array | **[投资者持仓锁定](#locked-investor-positions)** 对象列表 | - |

### Quota Lock Status
| 枚举值 | 描述 |
|--------------------------|-----------------------|
| `pending_documents` | 待文件 |
| `pending_approval` | 待审批 |
| `denied` | 已拒绝 |
| `approved` | 已批准 |

### Quota Lock Type
| 枚举值 | 描述 |
|--------------------------|-----------------------|
| `collateral` | 担保 |

### Collateral
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------|------- |-----------------------------------------------------------------------|------------|
| `recipient` | JSON | **[受益人](#recipient)** 对象 | - |
| `borrower` | JSON | **[借款人](#borrower)** 对象 | - |
| `assets` | Array | **[资产](#asset)** 对象列表 | - |
| `issuance_series` | Array | **[发行系列](#issuance_serie)** 对象列表 | - |
| `documents` | Array | **[担保文件](#collateral_document)** 对象列表 | - |

### Recipient
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------|------- |-----------------------------------------------------|------------|
| `name` | string | 受益人姓名 | 最多255 |
| `document_number` | string | 受益人 CPF / CNPJ | 14或18 |
| `person_type` | string | 自然人或法人枚举值 | 最多255 |
| `natural_person` | JSON | **[自然人](#natural_person)** 对象 | - |
| `legal_person` | JSON | **[法人](#legal_person)** 对象 | - |

### Borrower
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------|------- |-----------------------------------------------------|------------|
| `name` | string | 借款人姓名 | 最多255 |
| `document_number` | string | 借款人 CPF / CNPJ | 14或18 |
| `person_type` | string | 自然人或法人枚举值 | 最多255 |
| `natural_person` | JSON | **[自然人](#natural_person)** 对象 | - |
| `legal_person` | JSON | **[法人](#legal_person)** 对象 | - |

### Person Type
| 枚举值 | 描述 |
|--------------------------|-----------------------|
| `natural_person` | 自然人 |
| `legal_person` | 法人 |

### Natural Person
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------|------- |-----------------------------------------------------|------------|
| `birthdate` | string | 出生日期 | 10 |
| `mother_name` | string | 母亲姓名 | 最多255 |

### Legal Person
| 字段 | 类型 | 描述 | 字符数 |
|------------------|----------|----------------------------------------------------------|--------------|
| `activity_code` | string | 国家经济活动分类代码 (CNAE) | 10 |
| `representatives`| array | **[代表人](#representative)** 对象列表 | - |

### Representative
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------------|----------|------------------------------------------------|--------------|
| `name` | string | 代表人姓名 | 最多255 |
| `document_number` | string | 代表人 CPF | 14 |

### Asset
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------------|----------|---------------------------------------------------------------|--------------|
| `asset_key` | string | 资产唯一标识符 | 最多255 |
| `asset_type` | string | 资产类型枚举值 | 最多255 |
| `status` | string | 资产状态枚举值 | 最多255 |
| `credit_operation` | JSON | **[信贷操作](#credit_operation)** 对象 | - |
| `documents` | Array | **[资产文件](#asset_document)** 对象列表 | - |

### Asset Status
| 枚举值 | 描述 |
|--------------------------|-----------------------|
| `pending_approval` | 待审批 |
| `done` | 已完成 |

### Document
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------------|----------|---------------------------------------------------------------|--------------|
| `document_key` | string | 资产唯一标识符 | 最多255 |
| `document_type` | string | 资产类型枚举值 | 最多255 |

### Asset Type
| 枚举值 | 描述 |
|--------------------------|-----------|
| `ccb` | CCB |
| `cce` | CCE |

### Credit Operation
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------------|----------|-------------------------------------------------------|--------------|
| `contract_number` | string | 合同号 | 最多255 |
| `principal_value` | string | 操作本金价值 | - |
| `interest_rate_type` | string | 浮动/固定利率枚举值 | 最多255 |
| `pre_fixed` | JSON | **[固定利率](#pre_fixed)** 对象 | - |
| `post_fixed` | JSON | **[浮动利率](#pós_fixed)** 对象 | - |

### Interest Rate Type
| 枚举值 | 描述 |
|--------------------------|-----------------------|
| `pre_fixed` | 固定利率 |
| `post_fixed` | 浮动利率 |

### Pre fixed 
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|----------|--------------------------------------------------------------|------------|
| `calendar_base` | string | 工作日 / 360日历 / 365日历枚举值 | 最多255 |
| `monthly_rate` | float | 月利率 | - |

### Post fixed 
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|----------|-----------------------------------------------------------------|------------|
| `calendar_base` | string | 工作日 / 360日历 / 365日历枚举值 | 最多255 |
| `indexer` | string | DI / IPCA 枚举值 | 最多255 |
| `rate` | float | 利率 | - |
| `lag` | JSON | **[Lag](#lag)** 对象 | - |

### calendar_base
| 枚举值 | 描述 |
|--------------------------|-----------------------|
| `workdays` | 工作日 |
| `calendar_360` | 360日历 |
| `calendar_365` | 365日历 |

### Indexer
| 枚举值 | 描述 |
|--------------------------|-----------------------|
| `di` | DI |
| `ipca` | IPCA |

### Lag
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|----------|---------------------------------------------------|------------|
| `reference` | string | 每日 / 每月枚举值 | 最多255 |
| `amount` | integer | 滞后数量 | - |

### Reference
| 枚举值 | 描述 |
|--------------------------|-----------------------|
| `daily` | 每日 |
| `monthly` | 每月 |

### Locked Investor Positions
| 字段 | 类型 | 描述 | 字符数 |
|---------------------------------|------- |-----------------------------------------------------------------------|------------|
| `investor_position_lock_key` | string | 投资者持仓锁定唯一标识符 | 36 |
| `investor_position_key` | string | 投资者持仓唯一标识符 | 36 |
| `original_locked_quotas` | float | 原始锁定份额数量 | - |
| `current_locked_quotas` | float | 当前锁定份额数量 | - |
| `original_locked_value` | float | 原始锁定价值 | - |
| `current_locked_value` | float | 当前锁定价值 | - |

### Responses
```json title='Response Body'
{
    "quota_lock_key": "UUID"
}
```

---

# 查询投资者的份额锁定

URL: /zh-Hans/documentation/iaas/passivo/bloqueio_de_cotas/consulta_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
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------|------- |------------------------------------------------------------------------|------------|
| `quota_lock_key` | string | 份额锁定唯一标识符 | 36 |
| `status` | string | 份额锁定状态枚举值 | 最多255 |
| `type` | string | 份额锁定类型枚举值 | 最多255 |
| `original_locked_quotas` | float | 原始锁定份额数量 | - |
| `current_locked_quotas` | float | 当前锁定份额数量 | - |
| `original_locked_value` | float | 原始锁定价值 | - |
| `current_locked_value` | float | 当前锁定价值 | - |
| `collateral` | JSON | **[担保](#collateral)** 对象 | - |
| `investor_positions_locks` | Array | **[投资者持仓锁定](#locked-investor-positions)** 对象列表 | - |

### Quota Lock Status
| 枚举值 | 描述 |
|--------------------------|-----------------------|
| `pending_documents` | 待文件 |
| `pending_approval` | 待审批 |
| `denied` | 已拒绝 |
| `approved` | 已批准 |

### Quota Lock Type
| 枚举值 | 描述 |
|--------------------------|-----------------------|
| `collateral` | 担保 |

### Collateral
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------|------- |-----------------------------------------------------------------------|------------|
| `recipient` | JSON | **[受益人](#recipient)** 对象 | - |
| `borrower` | JSON | **[借款人](#borrower)** 对象 | - |
| `assets` | Array | **[资产](#asset)** 对象列表 | - |
| `issuance_series` | Array | **[发行系列](#issuance_serie)** 对象列表 | - |
| `documents` | Array | **[担保文件](#collateral_document)** 对象列表 | - |

### Recipient
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------|------- |-----------------------------------------------------|------------|
| `name` | string | 受益人姓名 | 最多255 |
| `document_number` | string | 受益人 CPF / CNPJ | 14或18 |
| `person_type` | string | 自然人或法人枚举值 | 最多255 |
| `natural_person` | JSON | **[自然人](#natural_person)** 对象 | - |
| `legal_person` | JSON | **[法人](#legal_person)** 对象 | - |

### Borrower
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------|------- |-----------------------------------------------------|------------|
| `name` | string | 借款人姓名 | 最多255 |
| `document_number` | string | 借款人 CPF / CNPJ | 14或18 |
| `person_type` | string | 自然人或法人枚举值 | 最多255 |
| `natural_person` | JSON | **[自然人](#natural_person)** 对象 | - |
| `legal_person` | JSON | **[法人](#legal_person)** 对象 | - |

### Person Type
| 枚举值 | 描述 |
|--------------------------|-----------------------|
| `natural_person` | 自然人 |
| `legal_person` | 法人 |

### Natural Person
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------|------- |-----------------------------------------------------|------------|
| `birthdate` | string | 出生日期 | 10 |
| `mother_name` | string | 母亲姓名 | 最多255 |

### Legal Person
| 字段 | 类型 | 描述 | 字符数 |
|------------------|----------|----------------------------------------------------------|--------------|
| `activity_code` | string | 国家经济活动分类代码 (CNAE) | 10 |
| `representatives`| array | **[代表人](#representative)** 对象列表 | - |

### Representative
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------------|----------|------------------------------------------------|--------------|
| `name` | string | 代表人姓名 | 最多255 |
| `document_number` | string | 代表人 CPF | 14 |

### Asset
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------------|----------|---------------------------------------------------------------|--------------|
| `asset_key` | string | 资产唯一标识符 | 最多255 |
| `asset_type` | string | 资产类型枚举值 | 最多255 |
| `status` | string | 资产状态枚举值 | 最多255 |
| `credit_operation` | JSON | **[信贷操作](#credit_operation)** 对象 | - |
| `documents` | Array | **[资产文件](#asset_document)** 对象列表 | - |

### Asset Status
| 枚举值 | 描述 |
|--------------------------|-----------------------|
| `pending_approval` | 待审批 |
| `done` | 已完成 |

### Document
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------------|----------|---------------------------------------------------------------|--------------|
| `document_key` | string | 资产唯一标识符 | 最多255 |
| `document_type` | string | 资产类型枚举值 | 最多255 |

### Asset Type
| 枚举值 | 描述 |
|--------------------------|-----------|
| `ccb` | CCB |
| `cce` | CCE |

### Credit Operation
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------------|----------|-------------------------------------------------------|--------------|
| `contract_number` | string | 合同号 | 最多255 |
| `principal_value` | string | 操作本金价值 | - |
| `interest_rate_type` | string | 浮动/固定利率枚举值 | 最多255 |
| `pre_fixed` | JSON | **[固定利率](#pre_fixed)** 对象 | - |
| `post_fixed` | JSON | **[浮动利率](#pós_fixed)** 对象 | - |

### Interest Rate Type
| 枚举值 | 描述 |
|--------------------------|-----------------------|
| `pre_fixed` | 固定利率 |
| `post_fixed` | 浮动利率 |

### Pre fixed 
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|----------|--------------------------------------------------------------|------------|
| `calendar_base` | string | 工作日 / 360日历 / 365日历枚举值 | 最多255 |
| `monthly_rate` | float | 月利率 | - |

### Post fixed 
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|----------|-----------------------------------------------------------------|------------|
| `calendar_base` | string | 工作日 / 360日历 / 365日历枚举值 | 最多255 |
| `indexer` | string | DI / IPCA 枚举值 | 最多255 |
| `rate` | float | 利率 | - |
| `lag` | JSON | **[Lag](#lag)** 对象 | - |

### calendar_base
| 枚举值 | 描述 |
|--------------------------|-----------------------|
| `workdays` | 工作日 |
| `calendar_360` | 360日历 |
| `calendar_365` | 365日历 |

### Indexer
| 枚举值 | 描述 |
|--------------------------|-----------------------|
| `di` | DI |
| `ipca` | IPCA |

### Lag
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|----------|---------------------------------------------------|------------|
| `reference` | string | 每日 / 每月枚举值 | 最多255 |
| `amount` | integer | 滞后数量 | - |

### Reference
| 枚举值 | 描述 |
|--------------------------|-----------------------|
| `daily` | 每日 |
| `monthly` | 每月 |

### Locked Investor Positions
| 字段 | 类型 | 描述 | 字符数 |
|---------------------------------|------- |-----------------------------------------------------------------------|------------|
| `investor_position_lock_key` | string | 投资者持仓锁定唯一标识符 | 36 |
| `investor_position_key` | string | 投资者持仓唯一标识符 | 36 |
| `original_locked_quotas` | float | 原始锁定份额数量 | - |
| `current_locked_quotas` | float | 当前锁定份额数量 | - |
| `original_locked_value` | float | 原始锁定价值 | - |
| `current_locked_value` | float | 当前锁定价值 | - |

### Responses
```json title='Response Body'
{
    "quota_lock_key": "UUID"
}
```

---

# 发送担保文件

URL: /zh-Hans/documentation/iaas/passivo/bloqueio_de_cotas/enviar_documento_da_garantia

---
### 简介
本资源旨在向我们发送与正在申请**份额锁定**的**担保**正式化相关的**文件**。

### 输入/输出：
作为***输入***，需发送**文件类型**和文件的 **base 64** 编码。请参见以下示例。

作为***输出***，将返回 ***collateral_document_key***。***collateral_document_key*** 用于标识已发送的**担保文件**。

### 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"
}
```

### Response
```json title='Response Body'
{
    "collateral_document_key": "UUID"
}
```

---

# 发送资产文件

URL: /zh-Hans/documentation/iaas/passivo/bloqueio_de_cotas/enviar_documento_do_ativo

---
### 简介
本资源旨在向我们发送作为正在申请**份额锁定**的**担保**对象的**资产****文件**。

### 输入/输出：
作为***输入***，需发送**文件类型**和文件的 **base 64** 编码。请参见以下示例。

作为***输出***，将返回 ***asset_document_key***。***asset_document_key*** 用于标识已发送的**资产文件**。

### 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"
}
```

---

# 减少份额锁定

URL: /zh-Hans/documentation/iaas/passivo/bloqueio_de_cotas/reduzir_bloqueio_de_cotas

---

### 简介
本资源旨在减少**投资者**的**份额锁定**金额。

### 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
LOCKED_
减少锁定价值

```json
{
    "type": "decrease_locked_value",
    "new_locked_value": 0.00
}
```

减少锁定份额数量

```json
{
    "type": "decrease_locked_quotas",
    "new_locked_quotas": 0.00
}
```

### Locked Investor Position Event
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------|------- |--------------------------------------|------------|-------------|
| `type` | string | 事件类型枚举值 | 最多255 | 是 |
| `new_locked_value` | float | 新的锁定金融价值 | - | 否 |
| `new_locked_quotas` | float | 新的锁定份额数量 | - | 否 |

### Quota Lock Type
| 枚举值 | 描述 |
|--------------------------|--------------------------------------------------|
| `decrease_locked_quotas` | 减少锁定份额数量 |
| `decrease_locked_value` | 减少锁定金融价值 |

---

# 申请份额锁定

URL: /zh-Hans/documentation/iaas/passivo/bloqueio_de_cotas/solicitar_bloqueio_de_cotas

---

### 简介
本资源旨在创建**投资者**的**份额锁定**申请。

### 输入/输出：
需发送**锁定类型**以及该锁定类型的具体信息。

作为***输出***，将返回代表**份额锁定**的 ***quota_lock_key***。

### Request

ENDPOINT /quota_lock/investor/INVESTOR_KEY/quota_lock
MÉTODO POST
STATUS 201

通过担保锁定份额 - 自然人

```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"
    },
}
```

通过担保锁定份额 - 法人

```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"
    },
}
```

### Quota Lock
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------|------- |------------------------------------------------------------------|------------|
| `type` | string | 份额锁定类型枚举值 | 最多255 |
| `collateral` | string | **[担保](#collateral)** 对象 | - |

### Quota Lock Type
| 枚举值 | 描述 |
|--------------------------|-----------------------|
| `collateral` | 担保 |

### Collateral
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------|------- |------------------------------------------------------------------|------------|-------------|
| `recipient` | JSON | **[受益人](#recipient)** 对象 | - | 是 |
| `borrower` | JSON | **[借款人](#borrower)** 对象 | - | 是 |
| `assets` | Array | **[资产](#asset)** 对象列表 | - | 是 |
| `issuance_series` | Array | **[发行系列](#issuance_serie)** 对象列表 | - | 是 |
| `bank_account_key` | string | 与担保关联的银行账户 UUID | - | 否 |

### Recipient
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------|------- |-----------------------------------------------------|------------|-------------|
| `name` | string | 受益人姓名 | 最多255 | 是 |
| `document_number` | string | 受益人 CPF / CNPJ | 14或18 | 是 |
| `person_type` | string | 自然人或法人枚举值 | 最多255 | 是 |
| `natural_person` | JSON | **[自然人](#natural_person)** 对象 | - | 否 |
| `legal_person` | JSON | **[法人](#legal_person)** 对象 | - | 否 |

### Borrower
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------|------- |-----------------------------------------------------|------------|------------ |
| `name` | string | 借款人姓名 | 最多255 | 是 |
| `document_number` | string | 借款人 CPF / CNPJ | 14或18 | 是 |
| `person_type` | string | 自然人或法人枚举值 | 最多255 | 是 |
| `natural_person` | JSON | **[自然人](#natural_person)** 对象 | - | 否 |
| `legal_person` | JSON | **[法人](#legal_person)** 对象 | - | 否 |

### Person Type
| 枚举值 | 描述 |
|--------------------------|-----------------------|
| `natural_person` | 自然人 |
| `legal_person` | 法人 |

### Natural Person
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------|------- |-----------------------------------------------------|------------|-------------|
| `birthdate` | string | 出生日期 | 10 | 是 |
| `mother_name` | string | 母亲姓名 | 最多255 | 是 |

### Legal Person
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|------------------|----------|----------------------------------------------------------|--------------|-------------|
| `activity_code` | string | 国家经济活动分类代码 (CNAE) | 10 | 是 |
| `representatives`| array | **[代表人](#representative)** 对象列表 | - | 是 |

### Representative
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|------------------------------------------------|--------------|-------------|
| `name` | string | 代表人姓名 | 最多255 | 是 |
| `document_number` | string | 代表人 CPF | 14 | 是 |

### Asset
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|-------------------------------------------------------|--------------|-------------|
| `asset_type` | string | 资产类型枚举值 | 最多255 | 是 |
| `credit_operation` | JSON | **[信贷操作](#credit_operation)** 对象 | - | 否 |

### Asset Type
| 枚举值 | 描述 |
|--------------------------|-----------|
| `ccb` | CCB |
| `cce` | CCE |

### Credit Operation
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|-------------------------------------------------------|--------------|-------------|
| `contract_number` | string | 合同号 | 最多255 | 是 |
| `principal_value` | string | 操作本金价值 | - | 是 |
| `interest_rate_type` | string | 浮动/固定利率枚举值 | 最多255 | 是 |
| `pre_fixed` | JSON | **[固定利率](#pre_fixed)** 对象 | - | 否 |
| `post_fixed` | JSON | **[浮动利率](#pós_fixed)** 对象 | - | 否 |

### Interest Rate Type
| 枚举值 | 描述 |
|--------------------------|-----------------------|
| `pre_fixed` | 固定利率 |
| `post_fixed` | 浮动利率 |

### Pre fixed 
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|----------|--------------------------------------------------------------|------------|
| `calendar_base` | string | 工作日 / 360日历 / 365日历枚举值 | 最多255 |
| `monthly_rate` | float | 月利率 | - |

### Post fixed 
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|----------|-----------------------------------------------------------------|------------|
| `calendar_base` | string | 工作日 / 360日历 / 365日历枚举值 | 最多255 |
| `indexer` | string | DI / IPCA 枚举值 | 最多255 |
| `rate` | float | 利率 | - |
| `lag` | JSON | **[Lag](#lag)** 对象 | - |

### calendar_base
| 枚举值 | 描述 |
|--------------------------|-----------------------|
| `workdays` | 工作日 |
| `calendar_360` | 360日历 |
| `calendar_365` | 365日历 |

### Indexer
| 枚举值 | 描述 |
|--------------------------|-----------------------|
| `di` | DI |
| `ipca` | IPCA |

### Lag
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|----------|---------------------------------------------------|------------|
| `reference` | string | 每日 / 每月枚举值 | 最多255 |
| `amount` | integer | 滞后数量 | - |

### Reference
| 枚举值 | 描述 |
|--------------------------|-----------------------|
| `daily` | 每日 |
| `monthly` | 每月 |

### Issuance Serie
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|-----------------------------------|----------|-------------------------------------------------------|--------------|-------------|
| `issuance_serie_key` | string | 发行系列键 | 36 | 是 |
| `number_of_quotas` | float | 要锁定的份额数量 | - | 否 |
| `financial_value` | float | 要锁定的金融价值 | - | 否 |

### Responses
```json title='Response Body'
{
    "quota_lock_key": "UUID"
}
```

---

# 份额锁定 Webhook

URL: /zh-Hans/documentation/iaas/passivo/bloqueio_de_cotas/webhooks_de_bloqueio_de_cota

---

### 简介
以下是**份额锁定**过程中发送的 webhooks 详细信息。

锁定已批准

```json
{
  "webhook_type": "quota_lock.quota_lock_status_change",
  "webhook_datetime": "2024-12-05T00:00:00Z",
  "data": {
    "status": "approved",
    "quota_lock_key": "UUID"
  }
}
```

锁定已拒绝
    
```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: /zh-Hans/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: /zh-Hans/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"
}
```

---

# 份额演变图分页查询

URL: /zh-Hans/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

| 参数 | 类型 | 必填 | 描述 |
| -------------------- | ------ | ----------- | ------------------------- |
| `fund_class_key` | `UUID` | 是 | 基金键 |
| `issuance_serie_key` | `UUID` | 是 | 发行系列键 |

### Query Params

| 参数 | 类型 | 必填 | 描述 |
| ---------------- | ------------ | ----------- | ------------------------------------------------ |
| `reference_date` | `YYYY-MM-DD` | 条件必填 | 单一参考日期查询 |
| `start_date` | `YYYY-MM-DD` | 条件必填 | 区间起始日期 |
| `end_date` | `YYYY-MM-DD` | 条件必填 | 区间结束日期 |
| `limit` | `int` | 否 | 每页记录数（默认：10） |
| `page` | `int` | 否 | 当前页码（默认：0） |

:::warning 注意
必须传入其中一个日期过滤器，`reference_date` 返回特定日期的演变图，`start_date` 和 `end_date` 组合返回日期区间内的演变图。若两个过滤器均未发送，将返回错误：CMP000018
:::

情况01：单日期返回

```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

| 字段 | 类型 | 描述 |
| ------------------------ | ------ | --------------------------------------------------------------- |
| `gross_net_worth` | number | 合成日的总净资产 |
| `net_net_worth` | number | 合成日的净资产净值 |
| `gross_quota_value` | number | 份额总值 |
| `net_quota_value` | number | 份额净值 |
| `number_of_quotas` | number | 当日份额总数 |
| `composition_date` | string | 合成日期（格式：`YYYY-MM-DD`） |
| `applied_value` | number | 当日申购金额 |
| `applied_quotas` | number | 当日申购份额数量 |
| `redeemed_value` | number | 当日赎回金额 |
| `redeemed_quotas` | number | 当日赎回份额数量 |
| `amortized_value` | number | 当日摊销金额 |
| `tax_anticipated_value` | number | 当日预缴税额 |
| `tax_anticipated_quotas` | number | 当日预缴税份额数量 |
| `daily_rentability` | number | 日收益率（十进制格式，例如：`0.0007` 表示 0.07%） |
| `monthly_rentability` | number | 月收益率（十进制格式，例如：`0.0060` 表示 0.60%） |
| `yearly_rentability` | number | 年收益率（十进制格式，例如：`0.096` 表示 9.6%） |

---

# 发行系列分页查询

URL: /zh-Hans/documentation/iaas/passivo/consultas/consultar_todas_series_de_emissao

### Request

ENDPOINT /quota/issuance_series
MÉTODO GET
STATUS 200

### Query Params

| 参数 | 描述 |
|-------------------------------|---------------------------------------------------------------------------|
| `issuance_serie_key` | 发行系列唯一标识键 |
| `fund_class_document_number` | 与发行系列相关的基金 CNPJ |

:::warning 注意
在集成过程中，将要求对发送的哈希值进行身份验证。
:::

情况01：返回一个发行系列

```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

| 字段 | 类型 | 描述 |
|-------------------------------|--------|---------------------------------------------------------------------------|
| `name` | string | 发行系列名称 |
| `investment_category` | string | 投资类别（例如：fidc） |
| `condominium_type` | string | 信托类型（`open_ended` 或 `closed_ended`） |
| `tax_classification` | string | 税务分类（例如：`long_term`） |
| `investment_restriction_type` | string | 投资限制类型（例如：`professional`） |
| `remuneration_type` | string | 报酬类型（例如：`residual`） |
| `issuance_serie_key` | string | 系列唯一标识键 |
| `minimum_share_capital` | number | 系列最低资本额 |
| `accounting_date` | string | 系列会计日期 |
| `start_date` | string | 系列起始日期 |
| `original_quota_value` | number | 原始份额价值 |
| `serie` | number | 系列编号 |
| `maturity_date` | string | 系列到期日期 |
| `sub_class` | JSON | 包含子类信息的 **[Sub Class](#sub-class)** 对象 |

### Sub Class

| 字段 | 类型 | 描述 |
|--------------------|--------|---------------------------------------------------------------------|
| `name` | string | 子类名称 |
| `sub_class_key` | string | 子类唯一键 |
| `subordination_level` | number | 从属级别 |
| `fund_class` | JSON | 包含基金信息的 **[Fund Class](#fund-class)** 对象 |

### Fund Class

| 字段 | 类型 | 描述 |
|-------------------|--------|---------------------------------------------------------------------------------------|
| `fund_class_key` | string | 基金唯一标识键 |
| `document_number` | string | 基金 CNPJ |
| `name` | string | 基金名称 |
| `administrator` | JSON | 包含管理员信息的 **[Administrator](#administrator)** 对象 |

### Administrator

| 字段 | 类型 | 描述 |
|---------------------|--------|------------------------------------------------|
| `administrator_key` | string | 管理员唯一标识键 |
| `name` | string | 管理员名称 |
| `document_number` | string | 管理员 CNPJ |

---

# 基金分页查询

URL: /zh-Hans/documentation/iaas/passivo/consultas/consultar_todos_fundos

---
:::warning 注意
本资源仅适用于担任**分销商**角色的集成。
:::

### Request

ENDPOINT /quota/fund_classes
MÉTODO GET
STATUS 200

### Query Params

| 参数 | 描述 |
|------------------------------|--------------------------------------------------------------------------------------|
| `document_number` | 基金证件号 |
| `fund_class_key` | 基金唯一标识键 |

:::warning 注意
在集成过程中，将要求对发送的哈希值进行身份验证。
:::
情况01：返回仅一个基金

```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

| 字段 | 类型 | 描述 |
| ----------------- | ------ | ------------------------------------------------------------------------------------- |
| `fund_class_key` | string | 基金唯一标识键 |
| `document_number` | string | 基金 CNPJ |
| `name` | string | 基金名称 |
| `administrator` | JSON | 包含管理员信息的 **[Administrator](#administrator)** 对象 |

### Administrator
| 字段 | 类型 | 描述 |
| ------------------- | ------ | ---------------------------------------------- |
| `administrator_key` | string | 管理员唯一标识键 |
| `name` | string | 管理员名称 |
| `document_number` | string | 管理员 CNPJ |

---

# 发送已签署认购公告

URL: /zh-Hans/documentation/iaas/passivo/controle_de_oferta/enviar_boletim_de_subscricao_assinado

---
### 简介
本资源旨在向我们发送**投资者**对某基金**份额发行**的**认购公告**签署证明。

:::warning 注意
本资源仅适用于担任**分销商**角色的集成。
:::

### 输入/输出：
作为***输入***，需发送与认购相关的信息、投资者认购的基金**份额发行**的 UUID、**签署类型**以及根据签署方式所需的验证内容。以下是示例。

作为***输出***，将返回 ***subscription_note_key***。***subscription_note_key*** 用于标识**认购公告**。

### 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 注意
在集成过程中，将要求对发送的哈希值进行身份验证。
:::

### Response
```json title='Response Body'
{
    "subscription_note_key": "UUID"
}
```

---

# 获取认购公告信息

URL: /zh-Hans/documentation/iaas/passivo/controle_de_oferta/informacoes_boletins_de_subscricao

---

### Request

ENDPOINT /quota_offering_control/investor/INVESTOR_KEY/subscription_notes
MÉTODO GET

:::warning 注意
以上端点仅适用于担任**分销商**角色的集成。
:::

ENDPOINT /quota_offering_control/fund_class/FUND_CLASS_KEY/subscription_notes
MÉTODO GET

:::warning 注意
以上端点仅适用于担任**经理**角色的集成。
:::
   ### Responses

STATUS 200

情况01：投资者拥有一份认购公告

```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
}
```

情况02：投资者没有认购公告
```json
{
   "data":[],
   "limit":50,
   "page":0,
   "is_last_page":true
}
```

### Response Fields

| 字段 | 类型 | 描述 |
|---------------|--------|----------------------------------------------------------------|
| `data` | array | **[Subscription Note](#subscription-note)** 对象列表 |
| `limit` | int | 每页返回对象数量上限 |
| `page` | int | 已返回页码 |
| `is_last_page` | boolean | 表示已返回页面是否为最后一页 |

### 备注

类型 * 表示该字段可能为空，
如下例所示：
| 类型 |
|----------|
| string * |

### Subscription Note
| 字段 | 类型 | 描述 |
|---------------------------|----------|-------------------------------------------------------------------------------------------------------|
| `subscription_note_key` | string | 认购公告唯一标识键 |
| `quota_offering` | JSON | **[Quota Offering](#quota-offering)** 对象 |
| `investor` | JSON | **[Investor](#investor)** 对象 |
| `status` | string | 发送生成文件 / 待文件 / 待签署 / 已取消 / 活跃 / 已售罄 |
| `transaction_type` | string | B3 / TED |
| `original_subscription_note_value` | float | 认购公告原始金额 |
| `issued_number_of_quotas` | float | 已发行份额数量 |
| `remaining_subscription_note_value` | float | 认购公告剩余金额 |
| `start_date` | string | 认购公告起始日期 |
| `financial_application_events` | array | **[Financial Application Event](#financial-application-event)** 对象列表 |
| `maturity_date` | string* | 到期日期 |
| `original_number_of_quotas` | string* | 已发行份额数量 |

### Quota Offering
| 字段 | 类型 | 描述 |
|-----------------------------------|----------|-----------------------------------------------------------------------------------------|
| `quota_offering_key` | string | 发行唯一标识键 |
| `status` | string | 活跃 / 关闭 |
| `original_quota_offering_value` | float | 发行原始金额 |
| `issued_number_of_quotas` | float | 已认购份额数量 |
| `remaining_quota_offering_value` | float | 发行剩余金额 |
| `start_date` | string | 发行起始日期 |
| `issuance_serie` | string | **[Issuance Serie](#issuance-serie)** 对象 |
| `type` | string | 公开/私募发行类型 |
| `cvm_registration` | JSON * | CVM 注册数据 |
| `lead_coordinator` | JSON * | 牵头协调人数据 |
| `maturity_date` | string * | 到期日期 |
| `original_number_of_quotas` | string * | 已发行份额数量 |

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
| 字段 | 类型 | 描述 |
|-----------------------------------|----------|-----------------------------------------------------------------------------------------|
| `financial_application_key` | string | 财务申请唯一标识键 |
| `financial_application_event_key` | string | 财务申请事件唯一标识键 |
| `type` | string | 消耗价值 / 更新份额 / 取消 |
| `event_datetime` | string | 事件日期和时间 |
| `share_capital` | float * | 财务申请出资金额 *仅在 'consume_value' 时显示 |
| `number_of_quotas` | float * | 财务申请份额数量 *仅在 'update_quotas' 时显示 |

### Issuance Serie
| 字段 | 类型 | 描述 |
|-------------------------------|----------|---------------------------------------------------|
| `name` | string | 发行系列名称 |
| `issuance_serie_key` | string | 发行系列唯一标识键 |
| `sub_class` | JSON | **[Sub Class](#sub-class)** 对象 |
| `classification` | string | 专业 / 合格 / 普通 |
| `market_type` | string | 一级 / 二级 |
| `serie` | integer | 收益曲线 / 剩余 |

### Sub Class
| 字段 | 类型 | 描述 |
|-------------------------------|----------|---------------------------------------------------|
| `name` | string | 子类名称 |
| `sub_class_key` | string | 子类唯一标识键 |
| `subordination_level` | int | 子类从属级别 |
| `fund_class` | JSON | **[Fund Class](#fund-class)** 对象 |

### Fund Class
| 字段 | 类型 | 描述 |
|-------------------------------|----------|---------------------------------------------------|
| `name` | string | 基金类名称 |
| `fund_class_key` | string | 基金类唯一标识键 |
| `document_number` | string | 基金类 CNPJ |
| `short_name` | string | 基金类简称 |

### Investor
| 字段 | 类型 | 描述 |
|--------------------------|----------|---------------------------------------------------|
| `name` | string | 投资者姓名 |
| `investor_key` | string | 投资者唯一标识键 |
| `document_number` | string | 投资者 CPF/CNPJ |
| `person_type` | string | 自然人 / 法人 / 基金类 |
| `distributor` | JSON | **[Distributor](#distributor)** 对象 |

### Distributor
| 字段 | 类型 | 描述 |
|--------------------------|----------|---------------------------------------------------|
| `name` | string | 分销商名称 |
| `distributor_key` | string | 分销商唯一标识键 |
| `document_number` | string | 分销商 CPF/CNPJ |

---

# 获取发行信息

URL: /zh-Hans/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 注意
本资源仅适用于担任**经理**角色的集成。
:::

   ### Responses

STATUS 200

   ### Query Params

| 参数 | 描述 |
|------------------------------|--------------------------------------------------------------------------------------|
| `sub_class_key` | 子类唯一标识键 |
| `issuance_serie_key` | 发行系列唯一标识键 |

情况01：基金拥有一个发行

```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
}
```

情况02：基金没有发行
```json
{
   "data":[],
   "limit":50,
   "page":0,
   "is_last_page":true
}
```

### Response Fields

| 字段 | 类型 | 描述 |
|---------------|--------|----------------------------------------------------------------|
| `data` | array | **[Quota Offering](#quota-offering)** 对象列表 |
| `limit` | int | 每页返回对象数量上限 |
| `page` | int | 已返回页码 |
| `is_last_page` | boolean | 表示已返回页面是否为最后一页 |

### 备注

类型 * 表示该字段可能为空，
如下例所示：
| 类型 |
|----------|
| string * |

### Quota Offering
| 字段 | 类型 | 描述 |
|-----------------------------------|----------|-----------------------------------------------------------------------------------------|
| `quota_offering_key` | string | 发行唯一标识键 |
| `status` | string | 活跃 / 关闭 |
| `original_quota_offering_value` | float | 发行原始金额 |
| `issued_number_of_quotas` | float | 已认购份额数量 |
| `remaining_quota_offering_value` | float | 发行剩余金额 |
| `start_date` | string | 发行起始日期 |
| `issuance_serie` | string | **[Issuance Serie](#issuance-serie)** 对象 |
| `type` | string | 公开/私募发行类型 |
| `cvm_registration` | JSON * | CVM 注册数据 |
| `lead_coordinator` | JSON * | 牵头协调人数据 |
| `maturity_date` | string * | 到期日期 |
| `original_number_of_quotas` | string * | 已发行份额数量 |

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
| 字段 | 类型 | 描述 |
|-------------------------------|----------|---------------------------------------------------|
| `name` | string | 发行系列名称 |
| `issuance_serie_key` | string | 发行系列唯一标识键 |
| `sub_class` | JSON | **[Sub Class](#sub-class)** 对象 |
| `classification` | string | 专业 / 合格 / 普通 |
| `market_type` | string | 一级 / 二级 |
| `serie` | integer | 收益曲线 / 剩余 |

### Sub Class
| 字段 | 类型 | 描述 |
|-------------------------------|----------|---------------------------------------------------|
| `name` | string | 子类名称 |
| `sub_class_key` | string | 子类唯一标识键 |
| `subordination_level` | int | 子类从属级别 |
| `fund_class` | JSON | **[Fund Class](#fund-class)** 对象 |

### Fund Class
| 字段 | 类型 | 描述 |
|-------------------------------|----------|---------------------------------------------------|
| `name` | string | 基金类名称 |
| `fund_class_key` | string | 基金类唯一标识键 |
| `document_number` | string | 基金类 CNPJ |
| `short_name` | string | 基金类简称 |

---

# 申请认购公告

URL: /zh-Hans/documentation/iaas/passivo/controle_de_oferta/solicitar_boletim_de_subscricao

---
### 简介
本资源旨在为**投资者**创建对某基金**份额发行**的**认购公告**申请。基于此申请，系统将根据发行中配置的生成类型生成认购公告文档。

### 输入/输出：
作为***输入***，需发送投资者认购的**份额发行**的 UUID、**认购公告金额**、**交易类型**，以及可选的签署方式和签署人组。以下是示例。

作为***输出***，将返回所创建的**认购公告**的完整对象，包括 ***subscription_note_key***。***subscription_note_key*** 用于标识**认购公告**。

### 请求

ENDPOINT /quota_offering_control/investor/INVESTOR_KEY/subscription_note
方法 POST
状态 201

### 路径参数

| 参数              | 描述              |
|-------------------|-------------------|
| `INVESTOR_KEY`    | 投资者的 UUID     |

### 请求体
```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
| 字段                               | 类型   | 描述                                                                                                                          | 必填 |
|------------------------------------|--------|-------------------------------------------------------------------------------------------------------------------------------|------|
| `original_subscription_note_value` | number | 认购公告金额。最小值 0。不能超过发行的剩余金额                                                                                  |  是  |
| `quota_offering_key`               | string | 份额发行的 UUID（36 个字符）。发行必须存在且状态为 `active`                                                                     |  是  |
| `transaction_type`                 | string | `ted` 或 `b3`。若为 `b3`，基金类别必须已注册 B3 账户                                                                            |  是  |
| `signature_method`                 | string | 签署方式枚举值。若省略，服务将根据主体类型确定：`natural_person` → `qi_sign`，`legal_person` → `certifiqi`                      |  否  |
| `signer_group_key`                 | string | 签署人组的 UUID（36 个字符）。若省略，使用投资者的默认签署人组                                                                  |  否  |

### 签署方式

| 枚举值        | 描述                                                         |
|---------------|--------------------------------------------------------------|
| `certifiqi`   | 通过 CertifiQi 签署（数字证书）                              |
| `qi_sign`     | 通过 QI Sign 签署（电子签名）                                |

### 响应
```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": "SENIOR",
        "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"
    }
  ]
}
```

**[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)** 和 **[Financial Application Event](/documentation/iaas/passivo/controle_de_oferta/informacoes_boletins_de_subscricao#financial-application-event)** 对象的详细说明请参阅**[认购公告信息](/documentation/iaas/passivo/controle_de_oferta/informacoes_boletins_de_subscricao)**页面。

---

# 获取公开份额

URL: /zh-Hans/documentation/iaas/passivo/fundos/cotas_publicas

---

### Request

ENDPOINT /public_dash/mark_to_market/fund_quota/mark_to_markets
METHOD GET
STATUS 200

### Query Params

| 参数 | 类型 | 描述 |
|-----------------------------|----------|---------------------------------------------------------------------------------------|
| `internal_codes` | list | 发行系列内部代码列表，用于精确过滤记录 |
| `from_reference_date` | string | 查询周期起始日期（YYYY-MM-DD） |
| `to_reference_date` | string | 查询周期结束日期（YYYY-MM-DD） |
| `internal_code` | string | 要查询的发行系列唯一代码 |
| `fund_class_document_number` | string | 要查询的基金 CNPJ（含标点） |
| `limit` | int | 每页返回对象数量上限 |
| `page` | int | 已返回页码 |

:::warning 注意
份额价值在**发行系列（issuance_serie）**层面，因此使用 **fund_class_document_number** 参数将返回所有系列。
建议仅将此过滤器用于映射发行系列的唯一标识符（**internal_code** 和 **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

| 字段 | 类型 | 描述 |
|-----------------------------------|--------|--------------------------------------------------------------|
| `issuance_serie_key` | string | 发行系列标识键 |
| `internal_code` | string | 内部标识发行系列的代码 |
| `fund_class_document_number` | string | 所查询投资基金的 CNPJ |
| `fund_class_name` | string | 所查询投资基金的名称 |
| `marks_to_market` | array | **[Marks To Market](#marks-to-market)** 对象列表 |

### Marks To Market

| 字段 | 类型 | 描述 |
|-----------------------------------|--------|--------------------------------------------------------------|
| `reference_date` | string | 发行系列份额价值日期（YYYY-MM-DD） |
| `before_amortization_unit_price` | float | 摊销前发行系列的份额价值 |
| `unit_price` | float | 收盘后发行系列的份额价值 |

---

# 简介

URL: /zh-Hans/documentation/iaas/passivo/inicio

欢迎使用**被动业务**相关操作的集成文档。本节介绍与所提供服务交互所需的所有工具和资源，从投资者注册到执行金融操作。

## 概述

被动业务 API 提供一套功能，旨在便于投资基金的金融操作管理和执行。通过它，可以进行投资者注册、金融申请、赎回申请、份额锁定及其他资产管理基本操作。

服务通过端点提供，使客户应用程序与平台之间能够进行安全高效的通信。

### 服务访问

要获得服务访问权限，需要在我们的均质化环境（Sandbox）和生产环境中完成必要的开放配置。请通过电子邮件 [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) 联系集成团队，申请访问凭证并获取激活流程指导。

## 可用资源

### 投资者注册

- **创建投资者/投资者分析**：允许注册投资者并进行初始注册分析。详见：[5.9.2.1 创建投资者](/documentation/iaas/investidor/cadastro/criar_investidor)
- **查询投资者信息**：查询投资者的注册信息。详见：[5.9.2.2 查询投资者信息](/documentation/iaas/investidor/cadastro/busca_informacoes_do_investidor)
- **查询投资者注册分析信息**：允许查询投资者注册分析状态。详见：[5.9.2.3 查询注册分析](/documentation/iaas/investidor/cadastro/busca_informacoes_de_uma_analise_cadastral_do_investidor)
- **发送注册数据**：发送补充注册数据进行分析。详见：[5.9.2.4 发送注册数据](/documentation/iaas/investidor/cadastro/enviar_dados_cadastrais)

### 金融申请

- **创建金融申请**：允许在某发行系列中创建金融申请。详见：[5.9.5.1 创建金融申请](/documentation/iaas/passivo/aplicacao_financeira/criar_aplicacao_financeira)
- **查询金融申请**：允许通过键或分页搜索查询金融申请。详见：[5.9.5.2 按键查询](/documentation/iaas/passivo/aplicacao_financeira/buscar_aplicacao_financeira_por_chave) 和 [5.9.5.3 分页查询](/documentation/iaas/passivo/aplicacao_financeira/busca_paginada_aplicacoes_financeiras)

### 赎回申请

- **创建赎回申请**：允许为投资者创建赎回申请。详见：[5.9.6.1 创建赎回申请](/documentation/iaas/passivo/pedido_de_resgate/criar_pedido_de_resgate)
- **查询赎回申请**：通过键或分页搜索查询赎回申请。详见：[5.9.6.2 按键查询](/documentation/iaas/passivo/pedido_de_resgate/buscar_pedido_de_resgate_por_chave)、[5.9.6.3 按投资者分页查询](/documentation/iaas/passivo/pedido_de_resgate/consulta_pedidos_resgate_investidor) 和 [5.9.6.4 按基金类别分页查询](/documentation/iaas/passivo/pedido_de_resgate/consulta_pedidos_resgate_classe_fundo)

### 份额锁定

- **申请份额锁定**：允许申请份额锁定作为担保。详见：[5.9.8.1 申请份额锁定](/documentation/iaas/passivo/bloqueio_de_cotas/solicitar_bloqueio_de_cotas)
- **查询份额锁定**：按投资者或分页方式查询份额锁定。详见：[5.9.8.2 查询份额锁定](/documentation/iaas/passivo/bloqueio_de_cotas/consulta_de_bloqueio_de_cotas)

## 结语

本文档作为被动业务服务集成和使用的完整指南。如有疑问，请通过电子邮件 [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) 联系我们的支持团队。

---

# 按键查询赎回申请

URL: /zh-Hans/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

情况 01：查询成功

```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",
            "issuance_serie_key":"UUID"
        }
    },
    "status_events": [
        {
            "event_datetime": "yyyy-mm-dd HH:MM:SS:ms",
            "status": "pending_quote | processing_quote | canceled | quoted"
        }
    ]
}
```

### 赎回申请
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|----------|---------------------------------------------------------------------------------|------------|
| `redemption_request_key` | string | 赎回申请的唯一标识键 | 36 |
| `redemption_request_type` | string | **[赎回申请类型](#redemption_request_type)**枚举值 | - |
| `status` | string | **[赎回申请状态](#redemption_request_status)**枚举值 | - |
| `quotation_date` | string | 报价日期 | - |
| `payment_date` | string | 付款日期 | - |
| `request_datetime` | string | 赎回申请创建日期 | - |
| `processed_value` | float | 已处理的赎回金额 | - |
| `investor_position` | JSON | **[投资者持仓](#investor_position)**对象 | - |
| `status_events` | array | **[状态事件](#status_event)**对象列表 | - |

### 赎回申请类型
| 枚举值 | 描述 |
|--------------------------------|-------------------------------------------------|
| `gross_redemption_value` | 按总值赎回 |
| `number_of_quotas` | 按份额数量赎回 |
| `remaining_application_value` | 按剩余值赎回 |

### 赎回申请状态
| 枚举值 | 描述 |
|--------------------------|-------------------------------------------------|
| `pending_quote` | 待付款 |
| `processing_quote` | 待报价 |
| `quoted` | 已报价 |
| `canceled` | 全额摊销 |

### 投资者持仓
| 字段 | 类型 | 描述 |
|--------------------------|--------|-------------------------------------------------------|
| `investor` | JSON | **[投资者](#investor)**对象 |
| `total_net_worth` | float | 投资者持仓的净资产 |
| `total_number_of_quotas` | float | 投资者持仓的份额数 |
| `issuance_serie` | JSON | **[发行系列](#issuance_serie)**对象 |
| `investor_position_key` | JSON | 投资者持仓的唯一标识键 |

### 投资者
| 字段 | 类型 | 描述 | 字符数 |
|--------------------------|----------|---------------------------------------------------|------------|
| `name` | string | 投资者名称 | 最多 255 |
| `investor_key` | string | 投资者的唯一标识键 | 36 |
| `document_number` | string | 投资者的 CPF/CNPJ | 14 或 18 |
| `person_type` | string | 自然人/法人/基金类 | 最多 50 |
| `distributor` | JSON | **[分销商](#distributor)**对象 | - |
| `account_data` | JSON | **[账户数据](#account_data)**对象 | - |

### 分销商
| 字段 | 类型 | 描述 | 字符数 |
|--------------------------|----------|---------------------------------------------------|------------|
| `name` | string | 分销商名称 | 最多 255 |
| `distributor_key` | string | 分销商的唯一标识键 | - |
| `document_number` | string | 分销商的 CPF/CNPJ | 14 或 18 |
| `account_data` | JSON | **[账户数据](#account_data)**对象 | - |

### 账户数据
| 字段 | 类型 | 描述 |
|------------------------------|----------|-----------------------------------------------------------------------------|
| `account_digit` | string | 银行账户验证码 |
| `account_branch` | string | 银行支行号 |
| `account_number` | string | 银行账号 |
| `financial_institution_code` | string | 金融机构代码 |
| `financial_institution_ispb` | string | 巴西支付系统中的金融机构标识符 |

### 发行系列
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|----------|---------------------------------------------------|------------|
| `name` | string | 发行系列名称 | 最多 255 |
| `issuance_serie_key` | string | 发行系列的唯一标识键 | 36 |
| `cetip_code` | string | 发行系列在 CETIP 中的资产代码 | 10 |
| `start_date` | string | 发行系列开始日期 | 10 |
| `maturity_date` | string | 发行系列到期日期 | 10 |
| `original_quota_value` | float | 原始份额价值 | - |
| `remuneration_type` | string | 收益率曲线/剩余 | 最多 50 |
| `investment_category` | string | FIDC/多市场 | 最多 50 |
| `condominum_type` | string | 开放式/封闭式 | 最多 50 |
| `tax_classification` | string | 短期/长期 | 最多 50 |
| `investment_restriction_type` | string | 无限制/合格投资者/专业投资者 | 最多 50 |
| `minimum_share_capital` | float | 最低投资金额 | - |
| `accounting_date` | string | 发行系列的会计日期 | 10 |
| `sub_class` | JSON | **[子类](#sub_class)**对象 | - |

### 子类
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|----------|---------------------------------------------------|------------|
| `name` | string | 子类名称 | 最多 255 |
| `sub_class_key` | string | 子类的唯一标识键 | 36 |
| `subordination_level` | int | 子类的从属级别 | - |
| `fund_class` | JSON | **[基金类](#fund_class)**对象 | - |

### 基金类
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|----------|---------------------------------------------------|------------|
| `name` | string | 基金类名称 | 最多 255 |
| `fund_class_key` | string | 基金类的唯一标识键 | 36 |
| `document_number` | string | 基金类的 CNPJ | - |

---

# Consulta paginada de pedidos de resgate por classe de fundo

URL: /zh-Hans/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: /zh-Hans/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"
}
```

---

# 创建赎回申请

URL: /zh-Hans/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",
    "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"
}
```

:::::warning
- redemption_request_type 字段定义是否需要传入 gross_redemption_value 、 remaining_application_value 和 number_of_quotas 字段。

- 若为 gross_redemption_value ，则 gross_redemption_value 字段为必填。
- 若为 remaining_application_value ，则 remaining_application_value 字段为必填。
- 若为 number_of_quotas ，则 number_of_quotas 字段为必填。
- 若为 net_value_redemption ，则 net_value 字段为必填。

- disbursement_account_key 字段用于将赎回清算到投资者的 特定账户 。如果未指定特定账户，将使用投资者的 主账户 。
:::::

### Body params
| 字段 | 类型 | 描述 | 必填 |
|-----------------------------------|----------|-----------------------------------------------------------------------------------------|-----|
| `issuance_serie_key` | string | 发行系列的唯一标识键 | 是 |
| `redemption_request_type` | string | **[赎回申请类型](#tipos_de_pedido_de_resgate)**枚举值 | 是 |
| `gross_redemption_value` | float | 赎回总值，未扣除所得税和金融交易税 | 否 |
| `net_value` | float | 赎回净值，已扣除所得税和金融交易税 | 否 |
| `remaining_application_value` | float | 应用剩余值 | 否 |
| `number_of_quotas` | float | 份额数量 | 否 |
| `disbursement_account_key` | string | 投资者银行账户的唯一标识键 | 否 |
| `quotation_date` | string | 赎回报价日期 | 否 |

### 赎回申请类型
| 枚举值 | 描述 |
|---------------------------------|-------------------------------------------------|
| `gross_redemption_value` | 按总值赎回 |
| `number_of_quotas` | 按份额数量赎回 |
| `remaining_application_value` | 按剩余持仓赎回 |
| `net_value_redemption` | 按净值赎回 |

### Response
```json title='Response Body'
{
    "redemption_request_key": "UUID"
}
```

---

# 发送已签署入会协议

URL: /zh-Hans/documentation/iaas/passivo/termo_de_adesao/enviar_termo_de_adesao_assinado

---
### 简介
本资源旨在向我们发送**投资者**对某基金**发行系列**的**入会协议**签署证明。

:::warning 注意
本资源仅适用于担任**分销商**角色的集成。
:::

### 输入/输出：
作为***输入***，需发送投资者已入会的基金**发行系列** UUID、**签署类型**以及根据签署方式所需的验证内容。以下是示例。

作为***输出***，将返回 ***investor_adhesion_key***。***investor_adhesion_key*** 用于标识**投资者的入会**。

### 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 注意
在集成过程中，将要求对发送的哈希值进行身份验证。
:::

### Response
```json title='Response Body'
{
    "investor_adhesion_key": "UUID"
}
```

---

# Solicitar Termo de Adesão

URL: /zh-Hans/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.

### 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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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.
:::

## 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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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** é o identificador curto acordado com a QI CTVM na configuração da entrega (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`.

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.
:::

## Entrega via SFTP

Os relatórios são disponibilizados diariamente via SFTP (Secure File Transfer Protocol). 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).

Os relatórios que entram na rotina diária são definidos por fundo, na configuração da entrega. Para incluir ou remover um relatório da rotina, entre em contato com o time de integração.

## 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 sob demanda, por cessão. | `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 sob demanda, por cessão. | `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: /zh-Hans/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. |

---

# Composição da Carteira

URL: /zh-Hans/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.

---

# XML ANBIMA (tipos 5 e 401)

URL: /zh-Hans/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 diária do SFTP**, junto com os demais relatórios. 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.

---

# 创建待回购/出售的资产

URL: /zh-Hans/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
payload 中提供的 external_id 必须对应基金投资组合中存在的资产的 external_id。
:::

#### Body Params

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `external_id` * | string | 合作伙伴提供的待回购/出售资产唯一标识键。 | 最多50 |
| `sale_value` *| float | 资产将被注销的金额 | 2位小数 |

### Response

STATUS 201

```json title='Response Body'
{
    "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "status": "pending_assets_insertion",
}
```

---

# 经理审批

URL: /zh-Hans/documentation/iaas/venda_ativos/assignment/aprovacao_recompra

:::info 致经理们
需要注意的是，此路由仅对经理开放。如果未集成，可以通过Portal执行此操作。
:::

### Request

ENDPOINT /trade_resolve/fund_class/FUND_CLASS_KEY/assignment/EXTERNAL_ID
MÉTODO PUT

```json title='Request Body'
{
	"assignment_status": "approved"
}
```

#### Assignment Status 枚举值
| 枚举值 | 描述 |
|--------------|---------------|
| **approved** | 批准批次 |
| **reproved** | 拒绝批次 |

### Response

STATUS 201

```json title='Response Body'
{
    "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "status": "approved",
}
```

---

# 创建回购批次

URL: /zh-Hans/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

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `external_id` * | string | 集成合作伙伴系统中此批次的唯一标识键。 | 最多50 |
| `assignment_date` *| string | 回购日期 | YYYY-MM-DD |
| `assignment_configuration_key` *| string | CTVM 提供的唯一键 | 36 |
| `source_account` *| 对象 | 将向基金付款的账户对象 | - |

### source account 对象

| 字段 | 类型 | 描述 | 字符数 |
|-|-|-|-|
| `document_number` * | string | 将向基金付款的账户证件号。 | 最多18 |

### Response

STATUS 201

```json title='Response Body'
{
    "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "status": "pending_assets_insertion",
}
```

---

# 结束资产插入

URL: /zh-Hans/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",
}
```

---

# 资产回购与出售

URL: /zh-Hans/documentation/iaas/venda_ativos/inicio

本节介绍用于**出售和回购**已纳入 QI CTVM 所管理基金投资组合的信用权利的 API。该流程涵盖从创建批次到将资产从基金投资组合中注销的全过程。

:::tip 背景
该服务仅将资产从基金**投资组合中注销**，不会向其他管理机构发送数据。

该服务有两个基本概念：**批次**（`assignment`）和**资产**（`asset`）。一个批次由一个或多个资产组成，插入的每个资产都必须已经存在于基金的投资组合中。
:::

:::info 前提条件
- 如需访问这些服务，请联系 [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br)，以便在同质化（Sandbox）环境和生产环境中获得相应权限。
- 您需要 `fund_class_key`（基金密钥），它构成本 API 所有端点的基础 URL；以及 `assignment_configuration_key`（配置密钥），在创建批次时提供：

```
/trade_resolve/fund_class/{fund_class_key}
```
:::

## 出售/回购流程

下图展示了主路径、分支以及每个步骤产生的状态。将鼠标悬停在节点上可查看端点，点击可打开该步骤的文档。

<FlowDiagram
  columns={3}
  labels={{ you: '集成方', qitech: 'QI Tech', manager: '基金管理人', docs: '查看文档' }}
  nodes={[
    { id: 'criacao', row: 1, col: 2, actor: 'you', num: 1,
      title: '创建批次',
      status: 'pending_assets_insertion',
      desc: '需提供唯一的 external_id、操作日期，以及向基金付款的账户。',
      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: '插入资产',
      status: '资产：pending_wallet_sale',
      desc: '每个资产一次请求，使用该资产入库时所用的同一个 external_id 标识。该资产必须在投资组合中处于有效状态。',
      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: '视情况而定',
      title: '确认价格',
      status: '资产：pending_validation',
      desc: '当售价与公允会计价值偏差超过 5% 时，资产将被暂缓，需要明确确认。该端点尚未提供文档 — 请与 integracao.dtvm@qitech.com.br 确认。' },

    { id: 'encerramento', row: 3, col: 2, actor: 'you', num: 3,
      title: '关闭批次',
      desc: '批次中至少需要有一个未被丢弃的资产。您可以提供 number_of_assets 和 total_value 让 API 核对总数。',
      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: '批次已丢弃',
      status: 'discarded',
      desc: '在关闭批次之前可以丢弃。一旦条款进入流转，批次便无法再被丢弃。' },

    { id: 'termo', row: 4, col: 2, actor: 'qitech',
      title: '回购条款',
      status: 'pending_signed_term_submission',
      desc: '内部条款：由 QI Tech 生成文件并收集签署。外部条款：由集成方提交已签署的条款。' },

    { id: 'credito', row: 5, col: 2, actor: 'qitech',
      title: '等待款项入账至基金账户',
      status: 'pending_payment',
      desc: '条款签署完成后，QI Tech 会在基金账户中登记付款预期。' },

    { id: 'baixa', row: 6, col: 2, actor: 'qitech', tone: 'ok',
      title: '资产已从投资组合注销',
      status: 'completed',
      desc: '款项确认后，资产将逐个注销。全部完成后，批次结束。' },
  ]}
  edges={[
    { from: 'criacao', to: 'ativos' },
    { from: 'ativos', to: 'validacao', label: '偏差超过 5%', dashed: true },
    { from: 'validacao', to: 'encerramento', label: '已确认', dashed: true },
    { from: 'ativos', to: 'encerramento' },
    { from: 'encerramento', to: 'descartado', label: 'discarded', tone: 'end' },
    { from: 'encerramento', to: 'termo', label: '已关闭', tone: 'ok' },
    { from: 'termo', to: 'credito', label: '已签署' },
    { from: 'credito', to: 'baixa', label: '已付款' },
  ]}
/>

## 分步说明

### 1. 创建批次

创建批次时需提供唯一标识符（`external_id`）、操作日期，以及向基金付款的账户。批次的初始状态为 `pending_assets_insertion`，它是所有待注销资产的容器。

**[查看创建批次的文档](/documentation/iaas/venda_ativos/assignment/criacao_recompra)**

### 2. 插入资产

每次请求插入一个资产，并使用该资产入库时所用的同一个 `external_id` 进行标识。插入时该资产必须在基金投资组合中处于**有效**状态。

**[查看插入资产的文档](/documentation/iaas/venda_ativos/asset/criacao_recompra)**

:::caution 价格偏差超过 5%
如果所提供的售价与资产的公允会计价值偏差**超过 5%**，该资产不会自动继续流转：它将停留在 `pending_validation` 状态，需要集成方明确确认后才能进入注销环节。偏差在 5% 以内的资产将直接进入 `pending_wallet_sale`。

确认端点目前尚未在本节中提供文档 — 如果您的流程可能产生超过 5% 的偏差，请与 [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) 确认具体操作方式。
:::

### 3. 关闭批次

插入所有资产后，关闭批次。批次中至少需要有一个未被丢弃的资产。您还可以选择性地提供 `number_of_assets` 和 `total_value`，以便 API 在接受关闭请求前核对合并后的资产数量与总金额。

**在此步骤之前**可以丢弃批次：一旦条款进入流转，批次便无法再被丢弃。

**[查看关闭批次的文档](/documentation/iaas/venda_ativos/assignment/fechamento_recompra)**

### 4. 回购条款

回购条款由谁出具取决于批次的配置：

- **内部条款** — 由 QI Tech 生成条款并收集各方签署，集成方无需任何操作。
- **外部条款** — 批次进入 `pending_signed_term_submission` 状态，集成方需提交已签署的条款，流程才能继续。

两种情况下，条款签署完成后批次都会进入 `pending_payment`，等待款项入账至基金账户。

### 5. 付款与资产注销

最后的步骤为自动执行：QI Tech 确认款项已入账至基金账户，资产从投资组合中注销；当所有资产处理完毕后，批次以 `completed` 状态结束。

---

# 获取账户信息

URL: /zh-Hans/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

| 字段 | 类型 | 描述 |
|---------------|--------|--------------------------------------------------------|
| `data` | array | **[Account](#account)** 对象列表 |
| `limit` | int | 每页返回对象数量上限 |
| `page` | int | 已返回页码 |
| `is_last_page` | boolean | 表示已返回页面是否为最后一页 |

### Account
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------|--------|------------------------------------------------|------------|
| `account_key` | string | 系统中账户唯一标识键 | 36 |
| `account_type` | string | 账户类型 | 最多50 |
| `financial_institution` | JSON | 金融机构对象 | - |
| `account_status` | string | 账户状态 | 最多50 |
| `account_number` | string | 账户号码 | 最多50 |
| `account_digit` | string | 账户校验位 | 1 |
| `account_branch` | string | 支行编号 | 最多50 |
| `accounting_identification` | int | 账户序列标识符 | - |
| `balance` | int | 当前账户余额 | - |
| `owner` | JSON | 持有人对象 | - |
| `owner_document_number` | string | 持有人证件号 | 14或18 |

:::caution **注意**

余额通过将元和分拼接提供，例如：1234 = R$ 12,34
:::
### Financial institution
| 字段 | 类型 | 描述 | 字符数 |
|--------|--------|--------------------------------------------------|------------|
| `ispb` | string | 巴西支付系统标识符 | 8 |
| `code` | string | 金融机构代码 | 3 |
| `name` | string | 金融机构名称 | 最多255 |

### Owner
| 字段 | 类型 | 描述 | 字符数 |
|-------------------|--------|---------------------------|------------|
| `name` | string | 持有人姓名 | 最多255 |
| `document_number` | string | 持有人证件号 | 14或18 |

---

# 获取账户交易记录

URL: /zh-Hans/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

| 字段 | 类型 | 描述 |
|---------------|--------|----------------------------|
| `status` | string | 交易状态 |
| `start_date` | string | 查询起始日期 |
| `end_date` | string | 查询结束日期 |
| `page` | string | 已返回页码 |

### Response Fields

| 字段 | 类型 | 描述 |
|---------------|--------|--------------------------------------------------------|
| `data` | array | **[Transaction](#transaction)** 对象列表 |
| `limit` | int | 每页返回对象数量上限 |
| `page` | int | 已返回页码 |
| `is_last_page` | boolean | 表示已返回页面是否为最后一页 |

### Transaction
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------|--------|---------------------------------------------------|------------|
| `transaction_key` | string | 交易唯一标识键 | 36 |
| `transaction_type` | string | 交易类型 | 最多50 |
| `transaction_status` | string | 交易状态 | 最多50 |
| `transaction_description` | string | 银行提供的交易描述 | 最多255 |
| `amount` | bigint | 交易金额乘以100（例如：R$1,00 == 100） | - |
| `transaction_datetime` | string | 交易日期和时间 | ISO 8601 |
| `account_balance` | bigint | 交易后账户余额 | - |
| `transaction_data` | JSON | 含交易附加信息的对象 | - |
| `account` | JSON | 包含交易的账户对象 | - |

### Account
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------|--------|-------------------------------------|------------|
| `account_key` | string | 账户唯一标识键 | 36 |
| `account_type` | string | 账户类型 | 最多50 |
| `financial_institution` | JSON | 金融机构对象 | - |
| `account_status` | string | 账户状态 | 最多50 |
| `account_number` | string | 账户号码 | 最多50 |
| `account_digit` | string | 账户校验位 | 1 |
| `account_branch` | string | 支行编号 | 最多50 |
| `accounting_identification` | int | 账户序列标识符 | - |
| `balance` | int | 当前账户余额 | - |
| `owner` | JSON | 持有人对象 | - |
| `owner_document_number` | string | 持有人证件号 | 14或18 |

:::caution **注意**

余额通过将元和分拼接提供，例如：1234 = R$ 12,34
:::
### Financial institution
| 字段 | 类型 | 描述 | 字符数 |
|--------|--------|---------------------------------------------------|------------|
| `ispb` | string | 巴西支付系统标识符 | 8 |
| `code` | string | 金融机构代码 | 3 |
| `name` | string | 金融机构名称 | 最多255 |

### Owner
| 字段 | 类型 | 描述 | 字符数 |
|-------------------|--------|---------------------------|------------|
| `name` | string | 持有人姓名 | 最多255 |
| `document_number` | string | 持有人证件号 | 14或18 |

### Conciliation Group
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|--------|------------------------------------------|------------|
| `description` | string | 交易对账描述 | 最多255 |
| `conciliation_group_key` | string | 对账唯一标识键 | 36 |
| `conciliation_group_datetime` | string | 对账日期和时间 | ISO 8601 |

---

# 获取账户交易记录

URL: /zh-Hans/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

| 字段 | 类型 | 描述 |
|---------------|--------|----------------------------|
| `status` | string | 交易状态 |
| `start_date` | string | 查询起始日期 |
| `end_date` | string | 查询结束日期 |
| `page` | string | 已返回页码 |

### Response Fields

| 字段 | 类型 | 描述 |
|---------------|--------|--------------------------------------------------------|
| `data` | array | **[Transaction](#transaction)** 对象列表 |
| `limit` | int | 每页返回对象数量上限 |
| `page` | int | 已返回页码 |
| `is_last_page` | boolean | 表示已返回页面是否为最后一页 |

### Transaction
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------|--------|---------------------------------------------------|------------|
| `transaction_key` | string | 交易唯一标识键 | 36 |
| `transaction_type` | string | 交易类型 | 最多50 |
| `transaction_status` | string | 交易状态 | 最多50 |
| `transaction_description` | string | 银行提供的交易描述 | 最多255 |
| `amount` | bigint | 交易金额乘以100（例如：R$1,00 == 100） | - |
| `transaction_datetime` | string | 交易日期和时间 | ISO 8601 |
| `account_balance` | bigint | 交易后账户余额 | - |
| `transaction_data` | JSON | 含交易附加信息的对象 | - |
| `account` | JSON | 包含交易的账户对象 | - |

### Account
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------|--------|-------------------------------------|------------|
| `account_key` | string | 账户唯一标识键 | 36 |
| `account_type` | string | 账户类型 | 最多50 |
| `financial_institution` | JSON | 金融机构对象 | - |
| `account_status` | string | 账户状态 | 最多50 |
| `account_number` | string | 账户号码 | 最多50 |
| `account_digit` | string | 账户校验位 | 1 |
| `account_branch` | string | 支行编号 | 最多50 |
| `accounting_identification` | int | 账户序列标识符 | - |
| `balance` | int | 当前账户余额 | - |
| `owner` | JSON | 持有人对象 | - |
| `owner_document_number` | string | 持有人证件号 | 14或18 |

:::caution **注意**

余额通过将元和分拼接提供，例如：1234 = R$ 12,34
:::
### Financial institution
| 字段 | 类型 | 描述 | 字符数 |
|--------|--------|---------------------------------------------------|------------|
| `ispb` | string | 巴西支付系统标识符 | 8 |
| `code` | string | 金融机构代码 | 3 |
| `name` | string | 金融机构名称 | 最多255 |

### Owner
| 字段 | 类型 | 描述 | 字符数 |
|-------------------|--------|---------------------------|------------|
| `name` | string | 持有人姓名 | 最多255 |
| `document_number` | string | 持有人证件号 | 14或18 |

### Conciliation Group
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|--------|------------------------------------------|------------|
| `description` | string | 交易对账描述 | 最多255 |
| `conciliation_group_key` | string | 对账唯一标识键 | 36 |
| `conciliation_group_datetime` | string | 对账日期和时间 | ISO 8601 |

---

# 简介

URL: /zh-Hans/documentation/iaas/visibildade_de_caixa/inicio

现金流动的可见性对于投资基金的管理至关重要。本节将介绍用于查询账户信息的可用工具。

要获得这些服务的访问权限，请联系 [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) 团队，以便在均质化环境（Sandbox）和生产环境中完成必要的授权配置。

### 账户信息
通过此工具，可以获取基金账户的信息列表，详见：[5.7.2.1 获取账户信息](/documentation/iaas/visibildade_de_caixa/get_accounts)。

---

# 基金账户间转账

URL: /zh-Hans/documentation/iaas/visibildade_de_caixa/post_internal_transfer

此功能允许在同一基金下的两个账户之间进行金额转账，从来源账户扣款并向目标账户入账。

---

### 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

| 字段 | 类型 | 描述 |
|------------------|--------|-----------------------------------------------|
| `fund_class_key` | string | QI CTVM 中基金唯一标识键 |

### Body Params

| 字段 | 类型 | 描述 |
|-----------------------|--------|--------------------------------------------------------------------|
| `amount` | int | 待转账金额，以分为单位（例如：`15000` = 150.00 巴西雷亚尔） |
| `description` | string | 转账描述 |
| `origin_key` | string | 转账的唯一幂等键（UUID v4），由集成方在每次请求时生成 |
| `origin_type` | string | 转账来源类型。必须以 `manual_transfer` 发送 |
| `source_account_key` | string | 待扣款账户（来源）的唯一标识键 |
| `target_account_key` | string | 待入账账户（目标）的唯一标识键 |
| `transfer_type` | string | 转账类型。接受 `pix` 或 `wire_transfer`，受来源账户所支持的类型限制 |

:::caution **注意**

为接收转账结果，需要配置转账确认的 webhook。
:::

---

# 创建退款申请

URL: /zh-Hans/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"
        },
    },
    "target_pix_key": "exemplo@gmail.com"
}
```

### Path Params

| 字段 | 类型 | 描述 |
|-----------------|--------|-----------------------------------------------|
| `fund_class_key`| string | QI CTVM 中基金唯一标识键 |

### Body Params

| 字段 | 类型 | 描述 |
|----------------------|-------------------------|----------------------------------------------------------------------------|
| `amount`* | float | 待退款金额 |
| `description`* | string | 退款描述 |
| `reversal_type`* | string | 退款类型 |
| `reference_date`* | string | 退款处理的参考日期 |
| `source_account_key` | int | 退款来源账户唯一标识键 |
| `source_account` | **[Account](#account)** | 退款来源账户对象 |
| `target_account` | **[Account](#account)** | 退款目标账户对象 |
| `transaction_key` | string | 现金系统中待退款转账的唯一标识键 |
| `target_pix_key` | string | 目标账户的 PIX 密钥 |

:::caution **注意**

`source_account_key` 和 `source_account` 字段以及 `target_account`、`transaction_key` 和 `target_pix_key` 字段分别是待退款金额来源和退款目标的标识符。每组**各发送1个字段**，若发送多个，将返回400错误。
:::

### Account
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------|--------|-------------------------------------|------------|
| `account_number` | string | 账户号码 | 最多50 |
| `account_digit` | string | 账户校验位 | 1 |
| `account_branch` | string | 支行编号 | 最多4 |
| `financial_institution` | JSON | 金融机构对象 | - |
| `owner` | JSON | 持有人对象 | - |

### Financial institution
| 字段 | 类型 | 描述 | 字符数 |
|--------|--------|---------------------------------------------------|------------|
| `ispb` | string | 巴西支付系统标识符 | 8 |
| `code` | string | 金融机构代码 | 3 |
| `name` | string | 金融机构名称 | 最多255 |

### Owner
| 字段 | 类型 | 描述 | 字符数 |
|-------------------|--------|---------------------------|------------|
| `name` | string | 持有人姓名 | 最多255 |
| `document_number` | string | 持有人证件号 | 14或18 |

---

# Webhooks

URL: /zh-Hans/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"
}
```

---

# 文档介绍

URL: /zh-Hans/documentation/introducao_api_reference

本文档旨在描述并引导开发者使用我们的 REST API。

## 介绍

我们是巴西首家创建独家银行即服务（BaaS）模式的金融机构。我们的目标是帮助任何金融科技公司/信贷管理公司或企业以其所需的方式快速、灵活、安全地访问金融服务。了解更多请访问 https://qitech.com.br。

## 环境（Hosts）

QI Tech 为 SANDBOX 和 PRODUCTION 环境提供完全独立的基础设施，其中 sandbox 环境中的货币价值完全是虚拟的，只有 Production 环境才会进行有效的金融交易。

Sandbox 环境是为开发者进行集成测试而创建的，当他们准备好投入生产时，只需将 Host 和 Access Token 变量更新为 Production 环境的参数即可。

除了按环境划分外，我们还根据下表对金融服务、分析服务和 QI Tech 认证服务相关的 HOST 进行了区分：

| 服务 | 环境 | Host |
|-|-|-|
| BaaS 和 LaaS | 生产 | https://api-auth.qitech.app/ |
| BaaS 和 LaaS | 沙盒 | https://api-auth.sandbox.qitech.app/ |
| CaaS | 生产 | https://api.caas.qitech.app/ |
| CaaS | 沙盒 | https://api.sandbox.caas.qitech.app/ |
| CertifiQI | 生产 | https://api.certifiqi.com.br/ |
| CertifiQI | 沙盒 | https://api.sandbox.certifiqi.com.br/ |

:::danger 重要提示！
不得在 QI Tech 的沙盒环境中使用真实自然人和/或法人的数据。
:::

各环境始终保持相同版本，因此当生产环境发生更新时，沙盒环境也会同步更新。

## 入门步骤

要开始与 QI Tech API 集成，请按照以下步骤操作：

1. [创建访问配置文件](/documentation/primeiros_passos/inicio)
2. [密钥交换](/documentation/primeiros_passos/troca_de_chaves)
3. [认证测试](/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2)
4. [配置 Webhooks](/documentation/primeiros_passos/configurando_webhooks)

## 本文档如何划分？

完成"入门步骤"章节中的初始步骤后，即可在沙盒环境中使用 QI Tech 的微服务。

本文档按产品划分，包括：

- **Banking as a Service**
- **Lending as a Service**
- **Risk Solutions**
- **Investment as a Service**

## 错误消息

:::danger 注意！
QI 返回的错误消息不应被严格映射。我们 API 的错误消息中未来可能会包含额外的字段。
:::

---

# 欢迎来到 QI Tech API 手册区

URL: /zh-Hans/documentation/introducao_manuais

本区域旨在为 QI Tech API 的不同使用案例提供指导。

## 信用贷款

- **[INSS](/documentation/manual_inss/manual_credito_novo)** — INSS 受益人的新信贷、再融资和可携性
- **[SIAPE-SIGEPE](/documentation/siape/manual_siape)** — 联邦公务员新信贷
- **[私人代扣](/documentation/manual_consignado_privado/manual_detalhamento_fluxo_ativo)** — 通过拍卖或主动渠道的发起、查询、发行和背书
- **[私人养老金](/documentation/manual_previdencia_privada/manual_previdencia_privada_consulta)** — 私人养老金的查询、新信贷和背书
- **[FGTS 周年提款](/documentation/manual_FGTS/manual_fgts)** — 发起和授权查询

## 卡片

- **[预付卡](/documentation/manual_pre_pago/casos_uso)** — QI 预付卡使用案例
- **[INSS 代扣卡](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_emissao)** — 发行、跟踪、Webhooks、文件和地址管理
- **[QI Fatura](/documentation/manual_qi_fatura/pix_parcelado)** — 通过分期 PIX 的卡片体验

## 可携性

- **[Port Out](/documentation/manual_portabilidade/portabilidade_out)** — 信贷可携性
- **[留存证据](/documentation/manual_portabilidade/evidencias_de_retencao)** — 可携性留存证据

## 其他产品

- **[QI Sign](/documentation/manual_qi_sign/manual_qi_sign)** — 电子签名
- **[BNPL 电商](/documentation/manual_bnpl_ecommerce/manual_bnpl_ecommerce)** — 电商先买后付
- **[信用权谈判](/documentation/iaas/negociacao_recebiveis/manual_api)** — 应收账款谈判与转让

---

# 欢迎来到 QI Tech API 手册区

URL: /zh-Hans/documentation/introducao_operational_guides

本区域旨在为 QI Tech API 的不同使用案例提供指导。

---

# 金融机构查询

URL: /zh-Hans/documentation/lista_de_instituicoes_financeiras/consulta_de_instituicoes_financeiras

## Request

ENDPOINT /financial_institution
MÉTODO GET

### QUERY PARAMS

| 字段               | 描述                       |
|-------------------|----------------------------|
| `ispb_number`     | 金融机构 ISPB 号。          |
| `name`            | 金融机构名称               |
| `compe_number`    | 金融机构 Compe 号。         |
| `min_str_start_date` | 最早操作开始日期。       |
| `max_str_start_date` | 最晚操作开始日期。       |
| `page_number`     | 当前查询的页码             |
| `page_size`       | 每页结果数量               |

## Response

status: 200

Response Body: 带分页的查询

```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: 不带分页的查询

```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

请求参数均为可选项，若未指定任何参数，响应将返回所有机构（不分页）。

:::

---

# 空军薪资代扣贷款手册

URL: /zh-Hans/documentation/manual_aeronautica/manual_consignado

---

:::danger 注意！
QI Tech 的 webhooks 不应以严格方式进行映射。
我们 API 返回的 webhook payload 中可能会包含额外字段。
:::

:::info Webhook 重发
您可以按照以下文档中的详细说明查询并重发 webhooks：[Webhook 重发](/documentation/notificacoes/reenvio_de_notificacoes)。
:::

:::info 空军系统运作方式
空军代扣贷款系统通过 API 运作，每周七天、每天 24 小时全天候可用，包括节假日。
:::

## 1. 授权

在提交任何空军代扣贷款请求（查询、债务发行等）之前，需要先上传军人授权同意书，授权 QI 进行查询、批注及工资扣款维护。
上传授权文件，请按照[**文件上传**](../upload_de_documentos/)章节中的步骤进行操作。

上传后将在返回字段 "**document_key**" 中返回唯一密钥，该密钥需在"**authorization_document_key**"字段中发送于查询薪资代扣额度请求的 payload 中，详见下方**[3. 查询薪资代扣额度。](#3-consulta-de-margem-consignável)**

## 2. 在沙箱环境中模拟余额查询、合同列表查询及批注的成功场景

出于测试目的，我们提供了一组可用于模拟沙箱中成功案例的数据，如下所示：

| document_number | registration_code  |    token       | birthdate |
|-----------------|--------------------|----------------|-----------|
| 60221284630     |       18571        |    abc123      |1954-09-08 |
| 57343241400     |       72893        |    abc123      |1998-02-06 |
| 13212590696     |       15410        |    abc123      |1959-11-14 |

这些信息应在模拟时发送于**请求的 payload** 中，结果将通过相应的成功 webhook 返回。

## 3. 查询薪资代扣额度 {#3-consulta-de-margem-consignavel}

在获得 **CPF**、**军人注册编号**及**授权文件密钥**后，集成合作方可通过以下端点对军人的薪资代扣额度进行**异步查询**：

### 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
 CPF 应以文本格式填写，最多 11 个字符，不含"."、不含"-"，并在左侧以零填充。
 注册编号也应以文本格式填写。
:::

#### Request Body Params

| 字段                         | 类型   | 描述                                 |
|------------------------------|--------|--------------------------------------|
| `document_number`            | string | 军人的 CPF。                         |
| `registration_code`          | string    | 军人的注册编号。                  |
| `authorization_document_key` | uuid   | 授权条款的 **document_key**。        |

### Sincronous Response

ENDPOINT /airforce_payroll/balance
STATUS 201

Response Body

```json
{
	"balance_key": "81da8afb-e1b2-4215-8093-c4b5feab8a9f",
	"status": "pending_search"
}
```

**由于是异步操作，借款人薪资代扣额度查询数据将通过 webhook 返回。**

#### Response Body Params

| 字段                         | 类型   | 描述                                                                                                              |
|------------------------------|--------|------------------------------------------------------------------------------------------------------------------------|
| `balance_key`                | string | 薪资代扣额度查询的标识密钥。                                                              |
| `status`                     | enum   | [以下薪资代扣额度查询状态枚举值。](#enumeradores-de-status-de-consulta-de-margem-consignável) |

#### 薪资代扣额度查询状态枚举值 {#enumeradores-de-status-de-consulta-de-margem-consignavel}

| 枚举值        | 描述                                                                   |
|-------------------|-----------------------------------------------------------------------------|
| `pending_search`  | 薪资代扣额度查询待空军系统响应。 |
| `processed`       | 薪资代扣额度查询已处理。                                  |

:::info
 状态 ***'processed'*** 仅表示余额请求已有效发送并处理，但不代表请求的成功或失败，相关信息将包含在通过 **Webhook** 发送的 payload 中，详见下文。 
:::

### 成功查询

成功 webhook 将以如下格式返回：

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
     }
}
```

#### 成功响应体参数
| 字段                              | 类型    | 描述                                                                        |
|------------------------------------|---------|----------------------------------------------------------------------------------|
| `webhook_type`                     | string  | Webhook 类型。                                                                 |
| `key`                              | uuid    | Webhook 的参考密钥。此处指 **balance_key**          |
| `event_datetime`                   | string  | Webhook 发送的日期和时间。                                                 |
| `status`                           | string  | 薪资代扣额度查询状态。                                        |
| `data`                             | json    | 包含查询相关数据的字段。                             |
| `data.military_unit`               | string  | 军人在 eConsig 系统中注册所属的机构。                  |
| `data.military_branch`             | string  | 军人所在的军事机关/组织。                                    |
| `data.category`                    | string  | 军人类别。                                                            |
| `data.name`                        | string  | 军人姓名。                                                                 |
| `data.document_number`             | string  | 军人的 CPF。                                                                  |
| `data.registration_code`           | string  | 军人的注册编号。                                                            |
| `data.balance`                     | string  | 可用于办理代扣贷款的可用额度。                     |
| `data.birth_date`                  | string  | 军人出生日期。                                                   |
| `data.grant_date`                  | string  | 军人入职日期。                                                     |
| `data.allowed_installment_numbers` | string  | 被查询军人可办理代扣贷款的最大分期数。 |

### 查询失败

失败 webhook 将以如下格式返回：

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": {} 
    }
}
```

每种**已映射**的错误类型都有标题、代码及更详细的描述。如果尚未映射，将以相同格式返回，但标题为 ***unknown_response***。除相同字段外，下表详细描述了返回的参数。

#### 失败响应体参数

| 字段                     | 类型   | 描述                                                                                                               |
|---------------------------|--------|-------------------------------------------------------------------------------------------------------------------------|
| `data.title`                     | string | 发生错误的标题。                                                                                       |
| `data.description`               | string | 发生错误的**英文**详细描述。                                                                      |
| `data.translation`               | string | 错误描述的翻译。                                                                                   |
| `data.code`                      | string | 收到的错误代码。**最后 3 位数字为 Zetra 收到的错误代码。**（例如：ZP000***329***） |
| `data.extra_fields`              |  json  | 用于可能的额外属性的字段。                                                                            |

 --- 

### 查询薪资代扣额度请求

如果合作方想了解已创建的 Balance 实体的进展，可以对其发起查询：

:::danger 注意！
我们强烈建议使用 Webhook 作为借款人薪资代扣额度查询信息的参考依据。此功能将来可能被移除。
:::

 #### 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. 合同列表查询

在获得潜在借款人的 **CPF**、**军人注册编号**及**Token** 后，集成合作方可通过以下端点查询可供购买的军人合同列表：

### Request

ENDPOINT /airforce_payroll/portability_contracts_report
MÉTODO POST

Request Body

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

:::info
 CPF 应以文本格式填写，最多 11 个字符，不含"."、不含"-"，并在左侧以零填充。注册编号也应以文本格式填写。
:::

#### Request Body Params

| 字段                         | 类型   | 描述                                 |
|------------------------------|--------|--------------------------------------|
| `document_number`            | string | 军人的 CPF。                         |
| `registration_code`          | string | 军人的注册编号。                     |
| `token`                      | string | 军人的密码。                         |

### 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"
}
```

**由于是异步操作，借款人合同列表查询数据将通过 webhook 返回。**

#### Response Body Params

| 字段                              | 类型   | 描述                                                                                                              |
|------------------------------------|--------|------------------------------------------------------------------------------------------------------------------------|
| `portability_contracts_report_key` | string | 合同列表查询的标识密钥。                                                              |
| `status`                           | enum   | [合同列表查询状态枚举值。](#enumeradores-de-status-da-consulta-da-lista-de-contratos) |

#### 合同列表查询状态枚举值 {#enumeradores-de-status-da-consulta-da-lista-de-contratos}

| 枚举值         | 描述                                                                   |
|--------------------|-----------------------------------------------------------------------------|
| `pending_search`   | 合同列表查询待空军系统响应。 |
| `processed`        | 合同列表查询已处理。                                  |

:::info
 状态 ***'processed'*** 仅表示合同列表查询请求已有效发送并处理，但不代表请求的成功或失败，相关信息将包含在通过 **Webhook** 发送的 payload 中，详见下文。 
:::

### 合同列表查询 Webhook

成功 webhook 将以如下格式返回：

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
| 字段                                             | 类型    | 描述                                                                        |
|---------------------------------------------------|---------|----------------------------------------------------------------------------------|
| `webhook_type`                                    | string  | Webhook 类型。                                                                 |
| `key`                                             | uuid    | Webhook 的参考密钥。此处指 **balance_key**          |
| `event_datetime`                                  | string  | Webhook 发送的日期和时间。                                                 |
| `status`                                          | string  | 薪资代扣额度查询状态。                                        |
| `data`                                            | json    | 包含查询相关数据的字段。                             |
| `data.document_number`                            | string  | 军人的 CPF。                                                                  |
| `data.contracts`                                  | array   | 合同及其各自信息的列表。                           |
| `data.contracts.econsig_id`                       | string  | Zetra 系统中合同的唯一标识符。                             |
| `data.contracts.consignatory`                     | string  | 合同的代扣机构。                                                       |
| `data.contracts.installment_amount`               | float   | 分期付款金额。                                                                |
| `data.contracts.number_of_installments`           | int     | 合同的总分期数。                                            |
| `data.contracts.number_of_paid_installments`      | int     | 截至当前有效期已支付的分期数。                                   |
| `data.contracts.contract_status`                  | string  | 合同状态。                                                            |

合同可能的状态映射如下。
| 合同状态             | 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
 这些合同状态同样适用于内部合同的可能状态。
:::

### 合同列表查询请求

如果合作方想了解合同列表查询的进展，可以对其发起查询：

:::danger 注意！
我们强烈建议使用 Webhook 作为借款人合同列表信息的参考依据。此功能将来可能被移除。
:::

#### 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. 个人信贷操作模拟

首先需要计算清偿原始信贷操作所需的个人信贷操作金额。

原始债务的未偿余额应填写在 _**disbursed_amount**_ 字段中。

:::caution 注意
操作必须以 1 期分期模拟，在 **D0** 放款，分期付款到期日为放款日（操作支付日）后**第 D+5 个工作日**。
:::

### 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. 空军薪资代扣信贷操作模拟

本次模拟中，各字段的值将按以下方式分配：

_**installment_face_value**_ = 薪资代扣额度值

_**disbursement_date**_ = 模拟时刻后的**第 D+5 个工作日**

_**due_balance**_ = 个人信贷操作模拟中返回的第 1 期 **total_amount**

_**original_deadline**_ = 个人信贷操作的总期限（天数）（5 天）

### 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
        }
    ]
}
```

模拟中返回的 _**data.final_disbursement_amount**_ 字段将是支付给客户的找零金额。

---

### 查询个人信贷操作的分期金额

#### Request

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

:::info 信息
DEBT-KEY 是操作创建响应中返回的密钥（/debt 的响应）
:::

---

## 7. 创建债务人名下账户

在录入提案之前，需要在 QI Tech 为债务人开立账户。

该账户将用于接收个人信贷操作的放款，以及通过银行单据（Boleto）、TED 或 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"
	}
}
```

| 参数                                                    | 描述                                          |
|--------------------------------------------------------------|----------------------------------------------------|
| **account_owner**                                            | 债务人数据                                   |
| **is_operation_account**                                     | 表明该账户为操作账户。 |

### 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
/account 中返回的账户数据应作为个人信贷操作的放款账户使用
:::

### 5xx 错误或超时

在账户成功开立之前，流程不应继续。
如出现失败情况，在可能重试开户之前，应先确认账户是否确实未为客户开立。

可以通过列出特定 CPF 下已开立的账户来确认账户是否已为客户开立。

#### Request

ENDPOINT /account
MÉTODO POST
PARAMETER owner_document_number, requester_key

| 参数                 | 描述                          |
|---------------------------|------------------------------------|
| **owner_document_number** | 债务人的 CPF                     |
| **requester_key**         | 集成的内部密钥。 |

#### 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 信息
以上响应 payload 中仅列出了相关读取字段。
:::

---

## 8. 操作发行

- **个人信贷操作**：须在 D0 放款，且仅有一期分期付款，到期日为放款后**第 D+5 个工作日**。

:::danger 注意
发行个人信贷操作时，"_**financial**_" 对象必须与其模拟时发送的信息完全相同。
:::

:::info 信息
个人信贷操作只能在**工作日**放款，且放款时间取决于原始债务未偿余额的支付方式：
- **TED**：放款时间为 **6:30 至 17:15**
- **Boleto**：放款时间为 **7:00 至 22:00**
- **PIX**：任何时间均可（但建议在工作时间内放款，因为若操作在深夜放款，例如，PIX 入账可能因涉嫌欺诈而被拒绝）
:::

### 发行个人信贷操作

发行个人信贷操作时，需发送放款后需支付的 Boleto/TED/PIX 信息。

:::caution 注意
合作方必须生成操作的内部标识密钥，并在债务发行请求的 "_**requester_identifier_key**_" 字段中发送。
:::

#### 示例请求

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"
    }
}
```
    

#### 婚姻状况枚举值
| 枚举值   | 描述     |
|--------------|---------------|
| **single**   | 未婚   |
| **married**  | 已婚     |
| **widower**  | 丧偶      |
| **divorced** | 离婚 |

#### 5xx 错误或超时

如果请求返回 5xx 或超时，为了确认操作确实未在 QI 中创建，建议合作方对返回 5xx 或超时的操作进行查询。

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

如果 GET 返回 200，合作方不应重试创建操作，应继续操作流程。
如果返回 404 - Not Found，合作方应重试创建操作。

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 信息
操作创建响应中的 "key" 字段是 **DEBT-KEY**，即操作在 QI 中的唯一密钥。
:::

#### 签名

#### 授权放款

操作签名后，需要授权该操作进行放款。

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

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

#### 放款

操作签名并授权放款后，将自动进入放款流程。

放款处理完成后，合作方将收到如下 webhook：

#### 放款成功

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"
}
```

#### 放款后操作

个人信贷操作在 QI 开立的债务人账户放款后，将执行 Boleto/TED/PIX 支付，用于清偿债务人原始债务未偿余额（放款后操作）。

#### 成功

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"
}
```

  

#### 放款后操作错误

如果放款后操作付款出错，合作方将通过以下 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"
}
```

#### 放款后操作 TED 退款

如果放款后操作中执行的 TED 被目标金融机构退回，合作方将通过以下 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"
}
```

#### 重试失败的放款后操作

如果放款后操作付款出错/被退回，可通过以下端点重试：[/baas/action/**[ACTION-KEY]**](/documentation/emissao_de_divida/reprocessar_acao_pos_desembolso)

### 发行空军薪资代扣信贷操作

空军代扣信贷操作必须清偿个人信贷操作，并（如有找零）向客户释放找零金额。

#### Request

ENDPOINT /debt
MÉTODO POST

**可携性录入**

```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"
        }
    ]
}
```

**自由额度录入**

```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"
        }
    ]
}
```

**再融资录入**

```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"
        }
    ]
}
```

### collateral_data 对象字段详情
| 字段             	| 描述             						| 值  												|
|-----------------------|-----------------------------------------------|-------------------------------------------------------|
| reservation_type		| 预留类型								| [枚举值](#reservation_type_enumerator)			|
| registration_code		| 军人注册编号							| 123456789               								|
| reservation_method	| 确定何时开始尝试代扣贷款批注，是在信贷操作创建时，还是在操作发行时。	| [枚举值](#reservation_method_enumerator)		|
| portability_data  	| 可携性数据						| [可携性对象](#portability_data_object)	|

### 预留类型枚举值表 {#reservation_type_enumerator}
| 枚举值  | 描述 		|
|-------------|-----------------|
| new_credit  | 新增信贷 	|
| portability | 可携性 	|
| refinancing | 再融资 |

### 预留创建方式枚举值表 {#reservation_method_enumerator}

:::caution 注意
此字段非常重要，因为它直接决定向 Zetra 发出预留意向请求的时机。
:::

| 枚举值 	| 描述                                     																		|
|---------------|-----------------------------------------------------------------------------------------------------------------------|
| creation		| 批注尝试将从信贷操作创建时开始。											|
| issuing		| 批注尝试将从信贷操作发行时开始，即操作正式确认后。	|

### portability_data 对象字段详情 {#portability_data_object}
| 字段             	| 描述             									| 值  						|
|-----------------------|-----------------------------------------------------------|-------------------------------|
| token             	| 军人提供的密码								| 1234abcd  					|
| origin_econsig_id		| Zetra 合同标识代码					| 1234567						|
| origin_econsig_ids	| 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"
}
```

#### 批注

空军代扣信贷操作创建后，QI 将启动操作的批注流程。

批注尝试流程在操作创建时开始，并将重试至操作的最后放款选项日期。

空军代扣额度批注完成后，QI 将通过以下 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"
}
```
如果提供的 token 无效，我们将发送以下 webhook。如果提供的 token 已被使用且需要新 token，也会发送此 webhook。

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"
}
```

#### 导致自动取消的响应

根据 Zetra 的响应，操作将被自动取消。
发生此情况时，我们将以如下格式发送 webhook，取消原因在 "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"

}
```
#### 枚举值表
| 枚举值                    				| 描述                             | Zetra 代码  |
|-----------------------------------------------|---------------------------------------|------------------|
| airforce_payroll_military_not_found			| 未找到军人。 				| 293              |
| airforce_payroll_portability_not_found		| 未找到原始合同。	| 294              |
| airforce_payroll_consignable_margin_exceeded	| 可用额度已超出。			| 359              |

#### 可携性到期

10 天后，Zetra 将取消等待确认的可携性申请。

因此，要重新启动可携性流程，需要提供新的有效 token。如果存在新的有效 token，提案将返回到可携性意向步骤（预留状态：pending_reservation）。但如果不存在有效 token（通常是因为发送的 token 已在之前的可携性意向中使用），提案将更新为 pending_valid_token 状态，等待发送新 token。发送新的有效 token 后，提案将正常进行可携性意向和确认流程。

将发送以下 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. 发送新的可携性 Token

可携性 token 为一次性使用，因此当之前的 token 被使用或 token 无效时，需要发送新的 token。

发送方式为简单调用：

### Request

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

Request Body

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

### 成功案例

ENDPOINT /debt/[DEBT-KEY]/collateral
STATUS 204

Response Body - No content

### 错误案例
:::info
此请求只应发送 token，否则流程将返回错误
:::
#### 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. 取消与注销批注：
要永久取消操作并注销薪资代扣额度，应使用以下端点：

:::caution 注意
值得注意的是，注销批注过程是异步的，即取消信贷操作**并不**必然意味着注销批注已完成。要查询注销批注状态，请参阅[获取最后请求的响应](#recuperar-ultima-request)"。
:::

:::caution 注意
永久取消也可能自动发生，这种情况发生在操作处于 "canceled" 状态超过 7 天时。
:::
### Request

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

#### 操作取消成功：

操作取消完成后，合作方将收到以下 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"
}
```

#### 注销批注成功

注销批注完成后，合作方将收到以下 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-ultima-request}

***last_response*** 是一种简单直观地映射 QI 与 Zetra 通信响应的方式，可以了解该请求的发起时间及获取的返回结果（通过枚举值）。

每个枚举值都有详细描述。以下将更详细地介绍 last_response 的数据呈现方式。

### 成功案例

#### 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"
    }
  }
```

可携性或再融资响应体

```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"
        }       
    }
}
```

#### 枚举值表
| 枚举值                        | 描述                        | 详情                                                           | 预留状态    |
|-----------------------------------|----------------------------------|--------------------------------------------------------------------| ---------------------|
| successfully_accepted             | 预留请求已接受     | 批注申请已接受，等待确认     | pending_confirmation |
| successfully_reserved             | 预留成功    | 预留已成功批注                                 | reserved             |
| successfully_deleted              | 预留已成功删除 | 预留已成功注销批注                              | deleted              |

### 错误案例

#### 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"
    }
  }
```

#### 枚举值表
| 枚举值                  | 描述                                 | QI 操作 | 对应 Zetra 代码  |
|-----------------------------|-------------------------------------------|---------|---------------------------------|
| waiting_confirmation        | 等待可携性确认       | retry   |                                 |
| communication_error         | 与 Zetra 通信错误            | retry   | 241                             |
| consignable_margin_excceded | 超出代扣额度               | retry   | 359                             |

## 12. 欠款余额通知

欠款余额通知在申请日后第 5 个工作日发生，所有通知的合同将通过 webhook 发送以下信息：

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: /zh-Hans/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                                                   |

---

# 对接路线图 - BNPL

URL: /zh-Hans/documentation/manual_bnpl_ecommerce/

## 概述
本文档指导客户完成与 QI Tech 平台的先买后付（BNPL）集成。文档概述了必要步骤，并解答常见问题。

## 1. 文件查询
可通过以下请求进行文件查询：

### 请求体上传

ENDPOINT /document/[document_key]/url
METHOD GET

### 路径参数

| 字段           | 描述                     |
|--------------- |--------------------------|
| `document_key` | 文件唯一标识符           |

:::caution 注意
文件 URL 将在生成后 10 分钟内过期。
:::

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_key，您需要通过以下请求上传文件：

### 请求体上传

ENDPOINT /upload
METHOD POST

Response Body

```json
{
  "document_key": "cfbc8469-89ea-4a80-9f64-ba7b1566c68b",
  "document_md5": "cd451103fa512frc98ce684d3896698c"
}
```

:::caution 注意
请保存 **document_key**，查询文件时需要用到此密钥。
:::

### API 调用示例

以下为从 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()
```

- 备注：上述示例使用 [node-fetch](https://www.npmjs.com/package/node-fetch) 库进行调用，您也可以使用自己选择的库。重要的是，调用必须使用 POST 方法，`Content-Type` 请求头设置为 `multipart/form-data`，请求体必须是包含键名为 `file`、值为待发送文件二进制数据的 FormData 对象。

:::warning 警告
'Axios' 库存在一个导致 FormData 发送为空的 bug，相关问题可在 [GitHub 仓库](https://github.com/axios/axios/issues/5986) 中查看。如果在您集成时该问题尚未解决，建议使用 'node-fetch' 库进行此调用。
:::

  

## 3. 债务模拟

### 请求债务模拟

QI Tech 为客户提供在实际发行信贷操作之前模拟其金额的功能。模拟与债务发行请求遵循相同的模式，但无需提供借款人的注册信息和放款账户详情。以下端点是 /debt_simulation 的简化版本，经过高度优化，仅用于计算单一放款选项。

ENDPOINT /v2/credit_operation/simulation
METHOD POST

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
}
```

### 请求体字段详情

| 字段  | 类型   | 描述 | 最大字符数 |
|---|--- |---|---|
| **credit_operation_type***                 | string    | 信贷协议类型      |  **[信贷操作类型枚举值](#credit-operation-type-enumerator)**           |
| **disbursed_issue_amount***                | float   | 实际发放给借款人的金额      | 15,2           |
| **disbursement_date***                     | string    | 贷款资金可用的具体日期      | 10            |
| **first_due_date***                        | string    | 第一期分期付款的到期日      | 10             |
| **force_installments_on_workdays***        | boolean | 如为 true，确保所有分期付款到期日顺延至下一个工作日  |       5       |
| **interest_type***                         | string    | 摊销方法      | **[利息类型枚举值](#interest-type-enumerator)**           |
| **issuer_person_type***                    | string    | 定义发行人是自然人还是法人（企业/公司）     | **[人员类型枚举值](#person-type-enumerator)**           |
| **monthly_interest_rate***                 | float   | 每月对本金余额收取的百分比利率    | 10,6           |
| **number_of_installments***                | integer    | 分期付款期数      | 3            |
| **principal_amortization_month_period***   | integer    | 分期付款之间的月数      | 1            |

### 债务模拟响应

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
            }
        ]
    }
```

### 响应体字段详情
| 字段                                   | 类型   | 描述                                                                                                                     |
|-----------------------------------------|--------|-------------------------------------------------------------------------------------------------------------------------------|
| **annual_cet**                          | float  | 以小数表示的年总有效成本                                                                                | -            |
| **assignment_amount**                   | float  | 信贷操作的收购价值                                                                                     | -            |
| **cet**                                 | float  | 以小数表示的月总有效成本                                                                                | -            |
| **fees**                                | object | **[费用对象](#object-fees)** - QI Tech 对操作收取的费用列表                            | -            |
| **disbursed_amount**                    | float  | 信贷操作中的放款金额                                                                                     | -            |
| **disbursement_date**                   | string   | 操作放款日期                                                                                                | -            |
| **installments**                        | array   | **[分期付款对象](#object-installments)** - 操作的分期付款信息                                                        | -            |
| **interest_type**                       | string   | **[利息类型枚举值](#enumerator-interest-type)** - 摊销方法和利息计算方法                 | -            |
| **additional_iof**                      | float  | 对交易本金征收的固定利率税，与信贷操作期限无关                                                                               | -            |
| **base_iof**                            | float  | 作为金融操作税计算基础的应税金额或本金价值  | -            |
| **total_iof**                           | float  | 对交易征收的金融操作税总额   | -            |
| **issue_amount**                        | float  | 信贷操作的发行/名义价值                                                                               | -            |
| **tax_configuration**                   | object | **[税务配置对象](#object-tax-configuration)** - IOF 利率值                                             | -            |
| **first_due_date**                      | string   | 第一期分期付款到期日                                                                                        | -            |
| **prefixed_interest_rate**              | object | **[利率对象](#object-interest-rate)** - 名义利率                              | -            |

## 4. 自然人债务发行

此端点通过 opt-in 方式发行债务并处理合同签名。放款在发行后立即自动进行。无需预注册；只需在债务请求时提供借款人详情即可。

### 请求

ENDPOINT /signed_debt
METHOD POST

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"
    }
}
```

### 请求体字段详情

| 字段  | 类型   | 描述 | 最大字符数 |
|---|--- |---|---|
| **borrower** *                  | object | 借款人对象 - 信贷操作的债务人         | **[借款人对象](#borrower-object)** |
| **disbursement_bank_account** * | object | 操作资金将存入的银行账户技术详情。                                                                                 | **[放款银行账户对象](#disbursement-bank-account-object)**          |
| **financial** *                 | object | 包含操作的所有财务详情和计算参数。 | **[财务对象](#financial-object)**            |
| **purchaser_document_number** * | string | 受让人税务识别码 – 信贷操作的买方（FIDC/应收账款投资基金）。   | 14           |
| **additional_data** * | object | 受让人税务识别码 – 信贷操作的买方（FIDC/应收账款投资基金）。   | **[附加数据对象](#additional-data-object)**          |

### 借款人对象

| 字段 | 类型 | 描述 | 最大字符数 |
|---|--- |---|---|
| name * | string | 借款人全名 | 100 |
| email | string | 借款人电子邮箱地址 | 254 |
| phone | object | 借款人联系电话详情 | **[电话对象](#phone-object)** |
| is_pep * | boolean | 政治敏感人士（PEP）指示符 | 5 |
| address * | object | 借款人住宅地址详情 | **[地址对象](#address-object)** |
| role_type * | enum | 该人员在操作中的角色。默认值：issuer | - |
| birth_date * | date | 借款人出生日期（格式："YYYY-MM-DD"） | 10 |
| mother_name * | string | 借款人母亲全名 | 100 |
| nationality | string | 借款人国籍 | 50 |
| person_type * | string | 人员分类 | 7 |
| individual_document_number * | string | 借款人税务识别码（CPF）- 仅数字 | 11 |
| document_identification * | string | 已上传身份证件（RG 或 CNH）的 DOCUMENT_KEY | 36 |
| document_identification_back | string | 已上传身份证件背面的 DOCUMENT_KEY | 36 |

### 地址对象

| 字段 | 类型 | 描述 | 最大字符数 |
|---|--- |---|---|
| city * | string | 地址所在城市名称 | 100 |
| state * | string | 州缩写（两个大写字母） | 2 |
| number * | string | 门牌号 | 10 |
| street * | string | 街道名称 | 100 |
| complement * | string | 地址补充信息（自由文本） | 100 |
| postal_code * | string | 邮政编码（CEP）- 仅数字 | 8 |
| neighborhood * | string | 街区或地区名称 | 100 |

### 电话对象

| 字段 | 类型 | 描述 | 最大字符数 |
|---|--- |---|---|
| number * | string | 用户电话号码 | 9 |
| area_code * | string | 两位数区号（例如："11"） | 2 |
| country_code * | string | 国际拨号代码（例如："055"） | 3 |

### 放款银行账户对象
| 字段 | 类型 | 描述 | 最大字符数 |
|---|--- |---|---|
| name | string | 账户持有人全名 | 50 |
| document_number | string | 账户持有人税务识别码（CPF） | 11 |
| bank_code * | string | 金融机构 COMPE 代码 | 3 |
| branch_number * | string | 支行号码（请勿包含支行验证码！） | 4 |
| account_number * | string | 账号（请勿包含账户验证码！） | 10 |
| account_digit * | string | 账户验证码（用零代替字母） | 1 |
| account_type | enum | 账户类型枚举值 - 银行账户类型 | **[账户类型对象](#account-type-object)** |

### 附加数据对象

| 字段 | 类型 | 描述 | 最大字符数 |
|---|--- |---|---|
| contract_number * | string | 合同的唯一标识符或参考编号 | 12 |
| signed * | boolean | 表示合同是否已成功签署 | 5 |
| signatures * | array | 数字签名证据对象列表（Opt-in） | - |
| name * | string | 签署人全名 | 255 |
| document_number * | string | 签署人税务识别码（CPF） | 11 |
| email * | string | 签署人电子邮箱地址 | 100 |
| area_code * | string | 两位数区号（例如："11"） | 2 |
| number * | string | 用户电话号码 | 9 |
| country_code * | string | 国际拨号代码（例如："055"） | 3 |
| ip_address * | string | 签署过程中使用的 IP 地址 | 45 |
| timestamp * | string | 签署日期和时间（DD-MM-YYYY HH:mm:ss） | 19 |
| file_url * | string | 已签署合同文件（PDF）的直接链接 | 2048 |
| file_type * | string | 签名文件格式（例如："pdf"） | 4 |
| long * | string | 签署位置的地理经度坐标 | 20 |
| lat * | string | 签署位置的地理纬度坐标 | 20 |
| fingerprint_device | string | 使用设备的唯一数字标识符 | - |

### 响应

此债务请求的响应将返回还款计划以及一个 **DEBT-KEY**，即该债务在 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

成功响应后，您将收到一个包含已签署 CCB 的 webhook，以及一个表示放款成功或失败的 webhook。

### 签名 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"
}

```

### 放款 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"
}

```

如果债务放款失败或被退回，您将收到取消 webhook。

### 取消 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"
  }

```

****取消原因****

| cancel_reason_enumerator | 描述 |  
|---|---|  
|disbursing_error|操作因放款过程中出现错误而取消。  
|waiting_signature |操作因缺少签名而取消。 
|pix_max_retry|操作因收款银行无法处理放款而取消。  
|manual|操作被手动取消。  
|agencia_conta_invalida|机构号或收款账户号无效。  
|invalid_account|目标账号不存在或无效。  
|invalid_document_number|目标账户的 CPF/CNPJ 不正确。  
|unsupported_transaction|目标账户不支持此类交易。  
|invalid_ispb|ISPB 号码无效或不存在。  
|rejected_payment|付款指令被收款银行拒绝。  
| refund_after_payee_request | 收款方申请退款                                                |
| invalid_account            | 目标账号不存在或无效。                    |
| invalid_document_number    | 目标账户的 CPF/CNPJ 不正确。                        |
| rejected_payment           | 付款被收款银行拒绝。                                      |
| blocked_account            | 目标账户已被冻结。                                          |
| unsupported_transaction    | 目标账户不支持此类交易。           |
| amount_too_great           | 付款/退款金额超过收款目标账户的限额。 |
| invalid_ispb               | ISPB 号码无效或不存在。                                   |
| receiver_error             | 由于收款方 PSP 出现错误，交易中断。                  |
| closed_account             | 目标账户已注销。                                           |
| disbursing_hour_closed     | 放款发生在允许的时间窗口之外。                     |
| unregistered_pix_key       | PIX 密钥未被使用。                                               |
| manual                     | 操作被手动取消。                                                 |
| spi_timeout                | SPI 超时控制。                                                     |

## 6. 取消

### 放款前取消债务

### 请求体

ENDPOINT /debt/ DEBT-KEY /cancel
MÉTODO PATCH

### 路径参数

| 字段  | 类型   | 描述 | 最大字符数 |
|---|---| ---| ---|
| `debt_key` * | string | 创建信贷操作时返回的债务唯一标识键。 | 32 |  

### 响应体

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
  }
}

```

### 放款后七天内取消债务

### 请求体

ENDPOINT /debt/reversal
MÉTODO POST

Request Body

```json
{
    "contract_number": "0000049343/TW"
}

```

### 请求体字段详情
| 字段  | 类型   | 描述 | 最大字符数 |
|-------------------|--------|--------------------------------|--------------|
| `contract_number` * | string | CCB 的合同编号 |              |

### 响应体

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. 债务查询

您也可以在之后查询债务以获取信息或跟踪其状态：

ENDPOINT /v2/credit_operation/ CREDIT-OPERATION-KEY
METHOD GET

### 路径参数

| 字段  | 类型   | 描述 | 最大字符数 |
|---|---|---|---|   
| `credit_operation_key` * | string | 信贷操作密钥。 | UUID |

### 响应

STATUS 200

Response Body

```json
{
    "credit_operation_key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "issue_amount": 201.84,
    "origin_key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "total_iof": 1.84,
    "disbursement_start_date": "2025-10-27",
    "disbursement_end_date": "2025-10-27",
    "issue_date": "2025-10-27",
    "requester_identifier_key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "installments": [
        {
            "business_due_date": "2025-11-28",
            "due_date": "2025-11-27",
            "calendar_days": 31,
            "due_interest": 0,
            "due_principal": 201.84,
            "fine_amount": 0,
            "has_interest": true,
            "post_fixed_amount": 0,
            "pre_fixed_amount": 29.26,
            "principal_amortization_amount": 58.17,
            "tax_amount": 0.15,
            "total_amount": 87.43,
            "workdays": 22,
            "accrual_reference_date": null,
            "advanced_paid_amount": 0,
            "bank_slip_key": "524440c0-302b-4553-8211-5cf012f2e718",
            "digitable_line": "32990001031000700326159000000204112780000008743",
            "installment_key": "e25fb146-0a61-4319-a722-d01b2213d0f9",
            "installment_status": "opened",
            "installment_type": "principal",
            "original_due_principal": 201.84,
            "original_pre_fixed_amount": 29.26,
            "original_principal_amortization_amount": 58.17,
            "paid_amount": 0,
            "original_total_amount": 87.43,
            "qr_code_key": "eeb4f5a6-6cba-4901-8113-21c7261b54ac",
            "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/eeb4f5a66cba4901811321c7261b54ac5204000053039865802BR5925QISOCIEDADEDECREDITODIRET6008SaoPaulo61080145200062070503***6304D300",
            "renegotiation_proposal_key": null,
            "total_accrual_amount": 0,
            "total_paid_amount": 0,
            "installment_number": 1,
            "paid_at": null,
            "updated_at": "2025-10-27T17:10:21",
            "principal_amortization_payment_amount": 0,
            "prefixed_interest_payment_amount": 0
        },
        {
            "business_due_date": "2025-12-30",
            "due_date": "2025-12-27",
            "calendar_days": 30,
            "due_interest": 0,
            "due_principal": 143.67477451,
            "fine_amount": 0,
            "has_interest": true,
            "post_fixed_amount": 0,
            "pre_fixed_amount": 20.11,
            "principal_amortization_amount": 67.32,
            "tax_amount": 0.34,
            "total_amount": 87.43,
            "workdays": 20,
            "accrual_reference_date": null,
            "advanced_paid_amount": 0,
            "bank_slip_key": "ece5355a-4b51-48af-aa4b-f074b93c9fef",
            "digitable_line": "32990001031000700326160000000202613080000008743",
            "installment_key": "2557de2b-6df1-4a8a-b46a-59206ece157f",
            "installment_status": "opened",
            "installment_type": "principal",
            "original_due_principal": 143.67,
            "original_pre_fixed_amount": 20.11,
            "original_principal_amortization_amount": 67.32,
            "paid_amount": 0,
            "original_total_amount": 87.43,
            "qr_code_key": "98781ab0-318a-43c4-9ce6-fdc22514c540",
            "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/98781ab0318a43c49ce6fdc22514c5405204000053039865802BR5925QISOCIEDADEDECREDITODIRET6008SaoPaulo61080145200062070503***63040687",
            "renegotiation_proposal_key": null,
            "total_accrual_amount": 0,
            "total_paid_amount": 0,
            "installment_number": 2,
            "paid_at": null,
            "updated_at": "2025-10-27T17:10:21",
            "principal_amortization_payment_amount": 0,
            "prefixed_interest_payment_amount": 0
        },
        {
            "business_due_date": "2026-01-28",
            "due_date": "2026-01-27",
            "calendar_days": 31,
            "due_interest": 0,
            "due_principal": 76.35924318,
            "fine_amount": 0,
            "has_interest": true,
            "post_fixed_amount": 0,
            "pre_fixed_amount": 11.07,
            "principal_amortization_amount": 76.36,
            "tax_amount": 0.58,
            "total_amount": 87.43,
            "workdays": 21,
            "accrual_reference_date": null,
            "advanced_paid_amount": 0,
            "bank_slip_key": "09888b40-6844-4c8c-a474-f22a94e463a9",
            "digitable_line": "32990001031000700326161000000200313390000008743",
            "installment_key": "cc503d1d-6387-4a1f-bd78-62b248d02ec8",
            "installment_status": "opened",
            "installment_type": "principal",
            "original_due_principal": 76.36,
            "original_pre_fixed_amount": 11.07,
            "original_principal_amortization_amount": 76.36,
            "paid_amount": 0,
            "original_total_amount": 87.43,
            "qr_code_key": "289792ad-3e5a-4308-8e3d-7b75afe0fea5",
            "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/289792ad3e5a43088e3d7b75afe0fea55204000053039865802BR5925QISOCIEDADEDECREDITODIRET6008SaoPaulo61080145200062070503***630443CC",
            "renegotiation_proposal_key": null,
            "total_accrual_amount": 0,
            "total_paid_amount": 0,
            "installment_number": 3,
            "paid_at": null,
            "updated_at": "2025-10-27T17:10:21",
            "principal_amortization_payment_amount": 0,
            "prefixed_interest_payment_amount": 0
        }
    ],
    "first_due_date": "2025-11-27",
    "requester_key": "6ca83592-ce8c-42f5-ac0d-5ce182dbe794",
    "original_total_iof": null,
    "contract_number": "TIK11267101212",
    "credit_operation_status_enumerator": "opened",
    "operation_type_enumerator": "structured_operation",
    "disbursement_date": "2025-10-27",
    "issuer_name": "Alan Mathison Turing",
    "issuer_document_number": "96969879003",
    "external_contract_fees": [],
    "cet": 14.75,
    "annual_cet": 421.33,
    "final_disbursement_amount": 200,
    "number_of_installments": 3,
    "disbursement_issue_amount": 200,
    "prefixed_interest_rate": {
        "annual_rate": 3.81790482,
        "daily_rate": 0.0043771607,
        "interest_base": {
            "enumerator": "calendar_days",
            "year_days": 360
        },
        "monthly_rate": 0.14
    },
    "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": "c8b191cb-7b90-4e37-9280-397a597babc1",
            "document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/c8b191cb-7b90-4e37-9280-397a597babc1/RAFAELAEBENJAMINFINANCEIRALTDA-ALAN_MATHISON_TURING-CCB-TIK11267101212-20251027170925.pdf",
            "signature_url": "https://storage.googleapis.com/sandbox-doc-api/documents/c8b191cb-7b90-4e37-9280-397a597babc1/RAFAELAEBENJAMINFINANCEIRALTDA-ALAN_MATHISON_TURING-CCB-TIK11267101212-20251027170925_signed.pdf",
            "document_type": "ccb_pre_price_days",
            "signature_required": true,
            "signed": true
        }
    ]
}
```

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. 转让查询

### 转让确认 Webhook
此 webhook 用于通知客户转让流程已启动。它提供了跟踪转让所需的基本元数据。

Response Body

```json
{
  "assignment_key": "77997168-5d61-430f-b5ae-08eb3d7b8c0e",
  "term_of_assignment_url": "https://example.com/assignment.pdf",
  "number_of_items": 5,
  "total_amount": 120000.00,
  "reference_date": "2026-02-06"
}

```

| 字段 | 类型 | 描述 | 最大长度 |
|---|---|---|---|
| assignment_key | string | 转让操作的唯一标识符 | 36 |
| term_of_assignment_url | string | 下载转让条款（PDF）的 URL | 2048 |
| number_of_items | integer | 本次转让包含的信贷操作（条目）总数 | 5 |
| total_amount | float | 转让中所有条目现值之和 | 15,2 |
| reference_date | string | 用于转让计算的基准日期（YYYY-MM-DD） | 10 |

要查询特定转让，客户可以使用转让标识键（assignment_key）对端点执行 GET 请求。

### 请求体

ENDPOINT /v2/assignment/[assignment_key] METHOD GET

### 参数

| 字段             | 描述                      |
| ---------------- | ------------------------------ |
| `assignment_key` | 转让唯一标识键 |

### 响应

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"
}
```

要查询转让中的合同，请使用相同的 **assignment_key** 对端点执行 GET 请求。

### 请求体

ENDPOINT /v2/assignment/[assignment_key]/assignment_items METHOD GET

### 参数

| 字段             | 描述                      |
| ---------------- | ------------------------------ |
| `assignment_key` | 转让唯一标识键 |

响应为包含转让中每个合同信息的分页列表（状态 200）：

### 响应体

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
    }
}
```

## 9. 技术规范与枚举值

### 费用对象
| 字段           | 类型  | 描述                                                                                                   |
|-----------------|-------|-----------------------------------------------------------------------------------------------------|
| **amount**      | float | 费用金额（百分比或绝对值，取决于 amount_type 字段提供的值）| -            |
| **amount_type** | enum  | 费用值单位                   |  **[金额类型枚举值](#amount-type-enumerator)**             |
| **fee_amount**  | float | 操作中收取费用的绝对值                                                           | -            |
| **fee_type**    | string  | 操作中收取的费用类型                   | **[费用类型枚举值](#fee-type-enumerator)**          |
| **type**        | string  | 操作中收取费用的来源                         | **[来源类型枚举值](#origin-type-enumerator)**          |

### 分期付款对象
| 字段                             | 类型    | 描述                                                                      | 
|-----------------------------------|---------|--------------------------------------------------------------------------------|
| **calendar_days**                 | integer    | 分期付款之间的自然日天数                                | -            |
| **due_date**                      | string    | 以自然日计的分期付款到期日                                   | -            |
| **due_principal**                 | float   | 分期付款到期日前未偿还的本金余额 | -            |
| **has_interest**                  | boolean | _true_ - 如为 true，该分期付款适用利息                           | -            |
| **installment_number**            | integer    | 分期付款编号                                                              | -            |
| **prefixed_amount**               | float   | 该分期付款支付的固定利息金额                                      | -            |
| **principal_amortization_amount** | float   | 该分期付款支付的本金金额                                           | -            |
| **tax_amount**                    | float   | 分期付款的基础 IOF 金额                                                            | -            |
| **amount**                        | float   | 分期付款总金额                                                         | -            |
| **due_interest**                  | float     | 分期付款到期日前未偿还的利息                                   | -            |
| **period**                        | float     | 分期付款期间 | -            |
| **period_workdays**               | float     | 以工作日计的分期付款期间 | -            |
| **period_to_disbursement**        | float     | 距放款的期间 | -            |
| **period_workdays_to_disbursement**| float     | 距放款的工作日数 | -            |
| **calendar_days_to_disbursement** | integer    | 距放款的自然日天数 | -            |
| **workdays**                      | integer    | 分期付款之间的工作日数 | -            |
| **workdays_to_disbursement**      | integer    | 距放款的工作日数 | -            |

### 利率对象
| 字段             | 描述                                                                             | 
|-------------------|---------------------------------------------------------------------------------------|
| **annual_rate**   | 以小数表示的年固定/浮动利率                                      | -            |
| **daily_rate**    | 以小数表示的日固定/浮动利率                                      | -            |
| **interest_base** | **[利息基准枚举值](#interest-base-enumerator)** - 利息计算基准  | -            |
| **monthly_rate**  | 以小数表示的月固定/浮动利率                                      | -            |

### 税务配置对象
| 字段                 | 描述                                                                             | 
|-----------------------|---------------------------------------------------------------------------------------|
| **base_rate**         | 基础 IOF 利率值                                                                | -            |
| **additional_rate**   | 附加 IOF 利率值                                                           | -            |

### 枚举值

### 人员类型枚举值
| 枚举值             | 描述             |
|------------------------|-----------------------|
| **legal**              | 法人       |
| **natural**            | 自然人          |

### 账户类型枚举值
| 枚举值             | 描述             |
|------------------------|-----------------------|
| **checking_account**   | 活期账户        |

### 金额类型枚举值
| 枚举值             | 描述             |
|------------------------|-----------------------|
| **absolute**           | 绝对值        |
| **percentage**         | 百分比值      |

### 利息类型枚举值
| 枚举值           | 描述                                                                                                                                                                |
|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **pre_price_days**   | 价格摊销法（等额分期），以日为单位计算固定利率利息                                                                                     |
| **pre_price**        | 价格摊销法（等额分期），以 30 天为周期计算固定利率利息                                                                |

### 信贷操作类型枚举值
| 枚举值    | 描述                      |
|---------------|--------------------------------|
| **ccb**       | 银行信用票据    |

### 利息基准枚举值
| 枚举值            | 描述                                                                 |
|-----------------------|---------------------------------------------------------------------------|
| **workdays**          | 以工作日为基准计算利息，假定一年 252 天    |
| **calendar_days**     | 以自然日为基准计算利息，假定一年 360 天 |
| **calendar_days_365** | 以自然日为基准计算利息，假定一年 365 天 |

### 费用类型枚举值
每种费用类型必须事先由 QI Tech 启用和配置

| 枚举值            | 描述                                                                  |
|-----------------------|----------------------------------------------------------------------------|
| **spread**            | 包含在信贷操作收购价值中的溢价                  |
| **spread_ted_fee**    | TED 转账费的溢价 |

### 来源类型枚举值
每种费用类型必须事先由 QI Tech 启用和配置

| 枚举值            | 描述                                                                  |
|-----------------------|----------------------------------------------------------------------------|
| **internal**          | 内部费用                                                   |
| **external**          | 外部费用                                                   |

---

# Consulta - Emissão BNPL

URL: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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.
:::

---

# 薪资卡手册 - 跟踪查询

URL: /zh-Hans/documentation/manual_cartao_beneficio/manual_cartao_beneficio_acompanhamento

:::info 导航
- [发行](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_emissao)（上一页）
- [Webhooks](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_webhook)（下一页）
:::

:::caution API 开发中
该 API 仍处于开发阶段，因此本手册可能会有所变更。
:::

---

## 1. 查询薪资卡预留

通过预留密钥（`payroll_card_reservation_key`）或请求控制密钥（`request_control_key`）查询特定预留的详细信息。返回包含预留详情的**单个对象**。

**GET**
/payroll_card_reservation/social_security/[PAYROLL-CARD-RESERVATION-KEY]
**GET**
/payroll_card_reservation/social_security/request_control_key/[REQUEST-CONTROL-KEY]

#### Query Params

**Query Params**

| 字段 | 类型 | 描述 |
|-------------|---------|---------------------------------------------------------------------------|
| retrieve_document_urls | bool  | 是否返回某些文档的 URL。默认设置为 False。 |

:::warning 参数 retrieve_document_urls

启用该参数可能会导致请求延迟。仅在必要时使用。

目前，只有 `benefit.policy_document_url` 字段受此参数影响，但其他 URL 字段（如 `attached_documents.document_url` 和 `attached_documents.signature_url`）将来也会依赖此参数。

受影响的字段（当前和未来）均以 (*) 标记。

:::

### 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**

| 字段 | 类型 | 描述 |
|---|---|---| 
| request_control_key | string | 请求识别密钥 | 
| payroll_card_reservation_key | string | 薪资卡预留密钥 | 
| payroll_card_reservation_status | string | 薪资卡预留状态 | 
| card_holder_document_number | string | 持卡人 CPF | 
| identifier_number | string | 操作识别号 | 
| reservation_amount | number | 薪资卡预留金额 |
| reservation_contract_number | string | Dataprev 批注合同号 | 
| withdrawal | object | 提款数据 | 
| payroll_card | object | 薪资卡数据 | 
| attached_documents | array | 附件文档列表 | 
| payroll_card_type | string | 卡类型（`social_security_benefit_card` 或 `social_security_payroll_card`） | 
| wallet_key | string | 创建的钱包唯一密钥（UUID4） | 
| signature_url | string | 预留合同签署 URL（仅在生成签署链接后存在于 payload 中） | 
| signature_data | object | 签署时收集的生物特征数据（仅在文件签署后存在于 payload 中） | 
| benefit | object | 与卡关联的保险/福利数据（仅在卡发行后存在于 payload 中） | 

#### Payload withdrawal

| 字段 | 类型 | 描述 | 
|---|---|---| 
| withdrawal_key | string | 提款唯一密钥 | 
| contract_number | string | 提款 CCB 合同号 | 
| withdrawal_amount | number | 提款 CCB 计算的放款金额 | 
| disbursement_date | date | 操作放款日期 | 
| withdrawal_status | string | 提款状态 | 
| withdrawal_data | object | 提款详细数据 |

#### Payload withdrawal_data

| 字段 | 类型 | 描述 |
|---|---|---| 
| prefixed_interest_rate | object | 固定利率 | 
| disbursement_options | array | 可用放款选项 | 

#### Payload prefixed_interest_rate

| 字段 | 类型 | 描述 | 
|---|---|---| 
| daily_rate | number | 日利率 | 
| interest_base | string | 利息计算基础 | 
| monthly_rate | number | 月利率 | 
| annual_rate | number | 年利率 | 

#### Payload disbursement_options

| 字段 | 类型 | 描述 | 
|---|---|---| 
| disbursement_date | string | 放款日期 | 
| cet | number | 月总有效成本 | 
| annual_cet | number | 年总有效成本 | 
| total_iof | number | IOF 总金额 |  
| disbursed_issue_amount | number | 放款金额 |  
| issue_amount | number | 发行金额 |  
| installments | array | 分期付款列表 | 

#### Payload installments

| 字段 | 类型 | 描述 | 
|---|---|---| 
| total_amount | number | 分期付款总额 | 
| due_date | string | 到期日期 | 
| installment_number | number | 分期序号 | 

#### Payload payroll_card

| 字段 | 类型 | 描述 | 
|---|---|---| 
| payroll_card_key | string | 薪资卡唯一密钥 | 
| payroll_card_status | string | 薪资卡状态 | 
| card_limit | number | 卡的计算总额度 | 
| card_issuance_entry_amount | number | 卡发行费金额 | 

#### Payload attached_documents

| 字段 | 类型 | 描述 | 
|---|---|---| 
| document_key | string | 文档唯一密钥 | 
| document_batch_key | string | 文档批次密钥 | 
| document_type | string | 文档类型 | 
| document_certifier | string | 文档认证机构 | 
| document_status | string | 文档状态 | 
| document_url (*) | string | 文档 URL | 
| signature_url (*) | string | 签署 URL | 

---

#### Payload signature_data

| 字段 | 类型 | 描述 | 
|---|---|---| 
| document_similarity_score | number | 签署人与提交文件之间的生物特征相似度评分（0-1） |
| similarity_score | number | 签署人与人脸库中找到的参考之间的生物特征相似度评分（0-1） |
| biometry_analysis_reference | string | 用于计算生物特征相似度评分的人脸来源库 |

---

#### Payload benefit

| 字段 | 类型 | 描述 | 
|---|---|---| 
| benefit_key | string | 福利唯一密钥（UUID） | 
| status | string | 保险发行状态（`created`、`pending_emission`、`active`、`canceled` 或 `inactive`）  |
| policy_document_key | string | 保单文件唯一密钥（UUID） |
| policy_document_url (*) | string | 保险保单文件 URL |

---

## 2. 按 CPF 查询薪资卡预留

查询特定 CPF 的有效预留。返回 `payroll_card_reservations` 属性中的**对象列表**。

**GET**
/payroll_card_reservation/social_security/card_holder_document_number/[CARD-HOLDER-DOCUMENT-NUMBER]

### 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. 状态机

### Payroll Card Reservation

**Payroll Card Reservation** 实体具有以下状态和转换：

```mermaid
stateDiagram-v2
    [*] --> pending_document_generation
    pending_document_generation --> pending_signature : Documentos gerados
    pending_signature --> pending_onboarding : Documentos assinados
    pending_onboarding --> pending_collateral_reservation : Onboarding aprovado
    pending_onboarding --> canceled : Falha no onboarding/KYC
    pending_collateral_reservation --> pending_additional_documents_submission : Colateral reservado
    pending_additional_documents_submission --> pending_additional_documents_validation : Documentos adicionais recebidos
    pending_additional_documents_validation --> pending_withdrawal_disbursement : Documentos adicionais aprovados
    pending_additional_documents_validation -->  pending_additional_documents_submission: Documentos adicionais rejeitados
    pending_withdrawal_disbursement --> pending_card_issuance : Desembolso realizado
    pending_card_issuance --> card_issued : Cartão criado
    canceled 
    card_issued --> [*]
```

#### 状态说明

| 状态 | 描述 |
|--------|-----------|
| `pending_document_generation` | 等待生成待签署文件 |
| `pending_onboarding` | 等待入驻和 KYC 流程 |
| `pending_collateral_reservation` | 等待担保品预留 |
| `pending_additional_documents_submission` | 边距已批注。等待提交确认视频 |
| `pending_additional_documents_validation` | 等待验证确认视频 |
| `pending_withdrawal_disbursement` | 等待提款操作放款 |
| `pending_card_issuance` | 等待创建钱包和发行卡 |
| `card_issued` | 卡已创建并激活 |
| `canceled` | 操作已取消 |

### Withdrawal

**Withdrawal** 实体具有以下状态和转换：

```mermaid
stateDiagram-v2
    [*] --> pending_signature
    pending_signature --> pending_disbursement : Documentos assinados
    pending_disbursement --> opened : Desembolso realizado
    opened --> [*]
```

#### 状态说明

| 状态 | 描述 |
|--------|-----------|
| `pending_signature` | 等待条款签署 |
| `pending_disbursement` | 等待提款操作放款 |
| `opened` | 已放款，操作激活 |
| `canceled` | 操作已取消 |

### Benefit

**Benefit** 实体具有以下状态和转换：

```mermaid
stateDiagram-v2
    [*] --> created
    created --> pending_emission : Aguardando emissão do seguro
    pending_emission --> active : Seguro emitido
    active --> canceled : Seguro cancelado
    active --> inactive : Seguro expirado
```

#### 状态说明

| 状态 | 描述 |
|--------|-----------|
| `created` | 保险处理中 |
| `pending_emission` | 等待保险发行 |
| `active` | 保险已发行并激活 |
| `canceled` | 保险已取消 |
| `inactive` | 保险已过期或失效 |

---

## 4. 取消预留

允许取消薪资卡预留。

:::warning 限制条件
通过 API 取消仅允许在提款放款**之前**（状态：`pending_withdrawal_disbursement` 或更早状态）。
如果提款已完成或卡已发行，取消必须通过支持处理，因为涉及财务退款。
:::

**PATCH**
/payroll_card_reservation/social_security/[PAYROLL-CARD-RESERVATION-KEY]/cancel

### Response

STATUS
**200** (OK)

请求已成功处理。无返回内容（Body 为空）。

```json
// Empty response body
```

---

# 文件与签名

URL: /zh-Hans/documentation/manual_cartao_beneficio/manual_cartao_beneficio_documentos

:::info 导航
- [Webhooks](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_webhook)（上一步）
- [地址管理](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_endereco)（下一步）
:::

本节详细介绍文件生成流程和电子签名流程，包括外部流程和 Qi Sign 流程。

:::info 备注
如果客户已接入 QISign 签名流程，本节中的条目均为可选项。
:::

## 1. 文件 Webhook

创建操作后，文件（`payroll_card_term`、`withdrawal_operation_term` 和 `payroll_card_consent_term`）将异步生成。API 会为每份文件发送一个 Webhook，通知文件状态变更。

:::caution 注意
如果客户不使用 QISign，客户必须实现对此 Webhook 的处理，以捕获文件 URL 并通过所选的外部认证机构引导受益人完成签名。
:::

:::info 通过 Webhook 跟踪
要查看完整的 payload 结构、事件场景以及如何捕获 URL，请参阅 Webhook 手册中的**[文件 Webhook（生成与验证）](./manual_cartao_beneficio_webhook.md#2-webhook-de-documentos-geração-e-validação)**章节。
:::

## 2. 外部文件签名

此接口用于当客户端（客户侧）或外部合作伙伴收集签名和生物特征数据时。客户必须发送已签名的文件和生物特征数据进行验证。

:::caution 注意
只有当签名流程**不是** Qi Sign 时，才应调用此步骤。如果使用 Qi Sign，确认将自动完成。
:::

:::tip 发送前
使用文件上传接口上传 5 份必要文件（自拍照、身份证正反面、卡片合同和取款合同），以获取 `document_key`。
:::

### 请求

**POST**
/payroll_card_reservation/social_security/{payroll_card_reservation_key}/signature

**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"
}
```

**请求体详情**

| 字段 | 类型 | 描述 | 必填 |
|---|---|---|---|
| documents | array | 所需的 5 份文件列表 | 是 |
| biometry_analysis_reference | string | 生物特征分析参考 | 是 |
| signature_datetime | string | 签名日期和时间（ISO 8601） | 是 |
| ip_address | string | 签名时的 IP 地址 | 是 |
| similarity_score | float | 生物特征相似度分数 | 是 |

#### 生物特征分析参考枚举值（_Biometry Analysis Reference_）

| 枚举值    | 描述                                                                                                                                                                                                                                                           |
|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| serpro    | 当 similarity_score 通过 Detran（由 Serpro 提供的服务）的带照片文件数据库查询返回时使用                                                                                                                                                                     |
| tse       | 当 similarity_score 通过 TSE 的带照片文件数据库查询返回时使用                                                                                                                                                                                                |
| not_found | 当面部生物特征未在任何政府数据库（serpro 或 tse）中找到时使用。此时 similarity_score 应为 null 或由合作伙伴返回的自拍照与官方带照片文件的相似度。 |

#### documents 中的条目

| 字段 | 类型 | 描述 | 格式 | 必填 |
|---|---|---|---|---|
| document_type | string | 文件类型 | 枚举值："selfie"、"document_identification"、"document_identification_back"、"payroll_card_term"、"payroll_card_consent_term"、"withdrawal_operation_term" | 是 |
| document_key | string | 文件唯一密钥 | UUID v4 | 是 |

**文件类型说明：**
- `selfie`：受益人照片
- `document_identification`：身份证件正面
- `document_identification_back`：身份证件背面
- `payroll_card_term`：已**签名**的卡片条款与条件
- `payroll_card_consent_term`：已**签名**的卡片申请同意书
- `withdrawal_operation_term`：已**签名**的取款操作条款

:::danger QI Sign
QI Tech 提供符合 IN 138 规定的签名服务，包括面部生物特征识别和文件提交。

如需报价，请联系我们的商业团队：

comercial@qitech.com.br 或 (11) 2339-4763
:::

### 响应

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"
    }
  ]
}
```

**响应体详情**

| 字段 | 类型 | 描述 |
|---|---|---|
| payroll_card_reservation_key | string | 薪资卡预约密钥 |
| payroll_card_reservation_status | string | 预约状态（pending_onboarding） |
| attached_documents | array | 文件及其状态列表 |

:::info 信息
确认两份文件的签名后，薪资卡的状态将变更为"pending_onboarding"，表示操作正在等待卡片入网流程。
:::

#### 常见错误

**404 - Document Not Found**

```json
{
  "title": "Document Not Found",
  "description": "Document selfie not found",
  "translation": "Documento selfie não encontrado"
}
```

**说明：** 当请求中提供的 `document_key` 在系统中未找到时，会发生此错误。请检查是否通过文件上传接口正确获取了 `document_key`。

---

## 3. 签名确认

无论使用何种签名方式（外部或 Qi Sign），成功完成流程后，您将收到一个预约状态变更 Webhook。

请参阅[主流程手册](./manual_cartao_beneficio_emissao.md)中的**状态变更 Webhook** 章节，查看状态为 `pending_onboarding` 的 payload 示例。

---

# 薪资卡手册 - 创建

URL: /zh-Hans/documentation/manual_cartao_beneficio/manual_cartao_beneficio_emissao

:::info 导航
- [跟踪](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_acompanhamento)（下一步）
:::

:::caution API 开发中
该 API 仍处于开发阶段，因此本手册可能会有所变动。
:::

---

:::info **福利查询**
如需查询福利数据及福利列表，请访问 INSS 文档中的以下章节：

- [查询福利列表](/documentation/manual_inss/manual_credito_novo/#1---consulta-da-lista-de-benefícios-com-formalização-do-termo-de-autorização-realizada-através-do-parceiro)
- [查询福利数据](/documentation/manual_inss/manual_credito_novo/#2---consulta-de-dados-do-benefício)
:::

## 1. 查询受益人资格

资格查询可验证某个 CPF 是否符合 INSS 薪资/福利卡申领条件。该操作为同步操作，立即返回核验结果。

持有 **CPF** 和**出生日期**数据后，即可查询受益人资格。目前唯一进行的资格验证是受益人年龄是否在 18 至 65 岁之间。

### Request

**GET**
/payroll_card_reservation/social_security/eligibility

**Params**

| 字段              | 类型   | 描述                      | 必填 | 格式          |
|-------------------|--------|---------------------------|------|---------------|
| document_number | string | 受益人 CPF 号码            | 是   | 11 位数字     |
| birth_date     | date   | 出生日期                  | 是   | YYYY-MM-DD    |

### Response

STATUS
**200** (OK)

**Response 示例**

**符合资格：**
```json
{
    "status": "eligible"
}
```

**不符合资格 - 年龄超出范围：**
```json
{
    "status": "not_eligible",
    "error_description": "Age 66 is not within the eligible range (18-65 years)"
}
```

**Response Body 详情**

| 字段              | 类型   | 描述                                           |
|-------------------|--------|------------------------------------------------|
| status            | string | 资格状态（eligible/not_eligible）              |
| error_description | string | 不符合资格时的错误描述（可选）                 |

---

## 2. 取款模拟与卡片额度

模拟计算可根据所提供的财务参数，计算可用取款金额和薪资卡额度。该操作适用于在签约前向受益人展示条件。

### Request
**POST**
/payroll_card_reservation/social_security/simulation

**Request Body**

```json
{
  "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
  },
  "collateral": {
    "collateral_type": "social_security_benefit_card"
  }
}
```

**Request Body 详情**

| 字段       | 类型   | 描述               | 格式 | 必填 |
|---|---|---|---|---|
| financial  | object | 操作财务数据        | -    | 是   |
| withdrawal | object | 取款数据            | -    | 是   |
| collateral | object | 担保物数据          | -    | 是   |

#### Payload financial

| 字段                   | 类型   | 描述                       | 格式                          | 必填 |
|---|---|---|---|---|
| salary_amount          | number | 受益人薪资金额              | 最小值: 1                     | 是   |
| number_of_installments | number | 取款 CCB 分期数             | 最小值: 1，最大值: 96         | 是   |
| monthly_interest_rate  | number | 取款 CCB 月利率             | 最小值: 0.01，最大值: 0.0246  | 是   |

#### Payload withdrawal

| 字段                    | 类型   | 描述                              | 格式                         | 必填                    |
|---|---|---|---|---|
| disbursement_date       | date   | 取款 CCB 放款日期                 | YYYY-MM-DD                   | 是                      |
| limit_days_to_disburse  | number | 取款 CCB 放款最长天数             | 最小值: 1，最大值: 10        | 是                      |
| withdrawal_ratio        | number | 用于取款的额度比例                | 最小值: 0.5，最大值: 0.7     | 否（默认: 0.7）         |

#### Payload collateral

| 字段            | 类型   | 描述       | 格式                                                                       | 必填 |
|---|---|---|---|---|
| collateral_type | string | 卡片类型   | Enum: "social_security_benefit_card", "social_security_payroll_card"       | 是   |

### 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 详情**

| 字段                          | 类型   | 描述                                       |
|---|---|---|
| total_limit_amount            | number | 考虑取款和卡片后的可用总额度               |
| reservation_amount            | number | 薪资卡预约金额                             |
| withdrawal                    | object | 取款数据                                   |
| withdrawal.withdrawal_amount  | number | 计算得出的取款 CCB 放款金额               |
| withdrawal.withdrawal_data    | object | 取款详细数据                               |
| payroll_card                  | object | 薪资卡数据                                 |
| payroll_card.card_limit       | number | 卡片计算得出的总额度                       |

#### Payload withdrawal.withdrawal_data

| 字段                   | 类型   | 描述             |
|---|---|---|
| prefixed_interest_rate | object | 固定利率         |
| disbursement_options   | array  | 可用放款选项     |

#### Payload prefixed_interest_rate

| 字段          | 类型   | 描述         |
|---|---|---|
| daily_rate    | number | 日利率       |
| interest_base | string | 利息计算基准 |
| monthly_rate  | number | 月利率       |
| annual_rate   | number | 年利率       |

#### Payload disbursement_options

| 字段                   | 类型   | 描述               |
|---|---|---|
| disbursement_date      | string | 放款日期           |
| cet                    | number | 月综合实际利率     |
| annual_cet             | number | 年综合实际利率     |
| total_iof              | number | IOF 总金额         |
| disbursed_issue_amount | number | 放款金额           |
| issue_amount           | number | 发行金额           |
| installments           | array  | 分期列表           |

#### Payload installments

| 字段               | 类型   | 描述         |
|---|---|---|
| total_amount       | number | 分期总金额   |
| due_date           | string | 到期日期     |
| installment_number | number | 分期编号     |

---

## 3. 创建取款操作并生成条款

创建取款操作将启动薪资卡签约流程。该操作创建卡片预约、生成所需文件，并返回用于跟踪流程的密钥。

**POST**
/payroll_card_reservation/social_security

### Request

**Request Body**

```json
{
  "request_control_key": "150e8400-e29b-41d4-a716-446655440000",
  "purchaser_document_number": "55566677000177",
  "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
  },
  "collateral": {
    "state": "MG",
    "benefit_number": "5556667777",
    "collateral_type": "social_security_benefit_card",
    "subcorban_document_number": "12123456000101",
    "assistance_type": "pension_by_death_rural_worker"
  },
  "credit_agent": {
    "document_number": "44455566677",
    "name": "Agente de Crédito Lima"
  }
}
```

**Request Body 详情**

| 字段                       | 类型   | 描述                     | 格式                   | 必填 |
|---|---|---|---|---|
| request_control_key        | string | 请求标识密钥              | UUID v4                | 是   |
| purchaser_document_number  | string | 买方 CNPJ               | 14 位数字               | 是   |
| card_holder                | object | 持卡人数据               | -                      | 是   |
| withdrawal                 | object | 取款数据                 | -                      | 是   |
| financial                  | object | 操作财务数据             | -                      | 是   |
| collateral                 | object | 担保物数据               | -                      | 是   |
| credit_agent               | object | 信贷代理人数据           | -                      | 是   |
| related_parties            | array  | 相关方列表               | -                      | 否   |

#### Payload card_holder

| 字段                    | 类型   | 描述                           | 格式                              | 必填 |
|---|---|---|---|---|
| name                    | string | 持卡人全名                     | 最少 1 个有效字符                 | 是   |
| email                   | string | 持卡人电子邮件                 | 有效电子邮件格式                  | 是   |
| phone                   | object | 电话数据                       | -                                 | 是   |
| gender                  | string | 性别                           | Enum: "male", "female"            | 是   |
| address                 | object | 持卡人地址及卡片寄送地址       | -                                 | 是   |
| birth_date              | date   | 出生日期                       | YYYY-MM-DD                        | 是   |
| mother_name             | string | 母亲姓名                       | 最少 1 个有效字符                 | 是   |
| nationality             | string | 国籍                           | 最少 1 个字符                     | 是   |
| document_number         | string | 持卡人 CPF                     | 11 位数字                         | 是   |
| document_identification | object | 身份证件数据                   | -                                 | 是   |

#### Payload related_parties

| 字段                       | 类型    | 描述               | 格式                                                                  | 必填 |
|---|---|---|---|---|
| name                       | string  | 相关方姓名         | 最少 1 个有效字符                                                     | 是   |
| email                      | string  | 相关方电子邮件     | 有效电子邮件格式                                                      | 是   |
| phone                      | object  | 电话数据           | -                                                                     | 是   |
| address                    | object  | 相关方地址         | -                                                                     | 是   |
| role_type                  | string  | 角色类型           | Enum: "issuer_legal_representative", "issuer_attorney"                | 是   |
| person_type                | string  | 人员类型           | Enum: "natural"                                                       | 是   |
| is_pep                     | boolean | 是否为政治敏感人士 | true/false                                                            | 是   |
| individual_document_number | string  | 相关方 CPF         | 11 位数字                                                             | 是   |
| birth_date                 | date    | 出生日期           | YYYY-MM-DD                                                            | 是   |
| mother_name                | string  | 母亲姓名           | 最少 1 个有效字符                                                     | 是   |
| document_identification    | object  | 身份证件数据       | -                                                                     | 是   |

#### Payload phone

| 字段         | 类型   | 描述         | 格式       | 必填 |
|---|---|---|---|---|
| number       | string | 电话号码     | 仅数字     | 是   |
| area_code    | string | 区号         | 仅数字     | 是   |
| country_code | string | 国家代码     | 仅数字     | 是   |

#### Payload address

| 字段         | 类型   | 描述   | 格式           | 必填 |
|---|---|---|---|---|
| city         | string | 城市   | 最少 1 个字符  | 是   |
| state        | string | 州     | 2 个字符       | 是   |
| number       | string | 门牌号 | 最少 1 个字符  | 是   |
| street       | string | 街道   | 最少 1 个字符  | 是   |
| complement   | string | 补充   | 最少 1 个字符  | 否   |
| postal_code  | string | 邮政编码 | 8 位数字     | 是   |
| neighborhood | string | 社区   | 最少 1 个字符  | 是   |

#### Payload document_identification

| 字段                           | 类型   | 描述         | 格式                                      | 必填 |
|---|---|---|---|---|
| document_identification_date   | date   | 证件签发日期 | YYYY-MM-DD                                | 是   |
| document_identification_type   | string | 证件类型     | Enum: "rg", "passport", "other"           | 是   |
| document_identification_number | string | 证件号码     | 最少 1 个字符                             | 是   |

#### Payload withdrawal

| 字段                   | 类型   | 描述                     | 格式                       | 必填 |
|---|---|---|---|---|
| disbursement_date      | date   | 放款日期                 | YYYY-MM-DD                 | 是   |
| limit_days_to_disburse | number | 放款最长天数             | 最小值: 1，最大值: 10      | 是   |
| contract_number        | string | 合同编号                 | 3 个大写字母 + 8 位数字    | 是   |
| disbursement_bank_account | object | 放款银行账户          | -                          | 是   |

#### Payload disbursement_bank_account

| 字段            | 类型   | 描述           | 格式                                                                                                                                            | 必填 |
|---|---|---|---|---|
| name            | string | 账户持有人姓名 | 最少 1 个有效字符                                                                                                                               | 是   |
| bank_code       | string | 银行代码       | 3 位数字                                                                                                                                        | 是   |
| account_digit   | string | 账户校验位     | 1 位数字                                                                                                                                        | 是   |
| branch_number   | string | 支行号         | 仅数字                                                                                                                                          | 是   |
| account_number  | string | 账户号码       | 仅数字                                                                                                                                          | 是   |
| document_number | string | 持有人 CPF     | 11 位数字                                                                                                                                       | 是   |
| transfer_method | string | 转账方式       | Enum: "pix", "ted"                                                                                                                              | 是   |
| account_type    | string | 账户类型       | Enum: "checking_account","deposit_account","guaranteed_account","investment_account","payment_account","saving_account","salary_account"         | 是   |

#### Payload financial

| 字段                   | 类型   | 描述                                               | 格式                         | 必填 |
|---|---|---|---|---|
| salary_amount          | number | 受益人薪资金额（福利总金额）                       | 最小值: 1                    | 是   |
| number_of_installments | number | CCB（取款和循环）分期数                            | 最小值: 1，最大值: 96        | 是   |
| monthly_interest_rate  | number | CCB（取款和循环）月利率                            | 最小值: 0.01，最大值: 0.0246 | 是   |
| emission_installments  | number | 卡片发行费分期数（根据向受益人收集的信息填写）     | 最小值: 1，最大值: 3         | 是   |

#### Payload collateral

| 字段                       | 类型   | 描述       | 格式                                                                                                 | 必填 |
|---|---|---|---|---|
| state                      | string | 州         | 2 个字符                                                                                             | 是   |
| benefit_number             | string | 福利编号   | 最少 1 个字符                                                                                        | 是   |
| collateral_type            | string | 担保物类型 | Enum: "social_security_benefit_card"（福利卡），"social_security_payroll_card"（薪资卡）             | 是   |
| assistance_type            | string | 福利类型   | Enum: [枚举值](#benefit_type_enumerator)                                                             | 是   |

#### Payload credit_agent

| 字段            | 类型   | 描述           | 格式                  | 必填 |
|---|---|---|---|---|
| document_number | string | 信贷代理人 CPF | 11 或 14 位数字       | 是   |
| name            | string | 信贷代理人姓名 | 最少 1 个有效字符     | 是   |

### 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 详情**

| 字段                            | 类型   | 描述                                                             |
|---|---|---|
| request_control_key             | string | 请求标识密钥                                                     |
| payroll_card_reservation_key    | string | 薪资卡预约密钥                                                   |
| payroll_card_reservation_status | string | 薪资卡预约状态                                                   |
| card_holder_document_number     | string | 持卡人 CPF                                                       |
| identifier_number               | string | 操作标识号                                                       |
| reservation_amount              | number | 薪资卡预约金额                                                   |
| reservation_contract_number     | string | Dataprev 批注合同编号                                            |
| withdrawal                      | object | 取款数据                                                         |
| payroll_card                    | object | 薪资卡数据                                                       |
| attached_documents              | array  | 附件文件列表                                                     |
| payroll_card_type               | string | 卡片类型（`social_security_benefit_card` 或 `social_security_payroll_card`） |
| wallet_key                      | string | 已创建钱包的唯一密钥（UUID4）                                    |

#### Payload withdrawal

| 字段                | 类型   | 描述                           |
|---|---|---|
| withdrawal_key      | string | 取款唯一密钥                   |
| contract_number     | string | 取款 CCB 合同编号              |
| withdrawal_amount   | number | 计算得出的取款 CCB 放款金额   |
| disbursement_date   | date   | 操作放款日期                   |
| withdrawal_status   | string | 取款状态                       |
| withdrawal_data     | object | 取款详细数据                   |

#### Payload withdrawal_data

| 字段                   | 类型   | 描述             |
|---|---|---|
| prefixed_interest_rate | object | 固定利率         |
| disbursement_options   | array  | 可用放款选项     |

#### Payload prefixed_interest_rate

| 字段          | 类型   | 描述         |
|---|---|---|
| daily_rate    | number | 日利率       |
| interest_base | string | 利息计算基准 |
| monthly_rate  | number | 月利率       |
| annual_rate   | number | 年利率       |

#### Payload disbursement_options

| 字段                   | 类型   | 描述               |
|---|---|---|
| disbursement_date      | string | 放款日期           |
| cet                    | number | 月综合实际利率     |
| annual_cet             | number | 年综合实际利率     |
| total_iof              | number | IOF 总金额         |
| disbursed_issue_amount | number | 放款金额           |
| issue_amount           | number | 发行金额           |
| installments           | array  | 分期列表           |

#### Payload installments

| 字段               | 类型   | 描述         |
|---|---|---|
| total_amount       | number | 分期总金额   |
| due_date           | string | 到期日期     |
| installment_number | number | 分期编号     |

#### Payload payroll_card

| 字段                       | 类型   | 描述                   |
|---|---|---|
| payroll_card_key           | string | 薪资卡唯一密钥         |
| payroll_card_status        | string | 薪资卡状态             |
| card_limit                 | number | 卡片计算得出的总额度   |
| card_issuance_entry_amount | number | 卡片发行费金额         |

#### Payload attached_documents

| 字段              | 类型   | 描述         |
|---|---|---|
| document_key      | string | 文件唯一密钥 |
| document_batch_key | string | 文件批次密钥 |
| document_type     | string | 文件类型     |
| document_certifier | string | 文件认证机构 |
| document_status   | string | 文件状态     |
| document_url      | string | 文件 URL     |
| signature_url     | string | 签名 URL     |

---

---

## 4. 发送附加文件

Dataprev 批注保证金后，预约状态更新为 `pending_additional_documents_submission`。要释放操作放款，必须发送附加文件（对于 INSS 薪资/福利卡产品，为**签约确认视频**）。

上传处理为异步操作。上传成功后将自动触发预约状态转换至 `pending_additional_documents_validation`，发送[状态变更](./manual_cartao_beneficio_webhook.md)和[文件更新](./manual_cartao_beneficio_documentos.md) Webhook，并触发文件验证。

:::info 附加文件被拒绝与重新提交
如果附加文件在系统验证中被拒绝，预约将返回至 `pending_additional_documents_submission` 状态，可通过同一接口重新提交附加文件。在系统分析批准/拒绝之前，不可重新提交附加文件，且每个预约和文件类型的分析次数上限为 5 次。
:::

:::warning 注意：放款触发条件
发送附加文件及系统随后的批准视为信贷操作的授权。文件验证成功后，操作将自动进入 `pending_withdrawal_disbursement` 状态（通过 Webhook 通知客户），并在受益人账户执行放款，**无需额外审批步骤**。
:::

### Request

**POST**
/payroll_card_reservation/social_security/[PAYROLL-CARD-RESERVATION-KEY]/additional_documents

**Params**

| 字段                         | 类型   | 描述                     | 必填 |
|---|---|---|---|
| payroll_card_reservation_key | string | 预约唯一密钥（UUID）      | 是   |

**Request Body**

```json
{
  "documents": [
      {
        "document_type": "payroll_card_confirmation_video", 
        "document_url": "https://download.samplelib.com/mp4/sample-5s.mp4"
      }
  ]
}
```

**Request Body 详情**

| 字段      | 类型   | 描述             | 必填 |
|---|---|---|---|
| documents | array  | 待附加文件列表   | 是   |

#### Payload documents

| 字段          | 类型   | 描述               | 格式                                         | 必填 |
|---|---|---|---|---|
| document_type | string | 文件类型           | Enum: "payroll_card_confirmation_video"      | 是   |
| document_url  | string | 视频文件公开下载链接 | 有效 URL                                    | 是   |

:::info **视频 URL**
请确保发送的 URL 可被外部用户访问，以便我们将文件上传至 QI 内部数据库。

- 支持的文件格式：.mp4
- 最大文件大小：256MB
:::

### Response

STATUS
**200** (OK)

请求已成功接收，文件将异步处理。

```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. 取款付款重新提交

如因数据不正确导致付款未能处理，可通过以下接口调整银行账户信息进行重新提交：

**PATCH**
/payroll_card_reservation/social_security/[PAYROLL-CARD-RESERVATION-KEY]/disbursement_account

### 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 详情**

| 字段                      | 类型   | 描述         | 格式 | 必填 |
|---|---|---|---|---|
| disbursement_bank_account | object | 放款银行账户 | -    | 是   |

#### Payload disbursement_bank_account

| 字段            | 类型   | 描述           | 格式                                                                                                                                            | 必填 |
|---|---|---|---|---|
| name            | string | 账户持有人姓名 | 最少 1 个有效字符                                                                                                                               | 是   |
| bank_code       | string | 银行代码       | 3 位数字                                                                                                                                        | 是   |
| account_digit   | string | 账户校验位     | 1 位数字                                                                                                                                        | 是   |
| branch_number   | string | 支行号         | 仅数字                                                                                                                                          | 是   |
| account_number  | string | 账户号码       | 仅数字                                                                                                                                          | 是   |
| document_number | string | 持有人 CPF     | 11 位数字                                                                                                                                       | 是   |
| transfer_method | string | 转账方式       | Enum: "pix", "ted"                                                                                                                              | 是   |
| account_type    | string | 账户类型       | Enum: "checking_account","deposit_account","guaranteed_account","investment_account","payment_account","saving_account","salary_account"         | 是   |

### Response

STATUS
**200** (OK)

---

## 6. 附录

### 同质化测试环境（Mock）

为方便在 **Sandbox** 环境中进行集成测试，系统根据创建 payload 中发送的**受益人 CPF 首位数字**模拟不同行为。

使用下表模拟成功和错误场景：

| CPF 首位数字 | 场景                    | 内部行为                                                                                     | 最终结果（客户）                                                                  |
| :---:        | ---                     | ---                                                                                          | ---                                                                               |
| **1**        | **理想流程（完整）**    | 签名**成功** <br/> 入网**成功** <br/> 批注（Dataprev）**成功**                              | **卡片已发行** <br/>（状态：`card_issued`）                                       |
| **2**        | **Dataprev 查询错误**   | 签名**成功** <br/> 入网**成功** <br/> 福利查询**失败**                                      | **预约已取消** <br/>（状态：`canceled`）<br/> + **发送状态 Webhook** <br/>（状态：`canceled`）|
| **3**        | **Dataprev 批注错误**   | 签名**成功** <br/> 入网**成功** <br/> 保证金批注/预约**失败**                               | **预约已取消** <br/>（状态：`canceled`）<br/> + **发送状态 Webhook** <br/>（状态：`canceled`）|
| **4**        | **地址错误**            | 签名**成功** <br/> 入网**成功**（地址不符） <br/> 批注（Dataprev）**成功**                  | **卡片已发行** <br/>（状态：`card_issued`）<br/> + **发送地址更新 Webhook**       |
| **5**        | **入网被拒**            | 签名**成功** <br/> 入网/KYC **被拒**                                                         | **预约已取消** <br/>（状态：`canceled`）<br/> + **发送状态 Webhook** <br/>（状态：`canceled`）|
| **6**        | **不符合资格（年龄 > 65）** | 签名**成功** <br/> 入网**成功**（返回年龄超过 65 岁）                                   | **预约已取消** <br/>（状态：`canceled`）<br/> + **发送状态 Webhook** <br/>（状态：`canceled`）|
| **7**        | **不符合资格（年龄 < 18）** | 签名**成功** <br/> 入网**成功**（返回年龄低于 18 岁）                                   | **预约已取消** <br/>（状态：`canceled`）<br/> + **发送状态 Webhook** <br/>（状态：`canceled`）|
| **8**        | **Teimosinha（重试）**  | 签名**成功** <br/> 入网**成功** <br/> 批注（Dataprev）**临时失败**                          | **等待释放** <br/>（状态：`pending_reservation`）<br/> + **发送 Collateral Webhook** |

:::tip 提示
要测试**理想流程**，请确保使用以 `1` 开头的 CPF（例如：`123.456.789-00`）且为有效 CPF（校验位计算正确）。
:::

:::warning 提示
成功 Mock 配置为模拟最高 R$10,000.00 的福利。如果使用超过此金额的福利值，系统将在批注时返回保证金超额错误，取消预约。
:::
---

### 福利类型表 {#benefit_type_enumerator}

| 代码 | 福利类型                                          |
| --- | ------------------------------------------------ |
| 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                                      |

---

# 地址管理

URL: /zh-Hans/documentation/manual_cartao_beneficio/manual_cartao_beneficio_endereco

:::info 导航
- [文件与签名](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_documentos)（上一步）
:::

在入网和 KYC 流程中，受益人的地址会经过我们的分析流程和受益人本人的验证。如果检测到任何不一致，将通知客户与受益人确认或更正数据。

## 1. 地址验证错误 Webhook

当 KYC 流程发现发送的地址与我们数据库中的地址之间存在不一致时，触发此 Webhook。

:::caution 需要采取行动
收到此 Webhook 后，客户必须联系受益人，并通过**地址更新**接口请求更正数据。不执行此更正可能导致卡片配送失败。
:::

WEBHOOK TYPE
laas.payroll_card_reservation.address

**Webhook Body**

```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_validation_failed",
        "rejection_details": {
            "description": "Endereço não encontrado na base de validação"
        }
    }
}
```

---

## 2. 地址更新

此接口用于在收到地址验证错误 Webhook 后更正受益人地址。

:::info 
如果受益人确认地址无误，则无需发送地址更新请求，已登记的地址将用于卡片配送。
:::

### 请求

**PATCH**
/payroll_card_reservation/social_security/{payroll_card_reservation_key}/address

**Request Body**

```json
{
    "address": {
        "city": "Belo Horizonte",
        "state": "MG",
        "number": "789",
        "street": "Rua das Palmeiras",
        "complement": "Casa 3",
        "postal_code": "30112000",
        "neighborhood": "Savassi"
    }
}
```

**参数详情**

| 字段         | 类型   | 描述          | 必填 |
|---|---|---|---|
| city         | string | 城市          | 是   |
| state        | string | 州（UF）      | 是   |
| number       | string | 门牌号        | 是   |
| street       | string | 街道名称      | 是   |
| complement   | string | 补充信息      | 否   |
| postal_code  | string | 邮政编码（仅数字） | 是 |
| neighborhood | string | 区/邻里       | 是   |

### 响应

STATUS
**200** (OK)

操作将在 KYC 流程中自动重新处理，如果再次检测到不一致，可能会产生新的错误 Webhook。

---

# 薪资卡手册 - Webhook

URL: /zh-Hans/documentation/manual_cartao_beneficio/manual_cartao_beneficio_webhook

:::info 导航
- [跟踪](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_acompanhamento)（上一步）
- [文件与签名](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_documentos)（下一步）
:::

:::caution API 开发中
该 API 仍处于开发阶段，因此本手册可能会有所变动。
:::

---

## 1. 全局状态变更 Webhook

为跟踪申请进度（签名完成、入网失败、放款完成或卡片发行），API 发送一个统一的 Webhook 通知预约状态变更。

WEBHOOK TYPE
laas.payroll_card_reservation.status_change

### Webhook 通用结构

| 字段           | 类型   | 描述                                            |
|---|---|---|
| key            | string | 卡片预约密钥                                    |
| status         | string | 预约的新状态                                    |
| webhook_type   | string | `laas.payroll_card_reservation.status_change`  |
| event_datetime | string | 事件日期和时间                                  |
| data           | object | 包含状态变更相关数据的对象                      |

### 场景

#### A. 签名完成（Pending Onboarding）
当文件通过 Qi Sign 或外部方式签名完成时触发。预约状态变更为 `pending_onboarding`，流程进入入网阶段。

返回预约的附件文件列表以及签名人的面部分析数据。

**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",
        }
    }
}
```

**响应体详情**

| 字段               | 类型   | 描述                       |
|---|---|---|
| attached_documents | array  | 为预约创建的文件列表       |
| signature_data     | object | 签名时收集的生物特征数据   |

##### signature_data Payload

| 字段                        | 类型   | 描述                                                                 |
|---|---|---|
| document_similarity_score   | number | 签署人与所发送文件之间的生物特征相似度分数（0-1）                    |
| similarity_score            | number | 签署人与人脸数据库中找到的参考之间的生物特征相似度分数（0-1）        |
| biometry_analysis_reference | string | 用于计算生物特征相似度分数的人脸数据来源                             |

#### B. 发送附加文件（Pending Additional Documents Submission）
当保证金在 Dataprev 成功预约**或**由于附加文件（视频）被拒绝而从验证阶段返回时触发。

此 Webhook 表示操作正在等待通过 `/additional_documents` 接口发送（或重新发送）确认视频。如果是因拒绝而重新发送，payload 将返回 `rejection_reason` 字段。

**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" // 仅在文件被拒绝后从 pending_additional_documents_validation 状态返回时出现
    }
}
```

#### C. 附加文件验证（Pending Additional Documents Validation）
确认视频成功发送后触发。状态变更为 `pending_additional_documents_validation`，表示视频/附加文件已进入验证和分析队列。

**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. 附加文件已批准（Pending Withdrawal Disbursement）
验证阶段分析并批准确认视频后触发。状态变更为 `pending_withdrawal_disbursement`（等待取款放款）。

**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:00:00Z",
    "data": {
        "credit_operation_key": "3571e292-3a83-4011-904d-20ee963022ef"
    }
}
```

#### E. 放款完成（Pending Card Issuance）
取款完成时触发。状态变更为 `pending_card_issuance`（等待卡片发行），流程进入卡片发行阶段。

不返回任何附加信息。

**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"
    }
}
```

#### F. 卡片已发行（Card Issued）
钱包和卡片创建完成时触发。

**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"
    }
}
```

---

#### G. 取消（Canceled）
操作因某种原因被取消时触发（身份或信用验证被拒、Dataprev 保证金预约错误等）。

返回取消原因和详情。

**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（生成与验证）

此 Webhook 通知操作中每个附件文件的单独状态变更。包括合同生成、签名收集阶段，以及附加文件（如确认视频）的验证阶段响应。

WEBHOOK TYPE
laas.payroll_card_reservation.attached_document.status_change

### Webhook 通用结构

| 字段           | 类型   | 描述                                                                                    |
|---|---|---|
| key            | string | 文件密钥                                                                                |
| status         | string | 文件的新状态（`generated`、`pending_signature`、`approved`、`rejected`）                |
| webhook_type   | string | `laas.payroll_card_reservation.attached_document.status_change`                         |
| event_datetime | string | 事件日期和时间                                                                          |
| data           | object | 包含状态变更相关数据的对象                                                              |

#### `data` 对象详情

| 字段                       | 类型   | 描述                                                           |
| --- | --- | --- |
| payroll_card_reservation_key | string | 卡片预约密钥                                                 |
| document_key               | string | 文件唯一密钥                                                   |
| document_type              | string | 文件类型                                                       |
| document_url               | string | 查看文件的链接                                                 |
| signature_url              | string | 签名流程链接。仅当 `status` 为 `pending_signature` 时出现。    |
| rejection_reason           | string | 拒绝原因。仅当 `status` 为 `rejected` 时出现。                 |

### 场景

#### A. 文件已生成（generated）
操作合同成功生成并可查看时触发。

**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. 待签名（pending_signature）
合同已生成并等待受益人签名时触发。返回 `signature_url`。

**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. 附加文件已批准（approved）
作为附加文件（如确认视频）验证的肯定响应触发，表示文件已由我们的团队或检查系统验证并接受。

**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. 附加文件已拒绝（rejected）
作为附加文件验证的否定响应触发。文件被拒绝，payload 将包含 `rejection_reason` 属性说明原因。

**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. Dataprev 返回 Webhook（担保物）

此 Webhook 通知 Dataprev 保证金预约进度。

主要用于**"Teimosinha"（持续重试）**场景，即临时故障（如保证金被占用或分期金额暂时超额）不会立即取消预约。在这些情况下，预约保持在批注队列中，直到配置的最后放款日期。

WEBHOOK TYPE
social_security.collateral

### Webhook 通用结构

| 字段                              | 类型    | 描述                                                                |
|---|---|---|
| key                               | string  | **卡片预约**密钥（`payroll_card_reservation_key`）                 |
| webhook_type                      | string  | 始终为 `social_security.collateral`                                |
| event_time                        | string  | 事件日期和时间                                                      |
| data                              | object  | Dataprev 返回的详细数据                                             |
| data.collateral_constituted       | boolean | 表示担保物是否成功构成（`true` 或 `false`）                         |
| data.collateral_data.status       | string  | 预约状态（例如：`pending_reservation`）                             |
| data.collateral_data.last_response| object  | 包含 Dataprev 返回的错误列表（例如：`installment_limit_excceded`）  |

**Payload 示例 - 临时故障**

```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
  }
}
```

---

## 4. 信贷操作 Webhook（放款与 CCB 状态）

此 Webhook 通知与预约关联的**信贷操作**（CCB）状态变更。在两个主要时刻触发：
1.  **成功（`opened`）：** 资金已成功转入客户账户。
2.  **取消（`canceled`）：** 放款时发生银行错误（如账户无效、持有人信息不符），操作被取消。

WEBHOOK TYPE
laas.credit_operation.status_change

### Webhook 通用结构

| 字段           | 类型   | 描述                                                  |
|---|---|---|
| key            | string | **信贷操作**密钥（`credit_operation_key`）            |
| status         | string | 操作新状态：`opened`（成功）或 `canceled`（失败）      |
| webhook_type   | string | 始终为 `laas.credit_operation.status_change`          |
| event_datetime | string | 事件日期和时间                                        |
| data           | object | 包含成功详情或错误原因的可变对象                      |

---

### 场景 A：放款成功（`opened`）

状态为 `opened` 时，`data` 对象包含最终财务详情和交易凭证。

| `data` 中的字段          | 类型   | 描述                                  |
|---|---|---|
| installments             | array  | 含最终日期和金额的已确认分期列表      |
| transaction_receipts     | array  | 银行转账凭证列表                      |
| requester_identifier_key | string | 请求方唯一标识符                      |

**Payload 示例 - 成功**

```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
        }
      ],
      "disbursement_type": "pix",
      "transaction_receipts": [...],
      "requester_identifier_key": "req_id_key_uuid"
    }
}
```

---

### 场景 B：放款失败（`canceled`）

状态为 `canceled` 时，`data` 对象包含银行拒绝原因（PIX 或 TED 退回）。

| `data` 中的字段           | 类型   | 描述                                                   |
|---|---|---|
| cancel_reason             | string | 取消的宏观原因（例如：`pix_refusal`、`ted_refusal`）   |
| cancel_reason_enumerator  | string | 原因枚举值（例如：`pix_refusal`）                       |
| pix_refusal               | object | PIX 拒绝详情（可选）                                   |
| ted_refusal               | object | TED 拒绝详情（可选）                                   |
| [refusal].reason          | string | 银行错误的描述性消息                                   |
| [refusal].reason_enumerator | string | 银行错误代码（例如：`invalid_account`）              |

**Payload 示例 - 放款错误**

```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 重新提交
与预约关联的信贷操作取消并不一定意味着预约本身也被取消。在放款错误的情况下，预约保持开放状态，信贷操作仍可在卡片发送日期前重新提交。

更多详情，请参阅创建预约中的[5. 取款付款重新提交](./manual_cartao_beneficio_emissao.md)。
:::

## 5. 保险/福利保单创建 Webhook

此 Webhook 通知与卡片关联的保险发行情况，并返回福利保单的 URL。
保险发行在卡片发行后异步进行，可能需要数小时才能确认。

WEBHOOK TYPE
laas.payroll_card_reservation.benefit.emission

### Webhook 通用结构

| 字段           | 类型   | 描述                                                               |
|---|---|---|
| key            | string | 与预约关联的福利/保险密钥（`benefit.benefit_key`）                  |
| status         | string | `active`（保险激活）                                               |
| webhook_type   | string | 始终为 `laas.payroll_card_reservation.benefit.emission`             |
| event_datetime | string | 事件日期和时间                                                     |
| data           | object | 包含保单详情的可变对象                                             |
| data.policy_url | string | 保险保单文件的 URL                                                |

**Webhook 示例**

```json
{
    "key": "550e8400-e29b-41d4-a716-446655440000",
    "status": "opened",
    "webhook_type": "laas.payroll_card_reservation.benefit.emission",
    "event_datetime": "2025-10-14 13:26:52",
    "data": {
      "policy_url": "https://example.com/policy.pdf",
    }
}
```

---

# CertifiQI 手册

URL: /zh-Hans/documentation/manual_certifiqi/dc37cf4f-adad-45c5-9251-9c957fb9ce8e

## 请求

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"
}
```

POST /document 方法用于发送文档（PDF 或 CNAB）并将其与一组文档关联。

请求的 form-data 中需发送以下数据：

- file - pdf 格式的文档。

:::caution **此请求的返回**

此请求的返回值应在后续的 POST /batch_group 请求中发送。与 batch_group 一起发送后，无需保存该信息。

:::

## 响应

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"
}

```

## 定义

### 请求体对象
| 字段                            | 类型     | 描述                                                                                                                                                                                                             | 最大字符数 | 
|---------------------------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| **file_name** *                  | string | 将要发送的文件名。                                                                                                                                        | -          | 
| **document_type** * | string | 将要发送的文档类型。                                                                                 | -          |
| **document_identifier** *                 | string | 合作伙伴系统中的文档标识符。 | -          |
| **endorsement_page** * | boolean | 表示是否应为文档生成背书。                                                                                                                                                           | -          |
| **endorser_name** * | string | 背书人姓名。                                                                                                                                                           | -          |
| **endorser_document_number** * | string | 背书人文件编号。                                                                                                                                                           | -          |
| **receiver_name** * | string | 接收人姓名。                                                                                                                                                           | -          |
| **receiver_document_number** * | string | 接收人文件编号。                                                                                                                                                           | -          |
| **control_number** | string | 可选字段，表示由 QI Tech 提供的转让控制号（当转让由 QI Tech 执行时）。                                                                                                                                                           | 36         |

## 请求

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
}
```

POST /batch_group 方法用于发送所有文档和事件签署方以进行签名。请求体中需要发送的数据请参见"创建 batch group"。

## 响应

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": []
}

```

## 定义

### 请求体对象
| 字段                            | 类型             | 描述                                                                                                                                                                                                             | 最大字符数 | 
|---------------------------------|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| **client_key** *                  | string | 代表合作伙伴密钥的 uuid。                                                                                                                                         | -          | 
| **name** * | string | 将要发送的文档组的名称。                                                                                 | -          |
| **main_related_party** *                 | string | 签署事件的主要关联方姓名（但这是一个自由字段）。 | -          |
| **batches** * | array of objects | 不同类型文档的列表。                                                                                                                                                           | -          |
| **total_value** * | float | 事件文档的总价值。                                                                                                                                                           | -          |
| **send_emails** * | boolean | 表示是否应为此签名事件发送签名邮件。                                                                                                                                                           | -          |
| **send_to_fund_administrator** * | boolean | 表示如果基金管理员使用 FROMTIS，是否应将事件发送给基金管理员。                                                                                                                                                           | -          |
| **requester_identifier** * | string | 合作伙伴提供的事件标识符。                                                                                                                                                           

### BATCHES 对象

| 字段                            | 类型             | 描述                                                                                                                                                                                                             | 最大字符数 | 
|---------------------------------|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| **related_parties** *                  | array of objects | 签署该批次的关联方。                                                                                                                                        | -          | 
| **documents** * | array of objects | POST /document 中发送的文档列表。                                                                                 | -          |
| **name** *                 | string | 文件名。 | -          |
| **signature_type** * | string | 签名类型。                                                                                                                                                           | -          |
| **document_type** * | string | 文档类型。                                                                                                                                                          | -          |      

### RELATED PARTIES 对象

| 字段                            | 类型             | 描述                                                                                                                                                                                                             | 最大字符数 | 
|---------------------------------|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| **role** *                  | string | 职位/角色。                                                                                                                                      | -          | 
| **name** * | string | 公司名称。                                                                          | -          |
| **document_number** *                 | string | 签署方文件编号。 | -          |
 
## 请求

ENDPOINT /batch_group/ BATCH_GROUP_KEY /send_to_signature
MÉTODO POST

### 路径参数

| 字段 | 描述 |
|---|---|
| **batch_group_key** * | 签名事件的唯一标识密钥。 |

POST /batch_group/ BATCH_GROUP_KEY /send_to_signature 方法用于完成文档组并将批次发送以进行签名。

---

# Cessão

URL: /zh-Hans/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: /zh-Hans/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 |

---

# 私人薪资抵押贷款手册 - 外部签署形式

URL: /zh-Hans/documentation/manual_consignado_privado/manual_assinatura_externa

:::info 导航
- [发行与正式化](/documentation/manual_consignado_privado/manual_credito_novo)（上一页）
- [核批与放款](/documentation/manual_consignado_privado/manual_averbacao_desembolso)（下一页）
:::

:::caution 开发中的 API
该 API 仍处于开发阶段，因此本手册可能会有所更改。
:::

本节将提供使用 API 对活跃流程中产生的操作进行签署所需的指导，无需使用 QI Tech 的电子签名解决方案 QIsign。

此流程适用于选择使用外部电子签名解决方案（如 DocuSign、Clicksign 等）来正式化合同的客户。

## 1 - 文件提交

必须提交合同的补充数据。

文件必须通过[文件上传端点](../upload_de_documentos)提交，并遵循以下格式：

| 验证     | 值           |
|----------------|--------------|
| 格式        | JPEG         |
| 最小尺寸 | 250 x 250 px |

文件上传后，提交的文件密钥必须在创建操作的 payload 中提供，或之后通过以下端点提供：

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",
    "selfie": "ca37979e-6f11-4465-bf3b-69cd8307549c"
}
```

:::info 信息
**related_party_key** 在创建债务的响应中的 **borrower** 对象内返回
:::

## 2 - 操作正式化

文件输入后，操作可以进入正式化阶段。

在法定代理人签署的情况下，"**data.contract.signers[i]**"字段将返回法定代理人的数据，"**data.contract.signers[i].signer_role**"对象的值将为"**issuer_legal_representative**"。

**在签署 payload 中，必须包含第 1 项中提交文件的必填字段。必填字段如下：_ip_address_ 和 _signature_datetime_。**

### Request

ENDPOINT /debt/ DEBT-KEY /signed
MÉTODO POST

#### **PAYLOAD 示例**
Request Body - 已签署 PDF

```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 - 凭证签署

```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 注意
签署 payload 根据合作伙伴的正式化流程而有所不同，必须与 QI Tech 的集成团队进行协调。
:::

#### _生物特征分析参考_ 枚举值
| 枚举值    | 描述                                                                                                                                                                                                                                                          |
|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **serpro**    | 当 similarity_score 通过查询 Detran 照片文件数据库（通过 Serpro 提供的服务）返回时使用 |
| **tse**       | 当 similarity_score 通过查询 TSE 照片文件数据库返回时使用 |
| **not_found** | 当面部生物特征在上述任何政府数据库（serpro 或 tse）中均未找到时填写。在这种情况下，similarity_score 应为 null，或由合作伙伴返回的自拍与带照片官方文件的相似度分数。 |

---

# 私人薪资抵押贷款手册 - 信贷操作跟踪

URL: /zh-Hans/documentation/manual_consignado_privado/manual_assinatura_leilao

## 1. 正式化

赢得内部拍卖后，合作伙伴应等待收到正式化 webhook，表明借款人已完成 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"
}
```

签署失败时，合作伙伴将收到以下模型的 webhook。

```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. 提案确认

发送第二个 webhook，通知操作正在等待核批授权调用。

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"
    },
    "key": "<credit_operation_key>",
    "event_datetime": "2025-04-09T20:00:20Z",
    "status": "pending_requester_authorization"
}
```

此时合作伙伴可以决定继续放款操作或取消提案：

### 授权核批

要继续核批，需进行以下调用：

#### Request

**PATCH**
/private_payroll/reservation/external_key/ EXTERNAL-KEY /authorize

#### 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"
}
```

### 取消操作
若不继续核批，需要取消操作。

如果操作来自拍卖，可以通过永久取消端点完成，方式与[第6项 - 取消核批](#desaverbacao)相同。

如果操作来自主动流程，则应通过[本手册](./manual_averbacao_desembolso.md)中的端点进行取消。

:::info 重要
`external_key` 字段是信贷操作的 UUID，与 `debt_key` 和 `credit_operation_key` 相同。
:::

## 3 - 核批

### 核批成功

核批成功时，合作伙伴将收到以下 webhook：

WEBHOOK TYPE
credit_operation.collateral

collateral_constituted
True

**Webhook Body**

```json
{
  "webhook": {
    "key": "<credit_operation_key>",
    "data": {
      "collateral_data": {},
      "collateral_type": "private_payroll",
      "collateral_constituted": true
    },
    "event_time": "2025-07-10 02:15:01",
    "webhook_type": "credit_operation.collateral"
  }
}
```

### 核批失败

核批失败时，将发送包含 DATAPREV 批评信息的 webhook。核批失败的可能原因可在[核批失败原因](#fail_reservation_reason)表中查阅。根据核批错误，QI 将保持提案处于"重试"状态，进行新的核批尝试，直到操作被手动取消或放款选项耗尽为止。

WEBHOOK TYPE
credit_operation.collateral

collateral_constituted
False

**Webhook Body**

```json title="Webhook Body"
{
    "key": "72926c65-35a5-4060-b5ec-af8661d8546a",
    "data": {
      "collateral_data": {
        "status": "pending_reservation",
        "last_response": {
          "errors": [
            {
              "enumerator": "monthly_interest_rate_exceeds_active_proposal"
            }
          ]
        },
        "last_response_event_datetime": "2025-10-10T19:45:39Z"
      },
      "collateral_type": "private_payroll",
      "collateral_constituted": false
    },
    "event_time": "2025-10-10 00:07:21",
    "webhook_type": "credit_operation.collateral"
}
```

## 4 - 放款

核批成功后，操作将自动进入放款阶段。

### 放款成功

WEBHOOK TYPE
laas.credit_operation.status_change

STATUS
opened

**Webhook Body**

```

```

### 放款失败

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 放款失败
若放款失败，必须对提案采取行动，因为保证金不会自动取消核批。

合作伙伴需要决定联系借款人以请求更新银行数据，从而[重新提交债务还款](#reapresentacao)，或者合作伙伴进行债务[永久取消](#desaverbacao)调用以取消薪资抵押保证金。
:::

## 5 - 重新提交还款 {#reapresentacao}

要重试债务放款，需进行以下调用，同时更新放款日期和银行数据（如果是同一银行账户重试，则只需发送放款日期参数即可）。

可能的放款账户 payload 示例请参见[放款 payload 示例页面](/documentation/emissao_de_divida/emissao/exemplo_payloads_desembolso)。
对于此 API，payload 中的 disbursement_bank_accounts 已更名为 disbursement_account。

要重新提交债务，需使用 auction_proposal_key 发起请求。
ENDPOINT - `/private_payroll_auction/auction_proposal/{auction_proposal_key}/change_disbursement_date`
MÉTODO - `PATCH`

```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 - 取消核批 {#desaverbacao}

要永久取消操作并取消保证金核批，需进行以下调用：

#### Request

ENDPOINT - `/private_payroll_auction/auction_proposal/{auction_proposal_key}/cancel`
MÉTODO - `PATCH`

#### Response

STATUS - 202 (Accepted)

Response Body: 提案已取消

```json
{
  "auction_proposal_key": "814e7ed3-4080-4cae-a853-8e12812817ea",
  "status": "cancelled"
}
```

修改成功时将返回状态 200。

STATUS - 200
若发送的 payload 格式有误，将返回无效 schema 错误

STATUS - 400

## 7 - 核批查询

要查询核批数据及核批或取消核批的协议凭证，可使用以下端点：

:::warning 核批凭证
可使用此方法查询核批、取消核批和暂停凭证。protocol_type 的可能枚举值请见[协议类型](#protocol_type)表
:::
#### Request

**GET**
/private_payroll/reservation/external_key/ [DEBT-KEY]

#### 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
    }
}
```

## 附件

### 重新提交放款详情

|         字段         |  类型   | 描述| 
|-----------------------|---------|----------|
| `disbursement_date` | string  | 新的放款日期，格式 YYYY-MM-DD，非必填| 
| `disbursement_account`              | dict  | 放款账户数据，非必填|

### 核批失败原因 {#fail_reservation_reason}

| 枚举值                                                            | 描述                                                                                                     | QI 操作                                                                         
|------------------------------------------                             |-------------------------------------------------------                                                        |----------
| **monthly_interest_rate_exceeds_active_proposal**                     | QI 在借款人 CTPS 应用中有一个利率低于本次核批尝试的有效提案 | 重试
| **margin_exceeded**                                                   | 薪资抵押保证金超额                                                                                   | 重试
| **allowed_number_of_contracts_exceeded**                              | 超过最大合同数量                                                                                       | 取消操作
| **employment_relationship_blocked**                                   | 雇佣关系被借款人锁定（可通过 CTPS 应用解锁）                                                                       | 取消操作

### 协议类型 {#protocol_type}

| 枚举值                                                            | 描述                                             
|------------------------------------------                             |-------------------------------------------------------
| **reservation**                                                       | 核批 
| **documents_inclusion**                                               | 文件提交（向 DATAPREV 发送正式化文件的流程）
| **suspension**                                                        | 暂停                                                                      
| **deletion**                                                          | 删除

---

# 私人薪资抵押贷款手册 - 核批与放款

URL: /zh-Hans/documentation/manual_consignado_privado/manual_averbacao_desembolso

:::info 导航
- [外部签署](/documentation/manual_consignado_privado/manual_assinatura_externa)（上一页）
:::

:::danger 注意！
QI Tech 的 webhook 不应进行严格映射。
返回的 webhook payload 中可能包含额外字段。
:::

:::info 重新发送 Webhook
您可以按照文档中的详细说明查询和重新发送 webhook：[重新发送 Webhook](/documentation/notificacoes/reenvio_de_notificacoes)。
:::

## 1. 提案确认

在主动流程中，可以配置环境，使操作在借款人完成债务正式化后立即进入核批和放款阶段，否则将发送 webhook 通知操作正在等待授权调用以继续流程（此配置需与运营团队协调）。

### 核批待授权

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"
    },
    "key": "<Debt Key>",
    "event_datetime": "2025-04-09T20:00:20Z",
    "status": "pending_requester_authorization"
}
```

此时合作伙伴可以决定继续放款操作或取消提案：

### 授权核批

要继续核批，需进行以下调用：

#### Request

**PATCH**
/private_payroll/reservation/external_key/ EXTERNAL-KEY /authorize

#### 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"
}
```

### 取消操作
若不继续核批，需要取消操作。

如果操作来自主动流程，可以通过永久取消端点完成，方式与[第5项 - 取消核批](#desaverbação)相同。

如果操作来自拍卖，则应通过拍卖文档中的提案取消端点进行取消。

:::info 重要
`external_key` 字段是信贷操作的 UUID，与 `debt_key` 和 `credit_operation_key` 相同。
:::

## 2 - 核批

### 核批成功

核批成功时，合作伙伴将收到以下 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"
  }
}
```

### 核批失败

核批失败时，将发送包含 DATAPREV 批评信息的 webhook。核批失败的可能原因可在[核批失败原因](#fail_reservation_reason)表中查阅。根据核批错误，QI 将保持提案处于"重试"状态，进行新的核批尝试，直到操作被手动取消或放款选项耗尽为止。

WEBHOOK TYPE
credit_operation.collateral

collateral_constituted
False

**Webhook Body**

```json title="Webhook Body"
{
    "key": "72926c65-35a5-4060-b5ec-af8661d8546a",
    "data": {
      "collateral_data": {
        "status": "pending_reservation",
        "last_response": {
          "errors": [
            {
              "enumerator": "monthly_interest_rate_exceeds_active_proposal"
            }
          ]
        },
        "last_response_event_datetime": "2025-10-10T19:45:39Z"
      },
      "collateral_type": "private_payroll",
      "collateral_constituted": false
    },
    "event_time": "2025-10-10 00:07:21",
    "webhook_type": "credit_operation.collateral"
}
```

## 3 - 放款

核批成功后，操作将自动进入放款阶段。

### 放款成功

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"
  }
```

### 放款失败

#### TED
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
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 放款失败
若放款失败，必须对提案采取行动，因为保证金不会自动取消核批。

合作伙伴需要决定联系借款人以请求更新银行数据，从而[重新提交债务还款](#reapresentacao)，或者合作伙伴进行债务[永久取消](#desaverbacao)调用以取消薪资抵押保证金。
:::

## 4 - 重新提交还款 {#reapresentacao}

要重试债务放款，需进行以下调用，同时更新放款日期和银行数据（如果是同一银行账户重试，则只需发送放款日期参数即可）。

可能的放款账户 payload 示例请参见[放款 payload 示例页面](/documentation/emissao_de_divida/emissao/exemplo_payloads_desembolso)。

#### Request

**POST**
/debt/ DEBT-KEY /change_disbursement_date

### 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 - 取消核批 {#desaverbacao}

合同的取消核批通过永久取消路由完成。该路由为合同设置最终状态，不可重试，并触发已核批保证金的取消核批。

要执行永久取消，请使用以下端点：

### Request

**POST**
/debt/ DEBT-KEY /cancel_permanently

### 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": {}
}
```

## 6 - 核批查询

要查询核批数据及核批或取消核批的协议凭证，可使用以下端点：

:::warning 核批凭证
可使用此方法查询核批、取消核批和暂停凭证。protocol_type 的可能枚举值请见[协议类型](#protocol_type)表
:::

**GET**
/private_payroll/reservation/external_key/ [DEBT-KEY]

### 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
    }
}
```

## 附件
---

### 核批失败原因 {#fail_reservation_reason}

| 枚举值                                                            | 描述                                                                                                     | QI 操作                                                                         
|------------------------------------------                             |-------------------------------------------------------                                                        |----------
| **monthly_interest_rate_exceeds_active_proposal**                     | QI 在借款人 CTPS 应用中有一个利率低于本次核批尝试的有效提案 | 重试
| **margin_exceeded**                                                   | 薪资抵押保证金超额                                                                                   | 重试
| **allowed_number_of_contracts_exceeded**                              | 超过最大合同数量                                                                                       | 取消操作
| **employment_relationship_blocked**                                   | 雇佣关系被借款人锁定（可通过 CTPS 应用解锁）                                                                       | 取消操作

### 协议类型 {#protocol_type}

| 枚举值                                                            | 描述                                             
|------------------------------------------                             |-------------------------------------------------------
| **reservation**                                                       | 核批 
| **documents_inclusion**                                               | 文件提交（向 DATAPREV 发送正式化文件的流程）
| **suspension**                                                        | 暂停                                                                      
| **deletion**                                                          | 删除

---

# 私人薪资抵押贷款手册 - 拍卖提案接收过滤器配置

URL: /zh-Hans/documentation/manual_consignado_privado/manual_configuracao_filtros

## 简介

通过拍卖发行操作的流程始于借款人在数字 CTPS 应用中申请贷款，QI Tech 定期查询所有申请，并针对每个请求开启内部提案拍卖，通过 webhook 通知合作伙伴。
本手册包含配置申请过滤器所需的端点，可控制操作目标群体。

## 修改过滤规则

ENDPOINT - `/private_payroll_auction/requester_configuration/custom_data`
MÉTODO - `PATCH`

此请求中有两种可修改的字段类型：客户状态和客户过滤器。关于客户状态，可在[活跃与非活跃](#status_do_cliente)之间切换，表示客户是否希望接收新的拍卖申请。

```json
{
    "status": "active"
}
```

[custom_data](#custom_data_params) 字段包含实际的过滤器。其中必须发送所有过滤字段，如下例所示：
```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"
        }
    }
}
```

:::warning 
除 received_daily_proposals、days_since_employment 和 alert_preferences 外，每个字段必须包含 min 和 max 键。
*注意：所有 custom data 字段都必须发送，即使不需要修改所有值。此外，所有 min/max 键的发送都是必填的，不需要使用该过滤器时传 'null'*。
:::

### [Body](#custom_data_payload) 示例

```json
{
    "status": "inactive",
    "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},
    }
}
```

### Response

STATUS - 201 (Accepted)

Response Body: 配置已更新

```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},
    }
}
```

## 添加过滤 CNPJ

对于只想接收特定 CNPJ 员工申请的客户，可以批量添加这些 CNPJ：
ENDPOINT - `/private_payroll_auction/requester_configuration/related_employer`
MÉTODO - `POST`

:::caution 注意！
DATAPREV 只使用 CNPJ 的根号，因此根据雇主文件号进行过滤时，**只需发送 CNPJ 的前 8 位数字**。
:::

### [Body](#employer_payload)
```json
{
  "employer_document_numbers": [
    "01234567",
    "12345678"
  ]
}
```

**[列表](#employer_payload)最多可包含 100 个 CNPJ。**

### Response

STATUS - 201
Response Body: 已添加 CNPJ

```json
{
  "employer_document_numbers": [
    "01234567",
    "12345678"
  ]
}
```
:::info 备注
只有实际添加的 CNPJ 才会被返回。如果某个 CNPJ 已经注册，则不会出现在响应列表中。如果没有任何 CNPJ 被添加，将返回空列表。
:::

## 删除过滤 CNPJ

ENDPOINT - `/private_payroll_auction/requester_configuration/remove_related_employers`
MÉTODO - `POST`

### [Body](#employer_payload)
```json
{
  "employer_document_numbers": [
    "01234567",
    "12345678"
  ]
}
```
**CNPJ 只需发送前 8 位数字，列表最多可包含 100 个 CNPJ。**

### Response

STATUS - 200
Response Body: 已删除 CNPJ

```json
{
    "employer_document_numbers": ["01234567", "12345678"]
}
```

## 查询过滤 CNPJ

要查询为申请方注册为过滤器的 CNPJ，请使用以下支持分页的端点。

### 端点

ENDPOINT - `/private_payroll_auction/requester_configuration/related_employers`
MÉTODO - `GET`

### Query Params

| 字段         | 类型 | 描述                          | 默认值 |
|---------------|------|------------------------------------|--------|
| `page_number` | int  | 当前页码             | 1      |
| `page_rows`   | int  | 每页记录数 | 100    |

### 响应示例 - 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
  }
}
```

## 附件

### 过滤规则修改 Payload 详情 {#custom_data_payload}

| 字段         | 类型      | 描述                             | 必填   |
|---------------|--------   |---------------------------------------|------------   |
| `status`      | string    | 客户新状态                | 否           |
| `custom_data` | dict      | 客户新过滤器          | 否           |

### 客户状态 {#status_do_cliente}

| 状态        | 描述                                                                 |
|----------     | ------------------------------------------------------------------------- |
| active        | 客户希望接收拍卖中的新提案申请            |
| inactive      | 客户**不**希望接收新提案申请             |

### Custom Data 参数 {#custom_data_params}

| 字段                       | 类型  | 描述                                                               | 必填 |
|---------------------------- |-------|-----------------------------------------------------------------------  |--------------|
| `disbursed_issue_amount`    | dict  | 已发行合同金额（最小值和最大值）                             | 是          |
| `number_of_installments`    | dict  | 分期数（最小值和最大值）                                    | 是          |
| `consigned_credit_balance`  | dict  | 薪资抵押信贷余额（最小值和最大值）                           | 是          |
| `days_since_employment`     | dict  | 自雇佣关系开始以来的天数（最小值）                    | 是          |
| `age`                       | dict  | 申请人年龄（最小值和最大值）                                   | 是          |
| `received_daily_proposals`  | dict  | 每日接收提案数量（最大值）                          | 是          |
| `alert_preferences`         | dict  | 带有某些提醒的贷款申请过滤器，详情请参阅 [alert_preferences 参数](#alert_preferences)| 是          |

### alert_preferences 参数 {#alert_preferences} 

| 字段                       | 类型    | 描述                                                                         | 必填  | 枚举值                                     |
|---------------------------- |-------  |-----------------------------------------------------------------------            |--------------|-------------                                     |
| `default`                   | string  | 默认行为，未配置特定行为时使用 | 是          | ignore 表示不接收，acknowledge 表示接收|
| `termination`               | string  | 带有解雇提醒的线索过滤器                                        | 否          | ignore 表示不接收，acknowledge 表示接收|
| `leave`                     | string  | 带有休假提醒的线索过滤器                                         | 否          | ignore 表示不接收，acknowledge 表示接收|

### 添加和删除过滤 CNPJ 的 Payload 详情 {#employer_payload}

| 字段         | 类型   | 描述                              | 必填 |
|---------------|--------|----------------------------------------|------------ |
| `employer_document_number` | string 数组  | CNPJ 根号列表（每个 8 位数字）。必须包含 1 至 100 个条目  | 是         |

---

# 私人薪资抵押贷款手册 - 账目查询

URL: /zh-Hans/documentation/manual_consignado_privado/manual_consultas_conciliacao

账目记录是公司人力资源部（RH）或人事部（DP）的强制性流程，用于在政府系统（通过 eSocial）中登记员工工资单上活跃薪资抵押贷款分期付款的扣款。从本质上说，账目记录是扣款的会计和财税正式化。正式化金额支付后，金额将转至联邦储蓄银行（Caixa Econômica Federal），再由其转交给债权金融机构。

当月工资单对应分期付款的账目记录必须在每月 15 日前完成。

## 1 - 账目查询

**GET**
/private_payroll_conciliation/registers

### Query Parameters

| 参数       | 类型    | 必填 | 描述                                 | 默认值 |
|-----------------|---------|-------------|-------------------------------------------|--------------|
| start_date      | date    | 是         | 账目最早日期（YYYY-mm-dd）  |              |
| end_date        | date    | 是         | 账目最晚日期（YYYY-mm-dd）  |              |
| page_number     | integer | 否         | 要返回的页码          | 1            |
| page_rows       | integer | 否         | 每页记录数        | 100          |

:::info
分页从 1 开始，因此第一页是第 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 账目属性
'contract_number'、'employer_document_number' 和 'registration_number' 属性不一定与信贷操作数据一致，因为它们是雇主人力资源部输入的数据。要将账目与信贷操作关联，应使用 "credit_operation_key" 键。
:::

### Response Body

分页响应由账目数组（*data*）和分页对象（*pagination*）组成。

#### 属性列表

*data* 数组中各项的描述：

| 参数                  | 类型    | 描述                              |
|----------------------------|---------|----------------------------------------|
| register_key               | string  | 账目标识符                      |
| contract_number            | string  | 雇主登记的合同编号     |
| amount                     | decimal | 账目总金额                        |
| reference_month            | string  | 账目所指的到期月份 |
| external_reference_month   | string  | DATAPREV 报告的能力月份         |
| registered_at              | string  | 账目日期                               |
| document_number            | string  | 客户 CPF                                     |
| employer_document_number   | string  | 雇主 CNPJ 或 CPF                          |
| registration_number        | string  | 员工工号                           |
| credit_operation_key       | string  | 信贷操作标识符               |
| register_type              | string  | 账目类型，可能的枚举值请见[账目类型](#register_type)表|
| credit_operation_key       | string  | 信贷操作标识符               |

#### 分页数据

*pagination* 对象中的数据：

| 参数     | 类型    | 必填 | 描述                          |
|---------------|---------|-------------|------------------------------------|
| current_page  | integer | 是         | 当前页                       |
| next_page     | integer | 是         | 下一页                     |
| rows_per_page | integer | 是         | 每页记录数 |

### 账目类型 {#register_type}
ENUMERADOR
register_type
| 枚举值                    | 描述                         | 
|-------------------------      |-----------------------------------|
|regular_pay                    |普通扣款                 |
|severance_pay                  |解除合同款项扣款       |

---

# 私人薪资抵押贷款手册 - 工人查询

URL: /zh-Hans/documentation/manual_consignado_privado/manual_consultas_trabalhador

:::info 导航
- [发行流程](/documentation/manual_consignado_privado/manual_detalhamento_fluxo_ativo)（上一页）
- [发行与正式化](/documentation/manual_consignado_privado/manual_credito_novo)（下一页）
:::

在私人薪资抵押贷款主动发行流程开始时，需要对工人进行两项主要查询：

1. 雇佣关系查询：仅提供工人 CPF 即可执行。此操作返回工人的有效雇佣关系列表，以及每个关系的信贷操作资格。

2. 工人数据查询：基于特定雇佣关系，提供在雇佣关系查询中获取的雇主文件号和工号。此操作返回所选雇佣关系的详细附加信息，包括个人数据、薪资抵押额度、雇佣关系历史及任何提醒。

:::caution 注意
执行任何一项查询，都必须发送[授权条款](#authorization_term)。
该条款必须基于借款人提供明确同意（opt-in）授权执行查询的证据而创建。
证据（如时间戳、IP 地址和会话标识符）必须包含在请求中，以确保流程的可追溯性和监管合规性。
:::

这些查询连同[授权条款](#authorization_term)是验证工人资格和在信贷操作正式化之前获取必要数据的基本步骤。

:::danger 注意！
QI Tech 的 webhook 不应进行严格映射。
返回的 webhook payload 中可能包含额外字段。
:::

:::info 重新发送 Webhook
您可以按照文档中的详细说明查询和重新发送 webhook：[重新发送 Webhook](/documentation/notificacoes/reenvio_de_notificacoes)。
:::

## 1 - 工人雇佣关系查询：
雇佣关系查询是一项异步操作。发送请求后，QI Tech 将在后台处理查询，并在完成后通过 webhook 返回结果。

Webhook 将发送到您环境中配置的 URL。

**POST**
/private_payroll/employment_relationships_inquiry

### Request

**情况 1：** 工人是[授权条款](#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"
            }
        }
    }
}
```

**情况 2：** 法定代理人是[授权条款](#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 注意
有法定代理人的情况下，必须在 **"legal_representative_document_number"** 字段填写法定代理人的 CPF，**"signer"** 对象中的数据也应填写法定代理人的信息。
:::

### Response

STATUS
**202** Accepted

**Response Body**

```json
{
    "employment_relationships_inquiry_key": "<UUID>",
    "employment_relationships_inquiry_status": "pending_inquiry"
}
```

:::info
**employment_relationships_inquiry_status** 枚举的可能值列在[雇佣关系查询状态](#status-das-consultas)部分。
:::

### Webhooks

WEBHOOK TYPE
laas.private_payroll.employment_relationships_inquiry_status_change

雇佣关系查询返回结果：

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 警告
要在沙盒环境中模拟失败，请使用以数字 2 开头的 CPF 进行查询。
:::
---

## 2 - 工人数据查询： {#consulta-de-dados}
工人数据查询是一项异步操作。发送请求后，QI Tech 将在后台处理查询，并在完成后通过 webhook 返回结果。

Webhook 将发送到您环境中配置的 URL。

执行查询有两种可能的情况：

1. 使用在雇佣关系查询中先前发送的[授权条款](#authorization_term)
2. 随查询一起发送新的[授权条款](#authorization_term)

两种情况都需要提供在雇佣关系查询中获取的工人工号。

**POST**
/private_payroll/balance_inquiry

### Request

**情况 1：** 使用先前发送的[授权条款](#authorization_term)进行工人数据查询。
**Request Body**

```json
{
    "document_number": "<CPF FUNCIONÁRIO>",
    "registration_number": "<NÚMERO DE MATRÍCULA>",
    "employer_document_number": "<CNPJ EMPREGADOR>"
}
```

**情况 2：** 发送[授权条款](#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 注意
有法定代理人的情况下，必须在 **"legal_representative_document_number"** 字段填写法定代理人的 CPF，**"signer"** 对象中的数据也应填写法定代理人的信息。
:::

### Response

STATUS
**202** (Accepted)

**Response Body**

```json
{
    "balance_inquiry_key": "<Balance Inquiry Key>",
    "balance_inquiry_status": "pending_inquiry"
}
```

:::info
**balance_inquiry_status** 枚举的可能值列在[工人数据查询状态](#status-das-consultas)部分。
:::

### Webhooks

WEBHOOK TYPE
laas.private_payroll.balance_inquiry_status_change

工人数据查询返回结果：

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"
            }
        ]
    }
}
```

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"
      }
    }
}
```

雇佣关系被锁定时的返回结果：

STATUS
completed

**Webhook Body**

```json
{
    "document_number": "99999999999",
    "registration_number": "abc",
    "employer_document_number": "12345678",
    "block_type": "blocked_by_the_worker",
    "blocked_at": "2025-12-11T10:00:00Z",
    "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 警告
要在沙盒环境中模拟失败，请使用以数字 2 开头的 CPF 进行查询。
:::

## 附件
---
### authorization_term 对象详情 {#authorization_term}
| 字段                   | 必填性 | 描述                          | 
|-------------------------|-----------------|------------------------------------|
|Name                     |必填      |借款人姓名                     |
|Email                    |可选         |借款人邮箱                    |
|Phone                    |可选         |借款人电话                 |
|Document_number          |必填      |借款人 CPF                      |
|Authentication_type      |必填      |必须为 "opt-in"           |
|Timestamp                |必填      |借款人接受的时间戳，必须为以下格式：2025-08-04T23:45:30Z|
|Ip_address               |必填      |用户会话 IP，可以是 IPv4（如：192.168.0.1）或 IPv6（如：2001:0db8:85a3:0000:0000:8a2e:0370:7334）|
|Fingerprint              |必填      |可发送有助于增强接受稳健性并有助于可追溯性的额外证据对象，虽为必填，但可发送空对象|
|Session_id               |必填      |用户会话的内部标识键，最小长度 10，最大长度 50|

**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"
}
```
### 数据查询 webhook 详情
| 字段                         | 描述                          | 
|-------------------------      |------------------------------------|
|document_number                |借款人文件号                 |
|registration_number            |雇佣关系工号                    |
|employer_document_number       |雇主文件号（CNPJ 仅前 8 位数字）|
|name                           |借款人姓名                      |
|gender                         |借款人性别           |
|birth_date                     |借款人出生日期|
|worker_category_code           |符合 eSocial 网站标准的[工人类别](https://www.gov.br/esocial/pt-br/documentacao-tecnica/manuais/leiautes-esocial-v-1-1-beta/tabelas.html#01)|
|eligible                       |雇佣关系是否有资格发行薪资抵押信贷|
|available_margin_amount        |薪资抵押额度|
|base_margin_amount             |工资|
|total_due_amount               |借款人未偿余额|
|admission_date                 |入职日期|
|termination_date               |离职日期|
|termination_reason_code        |符合 eSocial 网站标准的[离职原因](https://www.gov.br/esocial/pt-br/documentacao-tecnica/leiautes-esocial-versao-1-3-nt-03-2025/tabelas.html#19)|
|political_exposition           |借款人政治曝光程度，可能的枚举值请见[政治曝光](#exposição-política)表|
|employer_name                  |雇主名称|
|mother_name                    |借款人母亲姓名|
|nationality.description        |借款人国籍|
|nationality.code               |根据 ISO 3166 第 1 部分数字标准的国籍代码|
|occupation.description         |借款人根据巴西职业分类（CBO）的职业|
|occupation.code                |CBO 2002 代码|
|economic_activity.description  |雇主根据国家经济活动分类（CNAE）的经济活动|
|economic_activity.code         |CNAE 子类别 2.3 代码|
|ineligibility_reason           |雇佣关系不符合资格的原因|
|employer_activity_start_date   |雇主活动开始日期|
|legacy_loans                   |由金融机构报告的有效贷款列表，字段详情请参阅 [legacy_loans 对象详情](#legacy_loans)表|
|alerts                         |包含雇佣关系休假历史和离职通知的列表，字段详情请参阅 [alerts 对象详情](#alerts)表|
|suspended_loans_count          |已暂停贷款数量|
|block_type                     |雇佣关系锁定类型，可能的枚举值请见[工资锁定](#block)表|
|blocked_at                     |雇佣关系锁定日期|

### 政治曝光 {#exposicao-politica}

ENUMERADOR
political_exposition

| 枚举值    | 描述                                                                 |
| ------------- | ------------------------------------------------------------------------- |
| not_exposed   | 无政治曝光                                          |
| level_1       | 政治曝光级别 1                                      |
| level_2       | 政治曝光级别 2                                      |
| not_informed  | 无政治曝光信息                              |

### alerts 对象详情 {#alerts}
| 字段                         | 描述                          | 
|-------------------------      |------------------------------------|
|alert_type                     |提醒类型，可能的枚举值请见[提醒类型](#alert_type)表|
|reference_date                 |事件参考日期|
|event_id                       |事件标识符|
|leave_reason_code              |符合 eSocial 网站标准的[休假原因](https://www.gov.br/esocial/pt-br/documentacao-tecnica/leiautes-esocial-versao-1-3-nt-03-2025/tabelas.html#18)|
|leave_start_date               |休假开始日期|
|leave_end_date                 |休假结束日期|
|termination_reason_code        |符合 eSocial 网站标准的[离职原因](https://www.gov.br/esocial/pt-br/documentacao-tecnica/leiautes-esocial-versao-1-3-nt-03-2025/tabelas.html#19)|
|termination_date               |雇佣关系离职日期|
|notice_period_start_date       |预告期开始日期|
|notice_period_end_date         |预告期结束日期|

### 提醒类型 {#alert_type}
ENUMERADOR
alert_type
| 枚举值                    | 描述                         | 
|-------------------------      |-----------------------------------|
|leave                          |休假                        |
|termination                    |离职预告                       |

### legacy_loans 对象详情 {#legacy_loans}
| 字段                         | 描述                          | 
|-------------------------      |------------------------------------|
|loan_amount                    |放款金额|
|monthly_cet                    |月 CET|
|monthly_rate                   |月利率|
|contract_type                  |合同类型，可能的枚举值请见[遗留合同类型](#contract_type)表|
|contract_number                |合同编号|
|contract_end_date              |合同结束日期|
|paid_installments              |已支付分期数|
|total_installments             |总分期数|
|installment_amount             |分期金额|
|contract_start_date            |合同开始日期|
|outstanding_balance            |未偿余额|
|last_update_timestamp          |最后更新日期|
|financial_institution_code     |报告贷款的金融机构代码|

### 遗留合同类型 {#contract_type}
ENUMERADOR
contract_type
| 枚举值                    | 描述                         | 
|-------------------------      |-----------------------------------|
|unsecured_non_consigned_loan   |无担保非薪资抵押贷款|
|loan_with_payroll_deductions   |含工资单扣款的贷款|

### 雇佣关系查询和工人数据查询状态 {#status-das-consultas}

ENUMERADOR
employment_relationships_inquiry_status

ENUMERADOR
balance_inquiry_status

| 状态                | 描述                                                                     |
| --------------------- | ----------------------------------------------------------------------------- |
| pending_authorization | 授权数据已发送，待处理。    |
| pending_inquiry       | 查询已授权，待处理。                      |
| completed             | 查询已成功完成。                                         |
| failed                | 查询失败。                                                            |

### 雇佣关系锁定 {#block}

ENUMERADOR
block_type

| 枚举值            | 描述                                                                 |
| -------------         | ------------------------------------------------------------------------- |
| no_block              | 雇佣关系未锁定                                          |
| blocked_by_the_worker | 雇佣关系被员工锁定                                      |

---

# 私人薪资抵押贷款手册 - 遗留合同

URL: /zh-Hans/documentation/manual_consignado_privado/manual_contratos_legados

:::caution 开发中的 API 
该 API 仍处于开发阶段，因此本手册可能会有所更改。
:::

遗留合同的再融资通过创建新债务来实现，遗留合同数据在 *collateral_data* 字段中提供。

要验证已录入系统的遗留合同，需查询遗留贷款。
如未找到，请联系支持团队申请录入。

由于私人薪资抵押贷款的业务规则，目前工人只能有一份活跃合同。
因此，如果工人有多份遗留合同，只有其中一份可以进行再融资。
同样，如果工人有一份活跃合同，则无法为其创建再融资。

债务创建和签署流程与创建新信贷相同。区别在于债务的核批是在合同签署后由系统自动完成的，无需人工审批，也无需查询 SCR。

## 1 - 遗留贷款查询

**GET**
/private_payroll/legacy_contracts

### Query Parameters

| 参数       | 类型    | 必填 | 描述                          | 默认值 |
|-----------------|---------|-------------|------------------------------------|----|
| page            | integer | 否         | 要返回的页码   | 1            |
| page_size       | integer | 否         | 每页记录数 | 100          |
| document_number | string  | 否         | 无标点符号的客户 CPF       | N/A          |

:::info
分页从 1 开始，因此第一页是第 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

分页响应由合同数组（*data*）和分页对象（*pagination*）组成。

#### 合同列表

*data* 数组中各项的描述：

| 参数            | 类型    | 必填 | 描述                              |
|----------------------|---------|-------------|----------------------------------------|
| legacy_contract_key  | string  | 是         | 遗留合同唯一标识符 |
| document_number      | string  | 是         | 客户 CPF                         |
| contract_number      | string  | 是         | 合同编号                     |
| legacy_contract_data | object  | 是         | 遗留合同数据               |
| status               | string  | 是         | 合同状态                     |

#### 遗留合同数据

*legacy_contract_data* 对象中的数据：

| 参数                | 类型    | 必填 | 描述                   |
|--------------------------|---------|-------------|------------------------------|
| cet                      | decimal | 是         | 总有效成本         |
| due_balance              | decimal | 是         | 未偿余额               |
| total_amount             | decimal | 是         | 合同总金额     |
| contract_type            | string  | 是         | 合同类型            |
| interest_rate            | decimal | 是         | 利率               |
| period_amount            | decimal | 是         | 分期金额            |
| contract_end_date        | string  | 是         | 合同结束日期 |
| number_of_periods        | integer | 是         | 总分期数    |
| contract_start_date      | string  | 是         | 合同开始日期  |
| registration_number      | string  | 是         | 员工工号    |
| number_of_paid_periods   | integer | 是         | 已付分期数    |
| employer_document_number | string  | 是         | 雇主 CNPJ          |

#### 分页数据

*pagination* 对象中的数据：

| 参数     | 类型    | 必填 | 描述                          |
|---------------|---------|-------------|------------------------------------|
| current_page  | integer | 是         | 当前页                       |
| next_page     | integer | 是         | 下一页                     |
| rows_per_page | integer | 是         | 每页记录数 |
| total_pages   | integer | 是         | 总页数                   |
| total_rows    | integer | 是         | 总记录数                 |

## 2 - 删除遗留合同

通过以下端点删除遗留合同：

**DELETE**
/private_payroll/legacy_contract/ contract_number

其中路径参数 "contract_number" 应为要删除的合同编号，以字符串格式提供。

### Response

成功时将返回以下响应：

STATUS
**200** OK

若指向的遗留合同不存在，将返回 NotFound 错误，错误代码为 "PRP000079"。

STATUS
**404** NOT FOUND

## 3 - 创建再融资

遗留合同的再融资通过创建类似新信贷的债务来实现，区别在于遗留合同数据需在 *collateral_data* 字段中提供，如下例所示：

**POST**
/debt

```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
如有法定代理人，应在 *related_parties* 字段中提供，如新信贷示例所示。

```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"
                }
            }
        ]
    }
} 
```

---

# 私人薪资抵押贷款手册 - 新信贷

URL: /zh-Hans/documentation/manual_consignado_privado/manual_credito_novo

:::info 导航
- [工人查询](/documentation/manual_consignado_privado/manual_consultas_trabalhador)（上一页）
- [外部签署](/documentation/manual_consignado_privado/manual_assinatura_externa)（下一页）
:::

:::danger 注意！
QI Tech 的 webhook 不应进行严格映射。
返回的 webhook payload 中可能包含额外字段。
:::

:::info 重新发送 Webhook
您可以按照文档中的详细说明查询和重新发送 webhook：[重新发送 Webhook](/documentation/notificacoes/reenvio_de_notificacoes)。
:::

## 1 - 债务模拟：
CRÉDITO NOVO

### Request

**POST**
/debt_simulation

**分期金额**

```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"
        }
    ]
}
```

**放款金额**

```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"
        }
    ]
}
```

:::info
上述请求中进行了 2 项模拟。第一项固定了客户的分期金额（放款金额可变），第二项固定了放款金额（分期金额可变）。
::: 

### 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 - 操作发行：
"collateral_data" 对象中的 "registration_number" 字段是指雇佣关系的工号。该字段在雇佣关系查询中返回。

CRÉDITO NOVO

### Request

**POST**
/debt

**无法定代理人**

```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
        }
    ]
}
```

**有法定代理人**

```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
        }
    ]
}
```

### 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"
                }
            }
        ]
    }
} 
```

### Installments 对象

| 字段 | 描述 |
|-------|-----------|
| additional_costs | 额外费用 |
| business_due_date | 工作日到期日 |
| calendar_days | 自然日数 |
| due_date | 到期日 |
| due_interest | 到期利息 |
| due_principal | 到期本金 |
| fine_amount | 到期罚款 |
| has_interest | 表示到期是否有利息 |
| installment_number | 分期编号 |
| installment_status | 分期状态 |
| installment_type | 分期类型 |
| post_fixed_amount | 利息后分期金额 |
| pre_fixed_amount | 利息前分期金额 |
| principal_amortization_amount | 分期本金摊销金额 |
| tax_amount | 分期利息金额 |
| total_amount | 分期总金额 |
| workdays | 工作日数 |

### Prefixed Interest Rate 对象

| 字段 | 描述 |
|-------|-----------|
| monthly_rate | 月利率 |
| daily_rate | 日利率 |
| annual_rate | 年利率 |
| interest_base | 利率计算基础 |

### Webhooks

若操作未在最后一个放款日期选项前完成签署或核批，合作伙伴将收到操作取消通知 webhook：

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>"
    }
}
```

### Data 对象

| 字段 | 描述 |
|-------|-----------|
| cancel_reason | 取消原因 |
| cancel_reason_enumerator | 取消原因枚举值 |

## 3 - 文件收集与操作正式化
发送合同补充数据是操作正式化的必要条件。

我们强烈建议通过 **QI Sign** 进行操作文件的收集和签署，这是我们内嵌防欺诈技术的专有电子签名平台。

由于 QI Sign 是内部开发并与我们的系统完全集成的，使用 QI Sign 可确保：

- **正式化流程完全自动化**：签署后操作自动进入下一阶段。
- **文件自动上传**：所有签署文件直接发送到信贷系统，无需人工干预。
- **安全性和可追溯性**：流程安全、可审计，符合监管要求。

这种方法减少了操作错误，加快了信贷发放，并显著改善了客户体验。

### 为什么使用 QI Sign？

- **手机远程签名**，具备符合法规的人脸识别功能。
- **RESTful API 集成**，便于签署流程自动化。
- **法律安全性**，具有不同级别的身份验证。
- **可扩展解决方案**，按需为需要数字化流程的企业服务。

:::info QI Sign
**QI Sign** 是 QI Tech 的电子签名平台，内部开发以满足信贷市场的监管要求。
支持**人脸生物特征识别**和**文件自动发送**，确保正式化过程中的安全性、敏捷性和可追溯性。

如需更多信息或申请报价，请联系我们的商务团队：
📧 **comercial@qitech.com.br**
📞 **(11) 2339-4763**
:::
### 外部正式化
若操作正式化不通过 QI Sign 进行，正式化流程请参阅[外部正式化手册](./manual_assinatura_externa.md)。

## Webhooks

合同签署后，合作伙伴将收到有关合同签署情况的 webhook，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"
}
```

### Signers 对象

| 字段 | 描述 |
|-------|-----------|
| id | 签署人 ID |
| images | 签署人图像 |

### Images 对象

| 字段 | 描述 |
|-------|-----------|
| face_image_url | 签署人面部图像 URL |
| document_back_url | 签署人证件背面图像 URL |
| document_front_url | 签署人证件正面图像 URL |
| document_back_template | 签署人证件背面模板 |
| document_front_template | 签署人证件正面模板 |

### Biometry 对象

| 字段 | 描述 |
|-------|-----------|
| face_validation | 签署人面部验证（true 或 false） |
| face_validation.score | 签署人面部评分（0 到 100） |
| face_validation.available | 签署人面部验证可用性（true 或 false） |
| face_validation.provider | 签署人面部验证提供商（qitech 或 external） |
| fraud_base_flag | 基础欺诈标志（true 或 false） |

### Document 对象

| 字段 | 描述 |
|-------|-----------|
| template | 证件模板（cnh_front, cnh_back, rg_front, rg_back） |
| face_match_score | 签署人面部评分（0 到 100） |

### Liveness 对象

| 字段 | 描述 |
|-------|-----------|
| result | 活体检测结果（live 或 spoof） |

### Signer Data 对象

| 字段 | 描述 |
|-------|-----------|
| name | 签署人姓名 |
| email | 签署人邮箱 |
| phone | 签署人电话 |

### Address 对象

| 字段 | 描述 |
|-------|-----------|
| uf | 州/省份 |
| city | 城市 |
| number | 门牌号 |
| street | 街道 |
| complement | 补充信息 |
| postal_code | 邮政编码 |
| neighborhood | 社区/街区 |

## 枚举值

### 预留状态 {#status-da-reserva}

ENUMERADOR
reservation_status

| 状态                        | 描述                                                                 |
| ----------------------------- | ------------------------------------------------------------------------- |
| pending_auction               | 预留已创建，等待拍卖开始（接收提案请求）。                                |
| pending_reservation           | 预留已创建，待核批。                                      |
| pending_documents_submission  | 预留已核批，待文件提交。 |
| reserved                      | 预留核批成功。核批流程完成。 |
| canceled                      | 若提交了无效文件，预留将被取消。 |
| pending_suspension            | 预留已核批，已请求暂停。 |
| suspended                     | 预留已成功暂停。 |
| settled                       | 预留已成功清算。 |
| pending_deletion              | 预留已核批，已请求删除。 |
| deleted                       | 预留已成功删除。 |

---

# 私人薪资抵押贷款手册 - 主动发行流程

URL: /zh-Hans/documentation/manual_consignado_privado/manual_detalhamento_fluxo_ativo

:::info 下一步
- [工人查询](/documentation/manual_consignado_privado/manual_consultas_trabalhador)
:::

## 流程步骤

### 1. 工人查询
执行[工人查询](./manual_consultas_trabalhador.md)，以验证雇佣关系的信贷发行资格、可用薪资抵押额度及其他信息。

### 2. 操作发行与正式化

执行信贷操作的模拟和创建调用，并指导借款人完成 CCB 签署流程。

### 3. 核批

跟踪 DATAPREV 对核批尝试的返回结果。

### 4. 放款

跟踪操作放款情况并处理可能的放款失败。

---

# 私人薪资抵押贷款手册 - 拍卖发行流程

URL: /zh-Hans/documentation/manual_consignado_privado/manual_detalhamento_fluxo_leilao

## 流程步骤

### 1. 贷款申请过滤器配置
配置贷款申请接收过滤器，以选择目标受众。

### 2. 接收贷款申请 webhook 并发送提案

接收经过滤的贷款申请 webhook，模拟所需的信贷条件并向内部拍卖提交提案。

### 3. 跟踪内部拍卖提案状态和信贷操作签署情况

等待内部拍卖更新和操作签署的 webhook。

### 4. 授权核批并跟踪放款

授权核批并处理可能的核批和放款失败。

---

# 私人薪资抵押贷款手册 - 内部拍卖

URL: /zh-Hans/documentation/manual_consignado_privado/manual_leilao_interno

## 1. 拍卖开始

配置贷款申请过滤器后，合作伙伴将开始收到通知这些申请的 webhook。

```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"
                }
            ]
        },
    }
}
```

每个贷款申请经历两个阶段：内部拍卖和 CTPS 应用中的拍卖。内部拍卖在收到 webhook 时开始，在 *inclusion_limit_datetime* 字段指定的时间戳结束。在此期间，接收所有合作伙伴的提案并根据利率进行排名。内部拍卖结束后，条件最优的提案将发送至借款人的 CTPS，所有金融机构的提案都会在那里呈现。
如果在内部拍卖结束前没有提案发送，则在 *inclusion_limit_datetime* 之后发送的第一个提案将自动获胜并发送至 CTPS。

## 2. 信贷提案  

### Request

ENDPOINT - `/private_payroll_auction/issuer_proposal_request/{issuer_proposal_request_key}/auction_proposal`
MÉTODO - `POST`

Request Body: 在拍卖中加入 AuctionProposal

**Disbursed Amount & Interest Rate**

```json
{
    "request_control_key" : "111e7ed3-4080-4cae-a853-8e12812817ea",
    "disbursed_issue_amount": 15000,
    "monthly_interest_rate": 0.02,
    "number_of_installments": 48,
    "purchaser_document_number": "01272247000120",
    "days_to_expiration": 10,
    "rebates": [
        {
            "fee_type": "spread",
            "amount_type": "percentage",
            "amount": 4.17
        }
    ]
}
```

**Installment Value & Interest Rate**

```json
{
    "request_control_key" : "111e7ed3-4080-4cae-a853-8e12812817ea",
    "installment_face_value": 1000,
    "monthly_interest_rate": 0.02,
    "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: 已创建提案

```json
{
  "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": 15.46,
            "annual_cet": 0.0603,
            "monthly_cet": 0.0049,
            "issue_amount": 1015.46,
            "annual_interest_rate": 0.0180272568,
            "monthly_interest_rate": 0.00149,
            "disbursed_issue_amount": 1000.0,
            "installment_face_value": 102.25,
            "number_of_installments" : 48
        },
        "monthly_interest_rate": null,
        "disbursed_issue_amount": 15000,
        "installment_face_value": 102.25,
        "number_of_installments": 48
  },
}
```

STATUS - 400 (Rejected)

Response Body: Bad Request

```json
{
  "title": "Bad Request",
  "description": "Calculated installment face value is greater than consigned credit balance",
  "translation": "Schema Invalido",
  "extra_fields": {},
  "code": "QIT000001"
}
```

## 3. 拍卖结束

内部拍卖结束时，发送 webhook 通知合作伙伴是否赢得拍卖。若获胜，信贷操作被创建，QI Sign 正式化链接发送至借款人 CTPS 应用。从此刻起，操作跟踪应通过 *credit_operation_key* 进行。

WEBHOOK_TYPE laas.private_payroll_auction.end_of_auction

```json
{
    "key": "250cfea5-99dc-4c80-be3e-2231350cf9a2", // 此键等同于 auction_proposal_key
    "data": {
        "auction_proposal_key": "250cfea5-99dc-4c80-be3e-2231350cf9a2",
        "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"
    },
    "status": "won",
    "event_datetime": "2025-03-20T14:48:43Z",
    "webhook_type": "laas.private_payroll_auction.end_of_auction"
}
```

失败提案的信贷操作键将以 null 值返回。

:::info 注意
签署链接不会在生产环境中发送，仅在沙盒环境中发送，以便能够模拟借款人的签署操作。
:::

## 附件

### IssuerProposalRequest 对象定义

| 名称            | 类型   | 描述                                                                          |
| --------------- | ------ | ---------------------------------------------------------------------------------- |
| issuer_proposal_request_key | string  | **提案申请**的唯一标识符 |
| issuer_proposal_request_data| object  | 描述**提案申请**数据的对象 |
| status                      | string  | **提案申请**的状态（`ongoing`, `finished`, `expired`）|

### IssuerProposalRequestData 对象定义

| 名称            | 类型   | 描述                                                                          |
| --------------- | ------ | ---------------------------------------------------------------------------------- |
| name                        |string | 借款人全名 |
| document_number             |string | 借款人 CPF |
| birth_date                  |string | 借款人出生日期，格式 `YYYY-MM-DD` |
| disbursed_amount            |float  | 借款人申请的放款金额 |
| number_of_installments      |integer| 借款人申请的分期数 |
| consigned_credit_balance    |float  | 借款人可用薪资抵押额度余额 |
| admission_date              |string | 工人在当前职位的入职日期，格式 `YYYY-MM-DD` |
| issuer_registration_code    |string | 员工 eSocial 工号|
| employer_document_number    |string | 雇主 CNPJ |
| eligible                    |boolean| 有资格为 True，无资格为 False|
| employer_document_type      |string | CNPJ 或 CPF|
|alerts                         |包含雇佣关系休假历史和离职通知的列表，字段详情请参阅 [alerts 对象详情](#alerts)表|

### alerts 对象详情 {#alerts}
| 字段                         | 描述                          | 
|-------------------------      |------------------------------------|
|alert_type                     |提醒类型，可能的枚举值请见[提醒类型](#alert_type)表|
|reference_date                 |事件参考日期|
|event_id                       |事件标识符|
|leave_reason_code              |符合 eSocial 网站标准的[休假原因](https://www.gov.br/esocial/pt-br/documentacao-tecnica/leiautes-esocial-versao-1-3-nt-03-2025/tabelas.html#18)|
|leave_start_date               |休假开始日期|
|leave_end_date                 |休假结束日期|
|termination_reason_code        |符合 eSocial 网站标准的[离职原因](https://www.gov.br/esocial/pt-br/documentacao-tecnica/leiautes-esocial-versao-1-3-nt-03-2025/tabelas.html#19)|
|termination_date               |雇佣关系离职日期|
|notice_period_start_date       |预告期开始日期|
|notice_period_end_date         |预告期结束日期|

### 提醒类型 {#alert_type}
ENUMERADOR
alert_type
| 枚举值                    | 描述                         | 
|-------------------------      |-----------------------------------|
|leave                          |休假                        |
|termination                    |离职预告                       |

### 提案申请状态详情

| 状态  | 描述                                                                 |
| ------- | ------------------------------------------------------------------------- |
| ongoing | **提案申请**进行中，拍卖仍在进行。  |
| finished| **提案申请**已完成，拍卖结束，已接受并纳入一个发送的**提案**。 |
| expired | **提案申请**已过期，拍卖结束，未及时纳入任何**提案**。  |

### 拍卖提案请求详情

| 字段         | 类型    | 描述                                                                                                       | 必填 |
|---------------|---------|-----------------------------------------------------------------------------------------------------------------|-------------|
| `issuer_proposal_request_key` | string  | **IssuerProposalRequest** 的唯一标识键，uuid v4 格式。                          | 是         |
| `auction_proposal_key` | string  | **AuctionProposal** 的唯一标识键，uuid v4 格式。                                | 是         |
| `disbursed_issue_amount`| float   | **提案**的预期放款金额。                                                               | 是         |
| `purchaser_document_number` | integer | 债务购买方 CNPJ | 是         
| `monthly_interest_rate` | float   | **提案**的月利率，范围 0 到 1（分别对应 0% 到 100%）。                        | 否         |
| `installment_face_value`| float   | **提案**的预期分期金额。                                                                  | 否         |
| `number_of_installments`| integer | 提案的分期数。                                                                                 | 是         |
| `days_to_expiration`| integer | 提案到期前的天数。如不包含此键，提案有效期为 7 天 | 否         |
| `rebates` | list    | 信贷操作的返点列表。使用与主动发行（/debt）相同的标准                        | 否         |

---

# 私人薪资抵押贷款手册 - 再融资

URL: /zh-Hans/documentation/manual_consignado_privado/manual_refinanciamento

:::info 
本手册专门记录 QI Tech 已在工人信贷中发起的操作的再融资，或已转入工人信贷的遗留操作的再融资。
:::

:::danger 放款选项
与新信贷相同，再融资操作的放款选项将限于同一结算周期。此外，一旦再融资操作完成薪资抵押，必须在同一日期放款，否则将被永久取消并需要重新正式化。
:::

:::warning 结算日期
为保障借款人的撤销权，再融资操作仅在债务放款日期后 7 个工作日结算。
:::

要模拟和发行再融资债务，须在 payload 中以以下格式添加将被再融资的债务的键：

REFINANCIAMENTO

```json 
  "refinanced_credit_operations": [
    {
      "operation_key": "c63f3a4c-0cde-4be7-8bb2-00ffc564cddb"
    }
  ]
```

## 1 - 债务模拟：

### 请求

**POST**
/debt_simulation

```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"
        }
    ]
}
```

### 响应

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 - 操作发行：

REFINANCIAMENTO

### 请求

**POST**
/debt

```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"
        }
    ]
}
```

### 响应

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"
                }
            }
        ]
    }
} 
```

## 附录
### 相关字段

| 字段                                             | 描述                                                                                                                                                                                                        |
|---------------------------------                  |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **issue_amount**                                  | 发行金额                                                                                                                            |
| **disbursed_issue_amount**                        | 总放款金额（找零 + 结清款项）                                                                                |
| **final_disbursement_amount**                     | 找零金额                                                                            |
| **refinanced_credit_operations.due_balance**      | 再融资债务的未偿余额 |

---

# 保险

URL: /zh-Hans/documentation/manual_consignado_privado/manual_seguro

**本手册介绍与保险合同挂钩的薪资抵押信贷发行流程的各个步骤。这些操作的放款将存入发行流程中为借款人开立的内部账户。从该账户中，将对信贷放款进行拆分，将部分放款金额转入借款人在 QI 以外的外部账户，其余部分用于支付保险费。**

## 1. BC PROTEGE+ 查询

与信贷操作挂钩的保险发行流程将涉及在 QI 为借款人开立内部账户。要开立账户，借款人不得在 [BC PROTEGE+](https://www.bcb.gov.br/meubc/bcprotege) 名单中。
可通过以下端点使用 API 进行查询。若借款人在该名单中，保险将在正式化后被取消。

GET /bacen_protect/validate/ [document_number]

Response Body

**账户开立已批准**

```json
{
    "permission_result": "approved"
}
```

**账户开立已拒绝**

```json
{
    "permission_result": "rejected"
}
```

:::info 沙盒测试
以 9 开头的 CPF 将返回权限被拒绝。
:::

## 2. 债务模拟与发行

要模拟和发行与保险发行挂钩的债务，须在 financial 对象的折扣列表中添加一个对象。

```json title='Objeto Rebate'
{
  "rebates": [
    {
      "fee_type": "insurance_premium_qi",
      "description": "insurance_premium_description"
    }
  ]
}
```

### 模拟 payload 示例

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"
          }
        ]
    }
}
```

### 发行 payload 示例

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
        }
    ]
}
```

:::warning 产品选择
_description_ 枚举器用于定义将发行的保险产品类型，这直接影响保险费金额和保障范围。请咨询运营团队了解您的集成应使用哪些枚举器。
:::

## 3. 正式化

在 QI Sign 的债务正式化流程中，将显示若干屏幕以确保借款人了解并同意购买保险。

:::warning OPT-OUT
借款人可能决定放弃购买保险，仅签署信贷合同。在这种情况下，原本用于保险费的金额也将存入借款人账户。
:::

在信贷正式化 webhook 的同时，将发送一个事件，告知保险在正式化流程中是否被接受或拒绝。

WEBHOOK_TYPE insurance_premium.status_change

Webhook Body

**已正式化（含保险）的操作**

```json
{
  "data": {
    "credit_operation_key": "5ae2c008-44c1-4435-bbfa-094a4b11d962",
    "payment_account": {
      "account_number": "1234567",
      "account_digit": "8",
      "account_branch": "0001",
      "owner_document_number": "98765432100",
      "ispb": "32402502"
    }
  },
  "event_datetime": "2023-03-03 22:39:39",
  "key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
  "status": "accepted",
  "webhook_type": "insurance_premium.status_change"
}
```

**已正式化（不含保险）的操作**

```json
{
  "data": {
    "credit_operation_key": "5ae2c008-44c1-4435-bbfa-094a4b11d962",
    "rejection_reason": "" 
  },
  "event_datetime": "2023-03-03 22:39:39",
  "key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
  "status": "rejected",
  "webhook_type": "insurance_premium.status_change"
}
```

:::info 拒绝原因
拒绝原因的可能枚举值可在[拒绝原因](#rejection_reason)表中查询。
:::
:::info 账户开立
债务与保险正式化完成后，将开立内部账户，信贷操作的全额放款将存入该账户，并从中进行拆分——部分金额转给借款人，其余部分用于支付保险费。账户的银行信息在 *payment_account* 对象中提供。
:::

## 4. 内部放款

完成薪资抵押步骤后，操作将放款至正式化后开立的内部账户，并发送以下放款 webhook。

WEBHOOK_TYPE debt
STATUS disbursed

payload

```json
{
    "key": "53f23b3be-2bc8-46fb-943f-5d4532eecf5e",
    "data": {
      "installments": [
        {
          "due_date": "2026-01-24",
          "total_amount": 4645.64,
          "installment_key": "80f8f098-0232-4543-1e6b-50f970bac6e2",
          "pre_fixed_amount": 74.31,
          "installment_number": 1,
          "principal_amortization_amount": 4571.33
        }
      ],
      "ted_receipt_list": [],
    "status": "disbursed",
    "webhook_type": "debt",
    "event_datetime": "2025-12-26 18:56:45"
  }
}
```

## 5. 放款后操作

要跟踪向借款人外部账户转账的成功或失败，须监控以下 webhook。

WEBHOOK_TYPE after_disbursement_action_update

Webhook Body

**放款错误**

```json
{
  "data": [
    {
      "action_error": {
        "description": "An error occurred while sending pix_transfer bfea6188-879c-46e5-b842-d1e934d44775 to SPI",
        "error_code": "disbursing_error"
      },
      "status": "error",
      "action_data": {
        "pix_transfer_type": "manual",
        "target_account": {
          "document_number": "98765432100",
          "financial_institution_code": 1,
          "ispb": 0,
          "name": "Nome Tomador",
          "financial_institution_code_number": "341",
          "account_branch": "9123",
          "account_digit": "0",
          "account_number": "9999"
        },
        "transaction_amount": 100
      },
      "action_key": "fcec7529-3598-4ce2-9448-4c24d1cb9df0",
      "execution_data": null,
      "action_type": "pix"
    }
  ],
  "event_datetime": "2025-12-30 13:25:08",
  "key": "e7a73248-d737-4cb4-ad07-6d303fc4b96c",
  "webhook_type": "debt_actions"
}
```

**放款成功**

```json
{
  "key": "29294369-6d9e-4700-a11b-172f80e51802",
  "webhook_type": "debt_actions",
  "data": [
    {
      "action_type": "pix",
      "action_data": {
        "transaction_amount": 100,
        "target_account": {
          "ispb": 0,
          "name": "Nome Tomador",
          "account_number": "20001",
          "account_branch": "0897",
          "document_number": "98765432100",
          "account_digit": "0",
          "financial_institution_code_number": "341",
          "financial_institution_code": 1
        },
        "pix_transfer_type": "manual"
      },
      "action_key": "7b529465-fc0e-4a16-ab3b-259699632896",
      "execution_data": {
        "original_transfer_data": null,
        "pdf_encoded_string": "comprovante do desembolso em base64",
        "chargeback_unexpected_reason": null,
        "transacted_at": "2025-12-30 12:59:46",
        "source_subtype_translation_ptbr": "Desembolso PIX da Operação",
        "receiver_conciliation_id": null,
        "transaction_key": "6c039a31-0d4c-452f-b9aa-9a389ae354d3",
        "pix_message": "",
        "transaction_amount": 100,
        "end_to_end_id": "E32402502202512301259djWNilNGhHj",
        "translated_chargeback_reason": null,
        "transacted_at_br": "2025-12-30 09:59:46",
        "origin_key": "a9d91b03-6a4b-4833-bc89-69afcb07ee75",
        "chargeback_reason": null,
        "transacted_at_formatted": "30/12/2025, 12:59:46",
        "source_account": {
          "owner_name": "Nome Tomador",
          "account_number": "7617846",
          "account_branch": "0001",
          "owner_document_number_formatted": "987.654.321-00",
          "owner_document_number": "98765432100",
          "account_digit": "5",
          "financial_institution_compe_number": "329",
          "financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A."
        },
        "target_account": {
          "target_pix_key": null,
          "owner_document_number_formatted": "***.654.***-**",
          "owner_document_number": "***654*****",
          "owner_name": "Nome Tomador",
          "account_type_str": "Conta Corrente",
          "account_type": "checking_account",
          "account_number": "020001",
          "ispb_number": "60701190",
          "is_internal": false,
          "account_branch": "0897",
          "financial_institution_compe_number": 341,
          "account_digit": "0",
          "financial_institution_name": "ITAÚ UNIBANCO S.A."
        },
        "chargeback_returned_amount": null,
        "transaction_amount_formatted": "R$ 100,00",
        "source_subtype": "operation_pix_disbursement",
        "pix_transfer_type": "manual",
        "transacted_at_br_formatted": "30/12/2025, 09:59:46"
      },
      "action_error": null,
      "status": "done"
    }
  ],
  "event_datetime": "2025-12-30 13:00:58"
}
```

### 放款后操作重新呈报

如发生失败，须使用以下端点重新呈报放款后操作。

ENDPOINT /baas/action/ ACTION-KEY
MÉTODO PATCH

payload

**通过手动 pix 重新呈报的 Payload**

```json
{
  "pix_transfer_type": "manual",
  "target_account": {
      "name": "Nome Tomador",
      "account_digit": "0",
      "account_branch": "9123",
      "account_number": "9999",
      "document_number": "98765432100",
      "financial_institution_code_number": "341"
  }
}
```
**通过 pix 密钥重新呈报的 Payload**

```json
{
  "pix_transfer_type": "key",
  "pix_key": "98765432100" 
}
```

**通过 TED 重新呈报的 Payload**

```json
{
  "action_type": "funds_transfer",
  "destination": {
      "account_branch": "3181",
      "account_digit": "6",
      "account_number": "26284",
      "document_number": "48127500211248",
      "financial_institution_code_number": "001",
      "name": "JOANA LUCILIA GOMES DA SILVA",
      "transfer_type": "ted",
  },
}
```

:::info 沙盒测试
要模拟放款后操作失败，可使用账户号 11581339 进行手动 pix，或使用密钥 b9380607-dac6-4e17-8ca7-eb761e3aa1dc 进行 pix 密钥。

payload

**手动 pix 模拟 payload 示例**

```json
	"disbursement_bank_accounts": [{
			"document_number": "77564023082",
			"name": "Jorge Augusto Salgado Salhani",
			"pix_transfer_type": "manual",
			"bank_code": "001",
			"branch_number": "0001",
			"account_number": "11581339",
			"account_digit": "0",
			"percentage_receivable": 100
		}]
```
**pix 密钥模拟 payload 示例**

```json
	"disbursement_bank_accounts": [{
			"document_number": "61295118092",
			"name": "Mock Person Name",
			"pix_key": "b9380607-dac6-4e17-8ca7-eb761e3aa1dc",
			"pix_transfer_type": "key"
		}]
```

要模拟 TED 转账拒绝，须使用以下端点：

ENDPOINT /mock/ted/ted_refusal
MÉTODO POST

Request Body

```json
{
  "transaction_key": "\<Chave unitária da transação\>"
}
```

:::

## 6. 放款后操作失败时的取消

如果内部放款已完成，放款后操作失败且未重新呈报，须使用以下端点进行取消。

ENDPOINT /debt/ DEBT-KEY /reversal
MÉTODO PUT

payload
```json
{}
```

## 7. 保险发行

放款后操作成功后，将进行保险费转账和保险发行。要跟踪保险状态，须监控以下 webhook。

WEBHOOK_TYPE insurance_premium.status_change

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"
}
```

**保险已取消**

```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 保险取消
要查看保险取消的可能原因，请参阅[取消原因](#cancel-insurance)表。
:::
:::danger 必须向借款人发送保单凭据
保险发行后，必须将保单 PDF 发送给借款人。可通过**[文件查询](../upload_de_documentos/consulta_documents)**使用保险发行 webhook 中提供的 *insurance_policy_document_key* 查询该文件。
:::
:::info 沙盒测试
要测试保险取消，可使用以下端点：

POST /mock/insurance_premium/ [INSURANCE-PREMIUM-KEY] /cancel

:::
### 保险查询

要主动查询保险信息，可使用以下端点。

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
}
```

## 流程图

```mermaid
stateDiagram-v2
    [*] --> Consulta_BC_PROTEGE+ : Lead inicial
    Consulta_BC_PROTEGE+ --> Emissão_sem_seguro : permission_result = rejected
    Consulta_BC_PROTEGE+ --> Emissão_com_seguro : permission_result = approved
    Emissão_com_seguro --> QI_Sign : Formalização
    QI_Sign --> Emissão_sem_seguro : Tomador recusou seguro
    QI_Sign --> Abertura_de_conta : Tomador concordou com seguro
    Abertura_de_conta --> Averbação
    Averbação --> Desembolso_em_conta_interna
    Desembolso_em_conta_interna --> Split_por_ações_pós_desembolso  
```

## 附录
---

### 拒绝原因 {#rejection_reason}

| 枚举器                                | 描述                                             |
|------------------------------------------ |-------------------------------------------------------|
| **insurance_rejected**                    | 保险被拒绝                                      |
| **bacen_protect**                         | bc protege+                                           |

### 取消原因 {#cancel-insurance}

| 枚举器                                | 描述                                              |
|------------------------------------------ |-------------------------------------------------------|
| reversed_operation                        | 操作已撤销，保险已取消 |
| cover_limit_amount_exceeded               | 仅保险被取消。某项保障限额被超出，无法发行保险 |
| insurance_premium_cancel                  | 仅保险被取消。借款人直接向保险公司申请了取消 |

---

# 私人薪资抵押贷款手册 - 遗留合同归档

URL: /zh-Hans/documentation/manual_consignado_privado/manual_tombamento_legado

:::caution 开发中的 API 
该 API 仍处于开发阶段，因此本手册可能会有所更改。
:::

## 1 - 前提条件

要将合同归档到新的薪资抵押贷款模式，该合同必须已事先报告且状态为 "active"。如果仍有尚未报告或状态不正确的遗留合同，请立即通知运营团队。[遗留合同手册](./manual_contratos_legados)中有查询已报告合同的文档。

此外，根据 DATAPREV 的规定，借款人必须仍在合同所记录的同一雇佣关系中工作。可以不发送授权条款，通过以下调用查询借款人的有效雇佣关系（将验证同一 CPF 是否存在有效遗留合同）：

## 2 - 归档雇佣关系查询：
雇佣关系查询是异步操作。发送请求后，QI Tech 将在后台处理查询，并在完成后通过 webhook 返回结果。
Webhook 将发送到您环境中配置的 URL。

要查询拥有有效遗留合同的借款人的有效雇佣关系，应使用与发行流程相同的端点，并在请求 payload 根节点中添加额外字段。

**POST**
/private_payroll/employment_relationships_inquiry

### 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

雇佣关系查询返回结果：

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 - 遗留合同归档调用：

:::warning 注意！
借款人姓名、雇主文件号和雇佣关系工号字段必须填写雇佣关系查询中返回的数据，否则 DATAPREV 将在核批时返回错误。
:::
:::warning 注意！
如果原始操作中收取了注册费（TAC），该费用的金额将根据发行金额与放款金额和 IOF 金额之和的差值计算得出。
:::
TOMBAMENTO

### Request

**POST**
/credit_operation/external

**外部发行的遗留合同**

```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 注意！
所有分期都必须报告，即使已经支付。分期状态必须按照以下描述填写。
:::

#### 状态描述

| 状态 | 描述 |
|--------|-----------|
| `opened` | 待还分期 |
| `paid_partial` | 部分支付的分期 |
| `paid` | 已全额支付的分期 |
| `overdue` | 到期未付的分期 |

### 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
        },
        ...
    ]
}
```

---

# 手册 - 私人薪资抵押贷款：雇佣关系

URL: /zh-Hans/documentation/manual_consignado_privado/manual_vinculos_empregaticios

:::caution 开发中的 API  
该 API 仍处于开发阶段，因此本手册可能会有所更改。
:::

---

## 1. 文档目的
本手册介绍**私人薪资抵押贷款**中信贷借款人雇佣关系监控的运作方式，以及如何通过 **webhook** 通知更新。

---

## 2. 背景与动机
私人薪资抵押贷款合同依赖于有效的雇佣关系来维持预留的有效性。
因此，**Dataprev** 每日被查询以识别这些关系的变化（如：劳动合同终止或新雇佣关系创建）。

当有变化时，系统会向合作伙伴发送**自动 webhook**，告知预留的新状态或检测到的新雇佣关系。

---

### 🔄 流程概述

1. 系统每日查询 Dataprev 中的雇佣关系。
2. 若有效雇佣关系终止，合同将被更新并通知合作伙伴。
3. 若工人建立新的雇佣关系，系统会自动识别并尝试**重新关联预留**。
4. 在每个阶段都会发送 webhook，以便合作伙伴保持其系统更新。

---

## 3. Webhook - 雇佣关系终止

### 📅 发送时机
当工人**失去雇佣关系**且薪资抵押合同与该关系关联时。

### 🔍 发生的情况
预留状态更新为 **"terminated"**，表示预留因雇佣关系终止而结束。
合作伙伴应相应更新其系统。

### 💡 Payload 示例
```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",
            "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": "new_credit",
    }
}
```

## 4. Webhook - 新雇佣关系

### 📅 发送时机

当系统识别到持有有效合同的工人在之前终止后建立了新的雇佣关系。

### 🔍 发生的情况

系统向合作伙伴发送新雇佣关系的完整数据通知。

### 💡 Payload 示例

```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
        }
    }
}
```

## 5. Webhook - 预留重新关联到新雇佣关系

### 📅 发送时机

系统检测到新的雇佣关系后，自动将已终止的预留重新关联时。

### 🔍 发生的情况

仅当新保证金充足时才会重新关联。

分期付款不会重新计算，债务也不会重新配置。

生成新的预留键（reservation_key），保持相同的 credit_operation_key 或 external_key。

合作伙伴将收到两个 webhook，一个通知新预留状态为 "reserved"，另一个通知旧预留状态变为 "transferred"。这样可以追踪重新关联、已终止和已转移的合同。

### 💡 Payload 示例 - 重新关联的合同

```json
{
    "status": "reserved",
    "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": "reserved",
            "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",
    }
}
```

### 💡 Payload 示例 - 已转移的合同

```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",
            "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": "new_credit",
            "reservation_status": "transferred",
    }
}
```

### 注意：

external_key 或 credit_operation_key 及大多数数据保持不变。

## 6. 最佳实践

每日监控您的 webhook，以确保与 LaaS 系统同步。

以幂等方式处理状态更新（即避免对同一事件进行两次处理）。

保存 webhook 接收日志以供审计之用。

---

# Manual Consignado Privado - Portabilidade: Consultas Prévias

URL: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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/manual_vinculos_empregaticios).

---

# Manual Consignado Privado - Portabilidade: Formalização

URL: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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"`. |

---

# FGTS 授权查询手册

URL: /zh-Hans/documentation/manual_consulta_de_autorizacao_FGTS/

:::info 另请参阅
- [FGTS 发起](/documentation/manual_FGTS/manual_fgts)
:::

## 1. 受益人授权查询

授权查询允许验证受益人是否已授权在 FGTS 中进行批注和余额查询（与特定 CPF 关联），以便与 Caixa Econômica Federal 进行操作。

### 查询特征

- **同步请求**：立即返回结果
- **业务规则**：仅当受益人与最后一个有效绑定的合作伙伴查询时才会成功
- **例外**：如果受益人在过去 90 天内未进行任何操作，则查询将返回所有合作伙伴的数据

### 要求

进行查询时，需要提供受益人的 **CPF**。

### 接口端点

**GET**
`/fgts_issuer_auth_manager/issuer/{CPF}`

**路径参数**

| 字段            | 类型   | 描述                          | 必填 | 格式                       |
|-----------------|--------|-------------------------------|------|--------------------------|
| document_number | string | 受益人的 CPF 号码             | 是   | 11 位数字，无标点符号      |

### 成功响应

STATUS
**200** (OK)

**响应示例**

**已授权：**
```json
{
    "authorization_limit_date": "2026-01-01",
    "last_checked_at": "2025-10-01",
    "status": "authorized"
}
```

**未授权：**
```json
{
    "authorization_limit_date": null,
    "last_checked_at": "2025-10-01",
    "status": "unauthorized"
}
```

### 错误响应

STATUS
**404** (Not Found)

当 CPF 未在数据库中找到时返回。

## 状态参考

| 状态           | 描述                |
|----------------|---------------------|
| `authorized`   | 受益人已获授权      |
| `unauthorized` | 受益人未获授权      |

## 响应字段

| 字段                       | 类型   | 描述                                   |
|----------------------------|--------|----------------------------------------|
| `authorization_limit_date` | string | 授权到期日期（格式：YYYY-MM-DD）       |
| `last_checked_at`          | string | 授权最后更新日期                       |
| `status`                   | string | 当前授权状态                           |

---

# Consulta - Emissão Crédito Clean

URL: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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\"}"
}
```

# O que é a Análise de Risco (LAaS)?

:::caution Versão preliminar
Esta é a primeira versão desta página conceitual e pode sofrer pequenas alterações.
:::

Antes de entrar nos campos, tipos e códigos de erro, vale entender **por que** a Análise de Risco existe e **o que** ela resolve. Esta seção é o "mapa mental" — a documentação técnica completa (com todos os campos de request/response) está logo abaixo, em **[Análise de Risco](#análise-de-risco)**.

## A ideia em uma frase

A Análise de Risco (também chamada de **LAaS**, *Lending Analysis as a Service*) é um único endpoint que **combina, em uma só chamada, as verificações necessárias para decidir se um tomador pode ou não receber crédito** — onboarding, análise de crédito e, quando aplicável, consulta de margem consignável — e entrega o resultado consolidado no final, sem que você precise orquestrar cada verificação separadamente.

## A analogia: um check-in de aeroporto

Pense no pedido de crédito como um passageiro tentando embarcar em um voo.

- **Você (cliente/parceiro) é o balcão de check-in.** É você quem recebe o passageiro (o tomador) e decide encaminhá-lo para o processo de embarque, enviando um único `POST /lending_analysis`.
- **A consulta prévia (`inquiry`) é a checagem de documentos antes mesmo da fila de segurança.** Se o produto é consignado privado, antes de qualquer outra coisa a QI Tech confere se o passageiro tem "passagem válida" — isto é, se ele tem margem consignável disponível com o empregador informado. Sem isso, não faz sentido nem seguir para as próximas etapas.
- **As etapas (`analysis_steps`) são os controles de segurança e imigração, em sequência.** Cada etapa é um checkpoint independente, executado **na ordem**:
  1. **Onboarding** (`onboarding_natural_person`) — o controle de identidade: "esse documento é válido? essa pessoa é quem diz ser?"
  2. **Análise de crédito** (`credit_analysis_natural_person`) — o controle de "bagagem": "essa pessoa pode embarcar com esse valor de crédito, dentro de que limites de taxa e parcelas?"

  Se um checkpoint reprova, o passageiro não segue para o próximo — a análise já fecha como `reproved` ali mesmo. E nem todo passageiro passa pelos dois controles: quais etapas se aplicam a cada tomador dependem da configuração do produto (`AnalysisConfiguration`) do lado da QI Tech — em alguns casos só o onboarding é executado.
- **A resposta síncrona é o seu tíquete de fila.** Ao enviar o `POST`, você recebe na hora um `lending_analysis_key` e o status `pending_inquiry` — como dizer "seu passageiro está na fila, aqui está o número dele". Ainda não é a decisão final.
- **O webhook é o alto-falante do aeroporto anunciando o embarque.** Quando todos os checkpoints terminam, a QI Tech **avisa você via webhook** (`laas.lending_analysis.status_change`) com o resultado consolidado — aprovado, reprovado ou falha técnica. Você não precisa ficar checando a toda hora (embora possa, via polling — ver abaixo).
- **A consulta de elegibilidade é a pergunta "esse passageiro já tem um embarque em andamento?"** Antes de criar uma nova análise, você pode perguntar via `GET /lending_analysis` se aquele CPF já possui uma análise ativa para aquele produto — evitando embarcar o mesmo passageiro duas vezes.

## Da analogia para a API

| No aeroporto | Na API |
|---|---|
| Balcão de check-in recebe o passageiro | `POST /lending_analysis` |
| Passageiro já tem embarque em andamento? | `GET /lending_analysis` (elegibilidade) |
| Número da fila | `lending_analysis_key` |
| Checagem prévia de documento de viagem | `inquiries` (ex: consulta de margem consignável) |
| Controle de identidade | Etapa `onboarding_natural_person` |
| Controle de bagagem/valor | Etapa `credit_analysis_natural_person` |
| Painel de embarque, consultável a qualquer momento | `GET /lending_analysis/{lending_analysis_key}` |
| Anúncio de embarque no alto-falante | Webhook `laas.lending_analysis.status_change` |

## O fluxo, passo a passo

1. Você envia `POST /lending_analysis` com o CPF do tomador, o tipo de produto (`lending_analysis_type`) e os dados necessários (ex: `private_payroll` para consignado privado, `authorization_term` com a autorização assinada pelo tomador).
2. A API responde **na hora** (síncrono) com `analysis_status: pending_inquiry` e o `lending_analysis_key`. Essa resposta só confirma que a análise foi criada — **não é o resultado**.
3. Nos bastidores (assíncrono), a QI Tech:
   - roda a consulta prévia necessária (ex: margem consignável), se o produto exigir;
   - executa a etapa de **onboarding**;
   - se aprovada e a etapa estiver configurada para o produto, executa a etapa de **análise de crédito**;
   - se qualquer etapa reprovar ou falhar, a análise encerra ali com esse resultado.
4. Ao chegar a um status final (`approved`, `reproved` ou `failed`), a QI Tech dispara o **webhook** `laas.lending_analysis.status_change` para a URL configurada no seu ambiente, com o detalhe de cada etapa e das consultas realizadas.
5. Alternativamente, você pode consultar o andamento a qualquer momento com `GET /lending_analysis/{lending_analysis_key}` (bom para telas de acompanhamento ou para reconciliar caso um webhook se perca).

:::tip Dica
Pense duas vezes antes de fazer polling agressivo no `GET` de status — o webhook já te avisa assim que o resultado sai. Use o `GET` para reconciliação, não como substituto do webhook.
:::

## Os "vistos" (status) explicados sem juridiquês

| Status da análise | O que realmente significa |
|---|---|
| `pending_inquiry` | "Chegou na fila, ainda estamos conferindo os documentos de viagem." Estado inicial. |
| `pending_analysis` | "Passou na checagem prévia, está andando pelos controles de segurança (onboarding / análise de crédito)." |
| `approved` | "Embarque liberado." Estado final. |
| `reproved` | "Não pode embarcar desta vez." Estado final — algum checkpoint reprovou. |
| `failed` | "Aeroporto com problema técnico" — falha da própria análise (indisponibilidade de algum provedor, erro técnico), não uma reprovação de mérito. Estado final. |

Cada etapa individual (`onboarding_natural_person`, `credit_analysis_natural_person`) tem seu próprio mini-status (`approved`/`reproved`/`failed`) e um `reason` explicando o motivo — é o "aqui está exatamente por que barramos você nesse checkpoint".

## Perguntas rápidas

**Preciso me preocupar com a ordem das etapas, ou com quais etapas vão rodar?**
Não — tanto a ordem (`onboarding` antes de `credit_analysis`) quanto quais etapas se aplicam a cada tomador são definidas pela configuração do produto (`AnalysisConfiguration`) do lado da QI Tech. Você só recebe o resultado consolidado, já na ordem certa.

**E se o passageiro já tiver um embarque em andamento?**
Use a consulta de elegibilidade (`GET /lending_analysis`) antes de criar uma nova análise para o mesmo CPF/produto, evitando duplicidade.

**O que acontece se eu perder o webhook?**
Consulte o status a qualquer momento com `GET /lending_analysis/{lending_analysis_key}` — ele traz o mesmo resultado, incluindo o histórico completo de eventos, etapas e consultas.

## Para ir além

- **[Análise de Risco](#análise-de-risco)** — campos de request/response, objetos, enumeradores e casos de teste em sandbox.
- **[Catálogo de Erros LaaS](../emissao_de_divida/catalogo_de_erros_laas)** — todos os códigos de erro possíveis.
- **[Webhooks — Notificações BaaS e LaaS](../webhooks/notificacoes_baas_e_laas)** — como configurar e validar o recebimento dos webhooks.

# 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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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)

2.  POST /account  (conta interna QI p/ debt_purchase)

3.  POST /document/document_batch      → criar envelope de assinatura

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.
:::

---

## 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 |

**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"` |

:::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"`) |

---

# Webhooks

URL: /zh-Hans/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).

---

# FGTS 周年提款手册

URL: /zh-Hans/documentation/manual_FGTS/

:::info 另请参阅
- [FGTS 授权查询](/documentation/manual_consulta_de_autorizacao_FGTS/manual_consulta_de_autorizacao_FGTS)
:::

:::danger 注意！
QI Tech 的 webhook 不应以严格方式映射。
返回的 webhook payload 中可能会包含额外字段。
:::

:::info Webhook 重发
您可以按照文档中的详细说明查询和重发 webhook：[Webhook 重发](/documentation/notificacoes/reenvio_de_notificacoes)。
:::

本手册描述了 FGTS 周年提款预付款操作（以 FGTS 周年提款作为担保的个人信用）的查询、模拟、发行、放款及其他操作步骤。

## 前提条件
1 - 借款人必须选择 FGTS 周年提款模式；

2 - 借款人必须授权 QI 在 CEF（联邦储蓄银行）应用程序中查询其 FGTS 余额；

 

## 1 - 查询可用余额
**1.1.** 执行余额查询：

        **Request**

ENDPOINT /baas/v2/fgts/available_balance
MÉTODO POST

Request Body

```json
{
	"document_number": "06568225037"
}

```

| 字段 | 类型 | 必填 | 描述 |
|-|-|-|-|
| `document_number` | string(11) | 是 | 借款人 CPF |

在 Playground 中测试

余额查询成功后，主要返回活跃合同数量以及受益人的 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"
	}]
}

```

| 字段 | 类型 | 描述 |
|-|-|-|
| `available_balance_key` | string (UUID) | 余额查询的唯一键 |
| `document_number` | string(11) | 借款人 CPF |
| `status` | string | 查询状态（`pending`、`success`、`failed`） |
| `status_events[]` | array | 状态事件历史 |
| `status_events[].event_datetime` | string (datetime) | 事件日期/时间 |
| `status_events[].status` | string | 事件状态 |

 

**1.1.1.** 若在 CEF 中余额查询成功，合作伙伴将收到以下 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
			}
		]
	}
}
```

| 字段 | 类型 | 描述 |
|-|-|-|
| `webhook_type` | string | Webhook 类型（`available_balance`） |
| `event_datetime` | string (datetime) | 事件日期/时间 |
| `key` | string (UUID) | 余额查询键 |
| `status` | string | 状态（`success`） |
| `data.reference_date` | string (date) | 余额参考日期 |
| `data.periods[]` | array | 可用提款期 |
| `data.periods[].due_date` | string (date) | 提款到期日 |
| `data.periods[].amount` | number | 该期可提款金额 |

**1.1.2.** 若在 CEF 中余额查询失败，合作伙伴将收到以下 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"
	}
}
```

| 字段 | 类型 | 描述 |
|-|-|-|
| `webhook_type` | string | Webhook 类型（`available_balance`） |
| `event_datetime` | string (datetime) | 事件日期/时间 |
| `key` | string (UUID) | 余额查询键 |
| `status` | string | 状态（`failed`） |
| `data.error_description` | string | 错误描述 |
| `data.error_enumerator` | string | 错误枚举值 |

**1.1.3.** 若因操作日期不被允许而导致在 CEF 中余额查询失败，合作伙伴将在 "data" 字段中收到包含额外信息的 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": "Not permitted action on current date",
		"error_enumerator": "on_locked_date_range",
		"error_data": {
			"operation_not_allowed_until_date": "2023-01-03"
		}
	}
}
```

| 字段 | 类型 | 描述 |
|-|-|-|
| `webhook_type` | string | Webhook 类型（`available_balance`） |
| `event_datetime` | string (datetime) | 事件日期/时间 |
| `key` | string (UUID) | 余额查询键 |
| `status` | string | 状态（`failed`） |
| `data.error_description` | string | 错误描述 |
| `data.error_enumerator` | string | 错误枚举值 |
| `data.error_data.operation_not_allowed_until_date` | string (date) | 操作被允许的起始日期 |

余额查询失败的可能枚举值列于**第 2 节**。

**1.2.** 查询特定余额查询的结果：

可以使用创建时返回的键（`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
}
```

| 字段 | 类型 | 描述 |
|-|-|-|
| `available_balance_key` | string (UUID) | 余额查询的唯一键 |
| `document_number` | string(11) | 借款人 CPF |
| `status` | string | 查询状态（`success`、`pending`、`failed`） |
| `reference_date` | string (date) | 余额参考日期 |
| `number_of_active_contracts` | integer | FGTS 活跃合同数量 |
| `has_unavailable_balance` | boolean | 是否存在不可用余额 |
| `periods[]` | array | 可用提款期 |
| `periods[].due_date` | string (date) | 提款到期日 |
| `periods[].amount` | number | 可提款金额 |
| `has_succeeded` | boolean | 查询是否成功 |
| `error_message` | string/null | 错误信息（如有） |

在 Playground 中测试

**1.3.** 取消待处理的余额查询：

如需取消状态为 `pending` 的余额查询，请使用以下端点。

        **Request**

ENDPOINT /baas/v2/fgts/available_balance/{available_balance_key}
MÉTODO DELETE

        **Response**

STATUS 204 No Content

该端点返回状态码 204，响应体为空。

在 Playground 中测试

## 2 - 在 Sandbox 中模拟余额查询的成功与失败场景：

**2.1.** 对于以 0、1、2、3、4、5、6 和 7 开头的 CPF，将通过 Webhook（**1.1.1.**）返回异步成功响应。

**2.2.** 对于以 8 开头的 CPF，余额查询将返回异步成功响应（**1.1.1.**），但期数为零，可用于测试。

**2.3.** 模拟可用余额查询失败的情况：

所有以 9 开头的 CPF 查询都将通过 webhook（**1.1.2. 或 1.1.3.**）返回异步错误响应，包含以下错误之一。

以下是在 Sandbox 中测试失败案例的模拟，使用借款人文档前几位数字的逻辑：

| 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 - 余额查询的跟踪与处理措施

查询结果应触发合作伙伴的相应操作，以准确引导客户并避免我们队列中积压丢失的请求。

| 枚举值 | error_description | 描述 | QI 处理措施 | 客户处理措施 |
|-----------------------------------|--------------------- |-------------|-----------| -----------|
|ongoing_operation | There's an ongoing operation | 该 CPF 在 Caixa 存在进行中的操作，影响客户余额变更，导致无法提供精确分期金额 | 发送包含对应枚举值和描述的 webhook | 建议等待后重试 |
|unauthorized_institution | Institution isn't authorized by the client | 机构未获客户授权 | 发送包含对应枚举值和描述的 webhook | 引导客户在 FGTS APP 授权"**QI SOCIEDADE DE CREDITO S.A**"操作 FGTS 周年提款预付款 |
|inexistent_anniversary_membership | Client does not have membership for anniversary withdraw on current date | 劳动者在当前日期未加入周年提款模式 | 发送包含对应枚举值和描述的 webhook | 需要引导客户在 FGTS APP 中加入周年提款模式 |
|on_locked_date_range | Not permitted action on current date | 当前日期不允许该操作 | 发送包含对应枚举值和描述的 webhook | 该操作在下月第二个工作日才被允许。需告知客户，目前在任何金融机构均无法完成该操作 |
|anniversary_membership_egress | Client moving away from anniversary membership. It need to be canceled before requesting a reserve | 劳动者申请退出周年提款模式，须先取消后方可申请担保 | 发送包含对应枚举值和描述的 webhook | 告知客户其已申请退出周年提款模式，这将阻止其提前提款 |
|processing_pending_changes | Changes on profile info happened on client's FGTS account | 因周年提款支付流程存在待处理事项，操作不被允许 | 发送包含对应枚举值和描述的 webhook | 引导客户等待问题处理完成 |
|caixa_error | Request wasn't able to process due to an error on CEF | 因 Caixa 返回错误，请求未能完成 | 发送包含对应枚举值和描述的 webhook | 建议等待后重试 |

:::info
在生产环境中，余额查询具有重试机制，取决于 CEF 在查询时返回的错误。
部分错误可以重试，而上述错误为最终错误，不会将查询重新放入异步重试队列。
:::

## 4 - 最大金额模拟
获取余额查询（**第 1 节**）返回的每期（每年）可用提款金额后，即可模拟 FGTS 周年提款预付款操作。

本节展示的模拟方式，显示了借款人预付 100% 可用分期金额时可签约的最大金额。

        **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
        }
}
```

| 字段 | 类型 | 必填 | 描述 |
|-|-|-|-|
| `borrower` | object | 是 | 借款人数据 |
| `borrower.person_type` | string | 是 | 人员类型（`natural`） |
| `borrower.individual_document_number` | string(11) | 是 | 借款人 CPF |
| `financial` | object | 是 | 操作财务数据 |
| `financial.desired_installments[]` | array | 是 | 期望分期（余额查询返回的金额） |
| `financial.desired_installments[].total_amount` | number | 是 | 分期总金额 |
| `financial.desired_installments[].due_date` | string (date) | 是 | 分期到期日 |
| `financial.interest_type` | string | 是 | 利息类型（`pre_price_days`） |
| `financial.disbursement_date` | string (date) | 是 | 放款日期 |
| `financial.fine_configuration` | object | 是 | 罚款配置 |
| `financial.annual_interest_rate` | number | 是 | 年利率 |
| `financial.credit_operation_type` | string | 是 | 信用操作类型（`ccb`） |
| `financial.interest_grace_period` | integer | 是 | 利息宽限期 |
| `financial.number_of_installments` | integer | 是 | 分期数 |
| `financial.principal_grace_period` | integer | 是 | 本金宽限期 |

        **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"
}

```

在 Playground 中测试

## 5 - 目标金额模拟
本节展示的模拟方式，显示了借款人为放款指定金额需要预付的 FGTS 周年提款分期金额。

        **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
	}
}

```

| 字段 | 类型 | 必填 | 描述 |
|-|-|-|-|
| `borrower` | object | 是 | 借款人数据 |
| `borrower.person_type` | string | 是 | 人员类型（`natural`） |
| `borrower.individual_document_number` | string(11) | 是 | 借款人 CPF |
| `target_disbursed_amount` | number | 是 | 期望放款金额 |
| `financial` | object | 是 | 操作财务数据 |
| `financial.desired_installments[]` | array | 是 | 分期（余额查询返回的最大金额） |
| `financial.desired_installments[].total_amount` | number | 是 | 分期总金额 |
| `financial.desired_installments[].due_date` | string (date) | 是 | 分期到期日 |
| `financial.interest_type` | string | 是 | 利息类型（`pre_price_days`） |
| `financial.disbursement_date` | string (date) | 是 | 放款日期 |
| `financial.fine_configuration` | object | 是 | 罚款配置 |
| `financial.annual_interest_rate` | number | 是 | 年利率 |
| `financial.credit_operation_type` | string | 是 | 信用操作类型（`ccb`） |
| `financial.interest_grace_period` | integer | 是 | 利息宽限期 |
| `financial.number_of_installments` | integer | 是 | 分期数 |
| `financial.principal_grace_period` | integer | 是 | 本金宽限期 |

:::info
"***financial.desired_installments***" 对象中分期列表里的分期金额应为查询返回的金额。这些金额将在模拟中用作分期的最大金额。
:::

        **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"
}
```

在 Playground 中测试

## 6 - 创建操作
创建 FGTS 周年提款操作需要在请求中提供 4 个对象：

- borrower：债务借款人（**[Borrower 对象](#objeto-borrower)**）

- collaterals：付款分期信息（FGTS Collateral 对象）

- financial：操作财务流数据（FGTS 财务对象），与模拟中提供的对象相同。

- disbursement_bank_account：放款银行账户信息（银行账户对象）

FGTS 周年提款操作合同 PDF 将由 QI 在此时生成并在请求响应中返回。

:::caution 注意 
对于 "***financial.desired_installments***" 对象的分期列表中的分期金额，使用 "***total_amount***" 字段；对于 "***collaterals.collateral_data.periods***" 对象中的分期金额，使用 "***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
    }
}
```

| 字段 | 类型 | 必填 | 描述 |
|-|-|-|-|
| `borrower` | object | 是 | 借款人完整数据 |
| `borrower.person_type` | string | 是 | 人员类型（`natural`） |
| `borrower.name` | string | 是 | 全名 |
| `borrower.mother_name` | string | 是 | 母亲姓名 |
| `borrower.birth_date` | string (date) | 是 | 出生日期 |
| `borrower.individual_document_number` | string(11) | 是 | CPF |
| `borrower.document_identification_number` | string | 是 | 身份证件号码 |
| `borrower.document_identification_type` | string | 是 | 证件类型（`rg`、`cnh` 等） |
| `borrower.document_identification_date` | string (date) | 是 | 证件签发日期 |
| `borrower.document_identification` | string (UUID) | 是 | 证件键（正面） |
| `borrower.document_identification_back` | string (UUID) | 否 | 证件键（背面） |
| `borrower.email` | string | 是 | 借款人电子邮件 |
| `borrower.phone` | object | 是 | 借款人电话 |
| `borrower.address` | object | 是 | 借款人地址 |
| `collaterals[]` | array | 否 | FGTS 担保数据 |
| `collaterals[].collateral_type` | string | 是 | 担保类型（`fgts_balance`） |
| `collaterals[].collateral_data.periods[]` | array | 是 | 提款期 |
| `collaterals[].percentage` | number | 是 | 担保比例 |
| `financial` | object | 是 | 财务数据（与模拟中的对象相同） |
| `financial.desired_installments[]` | array | 是 | 期望分期 |
| `financial.disbursement_start_date` | string (date) | 是 | 放款开始日期 |
| `financial.disbursement_end_date` | string (date) | 是 | 放款结束日期 |
| `financial.monthly_interest_rate` | number | 是 | 月利率 |
| `financial.issue_date` | string (date) | 是 | 签发日期 |
| `disbursement_bank_account` | object | 是 | 放款银行账户 |
| `disbursement_bank_account.ispb_number` | string | 是 | 银行 ISPB |
| `disbursement_bank_account.branch_number` | string | 是 | 支行号码 |
| `disbursement_bank_account.account_number` | string | 是 | 账户号码 |
| `disbursement_bank_account.account_digit` | string | 是 | 账户校验位 |
| `disbursement_bank_account.document_number` | string | 是 | 账户持有人 CPF |
| `disbursement_bank_account.name` | string | 是 | 账户持有人姓名 |

        **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"
}

```
 

在 Playground 中测试

## 7 - 操作正式化
默认情况下，QI Tech 通过 QI Sign 收集签名，合同在发行时发送给签署人。但合作伙伴也可以独立收集签名，并将已签名的文件或签名证据发送给 QI Tech 以继续操作。

**接受的签名类型**

**QI Sign**

通过 QI Sign 签名在 QI Tech 平台上自动进行。一旦创建操作，文件就会通过 QI Sign 发送收集签名，签名完成后操作会自动更改状态，等待放款。

**pdf-signature**

此类型表示通过 "/debt" 发行的 PDF 将被签名，已签名 PDF 的链接将通过 API 4.1 作为认证方式发送。

        **Request**

ENDPOINT /debt/{debt_key}/signed
MÉTODO POST

Request Body

```json
{
    "type": "pdf-signature",
    "path-pdf-signed": "https://www.google.com/"
}
```

| 字段 | 类型 | 必填 | 描述 |
|-|-|-|-|
| `type` | string | 是 | 签名类型（`pdf-signature`） |
| `path-pdf-signed` | string (URL) | 是 | 已签名 PDF 的 URL |

        **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"
}
```

| 字段 | 类型 | 描述 |
|-|-|-|
| `data` | object | 附加数据（签名为空） |
| `event_datetime` | string (datetime) | 事件日期/时间 |
| `key` | string (UUID) | 操作键 |
| `status` | string | 状态（`signature_received`） |
| `webhook_type` | string | Webhook 类型（`debt`） |

**data-signature**

此类型表示通过 "/debt" 发行的 PDF 将通过附加在最后一页的哈希值进行签名。

数据认证可分为 3 种类型：

- **Opt-in**

通过 opt-in 签名意味着客户将通过前端接受合同。

为使此签名有效，必须强制发送某些数据。

        **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"
	}]
}
```

| 字段 | 类型 | 必填 | 描述 |
|-|-|-|-|
| `type` | string | 是 | 签名类型（`data-signature`） |
| `signatures[]` | array | 是 | 签名列表 |
| `signatures[].signed_object.document_key` | string (UUID) | 是 | 文件键 |
| `signatures[].signed_object.document_md5` | string | 是 | 文件 MD5 哈希 |
| `signatures[].signed_object.raw_text` | string | 是 | 合同文本 |
| `signatures[].authenticity.timestamp` | string (datetime) | 是 | 签名时间戳 |
| `signatures[].authenticity.ip_address` | string | 是 | 签署人 IP 地址 |
| `signatures[].authenticity.session_id` | string (UUID) | 否 | 会话 ID |
| `signatures[].authenticity.fingerprint` | object | 否 | 设备数据 |
| `signatures[].signer.name` | string | 是 | 签署人姓名 |
| `signatures[].signer.email` | string | 是 | 签署人电子邮件 |
| `signatures[].signer.phone` | object | 是 | 签署人电话 |
| `signatures[].signer.document_number` | string | 是 | 签署人 CPF |
| `signatures[].authentication_type` | string | 是 | 认证类型（`opt_in`） |

- **Zip**

通过 zip 签名包含发送证明文件，例如录音电话。

        **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"
        }
    ]
}
```

| 字段 | 类型 | 必填 | 描述 |
|-|-|-|-|
| `type` | string | 是 | 签名类型（`data-signature`） |
| `signatures[].signed_object.raw_text` | string | 是 | 合同文本 |
| `signatures[].signed_object.document_key` | string (UUID) | 是 | 文件键 |
| `signatures[].signed_object.document_md5` | string | 是 | 文件 MD5 哈希 |
| `signatures[].authenticity.timestamp` | string (datetime) | 是 | 签名时间戳 |
| `signatures[].authenticity.document_key` | string (UUID) | 是 | 证明文件键（zip） |
| `signatures[].authenticity.document_md5` | string | 是 | 证明文件 MD5 哈希 |
| `signatures[].signer.name` | string | 是 | 签署人姓名 |
| `signatures[].signer.email` | string | 是 | 签署人电子邮件 |
| `signatures[].signer.phone` | object | 是 | 签署人电话 |
| `signatures[].signer.document_number` | string | 是 | 签署人 CPF |
| `signatures[].authentication_type` | string | 是 | 认证类型（`zip`） |

- **Selfie**

通过自拍认证适用于使用 QI Tech CaaS 服务的合作伙伴，通过自拍进行认证验证并生成证明 ID。

        **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"
        }
    ]
}
```

| 字段 | 类型 | 必填 | 描述 |
|-|-|-|-|
| `type` | string | 是 | 签名类型（`data-signature`） |
| `signatures[].signed_object.raw_text` | string | 是 | 合同文本 |
| `signatures[].authenticity.timestamp` | string (datetime) | 是 | 签名时间戳 |
| `signatures[].authenticity.facial_recognition_key` | string (UUID) | 是 | 人脸识别键（CaaS） |
| `signatures[].signer.name` | string | 是 | 签署人姓名 |
| `signatures[].signer.email` | string | 是 | 签署人电子邮件 |
| `signatures[].signer.phone` | object | 是 | 签署人电话 |
| `signatures[].signer.document_number` | string | 是 | 签署人 CPF |
| `signatures[].authentication_type` | string | 是 | 认证类型（`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
所有通过 /debt/\{debt_key\}/signed 端点执行的操作，响应均相同。
:::

在 Playground 中测试

## 8 - 状态机与 Webhook
在我们系统中创建债务后，可能出现以下状态：

| 状态 | 说明 |
| -- | -- |
| waiting_signature | 等待签名 |
| signature_finished | 签名完成 |
| disbursed | 操作已放款（已支付） |
| canceled | 操作已取消 |
| cancel_permanently | 操作已永久取消 |

**8.1. signature_finished：** 通知操作已签名并提供已签名文件的 URL。

        **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（简化版）：** 通知操作已签名的简化 Webhook。

        **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：** 表示资金已发送至客户账户。
还提供付款转账数据以及已执行放款的 PDF 收据。

        **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：** 表示操作取消。这可能是由于付款尝试时银行账户数据不正确、缺少签名、超过放款日期限制或与余额背书相关的问题所致。

:::warning 注意
操作取消并不表示该操作将在 Caixa 中取消背书。若要触发客户余额取消背书请求，必须永久取消该操作。
:::

在此枚举值列表中，您可以找到因背书错误导致操作取消的所有可能原因。

        **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"
}

```

| 字段 | 类型 | 描述 |
|-|-|-|
| `key` | string (UUID) | 操作键 |
| `data.cancel_reason` | string | 取消原因描述 |
| `data.cancel_reason_enumerator` | string | 取消枚举值 |
| `status` | string | 状态（`canceled`） |
| `webhook_type` | string | Webhook 类型（`debt`） |
| `event_datetime` | string (datetime) | 事件日期/时间 |

 
**8.5. 已构成担保：**

        **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"
}
```

| 字段 | 类型 | 描述 |
|-|-|-|
| `key` | string (UUID) | 操作键 |
| `data.collateral_type` | string | 担保类型（`fgts`） |
| `data.collateral_constituted` | boolean | 表示担保是否已构成 |
| `event_time` | string (datetime) | 事件日期/时间 |
| `webhook_type` | string | Webhook 类型（`credit_operation.collateral`） |

 
## 9 - 在 Sandbox 中模拟背书的成功与失败场景：
**9.1.** 对于以 0、1、2 或 3 开头的 CPF，模拟理想场景。

| CPF 开头 | 操作 |
|---|---|
| 0、1、2 或 3 | 操作成功进行至放款 |

**9.2.** 模拟背书失败的情况：

所有以 9 开头的 CPF 背书都会出现错误，有些可以处理，有些会触发重试，还有些是意外错误。

所有以 8 开头的 CPF 背书都会因余额不足而出错。

:::caution 
某些背书错误即使触发了取消 webhook，也可以重试背书。因此，需要
:::
 
### 因背书错误导致取消的 Webhook 枚举值   
| cancel_reason_enumerator | cancel_reason | 描述 | QI 处理措施 |
| -- | -- | -- | -- |
| fgts_invalid_given_period | Given periods date does not match with CEF system | 提供的一个或多个提款预测日期与 Caixa 系统预测日期不符，或发送的分期金额大于可用金额 | 操作取消，不重试背书 |
| fgts_unauthorized_institution | Institution isn't authorized by the client | 机构未获客户授权 | 操作取消并重试背书 |
| fgts_processing_pending_changes | Changes on profile info happened on client's FGTS account | 因客户 FGTS 账户个人信息发生变更，操作不被允许 | 操作取消，不重试背书 |
| fgts_on_locked_date_range | Not permitted action on current date | 当前日期不允许该操作 | 操作取消，在允许的日期重试背书 |
| fgts_insufficient_balance | Available Balance is not sufficient for given periods amount | 劳动者没有足够余额用于信托操作 | 操作取消，不重试背书 |
| fgts_inexistent_anniversary_membership | Client does not have membership for anniversary withdraw on current date | 劳动者在当前日期未加入周年提款模式 | 操作取消，不重试背书 |
| fgts_period_rejected | Reservation period not accepted | Caixa 拒绝协议 | 操作取消，不重试背书 |
| fgts_deletion_request | Deletion request was before the reservation was completed | 取消背书请求在预留完成前提出 | 操作取消，不重试背书 |
| fgts_protocol_removed | Protocol was removed | Caixa 删除协议 | 操作取消，不重试背书 |
| fgts_insufficient_balance_available | The indicated value is not available for contracting | 指定金额不可用于签约 | 操作取消，不重试背书 |
| fgts_insufficient_balance_for_guarantee | Available balance is not sufficient for the required guarantee | 可用余额不足以满足所需担保 | 操作取消，不重试背书 |
| fgts_fgts_accounts_not_found | The informed worker does not have FGTS accounts | 提供的劳动者没有 FGTS 账户 | 操作取消，不重试背书 |

## 10 - 操作重新提交
在某些情况下，操作选择的放款日期可能在合同签署仍有待处理的情况下过期，导致合同被取消。

为了重新启动已取消合同的流程，需要重新计算操作。我们有两种提交方式：更改放款日期或更改放款银行账户数据。

### 10.1 - 更改放款日期：

        **Request**

ENDPOINT /debt/{debt_key}/disbursement_option
MÉTODO PATCH

Request Body

```json
{
    "disbursement_date": "2023-06-30",
    "status": "active"
}
```

| 字段 | 类型 | 必填 | 描述 |
|-|-|-|-|
| `disbursement_date` | string (date) | 是 | 新放款日期 |
| `status` | string | 是 | 期望状态（`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"
}
```

在 Playground 中测试

### 10.2 - 更改银行账户数据：

        **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
	}]
}
```

| 字段 | 类型 | 必填 | 描述 |
|-|-|-|-|
| `disbursement_bank_accounts[]` | array | 是 | 银行账户列表 |
| `disbursement_bank_accounts[].bank_code` | string | 是 | 银行代码 |
| `disbursement_bank_accounts[].branch_number` | string | 是 | 支行号码 |
| `disbursement_bank_accounts[].account_number` | string | 是 | 账户号码 |
| `disbursement_bank_accounts[].account_digit` | string | 是 | 账户校验位 |
| `disbursement_bank_accounts[].account_type` | string | 是 | 账户类型（`checking_account`、`savings_account`） |
| `disbursement_bank_accounts[].document_number` | string | 是 | 持有人 CPF |
| `disbursement_bank_accounts[].name` | string | 是 | 持有人姓名 |
| `disbursement_bank_accounts[].percentage_receivable` | number | 是 | 应收百分比（100） |

        **Response**

STATUS 200

**Response Body**

```json
{}
```

在 Playground 中测试

:::info 
**操作被取消后何时可以重新提交：**

- 如果发送的放款日期已过，而合同签署仍有待处理事项；

- 如果在放款日期前背书未完成；

- 如果操作付款的银行账户数据存在问题；
:::

## 11 - 取消操作
**允许信托机构向 FGTS 运营代理申请取消用作信托操作担保的劳动者周年提款金额的预留**

**注意：只有在操作已被取消后，才能取消背书。**

        **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。 |

        **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"
}
```

所有冲销成功执行后，每天运行一次例程，收集适当金额并发送给基金。

        **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\"}"
}
 ```

在 Playground 中测试

## 12 - 预留状态跟踪与映射
"last_response" 对象包含 QI 在 Caixa 执行的最后一次预留或释放（背书或取消背书）尝试的数据。

"last_response.success.enumerator" 字段将在预留/释放（背书/取消背书）成功完成时返回。

"last_response.errors.enumerator" 字段包含 Caixa 在最后一次预留/释放（背书/取消背书）尝试时返回的错误信息。

"last_response_event_datetime" 字段包含最后一次预留/释放（背书/取消背书）尝试的日期和时间。

在 Playground 中测试

### 12.1 - 成功案例

#### 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"
  }
}
```

| 枚举值 | 描述 | QI 处理措施 | 客户处理措施 |
|------------------------------|------------------------------|  ------------------------------|  ------------------------------|
| `protocol_created` | 协议创建成功 | 开始协议激活阶段 | 等待协议激活 |
| `successfully_reserved` | 协议激活成功，余额已预留 | 发送担保构成 webhook | 等待满足所有放款要求并支付信贷操作款项 |

### 12.2 - 错误案例

        **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"
  }
}
```

| 枚举值 | 描述 | QI 处理措施 | 客户处理措施 |
|--------------------------------------|-----------------------------------------------------------------------------|-------------|-----------|
| `unauthorized_institution` | 机构未获客户授权 | 取消操作，但继续重试背书 | 引导客户在 FGTS APP 授权"**QI SOCIEDADE DE CREDITO S.A**"操作 FGTS 周年提款预付款 |
| `inexistent_anniversary_membership ` | 劳动者在当前日期未加入周年提款模式 | 取消操作，不对客户余额背书（从重试队列中移除） | 需要引导客户在 FGTS APP 中加入周年提款模式 |
| `on_locked_date_range ` | 当前日期不允许该操作 | 仅在操作被允许的日期重试背书 | 该操作在下月第二个工作日才被允许。由于操作在此期间被锁定，建议发送永久取消并告知客户，因为他目前在任何金融机构都无法完成该操作 |
| `insufficient_balance ` | 劳动者没有足够余额用于信托操作 | 取消操作，不对客户余额背书（从重试队列中移除） | 建议减少操作金额，如余额为零则取消操作 |
| `processing_pending_changes ` | 因周年提款支付流程存在待处理事项，操作不被允许 | 取消操作，不对客户余额背书（从重试队列中移除） | 引导客户等待问题处理完成 |
| `invalid_given_period ` | 提供的一个或多个提款预测日期与 Caixa 系统不符，或发送的分期金额大于可用金额 | 建议减少操作金额，如余额为零则取消；取消操作，不对客户余额背书（从重试队列中移除） | 需要重新录入新操作 |
| `operation_in_process` | 协议等待预留 | 重试客户余额背书 | Caixa 每一两天有例程解锁这些预留。因此，需要告知客户预留卡在 Caixa，即将释放 |
| `not_found_operation` | 此状态仅在取消背书过程中的预留时返回 | 将预留发送至删除队列，确保客户没有被我们锁定的余额，然后将预留状态更改为已取消 | 需要重新录入新操作 |
| `anniversary_membership_egress ` | 劳动者申请退出周年提款模式 | 取消操作，不对客户余额背书（从重试队列中移除） | 告知客户其申请退出了周年提款模式，这将阻止其提前提款 |
| `protocol_removed` | Caixa 删除了协议 | 取消操作，不对客户余额背书（从重试队列中移除） | 需要重新录入新操作 |
| `protocol_rejected` | Caixa 拒绝了协议 | 取消操作，不对客户余额背书（从重试队列中移除） | 需要重新录入新操作 |
| `protocol_in_process` | 协议正在 Caixa 处理中 | 重试客户余额背书 | Caixa 每一两天有例程解锁这些预留。因此，需要告知客户预留卡在 Caixa，即将释放 |
| `timeout` | Caixa 返回超时错误 | 重试客户余额背书 | 需要跟踪 Caixa 后续返回并等待客户余额背书。在 Caixa 不稳定期间，此错误属于正常情况 |
| `unexpected_error` | Caixa 返回意外错误 | 重试客户余额背书 | 需要跟踪 Caixa 后续返回并等待客户余额背书 |
| `period_rejected` | Caixa 拒绝了预留期 | 取消操作，不对客户余额背书（从重试队列中移除） | 需要重新录入新操作，以便发送更新的期数 |
| `deletion_request` | 取消背书请求在预留完成前提出 | 取消操作，不对客户余额背书（从重试队列中移除） | 需要重新录入新操作以进行新的背书尝试 |
| `rate_limit_exceeded` | 超过 Caixa 每秒最大请求数 | 重试客户余额背书 | 跟踪 Caixa 后续返回并等待客户余额背书 |
| `misformatted_error ` | Caixa 返回格式错误的错误 | 重试客户余额背书 | 跟踪 Caixa 后续返回并等待客户余额背书 |
| `unlisted_error ` | Caixa 返回了未列出的错误 | 重试客户余额背书 | 跟踪 Caixa 后续返回并等待客户余额背书 |
| `registration_changes_or_debit_transactions ` | 对 FGTS 账户进行了注册更改或借记交易，导致签约流程无法进行 | 重试客户余额背书 | 待处理事项解决后，如仍有放款选项，需要重新提交操作 |
| `fgts_accounts_not_found ` | 提供的劳动者没有 FGTS 账户 | 取消操作，不对客户余额背书（从重试队列中移除） | 待处理付款流程解决后，需要重新录入新操作以进行新的背书尝试 |
| `inexistent_anniversary_membership_on_period` | Caixa 返回了未列出的错误 | 重试客户余额背书 | 跟踪 Caixa 后续返回并等待客户余额背书 |
| `insufficient_balance_available` | 指定金额不可用于签约 | 取消操作，不对客户余额背书（从重试队列中移除） | 建议减少操作金额重新尝试（如有可用余额），或取消操作并重新录入以获取更新余额 |
| `insufficient_balance_for_guarantee` | 可用余额不足以满足所需担保 | 取消操作，不对客户余额背书（从重试队列中移除） | 建议减少操作金额重新尝试（如有可用余额），或取消操作并重新录入以获取更新余额 |

---

# Manual de Garantia Veicular

URL: /zh-Hans/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
:::

---

# 我的 INSS 提案拍卖手册

URL: /zh-Hans/documentation/manual_leilao_meu_inss/

:::danger 注意！
QI Tech 的 webhooks 不应被严格映射。
返回的 webhooks payload 中可能会新增额外字段。
:::

## 简介

### 欢迎使用我的 INSS 提案拍卖 API。

**我的 INSS 提案拍卖**是一项服务，允许查询由受益人创建的*提案申请*，并由受托方提交*提案*，从而为退休人员/养老金领取者提供信贷机会。

该 API 允许在拍卖中创建、更新、查询和取消提案。***愿最佳提案胜出！！！***

### 遇到问题？

如有任何问题，请联系我们的支持团队（suporte@qitech.com.br），我们将尽快回复。

### 环境

我们为客户提供两个环境。API 的基础 URL 为：

- 生产环境 - `https://api-auth.qitech.app/`
- 沙盒环境 - `https://api-auth.sandbox.qitech.app/`

## 仅限 HTTPS

出于安全考虑，与 QI Tech API 的所有通信必须使用 HTTPS。为避免因疏忽或其他原因发起 HTTP 调用，本服务器仅开放端口 443 并使用 TLS 1.2 通信。使用其他协议的调用将被自动拒绝。

## ProposalRequest：信贷提案申请

`ProposalRequest` 是代表受益人发起的**信贷提案申请**的对象。养老金领取者或退休人员若要发起申请，需要有可用余额、具备资格，且其福利处于激活且未被锁定的状态。

当 QI Tech 收到新的**信贷提案申请**时，将向已配置的端点发送 Webhook。

以下是发送的 payload 示例：

```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 注意
以上是提案申请的初始数据。要查看受益人的**所有信息**，需要创建一个**提案**以接受相应的 **ProposalRequest**。其余数据包括 **CPF**、**姓名**、**出生日期**、**福利号码**、**福利类型**等...
:::

## ProposalRequest 对象定义

ProposalRequest 的所有信息交换均使用以下对象定义。在某些情况下，为便于实现并减少各方之间的数据流，部分信息可能会被省略。

| 名称 | 类型 | 描述 |
| --------------- | ------ | ---------------------------------------------------------------------------------- |
| proposal_request_key        | string  | **提案申请**的唯一标识符 |
| proposal_request_data       | object  | 描述**提案申请**数据的对象 |
| status                      | string  | **提案申请**状态（`ongoing`、`finished`、`expired`）|
| expiration_datetime         | string  | **提案申请**的过期日期，格式为 `YYYY-MM-DDTHH:MM:SSZ` |
| inclusion_limit_datetime    | string  | 在拍卖中提交**提案**的截止日期，格式为 `YYYY-MM-DDTHH:MM:SSZ` |

### ProposalRequestData 对象定义

| 名称 | 类型 | 描述 |
| --------------- | ------ | ---------------------------------------------------------------------------------- |
| name                        |string | 受益人全名 |
| state                       |string | 受益人所在州 |
| document_number             |string | 受益人 CPF |
| birth_date                  |string | 受益人出生日期，格式为 `DDMMYYYY` |
| benefit_number              |integer| 退休人员/养老金领取者的福利号码 |
| benefit_status              |string | 描述福利状况的枚举值 |
| assistance_type             |string | 福利**类型**的枚举值 |
| benefit_situation           |string | 描述福利状况的枚举值 |
| max_total_balance           |float  | 该福利种类可承诺的最大金额 |
| used_total_balance          |float  | 已批注贷款、为可携性预留、再融资、变更、RMC 和 RCC 的已承诺总额 |
| requested_disbursed_amount  |float  | 受益人申请的放款金额 |
| number_of_installments      |integer| 受益人申请的分期数 |
| has_legal_representative    |boolean| 是否有法定代表人 |
| has_power_of_attorney       |boolean| 是否有委托代理人 |
| has_entity_representation   |boolean| 是否有代表实体 |
| consigned_credit.balance    |float  | 受益人可用余额 |

### 提案申请状态详细说明

**提案申请**的状态可以是：

| 状态 | 描述 |
| ------- | ------------------------------------------------------------------------- |
| ongoing | **提案申请**进行中，拍卖仍然有效。  |
| finished| **提案申请**已结束，拍卖已关闭，所提交的某个**提案**已被接受并纳入。 |
| expired | **提案申请**已过期，拍卖已在未纳入任何**提案**的情况下关闭。  |

## 发送 Webhook 后查询提案申请

如有需要，仍可重新查询受益人发起的**提案申请**（即使在发送**自动 Webhook** 之后）。使用**提案申请**的 ***ID***（通过自动 Webhook 发送）通过 **API** 进行调用。

:::warning 注意
只有在合作伙伴接受**提案申请**并创建**提案**后，才允许完整查询受益人数据。
:::

ENDPOINT - `/social_security_auction/proposal_request/{proposal_request_key}`
MÉTODO - `GET`

### Path Params

| 字段 | 类型 | 描述 | 字符数 | 必填 |
|---------------|--------|----------------------------------------|------------| ----------- |
| `proposal_request_key` | uuidv4 | **ProposalRequest** 的唯一标识密钥，使用 uuid v4 格式。 | 36         | 是         |

### Response - 部分查询

STATUS - 200

Response Body：ProposalRequest 部分查询

```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：ProposalRequest 完整查询

```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"
}
```

*注：`Response Body` 字段的详细说明在上方 ProposalRequest 对象定义中描述。*

## Proposal：向受益人提交的信贷提案

`Proposal` 是代表受托方向受益人提交的**信贷提案**的对象。为使 QI Tech 针对特定**提案申请**向退休人员/养老金领取者提交新的**提案**，将进行拍卖，最佳信贷报价将被选中推进。

:::warning 注意
每个**提案申请**只接受一个**提案**——仅允许根据合作伙伴的意愿进行修改。
:::

## Proposal 对象定义

**Proposal** 的所有信息交换均使用以下对象定义。在某些情况下，为便于实现并减少各方之间的数据流，部分信息可能会被省略。

| 名称 | 类型 | 描述 |
| --------------------------- | ------- | ---------------------------------------------------------------------------------- |
| proposal_request_key        | string  | **提案申请**的唯一标识符。 |
| request_control_key         | string  | 提交的**提案**的唯一标识密钥，使用 uuid v4 格式。 |
| proposal_data               | object  | 描述合作伙伴发送的**提案**数据的对象。 |
| status                      | string  | **提案**状态（`created`、`bid`、`lost`、`won`、`cancelled`）。|
| cet                         | float   | 为拍卖中**提交**的提案计算的 CET 值（后续计算）。|
| updated_at                  | string  | **提案**提交或更新的日期，格式为 `YYYY-MM-DDTHH:MM:SSZ`。|
| rank_position               | integer | 当前**提案**在其对应**提案申请**的拍卖排名中的位置。|

*注：`proposal_data` 对象的内容由参与者在后续描述的请求中发送的信息组成。*

### 提案状态详细说明

**提案**的状态可以是：

| 状态 | 描述 |
|----------| ------------------------------------------------------------------------- |
| created  | **提案**已创建，但尚未提交到其对应进行中的**提案申请**的拍卖中。  |
| bid      | **提案**已以其条件提交至拍卖——仍可修改。 |
| lost     | **提案**在该**提案申请**的拍卖中落败。拍卖已关闭，未纳入本**提案**。  |
| won      | **提案**赢得了该**提案申请**的拍卖。拍卖已关闭，并纳入了本**提案**。  |
| cancelled| **提案**已被参与者取消。  |

## 接受提案申请并创建提案

要接受受益人创建的**提案申请**并查询其完整数据，请使用通过自动 Webhook 或后续查询获取的**提案申请** ***ID*** 进行 **API** 调用，示例如下：

ENDPOINT - `/social_security_auction/proposal_request/{proposal_request_key}/proposal`
MÉTODO - `POST`

### Path Params

| 字段 | 类型 | 描述 | 字符数 | 必填 |
|---------------|--------|----------------------------------------|------------| ----------- |
| `proposal_request_key` | uuidv4 | **ProposalRequest** 的唯一标识密钥，使用 uuid v4 格式。 | 36         | 是         |

### Response

STATUS - 201 (Created)

Response Body：提案已创建

```json
{"request_control_key": "814e7ed3-4080-4cae-a853-8e12812817ea"}
```

### Response Body Params

| 字段 | 类型 | 描述 | 字符数 | 必填 |
|---------------|--------|----------------------------------------|------------| ----------- |
| `request_control_key` | uuidv4 | 提交的**提案**的唯一标识密钥，使用 uuid v4 格式。 | 36         | 是         |

## 在拍卖中提交提案

要有效地**提交**或**更新**您在**信贷拍卖**中的提案，请使用**提案**的相关数据进行 **API** 调用，示例如下：

ENDPOINT - `/social_security_auction/proposal_request/{proposal_request_key}/proposal/{request_control_key}`
MÉTODO - `PATCH`

Request Body：在拍卖中提交 Proposal

```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 注意
对于 **monthly_interest_rate** 和 **installment_face_value** 字段，请求中只能填写这 2 个字段中的 **1 个**。另一个无需包含在发送的 Payload 中；如果包含，则必须设置为空值。
:::

### Body Params

| 字段 | 类型 | 描述 | 必填 |
|---------------|--------|----------------------------------------|------------|
| `disbursed_issue_amount`| float  | **提案**预期放款金额。                                                           | 是         |
| `monthly_interest_rate` | float  | **提案**月利率，区间为 0 到 1（分别对应 0% 到 100%）。                    | 否         |
| `installment_face_value`| float  | **提案**预期分期金额。                                                              | 否         |
| `number_of_installments`| integer| 提案的分期数。                                                                             | 是         |
| `contacts`              | array  | 将发送给受益人的**提案**联系方式列表                                          | 是         |
| `contacts.contact_type` | string | **提案**中注册的联系渠道类型。可选值为 `email`、`phone` 和 `website`。 | 是         |
| `contacts.contact`      | string | 将发送给受益人的合作伙伴联系方式。                                                  | 是         |
| `expiration_datetime`   | string | 发送给受益人的**提案**过期日期，格式为 `YYYY-MM-DDTHH:MM:SSZ`                | 是         |

### Response

STATUS - 202 (Accepted)

Response Body：提案已创建

```json
{
  "request_control_key": "814e7ed3-4080-4cae-a853-8e12812817ea",
  "status": "bid",
  "rank_position": 2
}
```

### Response Body Params

|         字段         |  类型   | 描述| 
|-----------------------|---------|----------|
| `request_control_key` | string  | 提交的**提案**的唯一标识密钥，使用 uuid v4 格式。 | 
| `status`              | string  | **提案**状态 |
| `rank_position`       | integer | 该提案在其对应**提案申请**的拍卖排名中的位置 |

## 取消提案

如需删除已创建或已提交至拍卖的提案，只需使用**提案**的相关数据进行 **API** 调用：

:::danger 注意！
每个**提案申请**只能创建/提交一个**提案**。鉴于拍卖的动态特性，一旦取消**提案**，将无法撤销，也无法为同一**提案申请**提交新的提案。
:::

ENDPOINT - `/social_security_auction/proposal_request/{proposal_request_key}/proposal/{request_control_key}/cancel`
MÉTODO - `PUT`

| 字段 | 类型 | 描述 | 字符数 | 必填 |
|---------------|--------|----------------------------------------|------------| ----------- |
| `proposal_request_key` | uuidv4 | **ProposalRequest** 的唯一标识密钥，使用 uuid v4 格式。 | 36         | 是         |
| `request_control_key`  | uuidv4 | 提交的**提案**的唯一标识密钥，使用 uuid v4 格式。         | 36         | 是         |

### Response

STATUS - 202 (Accepted)

Response Body：提案已取消

```json
{
  "request_control_key": "814e7ed3-4080-4cae-a853-8e12812817ea",
  "status": "cancelled"
}
```

### Response Body Params

|         字段         |  类型   | 描述| 
|-----------------------|---------|----------|
| `request_control_key` | string  | 提交的**提案**的唯一标识密钥，使用 uuid v4 格式。 | 
| `status`              | string  | **提案**状态 |

## 查询提案

如需查询您的**提案**，只需使用创建提案时返回的 ***ID*** 进行 **API** 调用：

ENDPOINT - `/social_security_auction/proposal/{request_control_key}`
MÉTODO - `GET`

### Path Params

| 字段 | 类型 | 描述 | 字符数 | 必填 |
|---------------|--------|----------------------------------------|------------| ----------- |
| `request_control_key`  | uuidv4 | 提交的**提案**的唯一标识密钥，使用 uuid v4 格式。 | 36         | 是         |

### Response

STATUS - 200

Response Body：查询已提交至拍卖的提案

```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：查询已创建但未提交至拍卖的提案

```json
{
    "proposal_request_key": "94340718-e90b-4641-b34b-7966297e49c4",
    "status": "created",
    "request_control_key": "01a7a1bf-b75b-4526-bbc3-a27e85e14325"
}
```

*注：`Response Body` 中返回字段的详细说明在上方 Proposal 对象定义中描述。*

## HTTP 状态码

签名 API 使用以下 HTTP 返回状态标准，遵循 RFC 7231 ：

| HTTP 状态码 | 含义 | 描述 |
| ----------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400         | Bad Request           | 发送的请求存在格式错误。大多数情况下，我们会在消息正文中返回错误位置的说明。                                 |
| 401         | Unauthorized          | 认证出现问题，请检查 API Key 是否正确以及是否在正确的 header 中，参见<a href='#autenticacao'>认证</a>部分。                  |
| 403         | Forbidden             | 访问的端点为内部使用，该 API Key 无权使用。                                                                                                   |
| 404         | Not Found             | 使用提供的密钥未找到所请求的数据。当请求无效的端点时也会返回此状态。                                       |
| 405         | Method Not Allowed    | 使用的 HTTP 方法不适用于该端点。                                                                                                                    |
| 406         | Not Acceptable        | 请求正文中发送的数据无效。通常意味着发送的数据不是有效的 JSON。                                                  |
| 409         | Conflict              | 请求 ID 与之前已处理的 ID 对应。当向服务器发送重复请求时会返回此状态。                             |
| 500         | Internal Server Error | 处理此请求时出现问题，遇到此错误时，我们的专家将自动收到通知并立即开始分析和解决。 |
| 503         | Service Unavailable   | 您遇到了我们服务器基础设施的计划或非计划中断。                                                                           |

---

# 可携性转出 - 保留证据

URL: /zh-Hans/documentation/manual_portabilidade/evidencias_de_retencao

# 保留证据

:::info 目标
为了有效保留受可携性攻击的合同，**必须**发送证据，以证明：
1. 已与借款人进行了联系；
2. 借款人明确同意保留。
:::

## 1. 证据收集

证据可通过消息（WhatsApp、聊天）、电子邮件或录音电话收集。无论通过哪种渠道，互动必须严格遵循以下针对每种保留原因列出的服务脚本。

### 1.1 有再融资的情况

当通过提供当前合同再融资来进行保留时，使用此脚本。

```text title="脚本 - 有再融资的保留"

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 无再融资的情况
当在保持原始条件、无再融资的情况下进行保留时，使用此脚本。

```text title="脚本 - 无再融资的保留"

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 当客户**未申请**可携性时
当客户表示不认可可携性申请时，使用此脚本。

```text title="脚本 - 不当攻击"

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
```

---

# 可携性 Out

URL: /zh-Hans/documentation/manual_portabilidade/portabilidade_out

:::danger 注意！
QI Tech 的 webhooks 不应被严格映射。
返回的 webhooks payload 中可能会新增额外字段。
:::

:::info 重新发送 Webhooks
您可以按照文档中的详细说明查询和重新发送 webhooks：[重新发送 Webhooks](/documentation/notificacoes/reenvio_de_notificacoes)。
:::

## 1. 收到可携性 out 通知

一旦 QI SCD 通过 CTC（信用转移中心）收到可携性申请，合作伙伴将通过以下 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"
    }
}
```

查阅 [received_portability webhook 详细说明](#received_portability) 表中的字段描述

## 2. 响应可携性攻击

### 2.1. 合同留存

:::warning 重新发送 Webhooks
要留存客户，合作伙伴必须执行**[留存证据](./evidencias_de_retencao)**的**[上传](../upload_de_documentos)**，并在收到攻击事件（_**credit_transfer.received_portability**_）后第 4 个工作日的 18:00 之前将其附加到操作中。
:::

ENDPOINT /credit_transfer/received_portability/ [received_portability_key]
MÉTODO PATCH

在 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 注意
**不接受压缩文件。**
:::

请查阅表格中的请求字段说明

### 2.2 批准可携性 out

如果客户未被留存，合作伙伴必须在收到可携性攻击通知（_**credit_transfer.received_portability**_）后第 4 个工作日的 10:00 之前告知不留存情况。

:::danger 注意
**如果可携性申请在 4 个工作日内未得到响应，QI Tech 将把操作的到期余额返还给提案人（可携性申请人）。**
:::

ENDPOINT /credit_transfer/received_portability/ [received_portability_key]
MÉTODO PATCH

在 Playground 中测试

```json title='Request Body'
{
	"received_portability_status": "accepted_by_creditor"
}
```

## 3. 查询可携性 out 申请

### 3.1. 查询可携性申请

如需验证可能的状态

ENDPOINT /credit_transfer/received_portability/ [received_portability_key]
MÉTODO GET

在 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. 列出可携性申请

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

在 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

以下是流程中可能收到的 webhooks，可查阅[状态机](#state-machine)了解可能的状态变化（`canceled_by_proponent` 状态可从任意非终态达到）

### 4.1. 等待到期余额付款

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. 提案被提案人取消

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. 可携性已清算

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. 可携性未清算

如果提案人未在可携性 out 响应（可携性攻击）中返回的到期余额规定期限内付款，提案将因逾期未付而被取消。

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. 沙盒验证 Mock 接口

:::info 沙盒环境
使用这些端点在沙盒中模拟可携性 out 流程，无需依赖真实的 CTC/STR 事件。
:::

:::danger 重要提示！
请勿在沙盒环境中使用真实的个人数据（CPF、CNPJ 等）。
:::

### 5.1. 模拟收到的可携性

调用此端点后，您将收到 `credit_transfer.received_portability` webhook（如[第 1 节](#1-收到可携性-out-通知)中所述），其数据根据提供的信贷操作计算得出。

ENDPOINT /mock/credit_transfer/received_portability
MÉTODO POST

#### 属性

credit_operation_key
string (UUID)
必填
要转移的信贷操作的密钥。

reference_date
string
必填
可携性的参考日期（格式 `YYYY-MM-DD`）。

ispb_number
string
必填
源机构的 ISPB 号码（最多 8 个字符）。

origin_contract_type
string
可选
源合同类型。允许值：`payroll`、`public_agency`。默认值：`payroll`。

proposal_type
string
可选
提案类型。允许值：`inss`。默认值：`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. 模拟 STR 清算

批准可携性（[第 2.2 节](#22-批准可携性-out)）并收到 `waiting_settlement` webhook（[第 4.1 节](#41-等待到期余额付款)）后，使用此端点模拟通过 STR 的清算或付款拒绝。根据选择的 `event_type`，将触发相应的 webhook（`settled` 或 `canceled_by_creditor`）。

ENDPOINT /mock/credit_transfer/str
MÉTODO POST

#### 属性

proposal_key
string (UUID)
必填
提案的密钥（在 `waiting_settlement` webhook 中返回）。

event_type
string
必填
事件类型。允许值：`settlement`、`payment_rejected`。

source_branch
string
可选
源分行代码。默认值：`"0001"`。

target_branch
string
可选
目标分行代码。默认值：`"0001"`。

provider_ispb
string
可选
提供者 ISPB 号码。默认值：`"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'
{}
```

## 附件
---

### received_portability webhook 详细说明 {#received_portability}
| 字段 | 描述 | 
|-------------------------      |------------------------------------|
|key                            |攻击密钥（received_portability_key）                 |
|webhook_type                   |事件类型                                             |
|received_portability_status    |攻击状态                                           |
|event_datetime                 |事件日期                                             |
|annual_interest_rate           |攻击中提供的利率                                   |
|annual_effective_interest_rate |攻击中提供的 CET                                    |
|number_of_installments         |攻击中提供的分期数                                |
|installment_face_value         |攻击中提供的分期金额                                       |
|phone_number                   |攻击中提供的电话号码                                     |
|address                        |攻击中提供的地址                               |
|due_balance                    |攻击中提供的到期余额|
|due_balance_date               |攻击中提供的到期余额参考日期|
|issuer_name                    |攻击中提供的借款人姓名|
|issuer_document_number         |攻击中提供的借款人文件号码|
|reference_date                 |攻击中提供的信息|
|contract_number                |攻击中提供的合同号|
|origin_credit_operation_key    |信贷操作密钥（DEBT_KEY/CREDIT_OPERATION_KEY）|
|retention_limit_date           |留存截止日期|
|due_balance_limit_date         |告知到期余额的截止日期|
|portability_number             |可携性号码（NU）|
|corban_document_number         |攻击中提供的信息|
|source_ispb_number             |攻击中提供的信息|

### authorization_term 对象详细说明 {#authorization_term}
| 字段 | 必填性 | 描述 | 
|-------------------------    |-----------------                    |------------------------------------|
|received_portability_status  |必填                          |是否释放余额           |
|retention_reason             |留存时必填      |留存原因，请查阅[留存原因](#retention_reason)表中的可能枚举值|
|document_type                |留存时必填      |必须为 "received_portability_retention_proof"|
|documents                    |留存时必填      |留存证据|
|file_type                    |留存时必填      |文档类型，请查阅[文档类型](document_type)表中的可能枚举值|
|document_key                 |留存时必填      |完成[上传](../upload_de_documentos)后返回的文档密钥|
|retention_type               |留存时必填      |留存证据类型，请查阅[留存类型](#retention_type)表中的可能枚举值|

### 留存原因 {#retention_reason}

| 枚举值 | 描述 |
|------------------------------------------|--------------------------------------------------------|
| **issuer_retention**                     | 客户留存                                    |
| **portability_not_requested**            | 客户未申请可携性                |

### 文档类型 {#document_type}

|枚举值  |
|------------|
| **pdf**    |
| **jpeg**   |
| **jpg**    |
| **png**    |
| **mp3**    |
| **wav**    |

:::note
留存证据（`retention_type`）仅接受 **jpg**、**jpeg**、**png** 和 **pdf** 格式。
:::

### 留存类型 {#retention_type}

|枚举值      |
|----------------|
| **sms**        |
| **whatsapp**   |

### 攻击状态 {#received_portability_status}

| 枚举值 | 描述 |
|------------------------------|----------------------------------------------------------|
| **received**                 | 已接收                                                 |
| **waiting_validation**       | 等待验证留存证明文件|
| **canceled_by_proponent**    | 被提案人取消                                |
| **canceled_by_creditor**     | 被原始债权人取消                           |
| **retained**                 | 已留存                                                   | 
| **waiting_settlement**       | 可携性已批准，等待清算              | 
| **settled**                  | 已清算                                                |

### 攻击状态机 {#state-machine}

```mermaid
stateDiagram-v2
    [*] --> received
    received --> waiting_validation : PATCH "retained"
    waiting_validation --> waiting_settlement : Evidências não validadas
    waiting_validation --> retained : Evidências validadas
    received --> waiting_settlement : PATCH "accepted_by_creditor"
    waiting_settlement --> settled : Saldo pago
    waiting_settlement --> canceled_by_creditor : Saldo não pago
```

---

# QI 卡 - 预付卡

URL: /zh-Hans/documentation/manual_pre_pago/casos_uso

## 使用场景

:::danger 注意！
QI Tech 的 Webhooks 不应以严格限制的方式映射。
我们 API 返回的 Webhook payload 中可能会添加额外字段。
:::

:::info Webhook 重发
您可以按照文档中的详细说明查询和重发 Webhooks：[重发 Webhooks](/documentation/notificacoes/reenvio_de_notificacoes)。
:::

---

为便于理解，将发行并为其客户提供卡片服务的 BaaS 客户称为"客户"，持有所发行卡片的最终用户称为"持卡人"。

## 1. 交易的完整授权与确认

这是卡片交易最常见的路径：持卡人在 POS 机上刷卡进行金额为 X 的交易，收单机构从发卡机构处扣取该金额。流程从持卡人在 POS 机上使用卡片开始。QI 将收到授权请求并向客户发起授权，如[授权请求](/documentation/cards/autorizacao/)中所述。客户随后进行验证并选择回复，将 *autorization_request_response* 设为 authorized。

[授权对象](/documentation/cards/search/buscar_autorizacao)详情请参见[此处](/documentation/cards/search/buscar_autorizacao)。

QI 将向卡网络回复授权，持卡人的账户余额将扣除交易金额。

此时，将发送一个引用刚刚获批授权的 Webhook。

授权已批准的 Webhook

```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"
}
```

收单机构在交易授权后进行资金扣划。该扣划由 QI 处理，并发送授权状态更新 Webhook，将此交易转为 *completed* 状态。可在 `Authorization` 对象的 *captured_amount* 变量中查询已扣划金额。

授权已确认的 Webhook

```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. 交易的授权与不足额确认

在此情况下，收单机构扣划的金额小于授权金额。流程从持卡人在 POS 机上使用卡片开始。QI 将收到授权请求并向客户发起授权，如[授权请求](/documentation/cards/autorizacao/)中所述。客户随后进行验证并选择回复，将 *autorization_request_response* 设为 authorized。

QI 将向卡网络回复授权，持卡人的账户余额将扣除交易金额。

此时，将发送一个引用刚刚获批授权的 Webhook。

授权已批准的 Webhook

```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"
}
```

收单机构在交易授权后进行资金扣划。该扣划由 QI 处理，并发送授权状态更新 Webhook，将此授权转为 *completed* 状态。可在 `Authorization` 对象的 *captured_amount* 变量中查询已扣划金额。

不足额确认的 Webhook

```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"
}
```

如果授权在未完全扣划的情况下过期，差额将作为信用返还到持卡人账户。

## 3. 交易的授权与超额确认

在此情况下，收单机构扣划的金额大于授权金额。流程从持卡人在 POS 机上使用卡片开始。QI 将收到授权请求并向客户发起授权，如[授权请求](/documentation/cards/autorizacao/)中所述。客户随后进行验证并选择回复，将 *autorization_request_response* 设为 authorized。

QI 将向卡网络回复授权，持卡人的账户余额将扣除交易金额。

此时，将发送一个引用刚刚授权交易的 Webhook。

授权已批准的 Webhook

```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"
}
```

收单机构在交易授权后进行资金扣划。该扣划由 QI 处理，并发送授权状态更新 Webhook，将此授权转为 *completed* 状态。可在 `Authorization` 对象的 *captured_amount* 变量中查询已扣划金额。在此使用场景中，扣划金额将大于原授权金额。

超额确认的 Webhook

```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"
}
```

此情况将在持卡人的 QI 账户中产生超额差额的借记，本例中将从持卡人的 QI 账户中扣除 R$ 2,00。如果在任何情况下均无法执行此借记，QI 将与客户（使用 QI 卡片服务的 BaaS 客户）单独处理这些情况。

### 部分取消

在此超额确认情况下，收单机构可通过发送全额退款 `refund` 或部分退款 `partial_refund` 来纠正错误，这些将以授权事件的形式呈现。以下是对不当多收的 R$2,00 进行部分退款的示例。

部分退款授权的 Webhook

```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. 交易的授权与取消

在此情况下，交易已获授权，但由于某种原因，卖家决定在扣划之前在 POS 机上取消该交易。流程从持卡人在 POS 机上使用卡片开始。QI 将收到授权请求并向客户发起授权，如[授权请求](/documentation/cards/autorizacao/)中所述。客户随后进行验证并选择回复，将 *approve* 设为 true。

QI 将向卡网络回复授权，持卡人的账户余额将扣除交易金额。

此时，将发送一个引用刚刚授权交易的 Webhook。

交易已授权的 Webhook

```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"
}
```

卖家在交易授权后，因某种原因（例如输入错误）决定取消该交易。该取消消息由 QI 处理，并发送交易状态更新 Webhook，将该交易转为已冲正 *reversed* 状态。在此情况下，授权全额已被取消。

授权已冲正的 Webhook

```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"
}
```

在此情况下，全额取消金额将作为信用返还到持卡人的 QI 账户。

### 授权过期

可能出现授权已批准但在卡片品牌规定的期限内未被扣划的情况。在此情况下，将发送授权过期 Webhook，未扣划金额将作为信用返还到持卡人的 QI 账户。

授权已过期的 Webhook

```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"
}
```

---

# 私人养老金手册 - 批注与放款

URL: /zh-Hans/documentation/manual_previdencia_privada/manual_previdencia_privada_averbacao_desembolso

:::info 导航
- [新增信贷](/documentation/manual_previdencia_privada/manual_previdencia_privada_credito_novo)（上一步）
:::

:::caution API 开发中
该 API 仍处于开发阶段，因此本手册可能会有所变动。
:::

:::danger 注意！
QI Tech 的 Webhooks 不应以严格限制的方式映射。
我们 API 返回的 Webhook payload 中可能会添加额外字段。
:::

:::info Webhook 重发
您可以按照文档中的详细说明查询和重发 Webhooks：[重发 Webhooks](/documentation/notificacoes/reenvio_de_notificacoes)。
:::

## 1 - 批注

### Webhooks

批注成功时，合作伙伴将收到以下 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"
  }
}
```

### 批注失败
如果预约失败，将以以下格式发送 Webhook 通知：

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 - 解除批注

合同的解除批注通过永久取消路由执行。该路由将合同设为最终状态，不可重试，并触发已批注保证金的解除批注。

要执行永久取消，请使用以下接口：

**POST**
/debt/ DEBT-KEY /cancel_permanently

### 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 - 放款失败

### TED
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
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 - 重新提交付款
更改放款日期而不影响操作的财务价值。

**POST**
/debt/ DEBT-KEY /change_disbursement_date

### 请求

**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
        }
    ]
}
```

 
### 响应

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
        }
    ]
}
```

---

# 私人养老金手册 - 查询

URL: /zh-Hans/documentation/manual_previdencia_privada/manual_previdencia_privada_consulta

:::info 下一步
- [新增信贷](/documentation/manual_previdencia_privada/manual_previdencia_privada_credito_novo)
:::

:::caution API 开发中
该 API 仍处于开发阶段，因此本手册可能会有所变动。
:::

---

## 1. 担保查询

担保查询允许核查与养老金产品相关的信息。此操作为异步操作，查询请求将被发送至我们的队列之一并随后处理。请求会立即返回与查询请求相关的唯一标识符及其处理状态。

### Request

**POST**
/private_pension/inquiry

**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**

| 字段               | 类型   | 描述                         |
|--------------------|--------|------------------------------|
| document_number    | string | 借款人 CPF                   |
| operating_entity   | string | 运营实体枚举                 |
| investment_funds   | 对象   | 投资基金数据                 |
| authorization_term | 对象   | 授权数据                     |

#### 对象 investment_funds

| 字段                  | 类型   | 描述                               |
|-----------------------|--------|------------------------------------|
| susep_process_number  | string | SUSEP 流程编号                     |
| certificate           | string | 养老金产品证书                     |
| name                  | string | 基金名称                           |
| document_number       | string | 基金 CNPJ                          |
| class                 | string | 基金类别                           |
| subclass              | string | 基金子类别                         |

#### 对象 authorization_term

| 字段                | 类型   | 描述                         |
|---------------------|--------|------------------------------|
| signature           | 对象   | 签名数据                     |
| authentication_type | string | 认证类型 (opt_in)            |
| authenticity        | 对象   | 真实性数据                   |

#### 对象 signature

| 字段               | 类型   | 描述                         |
|--------------------|--------|------------------------------|
| signer             | 对象   | 签署人数据                   |

#### 对象 signer

| 字段               | 类型   | 描述                         |
|--------------------|--------|------------------------------|
| name               | string | 签署人姓名                   |
| birth_date         | string | 签署人出生日期               |
| address            | 对象   | 签署人地址                   |
| email              | 对象   | 签署人电子邮件地址           |
| phone              | 对象   | 签署人电话                   |

#### 对象 address

| 字段               | 类型   | 描述                         |
|--------------------|--------|------------------------------|
| street             | string | 街道                         |
| neighborhood       | string | 街区                         |
| city               | string | 城市                         |
| state              | string | 州                           |
| postal_code        | string | 邮政编码                     |

#### 对象 phone

| 字段               | 类型   | 描述                         |
|--------------------|--------|------------------------------|
| number             | string | 电话号码                     |
| area_code          | string | 区号 (DDD)                   |
| country_code       | string | 国家电话代码                 |

#### 对象 authenticity

| 字段               | 类型   | 描述                                       |
|--------------------|--------|--------------------------------------------|
| timestamp          | string | 借款人接受的时间戳                         |
| ip_address         | string | 用户会话 IP                                |
| city               | string | 签署城市                                   |
| session_id         | string | 用户会话内部标识键                         |

### Response

STATUS
**201** (CREATED)

**Payload**

```json
{
    "inquiry_key": "69aac130-35cb-4bdd-80e9-ba01d18002bd",
    "inquiry_status": "pending_inquiry"
}
```

**Response Body Details**

| 字段                      | 类型    | 描述                                                                |
|---------------------------|---------|---------------------------------------------------------------------|
| inquiry_key       | string  | 担保查询的唯一标识符                                                |
| inquiry_status    | string  | 查询请求状态 (pending_inquiry/success/rejected)                     |

---

## 2. 担保处理查询

**GET**
/private_pension/inquiry/[inquiry_key]

### Response

**Response Body**

```json
{
    "inquiry_key": "69aac130-35cb-4bdd-80e9-ba01d18002bd",
    "inquiry_status": "pending_inquiry"
}
```

---

## 3. 担保查询 Webhook

查询请求处理完成后，客户将收到包含担保信息的 webhook。

:::caution 注意
客户必须实现此 webhook 的处理逻辑，以获取担保查询请求的信息。
:::

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": {
    "guarantees": [
        {
            "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**

| 字段                | 类型   | 描述                                 |
|---------------------|--------|--------------------------------------|
| key | string | 查询请求键                           |
| status              | string | 文档状态 (success)                   |
| webhook_type        | string | Webhook 类型                         |
| event_datetime      | string | 事件日期和时间                       |
| data                | object | Webhook 数据                         |

#### Payload data

| 字段                         | 类型   | 描述             |
|------------------------------|--------|------------------|
| guarantees                   | 对象   | 担保数据         |

#### 对象 guarantees

| 字段                          | 类型   | 描述                                                                         |
|-------------------------------|--------|------------------------------------------------------------------------------|
| contract_id                   | string | 担保合同附件 IV 模型编号                                                     |
| product                       | string | 运营实体中的产品名称                                                         |
| operation_type                | string | 产品类型 (previdencia)                                                       |
| operating_entity              | 对象   | 运营实体数据                                                                 |
| guarantor                     | 对象   | 担保人数据                                                                   |
| plan_type                     | 对象   | 养老金计划类型                                                               |
| initial_grace                 | bool   | 是否存在初始宽限期                                                           |
| accumulation_period_end_date  | 对象   | 积累期结束日期                                                               |
| tax_regime                    | enum   | 税收制度                                                                     |
| remaining_grace_period        | int    | 宽限期剩余天数（以天为单位）                                                 |
| load_percentage               | number | 费率百分比                                                                   |
| investment_funds              | 对象   | 投资基金数据                                                                 |

#### 对象 operating_entity

| 字段                  | 类型   | 描述                         |
|-----------------------|--------|------------------------------|
| document_number       | string | 运营实体 CNPJ                |
| operating_entity_name | string | 运营实体名称                 |
| street                | string | 街道                         |
| neighborhood          | string | 街区                         |
| city                  | string | 城市                         |
| state                 | string | 州                           |
| postal_code           | string | 邮政编码                     |
| authenticity          | object | 真实性数据                   |

#### 对象 authenticity

| 字段               | 类型   | 描述                                   |
|--------------------|--------|----------------------------------------|
| timestamp          | string | 运营实体接受的时间戳                   |
| city               | string | 签署城市                               |
| session_id         | string | 会话内部标识键                         |

#### 对象 guarantor

| 字段                   | 类型   | 描述                                   |
|------------------------|--------|----------------------------------------|
| contract_code          | string | 合同代码                               |
| person_type            | enum   | 人员类型 (自然人, 法人)                |
| document_number        | string | 担保人 CPF/CNPJ                        |
| name                   | string | 担保人姓名                             |
| social_name            | string | 担保人社会姓名                         |
| second_document_number | string | 担保人身份证号 (RG)                    |
| birth_date             | string | 担保人出生日期                         |
| street                 | string | 街道                                   |
| neighborhood           | string | 街区                                   |
| city                   | string | 城市                                   |
| state                  | string | 州                                     |
| postal_code            | string | 邮政编码                               |
| phone                  | string | 担保人电话号码                         |
| email                  | string | 担保人电子邮件地址                     |
| movement_type          | enum   | 操作类型                               |
| consent_term_code      | string | 同意条款代码                           |
| consent_file_url       | object | 同意文件 URL 数据                      |
| consent_file_hash      | string | 同意文件哈希值                         |
| legal_representatives  | object | 法定代表人                             |

#### 对象 investment_funds

| 字段                          | 类型   | 描述                                           |
|-------------------------------|--------|------------------------------------------------|
| susep_process_number          | string | SUSEP 流程编号                                 |
| certificate                   | string | 养老金产品证书                                 |
| name                          | string | 基金名称                                       |
| document_number               | string | 基金 CNPJ                                      |
| class                         | string | 基金类别                                       |
| subclass                      | string | 基金子类别                                     |
| inquiry_id                    | string | 担保标识符                                     |
| response_within_deadline      | bool   | 是否在截止日期内响应                           |
| inquiry_processing_status     | enum   | 查询请求处理状态                               |
| inquiry_status                | enum   | 请求状态                                       |
| rejection_reason              | enum   | 查询拒绝原因                                   |
| rejection_reason_description  | string | 查询拒绝原因描述                               |
| remuneration_criteria         | string | 报酬标准                                       |
| available_gross_amount        | number | 可用总金额                                     |
| elegible_gross_amount         | number | 符合条件的总金额                               |
| lock_gross_amount             | number | 待锁定总金额                                   |

#### 对象 consent_file_url

| 字段               | 类型   | 描述                                   |
|--------------------|--------|----------------------------------------|
| url                | string | 同意文件 URL                           |
| duration           | string | URL 访问有效期                         |

#### 对象 legal_representatives

| 字段               | 类型   | 描述                                   |
|--------------------|--------|----------------------------------------|
| person_type        | enum   | 人员类型                               |
| document_number    | string | 法定代表人 CPF/CNPJ                    |
| name               | string | 法定代表人姓名                         |
| social_name        | string | 法定代表人社会姓名                     |

#### 枚举 tax_regime

| 枚举值                    | 描述             |
|---------------------------|------------------|
| indefinite                | 不确定税收制度   |
| progressive               | 累进税收制度     |
| regressive                | 递减税收制度     |

#### 枚举 person_type

| 枚举值                    | 描述             |
|---------------------------|------------------|
| natural_person            | 自然人           |
| legal_person              | 法人             |

#### 枚举 movement_type

| 枚举值                    | 描述                   |
|---------------------------|------------------------|
| supply                    | 锁定同意               |
| renegotiate               | 重新谈判同意           |

#### 枚举 inquiry_processing_status

| 枚举值                            | 描述                         |
|-----------------------------------|------------------------------|
| inquiry_nuclea_register           | 请求已由 Núclea 登记         |
| inquiry_sent_operating_entity     | 请求已由运营实体接收         |
| inquiry_returned_operating_entity | 请求已由运营实体返回         |

#### 枚举 inquiry_status

| 枚举值                    | 描述                   |
|---------------------------|------------------------|
| success                   | 查询请求成功           |
| failed                    | 查询请求失败           |
| pending                   | 查询请求待处理         |

#### 枚举 rejection_reason

| 枚举值                        | 描述                   |
|-------------------------------|------------------------|
| invalid_signature             | 无效签名               |
| invalid_client_information    | 无效客户信息           |
| invalid_plan_information      | 无效计划信息           |
| incomplete_information        | 信息不完整             |
| others                        | 其他拒绝原因           |

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": {
    "guarantees": [
        {
            "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
                }
            ]
        }
    ]
  }
}
```

---

---

# 私人养老金手册 - 新增信贷

URL: /zh-Hans/documentation/manual_previdencia_privada/manual_previdencia_privada_credito_novo

:::info 导航
- [查询](/documentation/manual_previdencia_privada/manual_previdencia_privada_consulta)（上一页）
- [背书与放款](/documentation/manual_previdencia_privada/manual_previdencia_privada_averbacao_desembolso)（下一页）
:::

:::caution API 开发中
该 API 仍处于开发阶段，因此本手册可能会有所变动。
:::

:::danger 注意！
QI Tech 的 webhooks 不应被严格映射。
我们 API 返回的 webhook payload 中可能会新增额外字段。
:::

:::info Webhook 重发
您可以按照文档中的详细说明查询和重发 webhooks：[Webhook 重发](/documentation/notificacoes/reenvio_de_notificacoes)。
:::

## 1 - 债务模拟：
新增信贷

### Request

**POST**
/debt_simulation

**分期金额**

```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"
        }
    ]
}
```

**放款金额**

```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
上述请求中有 2 个模拟在执行。第一个固定了客户的分期金额（放款金额可变），第二个固定了放款金额（分期金额可变）。
::: 

### 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 - 操作发行：

新增信贷

### Request

**POST**
/debt

**无法定代表人**

```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": [ // 可选
            {
                "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_number": "",
                        "certificate": "",
                        "operating_entity_document_number": "",
                        "plan_type": "",
                        "initial_grace": false,   
                        "grace_days": 0,   
                        "accumulation_end_date": "2050-01-01",   
                        "tax_regime": "progressive",   
                        "load_percentage": 0.0,   
                        "name": "",
                        "document_number": "",
                        "class": "",
                        "subclass": "",
                        "lock_gross_amount": 500,
                    },
                    {
                        "susep_process_number": "",
                        "certificate": "",
                        "operating_entity_document_number": "",
                        "plan_type": "",
                        "initial_grace": false,   
                        "grace_days": 0,   
                        "accumulation_end_date": "2050-01-01",   
                        "tax_regime": "progressive",   
                        "load_percentage": 0.0,   
                        "name": "",
                        "document_number": "",
                        "class": "",
                        "subclass": "",
                        "lock_gross_amount": 500,
                    },
                    {
                        "susep_process_number": "",
                        "certificate": "",
                        "operating_entity_document_number": "",
                        "plan_type": "",
                        "initial_grace": false,   
                        "grace_days": 0,   
                        "accumulation_end_date": "2050-01-01",   
                        "tax_regime": "progressive",   
                        "load_percentage": 0.0,   
                        "name": "",
                        "document_number": "",
                        "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": {
                    "operating_entity_document_number": "",
                    "total_gross_amount_lock": 1500,
                    "investment_funds": [
                        {
                            "susep_process_number": "",
                            "certificate": "",
                            "plan_type": "", // 可选
                            "initial_grace": false,   
                            "grace_days": 0,   
                            "accumulation_end_date": "2050-01-01",   
                            "tax_regime": "progressive",   
                            "load_percentage": 0.0,   
                            "name": "",
                            "document_number": "",
                            "class": "", // 可选
                            "subclass": "", // 可选
                            "lock_gross_amount": 500,
                        },
                        {
                            "susep_process_number": "",
                            "certificate": "",
                            "plan_type": "",
                            "initial_grace": false,   
                            "grace_days": 0,   
                            "accumulation_end_date": "2050-01-01",   
                            "tax_regime": "progressive",   
                            "load_percentage": 0.0,   
                            "name": "",
                            "document_number": "",
                            "class": "",
                            "subclass": "",
                            "lock_gross_amount": 500,
                        },
                        {
                            "susep_process_number": "",
                            "certificate": "",
                            "plan_type": "",
                            "initial_grace": false,   
                            "grace_days": 0,   
                            "accumulation_end_date": "2050-01-01",   
                            "tax_regime": "progressive",   
                            "load_percentage": 0.0,   
                            "name": "",
                            "document_number": "",
                            "class": "",
                            "subclass": "",
                            "lock_gross_amount": 500,
                        }
                    ]
                },
                "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"
                }
            }
        ]
    }
} 
```

### 对象 Installments

| 字段 | 描述 |
|-------|-----------|
| additional_costs | 附加费用 |
| business_due_date | 工作日到期日 |
| calendar_days | 日历天数 |
| due_date | 到期日 |
| due_interest | 到期利息 |
| due_principal | 到期本金 |
| fine_amount | 到期罚款 |
| has_interest | 是否含有利息 |
| installment_number | 分期编号 |
| installment_status | 分期状态 |
| installment_type | 分期类型 |
| post_fixed_amount | 利息后分期金额 |
| pre_fixed_amount | 利息前分期金额 |
| principal_amortization_amount | 分期本金摊还金额 |
| tax_amount | 分期利息金额 |
| total_amount | 分期总金额 |
| workdays | 工作天数 |

### 对象 Prefixed Interest Rate

| 字段 | 描述 |
|-------|-----------|
| monthly_rate | 月利率 |
| daily_rate | 日利率 |
| annual_rate | 年利率 |
| interest_base | 利率计算基准 |

### Webhooks

如果操作在最后一个放款日期选项前未被签署或背书，合作伙伴将收到一条关于操作取消的 webhook：

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>"
    }
}
```

### 对象 Data

| 字段 | 描述 |
|-------|-----------|
| cancel_reason | 取消原因 |
| cancel_reason_enumerator | 取消原因枚举值 |

## Webhooks

合同签署后，合作伙伴将收到一条关于合同签署的 webhook，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"
}
```

### 对象 Signers

| 字段 | 描述 |
|-------|-----------|
| id | 签署人 ID |
| images | 签署人图像 |

### 对象 Images

| 字段 | 描述 |
|-------|-----------|
| face_image_url | 签署人面部图像 URL |
| document_back_url | 签署人证件背面图像 URL |
| document_front_url | 签署人证件正面图像 URL |
| document_back_template | 签署人证件背面模板 |
| document_front_template | 签署人证件正面模板 |

### 对象 Biometry

| 字段 | 描述 |
|-------|-----------|
| face_validation | 签署人面部验证 (true 或 false) |
| face_validation.score | 签署人面部评分 (0 至 100) |
| face_validation.available | 面部验证是否可用 (true 或 false) |
| face_validation.provider | 面部验证提供商 (qitech 或 external) |
| fraud_base_flag | 基础欺诈标志 (true 或 false) |

### 对象 Document

| 字段 | 描述 |
|-------|-----------|
| template | 证件模板 (cnh_front, cnh_back, rg_front, rg_back) |
| face_match_score | 签署人面部评分 (0 至 100) |

### 对象 Liveness

| 字段 | 描述 |
|-------|-----------|
| result | 活体检测结果 (live 或 spoof) |

### 对象 Signer Data

| 字段 | 描述 |
|-------|-----------|
| name | 签署人姓名 |
| email | 签署人电子邮件 |
| phone | 签署人电话 |

### 对象 Address

| 字段 | 描述 |
|-------|-----------|
| uf | 联邦单位 |
| city | 城市 |
| number | 门牌号 |
| street | 街道 |
| complement | 补充信息 |
| postal_code | 邮政编码 |
| neighborhood | 街区 |

## 枚举值

### 预留状态 {#status-da-reserva}

枚举值
reservation_status

| 状态                          | 描述                                                                      |
| ----------------------------- | ------------------------------------------------------------------------- |
| pending_reservation           | 预留已创建，待背书。                                                      |
| pending_documents_submission  | 预留已背书，待提交文件。                                                  |
| reserved                      | 预留已成功背书。背书流程已完成。                                          |
| canceled                      | 如提交无效文件，预留将被取消。                                            |
| settled                       | 预留已成功结算。                                                          |
| pending_deletion              | 预留已背书，已申请删除。                                                  |
| deleted                       | 预留已成功删除。                                                          |

---

# QI FATURA

URL: /zh-Hans/documentation/manual_qi_fatura/pix_parcelado

## 带 PIX 分期付款的卡片体验

---

:::caution API 开发中 
该 API 仍处于最终开发阶段，因此本手册可能会有所更改。
:::

:::danger 注意！
QI Tech 的 webhook 不应进行严格映射。
我们的 API 返回的 webhook payload 中可能会包含额外字段。
:::

:::info Webhook 重发
您可以按照文档中的详细说明查询并重发 webhook：[Webhook 重发](/documentation/notificacoes/reenvio_de_notificacoes)。
:::

## 1. 创建数字钱包

要能够在账单中添加条目（以 CCB 为基础的 PIX 入账），首先需要为每个客户创建一个数字钱包。

### Request

ENDPOINT /card_invoice/wallet
MÉTODO POST

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 详情
#### Wallet payload

| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---|---|
| `owner` | object  | 钱包所有者对象 |**[owner 对象](#objeto-owner)**  |
| `invoice_configuration` | object  | 每个钱包的账单配置对象 |**[invoicer_configuration 对象](#objeto-invoicer_configuration)**  |
| `invoice_authorization` | object  | 授权对象 |**[invoice_authorization 对象](#objeto-invoice_authorization)**  |
| `limit` | number  | 钱包限额 | |
| `default_monthly_interest_rate` | number  | 钱包的默认月利率。 | |

#### owner 对象

| 字段 | 类型 | 描述 | 字符数 |
|---| ---| ---| ---| 
| `person_type` | string | 标识发送的对象是自然人还是法人。|  |
| `name` | string |  PJ 业务时为公司名，PF 业务时为个人姓名。 | 100 |
| `document_number` | string | 个人 CPF（仅数字），限11个字符。 |  |
| `address` | string | 客户地址。 | **[address 对象](#objeto-address)** |  |
| `phone` | string | 电话数据对象 | **[phone 对象](#objeto-phone)**|
| `email` | string |  客户邮箱。 |  |

#### address 对象 

| 字段 | 描述 | 示例 |  最大字符数 | 
|---|---|---|---| 
| `street` | string | 地址街道  | 100 |
| `state` | string | 地址州（两个大写字母） | 2 |
| `city` | string | 地址城市 | 100 |
| `neighborhood` | string |地址街区 | 100 |
| `number` | string | 街道门牌号 | 10 |
| `postal_code` | string |地址 CEP（http://www.buscacep.correios.com.br/sistemas/buscacep/）（仅数字） |  8 |
| `complement` | string |地址补充（自由文本） | 100 |

#### phone 对象 

| 字段 | 描述 | 示例 |  最大字符数 | 
| --- | --- | --- | --- | 
|`country_code` | string | 电话国际区号（https://ddi.guiamais.com.br/） | 3 | 
| `area_code` | string | 电话区号（https://ddd.guiamais.com.br/） | 2 |
| `number` | string |电话号码（仅数字） |  10 |

#### invoice_configuration 对象

| 字段 | 描述 | 示例 |  最大字符数 | 
| --- | --- | --- | --- | 
| `closing_day` | number |  账单结账日（账单条目登记的截止日期）。| |
| `due_day` | number |  账单到期日。选项：1、5、10 | |
| `grace_months` | number |  结账日与到期日之间的月数差。| |
| `delay_fine_percentage` | number |  账单逾期付款时的滞纳金金额。| |
| `delay_monthly_interest_rate` | number |  账单逾期付款时每月利息金额。| |
| `issuing_and_due_day_difference` | number | 账单发行日与到期日之间的天数，用于计算账单发行日期。| |
| `invoice_payment_type` | string |  账单付款方式。选项：'bankslip'| |

:::info 账单配置 
在账单配置（invoice_configuration）中，固定数据如"delay_fine_percentage"、"grace_months"、"delay_monthly_interest_rate"、"invoice_payment_type"、"issuing_and_due_day_difference"可以直接在 API 合作伙伴初始设置中配置，从而简化钱包创建的 payload。在 API 合作伙伴初始设置中配置的信息将对所有客户固定适用。 
:::

:::caution 
账单到期日"invoice_configuration.due_day"与结账日"invoice_configuration.closing_day"之间的天数必须大于等于8天且小于等于10天。
:::

### 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 详情

| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---|---|
| `wallet_key` | string  |  钱包唯一标识符（uuid） | |
| `status` | string  |  钱包状态 | |

## 1.1. 查询现有钱包： 

#### QUERY PARAMETERS

| 枚举值                          | 描述                                                   |
|------------------------------|-------------------------------------------------------------|
| **owner_document_number**    |  钱包持有人的 CPF                                 |
| **page**                     |  查询页码                               |
| **page_size**                |  查询请求的每页条数                  |

### Request

ENDPOINT /card_invoice/wallets
MÉTODO GET

### 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. 查询特定钱包： 
### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]
MÉTODO GET

### 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. 修改钱包限额： 

### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]
MÉTODO PATCH

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. 向现有数字钱包添加卡片：
为客户创建数字钱包后，需要创建一张与该钱包关联的卡片。

### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/card
MÉTODO POST

Request Body

```json
{
    "settlement_method": "credit_operation"
}
```

### Request body 详情
#### Card payload

| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---|---|
| `settlement_method` | string  |  担保类型，即交易将如何进行担保。选项："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 详情

| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---|---|
| `card_key` | string  |  卡片唯一标识符（uuid）  | |

## 3. 模拟操作：

模拟交易（PIX）。
### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry/simulation
MÉTODO POST

Request Body

```json
{
  "amount": 200,
  "number_of_installments": 4,
  "monthly_interest_rate": 0.035
}
```

:::note 注意
无需填写"monthly_interest_rate"字段，未填写时，交易将采用钱包的默认利率。
:::

### 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. 在卡片中添加交易：

添加交易（PIX）。此步骤将生成 CCB，验证是否有足够的可用额度来执行交易。交易清算以同步方式处理。

### Request

:::note 注意
无需填写"monthly_interest_rate"字段，未填写时，交易将采用钱包的默认利率。
:::

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry
MÉTODO POST

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"
      }
    }
  }
}
```

使用 PIX 密钥放款
```json
{
    "disbursement": {
    "method": "pix",
    "data": {
      "pix_key": "\<CHAVE PIX\>",
      "end_to_end_id": "\<CHAVE END TO END DO PIX\>"
    }
  }
}
```

使用 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\>"
    }
  }
}
```

使用 PIX 手动方式放款
```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

交易放款成功时：

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 注意
由于巴西央行或目标银行的不稳定性，合同交易可能会延迟，从而使其进入"pending_activation"状态，并在交易成功完成或合同取消时进行更新。因此，流程将从同步转为异步，需要等待交易成功或失败的 [webhook](#92-alteração-de-status-da-transação)。
:::

## 4.1 查询特定交易（card entry）： 
### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry/[CARD-ENTRY-KEY]
MÉTODO GET

### Response

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry/[CARD-ENTRY-KEY]
MÉTODO GET
HTTP STATUS 200

PIX 手动交易 Response

```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"
}
```

PIX Key 交易 Response

```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"
}
```

PIX QR Code 交易 Response

```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"
}
```

#### Card Entry 状态枚举值

| 枚举值                          | 描述                                                     |
|------------------------------|------------------------------------------------------|
| **active**                   | 合同激活并已放款                        |
| **pending_activation**       | 合同等待放款                       |
| **canceled**                 | 合同已取消                                   |
| **paid**                     | 合同已清算                                   |

## 4.2 生成交易凭证：
### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry/[CARD-ENTRY-KEY]/receipt
MÉTODO GET

### 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. 列出数字钱包的账单：

### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/invoices
MÉTODO GET
<div className='badge
badge--primary'>PARAMETERS page, page_size

### Response

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/invoices
MÉTODO GET
HTTP STATUS 200
每页返回最多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. 列出账单交易：
### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]
MÉTODO GET

### 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
        }
    ]
}
```

#### 条目状态枚举值

| 枚举值                          | 描述                                                                                    |
|------------------------------|-----------------------------------------------------------------------------------------------|
| **pending_activation**       | 条目等待激活，条目金额计入账单金额                          |
| **active**                   | 条目激活，条目金额计入账单金额                                        |
| **canceled**                 | 条目已取消，条目金额从账单金额中移除                               |
| **paid**                     | 条目已在当月账单中付款，条目金额计入账单金额                        |
| **paid_early**               | 条目已提前付款，条目金额不再计入账单金额                      |
| **reversed**                 | 条目在账单结账后取消，条目金额将产生退款                   |

## 7. 生成 boleto：

普通 boleto 将在账单结账日自动生成，可通过账单付款的 GET 接口获取。查询参数"shorten_url"是请求缩短 boleto URL 的标志。

:::caution 注意
boleto 可以在账单到期后30天内支付。
:::

:::danger 注意
URL 缩短限制为每分钟60次请求。
:::

### 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

### Response

#### 参数 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,
    }
```

#### 参数 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 生成提前还款特别 boleto：

### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]/invoice_payment
MÉTODO POST

Request Body

```json
{
    "invoice_payment_type": "bankslip",
    "charge_type": "early",
    "expiration": "2023-08-15",
    "invoice_items": [
	    "key_1",
	    "key_2"
    ]
}
```

:::note 注意
条件："expiration"必须早于账单结账日至少两个工作日，以确保付款不会影响该例行程序。
:::

### 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 逾期特别 boleto 模拟：

:::caution 注意
模拟只能在普通 boleto 的付款期限结束后才能申请。
:::

### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]/invoice_payment/simulation
MÉTODO POST

Request Body

```json
    {
        "invoice_payment_type": "bankslip",
        "charge_type": "delay",
        "expiration": "2023-08-15"
    }
```

### 含折扣的请求

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 生成逾期特别 boleto：

:::caution 注意
逾期 boleto 只能在普通 boleto 的付款期限结束后才能生成。
:::

### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]/invoice_payment
MÉTODO POST

Request Body

```json
    {
        "invoice_payment_type": "bankslip",
        "charge_type": "delay",
        "expiration": "2023-08-15"
    }
```

### 含折扣的请求

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 取消账单付款 boleto

### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]/invoice_payment/[INVOICE-PAYMENT-KEY]
MÉTODO DELETE

### 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. 退款：

## 8.1. 查询退款：

### Request

ENDPOINT
        /card_invoice/wallet/[WALLET-KEY]/chargebacks
MÉTODO
        GET

#### PATH PARAMETERS

| 枚举值                          | 描述                                                   |
|------------------------------|-------------------------------------------------------------|
| **status**                   | 退款状态（'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. 账单状态变更：
### 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 注意
"data"字段的内容对所有状态保持相同格式。
:::

#### 账单状态枚举值

| 枚举值                          | 描述                                                     |
|------------------------------|------------------------------------------------------|
| **opened**                   | 账单已开启                                        |
| **closed**                   | 账单已关闭                                       |
| **paid**                     | 账单在到期日内已付款             |
| **paid_overdue**             | 账单逾期后已付款                                |

## 9.2. 交易状态变更：
### 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\>"
    }
}
```

#### Card Entry 状态枚举值

| 枚举值                          | 描述                                                     |
|------------------------------|------------------------------------------------------|
| **active**                   | 合同激活并已放款                        |
| **canceled**                 | 合同已取消                                   |

:::caution 注意
此 webhook 仅在交易处于"pending_activation"状态时才会发送。
:::

## 9.3. 账单结账后生成 boleto：
### 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\>"
    }
}
```

#### 付款类型枚举值

| 枚举值                          | 描述                                                     |
|------------------------------|------------------------------------------------------|
| **ordinary**                 | 普通付款                                  |
| **early**                    | 提前还款特别付款             |
| **delay**                    | 逾期特别付款                   |

## 9.4. 账单付款状态变更：
### 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
    }
}
```

#### 账单付款状态枚举值

| 枚举值                          | 描述                                                     |
|------------------------------|------------------------------------------------------|
| **issued**                   | 已发行账单付款 boleto           |
| **paid**                     | boleto 已付款                                          |
| **canceled**                 | boleto 付款已取消                        |

## 9.5. 退款状态变更：

### 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\>"
    }
}
```

#### 退款状态枚举值

| 枚举值                          | 描述                                                    |
|------------------------------|-------------------------------------------------------------|
| **active**                   | 退款已激活，可用于账单付款  |
| **used**                     | 退款已用于账单付款             |
| **pending_payment**          | 退款等待付款以激活               |

:::caution 'pending_payment' 状态 
pending_payment 状态表示属于已关闭但尚未付款的账单的条目退款，退款金额只能在账单付款后才能使用。
:::

## 9.6.1 交易重新协商拒绝：
### 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 交易重新协商付款：
### 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>"
        }
    }
}
```

#### 重新协商状态枚举值

| 枚举值                          | 描述                                                                                                          |
|------------------------------|--------------------------------------------------------------------------------------------------------------------|
| **pending_payment**          | 提前还款重新协商等待付款                                                                     |
| **paid**                     | 提前还款重新协商已付款                                                                     |
| **canceled**                 | 提前还款重新协商已取消                                                                |
| **rejected**                 | 由于在重新协商外分期付款或超过期限，提前还款重新协商被拒绝              |

## 10. 7天内取消购买：

## 10.1. 申请取消购买：

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry/[CARD-ENTRY-KEY]/reversal
MÉTODO POST

### 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. 查询有效的取消购买：

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry/[CARD-ENTRY-KEY]/reversal
MÉTODO GET

### 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. 购买重新协商：

## 11.1. 模拟购买重新协商：

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/renegotiation/simulation
MÉTODO POST

### 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 详情

| 字段 | 类型 | 描述 | 字符数 |
|---| ---| ---| ---| 
| `reference_date` | string | 重新协商的参考日期。|  |

### 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. 创建购买重新协商：

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/renegotiation
MÉTODO POST

:::caution 'items' 对象 
当未提供"items"对象时，将视为交易中所有可用条目都包含在重新协商中，即状态非"active"的条目将被忽略。

此外，如果钱包已有等待付款的重新协商，必须先取消才能生成新的重新协商。
:::

### 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"
        }
    ]
}
```

### 折扣字段

在请求中添加以下任一字段可以在创建或模拟重新协商方案时设置百分比或绝对折扣金额。

百分比折扣

```json
{
  "discount_percentage": 0.5
}
```

绝对折扣

```json
{
  "discount_amount": 200
}
```

### Request body 详情

| 字段 | 类型 | 描述 | 字符数 |
|---| ---| ---| ---| 
| `reference_date` | string | 重新协商的参考日期。|  |
| `proposal_due_date` | string | 重新协商方案的到期日。|  |

### 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 详情

| 字段 | 类型 | 描述 | 字符数 |
|---| ---| ---| ---| 
| `reference_date` | string | 重新协商的参考日期。|  |
| `proposal_due_date` | string | 重新协商方案的到期日。|  |
| `renegotiation_key` | string | 重新协商的唯一标识符（uuid）。|  |
| `renegotiation_payment_amount` | number | 重新协商的总金额。|  |
| `discount_percentage` | number | 重新协商中要应用的百分比折扣值。|  |
| `discount_amount` | number | 重新协商中要应用的绝对折扣值。|  |
| `payment` | object | 包含重新协商付款信息的对象。|  |
| `card_entries` | list | 要重新协商的交易及其各自分期的列表。|  |

## 11.3. 查询现有购买重新协商：

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/renegotiation/[RENEGOTIATION-KEY]
MÉTODO GET

#### QUERY PARAMETERS

| 枚举值                          | 描述                                                         |
|------------------------------|------------------------------------------------------------------|
| **shorten_url**              |  请求缩短 boleto URL 的参数  |

### 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. 手动取消重新协商：

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/renegotiation/[RENEGOTIATION-KEY]
MÉTODO DELETE

### Response

Response Body

```json
{
    "renegotiation_key": "2af29916-582b-4ce7-8440-352a0d9543f7",
    "renegotiation_status": "canceled"
}

```

## 12. 场景模拟：

## 12.1. 账单结账：

:::info DUE_DATE
due_date 字段为可选字段，未填写时账单保留已设定的到期日。结账日不能设置为未来日期，到期日不能早于结账日。
:::

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
{}

```

---

# QI Sign 手册

URL: /zh-Hans/documentation/manual_qi_sign/

:::danger 注意！
QI Tech 的 webhooks 不应被严格映射。
返回的 webhooks payload 中可能会新增额外字段。
:::

## 简介

欢迎使用 QiTech 签名 API！此 API 提供电子文件签名服务！

### 遇到问题？

如有任何问题，请联系我们的支持团队（suporte@qitech.com.br），我们将尽快回复。

### 环境

我们为客户提供两个环境。API 的基础 URL 为：

- 生产环境 - `https://api.sign.qitech.com.br/`
- 沙盒环境 - `https://api.sandbox.sign.qitech.com.br/`

:::danger 重要提示！
不得在 QI Tech 的沙盒环境中使用真实个人和/或法人数据。
:::

## 仅限 HTTPS

出于安全考虑，与 QI Tech API 的所有通信必须使用 HTTPS。为避免因疏忽或其他原因发起 HTTP 调用，本服务器仅开放端口 443 并使用 TLS 1.2 通信。使用其他协议的调用将被自动拒绝。

## 认证

> 要认证调用，请使用以下代码：

```shell
# No shell, você somente precisa adicionar o header adequado em cada requisição
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE_API_KEY"
```

> 将 API Key 'EXAMPLE_API_KEY' 替换为从我们支持获取的密钥。

我们使用 API Key 来授权访问 API。它可能已通过电子邮件发送给您。如果您还未收到密钥，请发送邮件至 suporte@qitech.com.br 。

我们的 API 要求在所有向服务器发送的请求中，通过如下 header 传递 API Key：

`Authorization: EXAMPLE_API_KEY`

您必须将 EXAMPLE_API_KEY 替换为从支持处收到的 API Key。

信封（Envelope）是包含待电子签名文件的对象。它们由一个或多个文件创建，可通过电子邮件、SMS 或 WhatsApp 发送以供签署。要创建信封，您需要向 API 发送一个或一组文件。信封将被创建，您将收到其唯一标识符。

## 创建信封

要创建信封，请向端点 `/sign/envelope` 发送 `POST` 请求，并附上签署人数据。

```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"
      }
    ]
  }'

```

## Envelope 对象定义

信封的所有信息交换均使用以下对象定义。在某些情况下，为便于实现并减少各方之间的数据流，部分信息可能会被省略。

| 名称 | 类型 | 描述 |
| --------------- | ------ | ---------------------------------------------------------------------------------- |
| id              | string | 信封的唯一标识符。<br /> **此编号必须是唯一的** |
| subject         | string | 信封标题。显示在电子邮件主题中。                                   |
| expiration_date | string | 信封过期日期，格式为 `YYYY-MM-DD`。                             |
| signers         | list   | 描述信封签署人的 Signer 类型对象列表。            |

### Signer 对象定义

|               名称               |  类型  | 描述                                                                                                          |
| :------------------------------: | :----: | ------------------------------------------------------------------------------------------------------------------ |
|                id                | string | 签署人的交易标识符。<br /> **此编号在每个信封中必须是唯一的**            |
|              email               | string | 签署人的电子邮件地址。                                                                                   |
|               name               | string | 签署人全名。                                                                                        |
|            birthdate             | string | 签署人出生日期，格式为 `YYYY-MM-DD`。                                                           |
|         document_number          | string | 签署人的文件号码。                                                                                  |
|              phone               | object | 描述签署人电话的对象。                                                                       |
|  phone.international_dial_code   | string | 签署人电话的国家代码。                                                                           |
|         phone.area_code          | string | 签署人电话的区号。                                                                 |
|           phone.number           | string | 签署人的电话号码。                                                                                   |
|    document_submission_method    |  enum  | 发送文件供签署的方式。<br /> 可用方式：**_email、sms 和 whatsapp_**           |
| authentication_submission_method |  enum  | 发送签署认证令牌的方式。<br /> 可用方式：**_email、sms 和 whatsapp_** |

- email 和 phone 字段可一起或单独发送，但至少需要发送其中一个。
- 所有字段均为必填。

### 信封创建响应

信封创建成功后，响应将是一个包含信封 id 和状态的 JSON，示例如下：

> 响应示例

```json
{
  "id": "814e7ed3-4080-4cae-a853-8e12812817ea",
  "status": "created"
}
```

## 向签署人添加身份证件

要向签署人添加身份证件，请为每个要添加的文件向端点 `/sign/envelope/\{envelope_id\}/signer/\{signer_id\}/personal_document` 发送 `POST` 请求。文件必须按以下格式在请求正文中发送：

```json
{
  "document_b64": "Q5YACgAAAABDlgAbAAAAAEOWAC0AAAAAQ5YAPwAAAABDlgdN...",
  "template": "cnh_front",
  "file_type": "jpeg"
}
```

### 可用模板

对于每种身份证件类型，需要提供相应的模板。可用模板为：

| 模板 | 描述 |
| --------- | ------------------------------------------------------------------------ |
| cnh_front | 巴西国家驾驶证正面（照片面）。       |
| cnh_back  | 巴西国家驾驶证背面（签名面）。 |
| rg_front  | 巴西身份证正面（照片面）。                 |
| rg_back   | 巴西身份证背面（数据面）。                |

### 发送属性说明

| 属性 | 描述 |
| ------------ | -------------------------------------------------------------------------------------------------- |
| document_b64 | 以 base64 编码的身份证件。                                                                   |
| template     | 声明用于图像分析的模板。                                   |
| file_type    | 标识发送文件的格式，`jpeg`。若未发送，则默认值为 `jpeg`。 |

- 身份证件的最大大小为 10 MB
- 除 `file_type` 外，所有字段均为必填。

### 添加身份证件的响应

身份证件添加成功后，响应将是一个包含 `created_at` 的 JSON，示例如下：

> 响应示例

```json
{
  "created_at": "2023-01-01T00:00:00.000Z"
}
```

### 身份证件采集

如果未上传签署人的身份证件，将在签署时要求签署人进行采集。

## 向信封添加文件

要向信封添加待签署文件，请为每个要添加的文件向端点 `/sign/envelope/\{envelope_id\}/document` 发送 `POST` 请求。文件必须按以下格式在请求正文中发送：

```json
{
  "id": "3dfc5526-ee47-4b63-ad97-ddaf5b1c9110",
  "document_b64": "Q5YACgAAAABDlgAbAAAAAEOWAC0AAAAAQ5YAPwAAAABDlgdN...",
  "name": "Laudo de vistoria de entrada",
  "document_type": "pdf"
}
```

- 文件的最大大小为 10 MB

### Document 对象定义

|     名称      |  类型  | 描述                                                                                                                                                                          |
| :-----------: | :----: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|      id       | string | 文件标识符。<br /> **此编号在信封中必须是唯一的** <br /> **可选** 若未提供，我们将生成一个 36 个字符的 UUID4 格式的 GUID。 |
| document_b64  | string | 以 base64 编码的文件。                                                                                                                                                    |
|     name      | string | 文件名称。                                                                                                                                                                 |
| document_type |  enum  | 文件类型。<br /> 可用类型：**_pdf_**                                                                                                                               |

### 向信封添加文件的响应

向信封添加文件成功后，响应将是一个包含文件标识符和创建日期的 JSON，示例如下：

> 响应示例

```json
{
  "id": "3dfc5526-ee47-4b63-ad97-ddaf5b1c9110",
  "created_at": "2023-01-01T00:00:00.000Z"
}
```

## 发送信封以供签署

要发送信封以供签署，请向端点 `/sign/envelope/\{envelope_id\}` 发送 `PATCH` 请求

```bash

  curl -X PATCH \
    https://api.sign.qitech.com.br/sign/envelope/\{envelope_id\} \
    -H "Authorization: EXAMPLE_API_KEY" \
    -d '{
      "status": "submitted"
    }'

```

### 发送信封以供签署的响应

信封发送成功后，响应将是一个包含信封状态的 JSON，示例如下：

> 响应示例

```json
{
  "status": "submitted"
}
```

信封发送签署后，签署人将收到含有文件签署链接的电子邮件或短信。

访问链接后，签署人需填写 CPF，签署文件并根据合作伙伴的流程完成人脸和/或文件验证。签署完成后，签署人将被重定向至成功页面。

## 查询信封数据

要查看信封数据（如状态和签署人信息），请向端点 `/sign/envelope/\{envelope_id\}` 发送 GET 请求

```bash

  curl -X GET \
    https://api.sign.qitech.com.br/sign/envelope/\{envelope_id\} \
    -H "Authorization: EXAMPLE_API_KEY"

```

如果请求成功，响应将是一个包含信封状态和签署人信息的 JSON，示例如下：

> 响应示例

```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"
        }
      ]
    }
  ]
}
```

- 信封状态可以是 `created`、`submitted`、`completed`、`canceled` 或 `expired`。

| 枚举值 | 描述 |
| :----------: | -------------------------------------------------------------------- |
|   created    | 信封已创建                                                      |
|  submitted   | 信封已发送以供签署                                     |
|  completed   | 信封的所有签署均已成功完成 |
|   canceled   | 信封因合作伙伴请求而取消                       |
|   expired    | 信封因签署时间超时而过期                            |

|      名称       |   类型   | 描述                                                                 |
| :-------------: | :------: | ------------------------------------------------------------------------- |
|       id        |  string  | 信封的唯一标识符。                                          |
|     status      |  string  | 信封状态。                                                       |
| expiration_date |  string  | 信封过期日期。                                            |
|     signers     |  Signer  | 描述信封签署人的 Signer 类型对象列表。   |
|    documents    | Document | 描述信封文件的 Document 类型对象列表。 |

## Webhook

当所有签署人完成签署并生成档案后，将通过 Webhook 发送通知。
为此，需要通过支持团队（suporte@qitech.com.br）配置接收更新通知的端点地址，以及用于签署请求的 _signature_key_。

客户也可以使用[轮询]( )技术，尽管不推荐。这种情况下，只需不配置 webhook 端点，并使用注册查询端点进行轮询即可。

## 签名

> Python 签名计算示例

```python
    hmac_obj = hmac.new(signature_key.encode('utf-8'), (endpoint + method + payload).encode('utf-8'), hashlib.sha1)
    return hmac_obj.hexdigest()
```

为确保 webhook 端点收到的请求来自我们的服务器，请求的 Header Signature 中会发送 HMAC 签名，类似于认证过程。

在服务器端计算出签名的预期值后，需要将计算出的签名与发送的签名进行比较。如果签名匹配，说明请求来自我们的服务器，是可信的。

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
      }
    }
  ]
}
```

|                   名称                    |  类型   | 描述                                                                        |
| :---------------------------------------: | :-----: | -------------------------------------------------------------------------------- |
|                    id                     | string  | 信封的唯一标识符。                                                 |
|                  status                   | string  | 信封状态。                                                              |
|                 signer.id                 | string  | 签署人的唯一标识符。                                                |
| signer.biometry.face_validation_available | boolean | 指示是否找到并验证了人脸。                                     |
|      signer.biometry.fraud_base_flag      | boolean | 指示签署人的人脸是否出现在欺诈数据库中。                 |
|   signer.biometry.face_validation_score   | integer | 指示人脸验证评分。                                              |
|          signer.liveness.result           | string  | 指示活体验证结果。可能的值为 `live` 或 `spoof` |
|     signer.document.face_match_score      | integer | 指示人脸匹配验证评分。                                       |

## 下载已签署的档案

如果所有签署人均已签署信封中的所有文件，信封状态将为 `completed`，每个文件的档案（包含签名和签署人数据）将可供下载。为此，请向端点 `/sign/envelope/\{envelope_id\}/report` 发送 `GET` 请求

```bash
  curl -X GET \
    https://api.sign.qitech.com.br/sign/envelope/\{envelope_id\}/report \
    -H "Authorization: EXAMPLE_API_KEY"

```

如果请求成功，响应将是一个包含信封 id 和状态，以及文件 id 和生成档案 URL 列表的 JSON，示例如下：

> 响应示例

```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"
    }
  ]
}
```

- 每个文件的报告链接有效期为 24 小时。
- 信封报告的状态可以是 `available` 或 `unavailable`。
- `documents_reports` 属性包含信封文件列表，通过文件 id 和报告链接标识。

## 按已签署文件下载档案

如果所有签署人均已签署信封中的所有文件，信封状态将为 `completed`，每个已签署文件的档案（包含签名和签署人数据）将可供下载。为此，请向端点 `/sign/envelope/\{envelope_id\}/document/{document_id}/report` 发送 `GET` 请求

```bash
  curl -X GET \
    https://api.sign.qitech.com.br/sign/envelope/\{envelope_id\}/document/{document_id}/report \
    -H "Authorization: EXAMPLE_API_KEY"

```

如果请求成功，响应将是一个包含 id、状态、URL 和文件档案 base64 的 JSON，示例如下：

> 响应示例

```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=..."
}
```

- 文件报告的链接有效期为 24 小时。
- 文件报告的状态可以是 `available` 或 `unavailable`。
- `document_report` 属性是以 base64 编码的 PDF 格式文件报告。

## 下载签署人的人脸照片

可以检索签署人的人脸图像。为此，请向端点 `/sign/envelope/\{envelope_id\}/signer/\{signer_id\}/face` 发送 `GET` 请求

```bash
  curl -X GET \
    https://api.sign.qitech.com.br/sign/envelope/\{envelope_id\}/signer/\{signer_id\}/face \
    -H "Authorization: EXAMPLE_API_KEY"

```

如果请求成功，响应将是一个包含 base64 编码图像的 JSON，示例如下：

> 响应示例

```json
{
  "face_image_url": "https://qisign-face-image.com/4fd09dab-6f3e-4ff5-bfed-6f7debfcde71.jpeg"
}
```

## 取消信封

要取消信封，请向端点 `/sign/envelope/\{envelope_id\}` 发送 `PATCH` 请求

```bash

  curl -X PATCH \
    https://api.sign.qitech.com.br/sign/envelope/\{envelope_id\} \
    -H "Authorization: EXAMPLE_API_KEY" \
    -d '{
      "status": "canceled"
    }'

```

如果请求成功，响应将是一个包含信封状态的 JSON，示例如下：

> 响应示例

```json
{
  "status": "canceled"
}
```

## 下载签署人的文件照片

可以检索签署人的文件图像。为此，请向端点 `/sign/envelope/\{envelope_id\}/signer/\{signer_id\}/personal_document` 发送 `GET` 请求

```bash
  curl -X GET \
    https://api.sign.qitech.com.br/sign/envelope/\{envelope_id\}/signer/\{signer_id\}/personal_document \
    -H "Authorization: EXAMPLE_API_KEY"

```

如果请求成功，响应将是一个包含 base64 编码图像的 JSON，示例如下：

> 响应示例

```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"
}
```

## 查询签署人状态

要查看签署人的状态，请向端点 /sign/envelope/\{envelope_id\}/signer/\{signer_id\} 发送 GET 请求

```bash

  curl -X GET \
    https://api.sign.qitech.com.br/sign/envelope/\{envelope_id\}/signer/\{signer_id\} \
    -H "Authorization: EXAMPLE_API_KEY"

```

如果请求成功，响应将是一个包含签署人状态的 JSON，示例如下：

> 响应示例

```json
{
  "name": "John Sample",
  "email": "johnsample@test.com",
  "status": "signed",
  "signed_at": "2023-03-21T15:30:00.000Z"
}
```

|   名称    |  类型  | 描述                                                               |
| :-------: | :----: | ----------------------------------------------------------------------- |
|   name    | string | 签署人姓名。                                                      |
|   email   | string | 签署人电子邮件。                                                    |
|  status   | string | 签署人签署状态。                                         |
| signed_at | string | 最近签署的日期和时间，格式为 `YYYY-MM-DDTHH:MM:SS.000Z`。 |

## HTTP 状态码

签名 API 使用以下 HTTP 返回状态标准，遵循 RFC 7231 ：

| HTTP 状态码 | 含义 | 描述 |
| ----------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400         | Bad Request           | 发送的请求存在格式错误。大多数情况下，我们会在消息正文中返回错误位置的说明。                                 |
| 401         | Unauthorized          | 认证出现问题，请检查 API Key 是否正确以及是否在正确的 header 中，参见<a href='#autenticacao'>认证</a>部分。                  |
| 403         | Forbidden             | 访问的端点为内部使用，该 API Key 无权使用。                                                                                                   |
| 404         | Not Found             | 使用提供的密钥未找到所请求的数据。当请求无效的端点时也会返回此状态。                                       |
| 405         | Method Not Allowed    | 使用的 HTTP 方法不适用于该端点。                                                                                                                    |
| 406         | Not Acceptable        | 请求正文中发送的数据无效。通常意味着发送的数据不是有效的 JSON。                                                  |
| 409         | Conflict              | 请求 ID 与之前已处理的 ID 对应。当向服务器发送重复请求时会返回此状态。                             |
| 500         | Internal Server Error | 处理此请求时出现问题，遇到此错误时，我们的专家将自动收到通知并立即开始分析和解决。 |
| 503         | Service Unavailable   | 您遇到了我们服务器基础设施的计划或非计划中断。                                                                           |

---

# 审批转账

URL: /zh-Hans/documentation/movimentacao_de_contas/aprovar_transferencia

ENDPOINT /wire_transfer_approval
方法 POST

## Body Params

| 字段 | 类型 | 描述 |
|---|---|---|
| `operation_key_list` | array | 待审批的操作 key 列表 |
| `feedback` | boolean | 审批结果：`true` 表示批准，`false` 表示拒绝 |

---

# 转账凭证

URL: /zh-Hans/documentation/movimentacao_de_contas/comprovante_de_transferencia

## Request

ENDPOINT /transaction_receipt/ TRANSACTION_KEY
MÉTODO GET

:::info

此请求的响应将返回所查询交易的相关数据。若参数 PDF 为 true，则 `pdf_encoded_string` 字段将以 base-64 编码的 PDF 字符串形式提供。
:::

### Request Path Params

| 字段                 | 类型    | 描述                      | 字符数 |
|---------------------|---------|---------------------------|--------|
| `transaction_key` * | uuidv4  | 交易唯一识别密钥。         | 36     |

### Request Query String Params

| 字段   | 类型    | 描述                              | 字符数 |
|-------|---------|-----------------------------------|--------|
| `pdf` * | boolean | 定义响应是否生成 PDF 的布尔值。  | -      |

## Response

### 成功响应

STATUS 200

**Response Body: Boleto 支付凭证**

```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": "<base64 encoded PDF string>"
}
```

**Response Body: 代收税款发票凭证**

```json
{
    "tax_collection": {
        "beneficiary": {
            "document_number": "03782617037",
            "document_number_formatted": "037.826.170-37",
            "name": "Beatriz Couto de Carvalho"
        },
        "payment_date": "2024-08-06",
        "payment_date_formatted": "06/08/2024",
        "payment_key": "ca944fbb-7f0f-42d7-b775-1014f5804155"
    },
    "origin_key": "ca944fbb-7f0f-42d7-b775-1014f5804155",
    "pdf_encoded_string": "<base64 encoded PDF string>"
}
```

**Response Body: TED 凭证**

```json
{
    "ted": {
        "payer": {
            "document_number": "32402502000135",
            "document_number_formatted": "32.402.502/0001-35",
            "name": "QI SCD S.A.",
            "account_branch": "0001",
            "account_number": "000002",
            "account_digit": "5"
        },
        "receiver": {
            "document_number": "12345678000195",
            "document_number_formatted": "12.345.678/0001-95",
            "name": "Empresa Destino",
            "account_branch": "0001",
            "account_number": "1234567",
            "account_digit": "8",
            "financial_institution_compe_number": "001",
            "financial_institution_name": "Banco do Brasil S.A."
        },
        "amount": 100.00,
        "amount_formatted": "R$ 100,00",
        "payment_date": "2024-08-06",
        "payment_date_formatted": "06/08/2024",
        "payment_key": "ca944fbb-7f0f-42d7-b775-1014f5804155"
    },
    "origin_key": "ca944fbb-7f0f-42d7-b775-1014f5804155",
    "pdf_encoded_string": "<base64 encoded PDF string>"
}
```

**Response Body: PIX 凭证**

```json
{
    "pix": {
        "payer": {
            "document_number": "32402502000135",
            "document_number_formatted": "32.402.502/0001-35",
            "name": "QI SCD S.A."
        },
        "receiver": {
            "document_number": "12345678000195",
            "document_number_formatted": "12.345.678/0001-95",
            "name": "Empresa Destino"
        },
        "amount": 100.00,
        "amount_formatted": "R$ 100,00",
        "payment_date": "2024-08-06",
        "payment_date_formatted": "06/08/2024",
        "payment_key": "ca944fbb-7f0f-42d7-b775-1014f5804155",
        "end_to_end_id": "E32402502202408061500Xl7fS6mvuFW"
    },
    "origin_key": "ca944fbb-7f0f-42d7-b775-1014f5804155",
    "pdf_encoded_string": "<base64 encoded PDF string>"
}
```

**Response Body: 银行卡消费凭证**

```json
{
    "card_purchase": {
        "card_holder": {
            "document_number": "32402502000135",
            "document_number_formatted": "32.402.502/0001-35",
            "name": "QI SCD S.A."
        },
        "merchant": {
            "name": "Nome do Estabelecimento",
            "mcc": "0000"
        },
        "amount": 17.00,
        "amount_formatted": "R$ 17,00",
        "transaction_date": "2024-08-06",
        "transaction_date_formatted": "06/08/2024",
        "transaction_key": "b71ea9a3-e012-4761-bea6-e65c6bfc228f",
        "authorization_code": "U3UUUU"
    },
    "origin_key": "b71ea9a3-e012-4761-bea6-e65c6bfc228f",
    "pdf_encoded_string": "<base64 encoded PDF string>"
}
```

### 错误响应

STATUS 4XX

Response Body

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

---

# 交易查询

URL: /zh-Hans/documentation/movimentacao_de_contas/consulta_de_transacoes

## Request

ENDPOINT /account/ ACCOUNT_KEY /transaction
MÉTODO GET

### Request Path Params

| 字段            | 类型   | 描述                         |
|----------------|--------|------------------------------|
| `account_key` * | string | QI 账户唯一识别密钥          |

### Query Params

| 字段        | 类型    | 描述                                               |
|------------|---------|---------------------------------------------------|
| `date_from` | string  | 开始日期。格式 "YYYY-MM-DD"                        |
| `date_to`   | string  | 结束日期。格式 "YYYY-MM-DD"                        |
| `order_by`  | string  | "asc" 升序或 "desc" 降序。默认为 "desc"            |
| `page`      | integer | 请求的页码。默认为 1                               |
| `page_size` | integer | 查询中请求的每页大小。默认为 4000                  |

## Response

### 成功响应

STATUS 200

:::info 关于 Transaction Details 字段

此字段是一个对象，包含所执行交易类型的具体信息（Boleto 支付、TED 或 Pix）。 

:::

Response Body: 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ÉDITO DIRETO S.A.",
            "origin_key": "4983e0ad-2212-44f9-8ab9-c243f72f90a8",
            "source_subtype": {
                "enumerator": "internal_pix_transfer",
                "translation_ptbr": "Transferência 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: 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ÉDITO 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: Boleto 支付交易

```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ÉDITO 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: 银行卡清算交易

```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: 银行卡消费交易

```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 关于 next_page 字段
`pagination` 对象中的 `next_page` 字段表示下一个可查询的页面。若无更多页面，返回值将为 `null`。
:::

:::caution 注意！
信用卡清算交易的 `transaction_details` 对象中的 `product_type` 字段由卡清算系统提供，可能返回 `null`。对于此类情况，应读取 `product_description` 字段以识别清算的 `product_type`。
:::

### product_type 枚举值
| 枚举值 | 描述                                                       |
|--------|-----------------------------------------------------------|
|ACC| American Express 信用卡                                    |
|BCC| Banescard 信用卡                                           |
|BCD| Banescard 借记卡                                           |
|BVV| Ben Visa Vale 预付卡                                       |
|CAC| Cielo Amex 信用卡                                          |
|CBC| Cabal 信用卡                                               |
|CBD| Cabal 借记卡                                               |
|CBP| Cabal 预付卡                                               |
|CC3| 信用让渡中心                                               |
|CDC| Cielo Diners 信用卡                                        |
|CEC| Cielo Elo 信用卡                                           |
|CED| Cielo Elo 借记卡                                           |
|CHC| Cielo Hipercard 信用卡                                     |
|CMC| Cielo Mastercard 信用卡                                    |
|CMD| Cielo Mastercard 借记卡                                    |
|COP| COPASA - 米纳斯吉拉斯州卫生公司                             |
|CUP| Cup 信用卡                                                 |
|CZC| Credz 信用卡                                               |
|DCC| Diners 跨境清算信用卡                                      |
|ECB| Elo PAT - 福利卡                                           |
|ECC| Elo 信用卡                                                 |
|ECD| Elo 借记卡                                                 |
|GCC| Goodcard 信用卡                                            |
|GDC| Global Payments Diners 信用卡                              |
|GMC| Global Payments MasterCard 信用卡                          |
|GMD| Global Payments MasterCard 借记卡                          |
|GVC| Global Payments VISA 信用卡                                |
|GVD| Global Payments VISA 借记卡                                |
|HCC| Hipercard 信用卡                                           |
|HCD| Hiper 借记卡                                               |
|JCC| JCB 信用卡                                                 |
|MAC| Mais 信用卡                                                |
|MCA| MasterCard ATM 卡                                          |
|MCC| Mastercard 信用卡                                          |
|MCD| Maestro 借记卡                                             |
|MCP| Mastercard 预付卡                                          |
|NBA| Neoenergia - 巴伊亚州电力公司                              |
|NBR| Neoenergia - 巴西利亚配电公司                              |
|NEK| Neoenergia - Elektro Redes S/A                            |
|NPE| Neoenergia - 伯南布哥州能源公司                            |
|NRN| Neoenergia - 北里奥格朗德州能源公司                        |
|OCD| Ourocard 借记卡                                            |
|OT| 其他转账清算产品                                           |
|PCA| 集中征收平台                                               |
|SCC| Sorocred 信用卡                                            |
|SCD| Sorocred 借记卡                                            |
|SLC| 集中清算服务                                               |
|STC| SELTEC                                                    |
|TCB| Tecban                                                    |
|TED| TED 清算产品                                               |
|VCA| Visa ATM 卡                                                |
|VCC| Visa 信用卡                                                |
|VCD| Visa Electron 借记卡                                       |
|VCP| Visa 预付卡                                                |
|VDC| Verdecard 信用卡                                           |
|VDP| Verdecard 预付卡                                           |
|VIA| Visa 国际 ATM 取款                                         |
|VIC| Visa 国际信用购物                                          |
|VID| Visa 国际借记购物                                          |
||Alelo 预付卡|
||Agiplan 信用卡|
||Aura 信用卡|
||Calcard 信用卡|
||Credsystem 信用卡|
||Redesplan 信用卡|
||Sicred 信用卡|
||Avista 信用卡|
||Discover 信用卡|
||Sicredi 借记卡|
||Hiper 信用卡|
||Ticket 预付卡|
||Sodexo 预付卡|
||VR 预付卡|
||Policard 预付卡|
||Valecard 预付卡|
||Greencard 预付卡|
||Coopercard 预付卡|
||Verocheque 预付卡|
||Nutricash 预付卡|
||Banricard 预付卡|
||Socored 预付卡|
||Cielo 封闭安排信用卡|
||Cielo 封闭安排借记卡|

### source_sub_types 枚举值:

| 枚举值                                  | 描述                                            |
|-----------------------------------------|-------------------------------------------------|
| operation_disbursement                  | 操作放款                                        |
| protest_expense                         | 抗议费用                                        |
| automatic_integrated_payment            | 自动集成支付                                    |
| tax                                     | 税款                                            |
| electronic_funds_fee                    | TED 手续费                                      |
| credit_operation_fee                    | 信贷开户手续费                                  |
| internal_funds_transfer                 | 内部转账                                        |
| incoming_funds_transfer                 | 入账转账                                        |
| outgoing_funds_transfer                 | TED                                             |
| deposit                                 | 存款                                            |
| withdrawal                              | 转账                                            |
| withdrawal_reversal                     | 转账冲销                                        |
| trade_funds_transfer                    | 让渡支付转账                                    |
| settlement_funds_transfer               | 清算转账                                        |
| bank_slip_fee                           | Boleto 手续费                                   |
| bank_slip_settlement                    | Boleto 清算                                     |
| outgoing_funds_transfer_reversal        | TED 冲销                                        |
| incoming_funds_transfer_refusal         | 转账被拒                                        |
| electronic_funds_fee_reversal           | TED 手续费冲销                                  |
| monthly_account_fee_reversal            | 账户维护费冲销                                  |
| bank_slip_fee_reversal                  | Boleto 手续费冲销                               |
| correspondent_bank_transfer             | 银行代理转账                                    |
| credit_analysis_fee                     | 信贷分析手续费                                  |
| credit_operation_fee_reversal           | 信贷开户手续费冲销                              |
| financial_investments_income            | 金融投资收益                                    |
| bank_slip_settlement_reversal           | Boleto 清算冲销                                 |
| bank_slip_settlement_expense_reversal   | Boleto 清算手续费冲销                           |
| bank_slip_settlement_incoming_reversal  | Boleto 清算收款冲销                             |
| correspondent_bank_transfer_reversal    | 银行代理转账冲销                                |
| credit_analysis_fee_reversal            | 信贷分析手续费冲销                              |
| doc_expense_reversal                    | DOC 手续费冲销                                  |
| incoming_doc_reversal                   | DOC 入账冲销                                    |
| operation_disbursement_reversal         | 操作放款冲销                                    |
| operation_settling_reversal             | 操作付款冲销                                    |
| outgoing_doc_reversal                   | DOC 出账冲销                                    |
| rebate_reversal                         | 返点冲销                                        |
| settlement_funds_transfer_reversal      | 清算转账冲销                                    |
| tax_reversal                            | 税款冲销                                        |
| trade_funds_transfer_reversal           | 让渡支付转账冲销                                |
| bank_slip_permanency_fee                | 票据保留手续费                                  |
| bank_slip_cancel_protest_fee            | 票据保留手续费                                  |
| bank_slip_protest_fee                   | 申请抗议手续费                                  |
| bank_slip_notary_office_fee             | 公证处抗议费用                                  |
| bank_slip_registration_fee              | 登记手续费                                      |
| bank_slip_extension_fee                 | 延期手续费                                      |
| bank_slip_rebate_fee                    | 折扣手续费                                      |
| bank_slip_discount_fee                  | 折扣手续费                                      |
| bank_slip_settlement_fee                | 清算手续费                                      |
| bank_slip_write_off_term_fee            | 到期注销手续费                                  |
| bank_slip_write_off_fee                 | 注销手续费                                      |
| bank_slip_cancel_protest_write_off_fee  | 中止抗议并注销手续费                            |
| bank_slip_notary_office_settlement_fee  | 公证处清算手续费                                |
| rebate_tax_free                         | 代收转付                                        |
| rebate_tax_free_reversal                | 代收转付冲销                                    |
| incoming_funds_transfer_reversal        | 内部转账冲销                                    |
| bank_slip_payment                       | Boleto 支付                                     |
| bank_slip_payment_reversal              | Boleto 支付冲销                                 |
| warranty_analysis_fee                   | 担保分析手续费                                  |
| bank_slip_settlement_deposit            | Boleto 清算                                     |
| bank_slip_payment_withdrawal            | Boleto 支付                                     |
| account_setup_fee                       | 开户手续费                                      |
| account_setup_fee_reversal              | 开户手续费冲销                                  |
| bank_slip_payment_withdrawal_reversal   | Boleto 支付冲销                                 |
| incoming_anticipation_of_receivable     | -                                               |
| incoming_credit_card_settlement         | 信用卡清算                                      |
| incoming_debit_card_settlement          | 借记卡清算                                      |
| assignment_automatic_transfer           | 自动让渡扣款                                    |
| assignment_automatic_transfer_reversal  | 自动让渡扣款冲销                                |
| pix_fee                                 | PIX 手续费                                      |
| incoming_pix_transfer                   | PIX 入账                                        |
| outgoing_pix_transfer                   | PIX 出账                                        |
| pix_fee_reversal                        | PIX 手续费冲销                                  |
| incoming_pix_transfer_reversal          | PIX 入账冲销                                    |
| outgoing_pix_transfer_reversal          | PIX 出账冲销                                    |
| pix_deposit                             | PIX 存款                                        |
| pix_withdrawal                          | PIX 转账                                        |
| pix_withdrawal_reversal                 | PIX 转账冲销                                    |
| pix_chargeback_withdrawal               | 发送 PIX 退款                                   |
| outgoing_pix_chargeback                 | PIX 退款出账                                    |
| incoming_pix_chargeback                 | 收到 PIX 退款                                   |
| pix_chargeback_deposit                  | PIX 退款入账                                    |
| pix_chargeback_withdrawal_reversal      | 发送 PIX 退款冲销                               |
| outgoing_pix_chargeback_reversal        | PIX 退款出账冲销                                |
| incoming_pix_chargeback_reversal        | 收到 PIX 退款冲销                               |
| operation_pix_disbursement              | 操作 PIX 放款                                   |
| operation_pix_disbursement_reversal     | 操作 PIX 放款冲销                               |
| receivables_inquiry_fee                 | 应收账款查询手续费                              |
| pix_deposit_reversal                    | PIX 存款冲销                                    |
| internal_pix_transfer                   | PIX 转账                                        |
| automatic_integrated_payment_reversal   | 自动集成支付冲销                                |
| operation_dibursement_reversal          | 操作放款冲销                                    |
| available_yield                         | 流动性投资存款                                  |
| bank_slip_convenant_payment             | 协议 Boleto 支付                                |

### prepaid_card_transaction_type 枚举值:
| 枚举值                   | 描述                      |
|-------------------------|---------------------------|
| purchase                | 刷卡消费                  |
| international_purchase  | 国际刷卡消费              |
| withdrawal              | ATM 取款                  |

### card_type 枚举值:
| 枚举值    | 描述       |
|----------|------------|
| plastic  | 实体卡     |
| virtual  | 虚拟卡     |

---

# 查询待处理交易

URL: /zh-Hans/documentation/movimentacao_de_contas/consulta_de_transacoes_pendentes

ENDPOINT /pending_movement
方法 GET

## 响应字段

响应中包含 `movement_request_list`，其中每条记录包含以下字段：

| 字段 | 类型 | 描述 |
|---|---|---|
| `account_key` | string | 账户的唯一标识符 |
| `movement_amount` | float | 交易金额 |
| `movement_data` | object | 交易相关数据 |
| `movement_status` | string | 交易状态 |
| `movement_type` | string | 交易类型 |
| `requester_key` | string | 请求者的唯一标识符 |

---

# 查询已完成转账

URL: /zh-Hans/documentation/movimentacao_de_contas/consulta_de_transferencias_realizadas

ENDPOINT /account_statement
方法 GET

## Query Params

| 字段 | 类型 | 描述 |
|---|---|---|
| `account_key` | string | 账户的唯一标识符 |
| `date_from` | string | 查询起始日期（格式 "YYYY-MM-DD"）|
| `date_to` | string | 查询结束日期（格式 "YYYY-MM-DD"）|
| `page` | int | 页码 |
| `page_size` | int | 每页记录数 |
| `order_by` | string | 排序字段 |

## 响应

响应中包含 `account_info`（账户信息）和 `transaction_list`（交易列表）。

---

# 发起转账

URL: /zh-Hans/documentation/movimentacao_de_contas/realizar_transferencia

ENDPOINT /wire_transfer
方法 POST

## Body Params

| 字段 | 类型 | 描述 |
|---|---|---|
| `source_account` | object | 转出账户信息 |
| `target_account` | object | 转入账户信息 |
| `transaction_amount` | float | 转账金额 |
| `schedule_date` | string | 计划转账日期（可选，格式 "YYYY-MM-DD"）|

### source_account / target_account 对象

| 字段 | 类型 | 描述 |
|---|---|---|
| `branch` | string | 支行号 |
| `number` | string | 账号 |
| `digit` | string | 验证位 |
| `owner_document` | string | 账户持有人 CPF 或 CNPJ |
| `owner_name` | string | 账户持有人姓名 |

---

# 模拟交易

URL: /zh-Hans/documentation/movimentacao_de_contas/transacao

此文档介绍如何在测试环境中模拟外部代理操作，以触发内部交易。

## 内部交易

ENDPOINT /mock/account/transaction
方法 POST

## 传入 TED

ENDPOINT /mock/ted/incoming_ted
方法 POST

## TED 拒绝

ENDPOINT /mock/ted/ted_refusal
方法 POST

---

# Webhooks

URL: /zh-Hans/documentation/movimentacao_de_contas/webhook_movimentacoes

:::danger 注意！
QI Tech 的 Webhook 不应进行严格映射。
我们 API 返回的 Webhook 载荷中可能会新增额外字段。
:::

:::info 重新发送 Webhook
您可以按照文档中的详细说明查询和重新发送 Webhook：[重新发送 Webhook](/documentation/notificacoes/reenvio_de_notificacoes)。
:::

## 账户变动 Webhook
任何账户变动都将发送 "***account_transaction***" Webhook。

每笔交易都有一个分类类型（**Source Sub Type**）。该分类用于对账户中的每笔变动进行归类。Source Sub Type 列表如下所示。

### 账户入账

账户入账将产生 `data.amount` 为正值的 Webhook，其中 `data.origin` 为资金来源账户，`data.destination` 为资金目标账户：

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: 其他交易

```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"
}
```

## 账户出账
账户出账将产生 `data.amount` 为负值的 Webhook，其中 `data.origin` 为资金目标账户，`data.destination` 为资金来源账户：

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"
}
```
 

**source_sub_types 列表：**

| 枚举值                                  | 描述                                            |
|-----------------------------------------|-------------------------------------------------|
| operation_disbursement                  | 操作放款                                        |
| protest_expense                         | 抗议费用                                        |
| automatic_integrated_payment            | 自动集成支付                                    |
| tax                                     | 税款                                            |
| electronic_funds_fee                    | TED 手续费                                      |
| credit_operation_fee                    | 信贷开户手续费                                  |
| internal_funds_transfer                 | 内部转账                                        |
| incoming_funds_transfer                 | 入账转账                                        |
| outgoing_funds_transfer                 | TED                                             |
| deposit                                 | 存款                                            |
| withdrawal                              | 转账                                            |
| withdrawal_reversal                     | 转账冲销                                        |
| trade_funds_transfer                    | 让渡支付转账                                    |
| settlement_funds_transfer               | 清算转账                                        |
| bank_slip_fee                           | Boleto 手续费                                   |
| bank_slip_settlement                    | Boleto 清算                                     |
| outgoing_funds_transfer_reversal        | TED 冲销                                        |
| incoming_funds_transfer_refusal         | 转账被拒                                        |
| electronic_funds_fee_reversal           | TED 手续费冲销                                  |
| monthly_account_fee_reversal            | 账户维护费冲销                                  |
| bank_slip_fee_reversal                  | Boleto 手续费冲销                               |
| correspondent_bank_transfer             | 银行代理转账                                    |
| credit_analysis_fee                     | 信贷分析手续费                                  |
| credit_operation_fee_reversal           | 信贷开户手续费冲销                              |
| financial_investments_income            | 金融投资收益                                    |
| bank_slip_settlement_reversal           | Boleto 清算冲销                                 |
| bank_slip_settlement_expense_reversal   | Boleto 清算手续费冲销                           |
| bank_slip_settlement_incoming_reversal  | Boleto 清算收款冲销                             |
| correspondent_bank_transfer_reversal    | 银行代理转账冲销                                |
| credit_analysis_fee_reversal            | 信贷分析手续费冲销                              |
| doc_expense_reversal                    | DOC 手续费冲销                                  |
| incoming_doc_reversal                   | DOC 入账冲销                                    |
| operation_disbursement_reversal         | 操作放款冲销                                    |
| operation_settling_reversal             | 操作付款冲销                                    |
| outgoing_doc_reversal                   | DOC 出账冲销                                    |
| rebate_reversal                         | 返点冲销                                        |
| settlement_funds_transfer_reversal      | 清算转账冲销                                    |
| tax_reversal                            | 税款冲销                                        |
| trade_funds_transfer_reversal           | 让渡支付转账冲销                                |
| bank_slip_permanency_fee                | 票据保留手续费                                  |
| bank_slip_cancel_protest_fee            | 票据保留手续费                                  |
| bank_slip_protest_fee                   | 申请抗议手续费                                  |
| bank_slip_notary_office_fee             | 公证处抗议费用                                  |
| bank_slip_registration_fee              | 登记手续费                                      |
| bank_slip_extension_fee                 | 延期手续费                                      |
| bank_slip_rebate_fee                    | 折扣手续费                                      |
| bank_slip_discount_fee                  | 折扣手续费                                      |
| bank_slip_settlement_fee                | 清算手续费                                      |
| bank_slip_write_off_term_fee            | 到期注销手续费                                  |
| bank_slip_write_off_fee                 | 注销手续费                                      |
| bank_slip_cancel_protest_write_off_fee  | 中止抗议并注销手续费                            |
| bank_slip_notary_office_settlement_fee  | 公证处清算手续费                                |
| rebate_tax_free                         | 代收转付                                        |
| rebate_tax_free_reversal                | 代收转付冲销                                    |
| incoming_funds_transfer_reversal        | 内部转账冲销                                    |
| bank_slip_payment                       | Boleto 支付                                     |
| bank_slip_payment_reversal              | Boleto 支付冲销                                 |
| warranty_analysis_fee                   | 担保分析手续费                                  |
| bank_slip_settlement_deposit            | Boleto 清算                                     |
| bank_slip_payment_withdrawal            | Boleto 支付                                     |
| account_setup_fee                       | 开户手续费                                      |
| account_setup_fee_reversal              | 开户手续费冲销                                  |
| bank_slip_payment_withdrawal_reversal   | Boleto 支付冲销                                 |
| incoming_anticipation_of_receivable     | -                                               |
| incoming_credit_card_settlement         | 信用卡清算                                      |
| incoming_debit_card_settlement          | 借记卡清算                                      |
| assignment_automatic_transfer           | 自动让渡扣款                                    |
| assignment_automatic_transfer_reversal  | 自动让渡扣款冲销                                |
| pix_fee                                 | PIX 手续费                                      |
| incoming_pix_transfer                   | PIX 入账                                        |
| outgoing_pix_transfer                   | PIX 出账                                        |
| pix_fee_reversal                        | PIX 手续费冲销                                  |
| incoming_pix_transfer_reversal          | PIX 入账冲销                                    |
| outgoing_pix_transfer_reversal          | PIX 出账冲销                                    |
| pix_deposit                             | PIX 存款                                        |
| pix_withdrawal                          | PIX 转账                                        |
| pix_withdrawal_reversal                 | PIX 转账冲销                                    |
| pix_chargeback_withdrawal               | 发送 PIX 退款                                   |
| outgoing_pix_chargeback                 | PIX 退款出账                                    |
| incoming_pix_chargeback                 | 收到 PIX 退款                                   |
| pix_chargeback_deposit                  | PIX 退款入账                                    |
| pix_chargeback_withdrawal_reversal      | 发送 PIX 退款冲销                               |
| outgoing_pix_chargeback_reversal        | PIX 退款出账冲销                                |
| incoming_pix_chargeback_reversal        | 收到 PIX 退款冲销                               |
| operation_pix_disbursement              | 操作 PIX 放款                                   |
| operation_pix_disbursement_reversal     | 操作 PIX 放款冲销                               |
| receivables_inquiry_fee                 | 应收账款查询手续费                              |
| pix_deposit_reversal                    | PIX 存款冲销                                    |
| internal_pix_transfer                   | PIX 转账                                        |
| automatic_integrated_payment_reversal   | 自动集成支付冲销                                |
| operation_dibursement_reversal          | 操作放款冲销                                    |
| available_yield                         | 流动性投资存款                                  |
| bank_slip_convenant_payment             | 协议 Boleto 支付                                |

## 账户冻结 Webhook

账户冻结 Webhook 在特定金额被冻结或解冻时发送。`origin_type` 字段标识冻结来源类型。

冻结时，`blocked_balance` 为正值。解冻时，值为负数，表示之前冻结金额的释放。

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

| 字段               | 类型   | 描述                                   | 最大字符数                                   |
|-------------------|--------|----------------------------------------|----------------------------------------------|
| webhook_type      | string | 定义报告事件类型的枚举值               | 23                                           |
| blocked_balance   | string | Webhook 发送日期和时间                 | 20                                           |
| data              | string | 司法令相关数据                         | **[data 对象](#objeto-data)**                |

#### data 对象
| 字段               | 类型   | 描述                                   | 最大字符数                                               |
|-------------------|--------|----------------------------------------|----------------------------------------------------------|
| account_key       | string | QI 账户唯一识别密钥                    | 36                                                       |
| blocked_balance   | number | 冻结余额                               | 15                                                       |
| origin_key        | string | 司法令来源唯一识别密钥                 | 36                                                       |
| origin_type       | string | 司法令来源                             | **[origin_type 枚举值](#enumeradores-origin_type)**      |
| block_details     | string | 冻结详情                               | **[block_details 对象](#objeto-block_details)**          |

#### block_details 对象
| 字段                          | 类型       | 描述                       | 最大字符数                                                   |
|------------------------------|------------|----------------------------|--------------------------------------------------------------|
| block_order_protocol         | number     | 司法冻结令协议号           | 14                                                           |
| block_order_sequence         | number     | 冻结序列号                 | 5                                                            |
| requester_judge              | string     | 法官                       | 115                                                          |
| defendant_document_number    | number     | 被告文件号                 | 14                                                           |
| case_number                  | number     | 案件编号                   | 30                                                           |
| court_code                   | string     | 负责法院代码               | 5                                                            |
| requested_amount             | number     | 申请冻结金额               | 15                                                           |
| lawsuit_author_name          | string     | 诉讼原告姓名               | 115                                                          |
| institution_document_number  | number     | 机构文件号                 | 14                                                           |
| lawsuit_type                 | enumerator | 诉讼类型                   | **[lawsuit_type 枚举值](#enumeradores-lawsuit_type)**        |
| protocol_datetime            | string     | 冻结令日期和时间           | 20                                                           |

#### lawsuit_type 枚举值
| 枚举值    | 描述       |
|----------|------------|
| civil    | 民事诉讼   |
| criminal | 刑事诉讼   |
| labor    | 劳动诉讼   |
| tax      | 税务诉讼   |
| food     | 抚养诉讼   |

#### origin_type 枚举值
| 枚举值                        | 类型   | 描述               |
|------------------------------|--------|--------------------|
| `credit_operation`           | string | 信贷操作           |
| `credit_operation_installment` | string | 信贷分期还款       |
| `wallet_trade`               | string | 钱包操作           |
| `wallet_settlement`          | string | 钱包清算           |
| `ted_incoming`               | string | 收到 TED           |
| `ted_outgoing`               | string | 发送 TED           |
| `bank_slip_expense`          | string | Boleto 费用        |
| `bank_slip`                  | string | Boleto             |
| `bank_slip_cnab`             | string | CNAB Boleto        |
| `future_transaction`         | string | 未来交易           |
| `internal_operation`         | string | 内部操作           |
| `lego`                       | string | Lego               |
| `siloc`                      | string | SILOC              |
| `bank_slip_payment`          | string | Boleto 支付        |
| `movement_request`           | string | 变动申请           |
| `slc`                        | string | SLC                |
| `julius`                     | string | Julius             |
| `batch_disbursement`         | string | 批量放款           |
| `card_transaction`           | string | 银行卡交易         |
| `credit_transfer`            | string | 信贷转账           |
| `pix_outgoing`               | string | 发送 PIX           |
| `pix_incoming`               | string | 收到 PIX           |
| `collateral`                 | string | 担保               |
| `celcoin`                    | string | Celcoin            |
| `investment`                 | string | 投资               |
| `routing`                    | string | 路由               |
| `c3`                         | string | C3                 |
| `billing`                    | string | 账单               |
| `disbursement`               | string | 放款               |
| `rebate`                     | string | 返点               |
| `card_invoice`               | string | 信用卡账单         |
| `b3_operation`               | string | B3 操作            |
| `bill_payment`               | string | 账单支付           |
| `med`                        | string | MED                |
| `peer_to_peer`               | string | 对等转账           |
| `settlement_notification`    | string | 清算通知           |
| `reversal_notification`      | string | 冲销通知           |
| `insurance_premium`          | string | 保险费             |
| `liquidation`                | string | 清算               |
| `purchase`                   | string | 购买               |
| `lending_billing`            | string | 贷款账单           |
| `lending_rebate`             | string | 贷款返点           |
| `sisbajud`                   | string | SISBAJUD           |

#### lawsuit_type 枚举值
| 枚举值    | 类型   | 描述       |
|----------|--------|------------|
| `civil`    | string | 民事诉讼   |
| `criminal` | string | 刑事诉讼   |
| `labor`    | string | 劳动诉讼   |
| `tax`      | string | 税务诉讼   |
| `food`     | string | 抚养诉讼   |

## 账户封锁 Webhook

账户封锁 Webhook 在账户被封锁时发送。

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"
  }
}
```

**block_reason 列表**：

| 值                                   | 描述                         |
|--------------------------------------|------------------------------|
| `judicially_suspended`              | 司法令冻结                   |
| `pawn`                              | 质押冻结                     |
| `pending_fee`                       | 待缴手续费冻结               |
| `missing_credit_operation_payment`  | 未支付信贷操作款项冻结       |
| `pending_setup_payment`             | 未支付开户手续费冻结         |
| `fraud`                             | 涉嫌欺诈冻结                 |

---

# 通知配置

URL: /zh-Hans/documentation/notificacoes/configuracao_de_notificacao

## 创建通知配置

ENDPOINT /notification_configuration
方法 POST

## 查询通知配置列表

ENDPOINT /notification_configuration
方法 GET

## 更新通知配置

ENDPOINT /notification_configuration/CONFIGURATION_KEY
方法 PATCH

## Body Params

| 字段 | 类型 | 描述 |
|---|---|---|
| `callback` | boolean | 是否启用 webhook 回调通知 |
| `email` | boolean | 是否启用电子邮件通知 |
| `sms` | boolean | 是否启用 SMS 通知 |
| `event_type` | string | 事件类型 |

---

# 模板配置

URL: /zh-Hans/documentation/notificacoes/configuracao_template

此文档说明如何管理事件的 SMS 和电子邮件模板，包括创建、查询和更新操作。

## 创建模板

ENDPOINT /notification_template
方法 POST

## 查询模板列表

ENDPOINT /notification_template
方法 GET

## 更新模板

ENDPOINT /notification_template/TEMPLATE_KEY
方法 PATCH

:::info 电子邮件模板

电子邮件模板内容应为 HTML，并以 base64 格式编码后发送。

:::

---

# 通知简介

URL: /zh-Hans/documentation/notificacoes/introducao

QI Tech 提供个性化通知管理系统，允许您为不同事件配置通知渠道和消息内容。

## 可用渠道

- **电子邮件**：发送电子邮件通知
- **SMS**：发送短信通知
- **Webhook**：通过回调 URL 接收通知

## 功能特点

- 灵活选择每种事件类型的通知渠道
- 通过自定义模板个性化消息内容
- 对特定事件类型进行精细化控制

---

# 重发 Webhook

URL: /zh-Hans/documentation/notificacoes/reenvio_de_notificacoes

## 查询可重发的事件

ENDPOINT /webhook/event
方法 GET

### Query Params

| 字段 | 类型 | 描述 |
|---|---|---|
| `event_type` | string | 事件类型 |
| `callback_status` | string | 回调状态 |
| `origin_key` | string | 事件来源 key |
| `start_datetime` | string | 查询开始时间 |
| `end_datetime` | string | 查询结束时间（与开始时间的间隔不超过 14 天）|

## 重发特定 Webhook

ENDPOINT /webhook/event/EVENT_KEY
方法 PATCH

此操作将重新发送指定的 webhook 回调。

---

# 通知模板

URL: /zh-Hans/documentation/notificacoes/template

## 创建模板

此功能允许创建用于 SMS 和电子邮件通知的自定义模板。

### 自定义变量

可以使用 `[variable_name]` 格式在模板中插入自定义变量。例如：

```
您好 [client_name]，您的交易已完成。金额：[transaction_amount]
```

:::info 电子邮件模板

电子邮件模板必须为 HTML 格式，并以 **base64** 编码后发送。

:::

---

# 事件类型

URL: /zh-Hans/documentation/notificacoes/tipos_de_evento

## 查询可用事件类型

ENDPOINT /notification/event_type
方法 GET

此端点用于查询可用的事件类型，并了解每种事件类型支持哪些通知方式（SMS、电子邮件、回调）以及可使用哪些自定义变量。

## 响应字段

| 字段 | 类型 | 描述 |
|---|---|---|
| `event_type` | string | 事件类型标识符 |
| `sms_allowed` | boolean | 是否允许 SMS 通知 |
| `email_allowed` | boolean | 是否允许电子邮件通知 |
| `callback_allowed` | boolean | 是否允许 webhook 回调通知 |
| `available_variables` | array | 该事件类型可用的自定义变量列表 |

---

# Address 对象

URL: /zh-Hans/documentation/objetos_compartilhados/address

`address` 对象用于各类 API 中表示地址信息。该结构在所有端点中均已标准化。

## 结构

| 字段 | 类型 | 必填 | 描述 |
|-|-|-|-|
| `street` | string | 是 | 街道名称。 |
| `number` | string | 是 | 门牌号。 |
| `complement` | string | 否 | 补充信息。 |
| `neighborhood` | string | 是 | 街区/社区。 |
| `city` | string | 是 | 城市。 |
| `state` | string | 是 | 州代码（2字符缩写）。 |
| `postal_code` | string | 是 | 邮政编码（格式 `XXXXXXXX`，无连字符）。 |

## 示例

```json
{
  "street": "Rua Example",
  "number": "123",
  "complement": "Sala 1",
  "neighborhood": "Centro",
  "city": "São Paulo",
  "state": "SP",
  "postal_code": "01001000"
}
```

## 使用此对象的端点

- [开设个人账户 (BaaS)](/documentation/baas/escrow/abrir_conta_pf)
- [开设企业账户 (BaaS)](/documentation/baas/escrow/abrir_conta_pj)
- [投资者注册 (IaaS)](/documentation/iaas/investidor/cadastro/criar_investidor)
- [债务发行](/documentation/emissao_de_divida/simulacao_de_divida/simulacao_de_divida)

---

# Borrower 对象

URL: /zh-Hans/documentation/objetos_compartilhados/borrower

`borrower` 对象代表债务操作中的信贷借款人。用于 Lending-as-a-Service 的多个端点。

## 结构 — 自然人 (natural_person)

| 字段 | 类型 | 必填 | 描述 |
|-|-|-|-|
| `person_type` | string | 是 | 人员类型。值：`natural` 或 `legal`。 |
| `name` | string | 是 | 借款人全名。 |
| `document_number` | string | 是 | CPF（11位数字，无标点）。 |
| `mother_name` | string | 否 | 母亲姓名。 |
| `birth_date` | string | 否 | 出生日期（格式 `YYYY-MM-DD`）。 |
| `nationality` | string | 否 | 国籍。 |
| `gender` | string | 否 | 性别。值：`male`、`female`。 |
| `email` | string | 否 | 借款人电子邮件。 |
| `phone` | object | 否 | [phone](#phone) 对象。 |
| `address` | object | 否 | [address](/documentation/objetos_compartilhados/address) 对象。 |

## 结构 — 法人 (legal_person)

| 字段 | 类型 | 必填 | 描述 |
|-|-|-|-|
| `person_type` | string | 是 | 值：`legal`。 |
| `company_name` | string | 是 | 公司注册名称。 |
| `trading_name` | string | 否 | 商业名称。 |
| `document_number` | string | 是 | CNPJ（14位数字，无标点）。 |
| `foundation_date` | string | 否 | 成立日期（格式 `YYYY-MM-DD`）。 |
| `email` | string | 否 | 企业电子邮件。 |
| `phone` | object | 否 | [phone](#phone) 对象。 |
| `address` | object | 否 | [address](/documentation/objetos_compartilhados/address) 对象。 |

## Phone

| 字段 | 类型 | 必填 | 描述 |
|-|-|-|-|
| `country_code` | string | 是 | 国家代码（如 `"55"`）。 |
| `area_code` | string | 是 | 区号（如 `"11"`）。 |
| `number` | string | 是 | 电话号码。 |

## 示例

```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"
  }
}
```

---

# Disbursement Account 对象

URL: /zh-Hans/documentation/objetos_compartilhados/disbursement_account

`disbursement_account` 对象代表信贷操作中用于资金放款的银行账户。

## 结构

| 字段 | 类型 | 必填 | 描述 |
|-|-|-|-|
| `account_branch` | string | 是 | 银行机构号（不含检验位）。 |
| `account_digit` | string | 是 | 账户检验位。 |
| `account_number` | string | 是 | 账户号（不含检验位）。 |
| `document_number` | string | 是 | 账户持有人的 CPF/CNPJ。 |
| `financial_institution_code` | string | 是 | 金融机构的 ISPB 或 COMPE 代码。 |
| `name` | string | 是 | 账户持有人姓名。 |
| `account_type` | string | 是 | 账户类型。值：`checking_account`、`savings_account`、`payment_account`。 |

## 示例

```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"
}
```

## 使用此对象的端点

- [债务模拟](/documentation/emissao_de_divida/simulacao_de_divida/simulacao_de_divida)
- [授权放款](/documentation/emissao_de_divida/autorizar_desembolso)
- [私人代扣](/documentation/manual_consignado_privado/criacao_da_operacao)

---

# Financial Institution 对象

URL: /zh-Hans/documentation/objetos_compartilhados/financial_institution

`financial_institution` 对象标识参与操作的金融机构。

## 结构

| 字段 | 类型 | 必填 | 描述 |
|-|-|-|-|
| `ispb_code` | string | 是 | 金融机构的 ISPB 代码（8位数字）。 |
| `compe_code` | string | 否 | 金融机构的 COMPE 代码（3位数字）。 |
| `name` | string | 否 | 金融机构名称。 |

## 示例

```json
{
  "ispb_code": "32402502",
  "compe_code": "329",
  "name": "QI Sociedade de Crédito Direto S.A."
}
```

## 参考

有关金融机构及其代码的完整列表，请参阅[金融机构列表](/documentation/lista_de_instituicoes_financeiras)。

---

# 银行单据（Boletos）运营手册

URL: /zh-Hans/documentation/operational_guide/boletos

## 收款类型

### 银行单据（Boletos bancários）

银行单据是由金融机构应在该机构开设账户的个人或法人请求而发行的收款工具。

这些收款工具由金融机构注册在巴西中央化应收账款平台（[PCR - Nuclea](https://www.nuclea.com.br/plataforma-centralizada-de-recebiveis/)）中。

### 征税凭单与税款

征税凭单是用于征收/接收州、市、联邦税款/费用以及公共服务（如电力、用水、电话和燃气）特许经营商账单的收款工具。

每个征收协议/机构都有其自己的付款时间/日期规定。您可以通过此[链接](https://storage.googleapis.com/live-doc-api/public_samples/active_covenants.xlsx)查看协议和时间列表。

:::caution 注意！
QI Tech 仅对含有可打印行（linha digitável）或条形码的征税凭单进行付款。
:::

## 付款

要支付银行单据或征税凭单，只需提供付款来源账户、待支付的银行单据/凭单的可打印行以及应执行付款的日期。

以下列出了在 QI Tech 内支付银行单据、征税凭单和税款的时间：

| 单据金额        | 时间        | 可用性   |
|------------------------|----------------|-------------------|
| 至 R$ 249,999.99      | 06:00 至 22:00 | 仅工作日 |
| 超过 R$ 250,000.00 | 07:00 至 17:00 | 仅工作日 |

:::caution 注意！
某些特定类型的征税凭单和税款，由于与发行人/收款方相关的特殊性，其时间与上表不同。如需了解更多信息，请通过此[链接](https://storage.googleapis.com/live-doc-api/public_samples/active_covenants.xlsx)查看这些收款类型的时间表。
:::

### 付款限额

银行单据的付款金额限于付款方的账户余额。

### 付款的财务结算

#### 银行单据

当任何提供该支付方式的金融机构支付一张银行单据时，付款金额将在付款日的下一个工作日由收款发行人收到（例如：周四支付的单据，将在周五结算；周六支付的单据，将在周一结算）。

也就是说，如果 QI Tech 的客户在其账户中注册了一张银行单据，他只会在付款后一个工作日才能收到该单据的金额（即使该付款是由 QI Tech 本身执行的）。

#### 征税凭单与税款

征税凭单和税款的结算取决于各发行机构/代理方的规则和操作要素。

---

# 执行 Peer To Peer 交易

URL: /zh-Hans/documentation/peer_to_peer

:::danger 注意
此方法只能用于同一集成合作方下 QI 账户之间的交易。
:::

## Request

ENDPOINT /account/ SOURCE_ACCOUNT_KEY /transaction/peer_to_peer
MÉTODO POST

### Path params

| 字段                    | 类型   | 描述                                                                         | 字符数                     |
|-------------------------|--------|------------------------------------------------------------------------------|----------------------------|
| `source_account_key` *  | uuidv4 | 标识转账来源账户的唯一密钥。                                                 | 36                         |

Request Body

```json
{
    "transaction_amount": 15,
    "request_control_key": "540ca9f6-7ccf-42a8-92d2-eafa6c8ac152",
    "target_account_key": "f8b5d8cf-23d3-47eb-8f2d-c97278372ecf",
    "description": "Compra com autorização externa"
}
```

### Body Atributes

| 字段                    | 类型   | 描述                                                                         | 字符数                     |
|-------------------------|--------|------------------------------------------------------------------------------|----------------------------|
| `transaction_amount` *  | float  | 从来源账户转至目标账户的金额。                                               | 小数点后2位的浮点数         |
| `request_control_key` * | uuidv4 | 用于维护交易幂等性的唯一标识密钥。                                           | 36                         |
| `target_account_key` *  | uuidv4 | 标识转账目标账户的唯一密钥。                                                 | 36                         |
| `description` *         | string | 用于在账户流水中识别的交易描述。                                             | 36                         |

## Response

STATUS 201

Response Body

```json
{
    "peer_to_peer_transaction_key": "c102f984-d93c-4d74-aca1-bbf83310c835",
    "request_control_key": "540ca9f6-7ccf-42a8-92d2-eafa6c8ac152",
    "transactions": [
        {
            "account_balance": 15.0,
            "account_branch": "0001",
            "account_number": "7107708",
            "description": "Compra com autorização externa",
            "document_number": "30461737337",
            "source_account_key": "cf069da7-5f3e-4808-9cfa-ac49a3928b70",
            "target_account_key": "f8b5d8cf-23d3-47eb-8f2d-c97278372ecf",
            "transacted_at": "2020-08-06 19:22:06",
            "transaction_amount": 15,
            "transaction_key": "848d3ff7-4e98-4911-8773-f1d1b48c3068"
        },
        {
            "account_balance": 35.0,
            "account_branch": "0001",
            "account_number": "9629460",
            "description": "Compra com autorização externa",
            "document_number": "74106519461",
            "source_account_key": "f8b5d8cf-23d3-47eb-8f2d-c97278372ecf",
            "target_account_key": "cf069da7-5f3e-4808-9cfa-ac49a3928b70",
            "transacted_at": "2020-08-06 19:22:06",
            "transaction_amount": -15,
            "transaction_key": "848d3ff7-4e98-4911-8773-f1d1b48c3068"
        }
    ]
}

```
STATUS 4XX

Response Body

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

| HTTP 状态码 | QI 代码<br/>`code` | 标题<br/>`title`             | 英文描述<br/>`Description`                                           | 葡语描述<br/>`translation`                                                       |
|-------------|-------------------|------------------------------|----------------------------------------------------------------------|----------------------------------------------------------------------------------|
| 404         | ACC000208         | Account not found            | Account not found.                                                   | Conta não encontrada.                                                            |
| 405         | ACC000209         | Method not allowe            | you are not allowed to call this method.                             | Você não tem permissão para este método.                                         |
| 403         | ACC000210         | Forbidden                    | Escrow account are not allowed to call this method.                  | Método não permitido para contas escrow.                                         |
| 409         | ACC000211         | Conflict                     | Duplicated request control key <strong>request_control_key</strong>. | Entrada duplicada para request control key <strong>request_control_key</strong>. |
| 402         | ACC000027         | Account Balance Error        | Account balance must not be negative after the transaction.          | Saldo da conta não pode ser negativo após a transação.                           |

---

# 为 Alias 创建 PIX 密钥

URL: /zh-Hans/documentation/pix_indireto/chaves_pix/criacao_de_chaves

## 请求

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_key
MÉTODO POST

**请求体 - 'random_key' 类型密钥**

```json
{
  "request_control_key": "3d3d0083-ac71-46f0-8a90-c00a157a4893",
  "pix_key_type": "random_key"
}
```

**请求体 - CPF 类型密钥**

```json
{
  "request_control_key": "3d3d0083-ac71-46f0-8a90-c00a157a4893",
  "pix_key_type": "cpf",
  "pix_key": "67824450007"
}
```

### 请求路径参数

| 字段 | 类型 | 描述 | 字符数 |
|---------------|--------|-----------------------|------------|
| `account_key` | uuidv4 | 账户唯一密钥。 | 36 |
| `alias_key`   | uuidv4 | Alias 唯一密钥。 | 36 |

### 请求体参数

| 字段 | 类型 | 描述 | 最大字符数 |
|-------------------------|--------|---------------------------------------------------------------------------------|-----------------|
| `request_control_key` * | string | 用于查询所发起请求的 UUID4。 | 36 |
| `pix_key_type` *        | string | 定义将创建的密钥类型。可选值：'cpf'、'cnpj'、'email'、'phone_number'、'random_key' | 10 |
| `pix_key`         | string | 要创建的 PIX 密钥值。'random_key' 类型无需发送。 | 10 |

:::info PIX 密钥类型
请求中发送的 `pix_key` 可以是 CPF、CNPJ、电子邮件或手机号码，格式如下：

**CPF**：11 位整数。

**CNPJ**：14 位整数。

**电子邮件**：包含至少一个"@"的文本。

**手机号码**：包含以下值的文本："+55" + "手机区号" + "至少 8 位、最多 9 位的手机号码整数"。例如："+5511987654321"。

:::

## 响应

STATUS 200

响应体

```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"
}

```

### 响应体参数

| 字段 | 类型 | 描述 | 最大字符数 |
|-------------------------|--------|---------------------------------------------------------------------------------|-----------------|
| `pix_key`         | string | 创建的 PIX 密钥值。 | 200 |
| `pix_key_status`         | string | PIX 密钥激活状态。可以是 "active"、"inactive" 或 "pending" | 8 |
| `created_at`            | datetime Zulu | 请求创建日期。 | 20 |

:::info PIX 密钥类型
请求响应中返回的 `pix_key` 可以是 CPF、CNPJ、电子邮件、手机号码或随机密钥，格式如下：

**CPF**：11 位整数。

**CNPJ**：14 位整数。

**电子邮件**：包含至少一个"@"的文本。

**手机号码**：包含以下值的文本："+55" + "手机区号" + "至少 8 位、最多 9 位的手机号码整数"。例如："+5511987654321"。

**随机密钥**：UUIDV4。
:::

STATUS 4XX

响应体：错误

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

| HTTP 状态码 | QI 错误码<br/>`code` | 标题<br/>`title` | 英文描述<br/>`Description` | 葡文描述<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                             |

---

# 删除 Alias 的 PIX 密钥

URL: /zh-Hans/documentation/pix_indireto/chaves_pix/deletar_chaves

## 请求

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_key/ PIX_KEY
MÉTODO DELETE

请求体

```json

{}

```

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|---------------|--------|------------------------------|------------|
| `account_key` | uuidv4 | 账户唯一密钥。 | 36 |
| `alias_key`   | uuidv4 | Alias 唯一密钥。 | 36 |
| `pix_key`     | string | 将被删除的 PIX 密钥。 | 200 |

## 响应

STATUS 200

响应体

```json
{}
```

STATUS 4XX

响应体：错误

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

| HTTP 状态码 | QI 错误码<br/>`code` | 标题<br/>`title` | 英文描述<br/>`Description` | 葡文描述<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\}  |

---

# 为 Alias 管理 PIX 密钥简介

URL: /zh-Hans/documentation/pix_indireto/chaves_pix/introducao_chaves_pix

间接参与者在 QI Tech 为其账户注册 Alias 后，即可为该 Alias 注册 PIX 密钥，该 Alias 实际上代表间接参与者的客户。

由于间接参与者已完成 Alias 注册，只需告知 QI Tech 希望为特定 Alias 开通 PIX 密钥即可。该 Alias 拥有一个在间接参与者注册 Alias 时提供的唯一密钥。

:::info 信息

本简介部分所描述的所有内容，以及间接参与者应如何通过 API 进行处理，均在后续各节中详细说明。

:::

---

# 列出 Alias 的 PIX 密钥

URL: /zh-Hans/documentation/pix_indireto/chaves_pix/listar_chaves

## 请求

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_key
MÉTODO GET

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|---------------|--------|-----------------------|------------|
| `account_key` | string | 账户唯一密钥。 | 36 |
| `alias_key`   | string | Alias 唯一密钥。 | 36 |

:::info PIX 密钥类型
"pix_key" 为随机密钥（UUID4）类型，格式如下：

随机密钥：UUID4。
:::

### 查询参数

| 字段 | 类型 | 描述 | 字符数 |
|---------------|---------|-----------------------------------------|------------|
| `page_number` | integer | 当前查询的页码。 | - |
| `page_size`   | integer | 每页结果数量。 | - |

## 响应

STATUS 200

响应体：活跃密钥

```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
  }
}
```

### 响应体参数

| 字段 | 类型 | 描述 | 最大字符数 |
|------------------|---------------|----------------------------------------------------------------------------|-----------------|
| `pix_key`        | string        | PIX 密钥。 | 77 |
| `pix_key_type`   | string        | PIX 密钥类型。可以是 "random_key" | 10 |
| `pix_key_status` | string        | PIX 密钥激活状态。可以是 "active"、"inactive" 或 "pending" | 8 |
| `created_at`     | datetime Zulu | 请求创建日期。 | 20 |

STATUS 4XX

响应体：错误

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

| HTTP 状态码 | QI 错误码<br/>`code` | 标题<br/>`title` | 英文描述<br/>`Description` | 葡文描述<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              |

---

# 取消退款请求

URL: /zh-Hans/documentation/pix_indireto/devolucao/cancelar_devolucao

间接参与者可在必要时**取消**退款请求。

只有创建退款请求的参与者（直接或间接）才能取消它。

取消时，状态必须为 OPEN 。

:::danger 重要
巴西中央银行规定，间接参与者收到退款请求后 1 天 内，退款请求必须被 关闭 。

如果间接参与者出现延误，QI Tech 将以 totally_accepted 状态关闭退款请求，以避免机构受到巴西中央银行的处罚。
:::

## 请求

ENDPOINT /pix/refund_request/ REFUND_REQUEST_KEY
MÉTODO PATCH

**请求体**

```json
{
    "refund_request_status": "cancelled",
    "request_control_key": "e09aba97-0051-4c18-b645-1cb3c2581c34"
}

```

### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
| ---------------------- | ------ | ----------------------------- | ---------- |
| `refund_request_key` * | string | 已创建退款的 UUID4。 | 36 |

### 请求体参数

| 字段 | 类型 | 描述 | 字符数 |
| ------------------------- | ------ | ----------------------------------------------------- | ---------- |
| `refund_request_status` * | string | 退款更新状态。 | 36 |
| `request_control_key` *   | uuidv4 | 用于查询所发起请求的 UUID4。 | 36 |

## 响应

STATUS 200

**响应体**

```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"
}
```

### 响应体参数
| 字段 | 类型 | 描述 | 字符数 |
| --------------------------- | ------ | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `pix_transfer_key`*         | string | PIX 交易唯一标识符。 | 36 |
| `refund_request_key`*       | string | 退款唯一标识符。 | 36 |
| `infraction_report_key`*    | string | 与退款相关的违规唯一标识符。仅当类型为欺诈时。 | 36 |
| `refund_request_type`       | enum   | 退款请求类型。 | **[refund_request_type 枚举值](#enumeradores-refund_request_type)** |
| `requested_amount`*         | float  | 退款金额。 | - |
| `refund_request_status`*    | enum   | 状态。 | **[refund_request_status 枚举值](#enumeradores-refund_request_status)** |
| `contested_participant`*    | string | 被贷记参与者（被争议方）的 ISPB。 | 8 |
| `requesting_participant`*   | string | 被借记参与者（请求方，即提出退款请求的一方）的 ISPB。 | 8 |
| `refund_request_details`*   | string | 退款详情。 | - |
| `analysis_result`*          | enum   | 退款关闭分析结果。 | **[analysis_result 枚举值](#enumeradores-analysis_result)** |
| `analysis_details`*         | string | 退款关闭分析详情。 | - |
| `reject_reason`*            | string | 退款被拒绝时的拒绝原因（以 REJECTED 关闭时）。 | **[reject_reason 枚举值](#enumeradores-reject_reason)** |
| `refund_transfer_key`*      | string | 退款交易的 pix_transfer_key（接受关闭时）。 | - |
| `refunded_amount`*          | float  | 退款交易中已退还的金额。 | - |
| `refund_request_direction`* | string | 退款请求方向。 | **[refund_request_direction 枚举值](#enumeradores-refund_request_direction)** |
| `created_at` *              | string | 退款请求创建日期。 | 24 |

### refund_request_status 枚举值
| 字段 | 描述 |
| ----------- | ---------------------------------------------------------------------------- |
| `open`      | 退款请求已<strong>创建</strong>并在 BACEN 中开放。 |
| `cancelled` | 退款请求在 BACEN 中已<strong>取消</strong>。 |
| `closed`    | 退款请求在 BACEN 中已<strong>关闭</strong>。 |

### refund_request_type 枚举值
| 字段 | 描述 |
| ------------------ | ------------------------------------------------------ |
| `fraud`            | 退款请求源于欺诈行为。 |
| `operational_flaw` | 退款请求源于内部错误。 |

### analysis_result 枚举值
| 字段 | 描述 |
| -------------------- | ------------------------------------------------- |
| `totally_accepted`   | 退款请求已完全接受。 |
| `partially_accepted` | 退款请求已部分接受。 |
| `rejected`           | 退款请求已被拒绝。 |

### reject_reason 枚举值
| 字段 | 描述 |
| ----------------- | -------------------------------------------------------------------------- |
| `no_balance`      | 账户余额不足以进行退款。 |
| `account_closure` | 账户已关闭，因此无法进行退款。 |
| `other`           | 其他原因。 |

### refund_request_direction 枚举值
| 字段 | 描述 |
| ---------- | ------------------------------------------------- |
| `outgoing` | 参与者是退款请求的发起方。 |
| `incoming` | 参与者是退款请求的目标方。 |

---

# 查询退款请求

URL: /zh-Hans/documentation/pix_indireto/devolucao/consultar_devolucao

如果间接参与者希望查询退款请求的信息，可通过以下路由实现。

:::danger 重要
巴西中央银行规定，间接参与者收到退款请求后 1 天 内，退款请求必须被 关闭 。

如果间接参与者出现延误，QI Tech 将以 totally_accepted 状态关闭退款请求，以避免机构受到巴西中央银行的处罚。
:::

## 请求

ENDPOINT /pix/refund_request/ REFUND_REQUEST_KEY
MÉTODO GET

### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
| -------------------- | ------ | ------------------- | ---------- |
| `refund_request_key` | string | 退款的 UUID4。 | 36 |

## 响应

STATUS 200

**响应体**

```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"
    }
  ]
}
```

### 响应体参数
| 字段 | 类型 | 描述 | 字符数 |
| --------------------------- | ------ | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `pix_transfer_key`*         | string | PIX 交易唯一标识符。 | 36 |
| `refund_request_key`*       | string | 退款唯一标识符。 | 36 |
| `infraction_report_key`*    | string | 与退款相关的违规唯一标识符。仅当类型为欺诈时。 | 36 |
| `refund_request_type`       | enum   | 退款请求类型。 | **[refund_request_type 枚举值](#enumeradores-refund_request_type)** |
| `requested_amount`*         | float  | 退款金额。 | - |
| `refund_request_status`*    | enum   | 状态。 | **[refund_request_status 枚举值](#enumeradores-refund_request_status)** |
| `contested_participant`*    | string | 被贷记参与者（被争议方）的 ISPB。 | 8 |
| `requesting_participant`*   | string | 被借记参与者（请求方）的 ISPB。 | 8 |
| `refund_request_details`*   | string | 退款详情。 | - |
| `analysis_result`*          | enum   | 退款关闭分析结果。 | **[analysis_result 枚举值](#enumeradores-analysis_result)** |
| `analysis_details`*         | string | 退款关闭分析详情。 | - |
| `reject_reason`*            | string | 退款被拒绝的原因（以 REJECTED 关闭时）。 | **[reject_reason 枚举值](#enumeradores-reject_reason)** |
| `refund_transfer_key`*      | string | 退款交易的 pix_transfer_key（接受关闭时）。 | - |
| `refunded_amount`*          | float  | 退款交易中已退还的金额。 | - |
| `refund_events`*            | object | 退款请求事件对象。 | **[refund_events 对象](#objetos-refund_events)** |
| `refund_request_direction`* | string | 退款请求方向。 | **[refund_request_direction 枚举值](#enumeradores-refund_request_direction)** |
| `created_at` *              | string | 退款请求创建日期。 | 24 |

### refund_request_status 枚举值
| 字段 | 描述 |
| ----------- | ---------------------------------------------------------------------------- |
| `open`      | 退款请求已<strong>创建</strong>并在 BACEN 中开放。 |
| `cancelled` | 退款请求在 BACEN 中已<strong>取消</strong>。 |
| `closed`    | 退款请求在 BACEN 中已<strong>关闭</strong>。 |

### refund_request_type 枚举值
| 字段 | 描述 |
| ------------------ | ------------------------------------------------------ |
| `fraud`            | 退款请求源于欺诈行为。 |
| `operational_flaw` | 退款请求源于内部错误。 |

### analysis_result 枚举值
| 字段 | 描述 |
| -------------------- | ------------------------------------------------- |
| `totally_accepted`   | 退款请求已完全接受。 |
| `partially_accepted` | 退款请求已部分接受。 |
| `rejected`           | 退款请求已被拒绝。 |

### reject_reason 枚举值
| 字段 | 描述 |
| ----------------- | -------------------------------------------------------------------------- |
| `no_balance`      | 账户余额不足以进行退款。 |
| `account_closure` | 账户已关闭，因此无法进行退款。 |
| `other`           | 其他原因。 |

### refund_request_direction 枚举值
| 字段 | 描述 |
| ---------- | ------------------------------------------------- |
| `outgoing` | 参与者是退款请求的发起方。 |
| `incoming` | 参与者是退款请求的目标方。 |

### refund_events 对象
| 字段 | 描述 |
| --------------- | --------------------------------------------------------------------------------------------------------------------- |
| `event_type`    | 退款变更事件类型。**[refund_request_status 枚举值](#enumeradores-refund_request_status)** |
| `event_details` | 事件详情。 |
| `created_at`    | 事件创建日期。 |

---

# 创建退款请求

URL: /zh-Hans/documentation/pix_indireto/devolucao/criar_devolucao

退款请求是 BACEN 定义的 MED 中的另一项功能。

其主要目的是便于退还已完成的 PIX 交易。退款请求可因 操作失误 或 违规 而产生。在后一种情况下，需存在一份针对某笔 PIX 交易的违规报告，且已处于 关闭 和 已接受 状态。

:::caution **注意**
为了理解退款请求的流程，需要了解创建退款的间接参与者可以使用哪些 **ENDPOINTS**。

当间接参与者**创建**退款请求时，如果请求是错误生成的，可以（在必要时）取消该请求。

当间接参与者**收到**退款请求时，必须通过告知请求分析结果来响应。

上述两种流程将在后续章节中描述。

还需注意，如果间接参与者发起请求，则其**争议**另一个参与者。在相反的流程中，间接参与者是**被争议方**。
:::

:::danger 重要
巴西中央银行规定，间接参与者收到退款请求后 1 天 内，退款请求必须被 关闭 。

如果间接参与者出现延误，QI Tech 将以 totally_accepted 状态关闭退款请求，以避免机构受到巴西中央银行的处罚。
:::

## 请求

ENDPOINT /pix/refund_request
MÉTODO POST

**请求体**

```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"
}

```

### 请求体参数

| 字段 | 类型 | 描述 | 字符数 |
| ------------------------ | ------ | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| `pix_transfer_key` *     | string | PIX 交易唯一标识符。 | 36 |
| `request_control_key` *  | uuidv4 | 用于查询所发起请求的 UUID4。 | 36 |
| `amount`                 | float  | 退款金额。若未提供，将使用原始交易金额。 | 19 |
| `refund_request_details` | string | 关于将创建的退款请求的详情。 | \<\= 2000 |
| `refund_request_type` *  | enum   | 可以是 (fraud/operational_flaw)。 | **[refund_request_type 枚举值](#enumeradores-refund_request_type)** |

## 响应

STATUS
        200

**响应体**

```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 信息
如果字段 "refund_request_type" 为 "fraud"，QI Tech 将在响应中告知已关闭并接受的 infraction_report_key 。
:::

### 响应体参数
| 字段 | 类型 | 描述 | 字符数 |
| --------------------------- | ------ | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `pix_transfer_key`*         | string | PIX 交易唯一标识符。 | 36 |
| `refund_request_key`*       | string | 退款唯一标识符。 | 36 |
| `infraction_report_key`*    | string | 与退款相关的违规唯一标识符。仅当类型为欺诈时。 | 36 |
| `refund_request_type`       | enum   | 退款请求类型。 | **[refund_request_type 枚举值](#enumeradores-refund_request_type)** |
| `requested_amount`*         | float  | 退款金额。 | - |
| `refund_request_status`*    | enum   | 状态。 | **[refund_request_status 枚举值](#enumeradores-refund_request_status)** |
| `contested_participant`*    | string | 被贷记参与者（被争议方）的 ISPB。 | 8 |
| `requesting_participant`*   | string | 被借记参与者（请求方）的 ISPB。 | 8 |
| `refund_request_details`*   | string | 退款详情。 | - |
| `analysis_result`*          | enum   | 退款关闭分析结果。 | **[analysis_result 枚举值](#enumeradores-analysis_result)** |
| `analysis_details`*         | string | 退款关闭分析详情。 | - |
| `reject_reason`*            | string | 退款被拒绝的原因（以 REJECTED 关闭时）。 | **[reject_reason 枚举值](#enumeradores-reject_reason)** |
| `refund_transfer_key`*      | string | 退款交易的 pix_transfer_key（接受关闭时）。 | - |
| `refunded_amount`*          | float  | 退款交易中已退还的金额。 | - |
| `refund_request_direction`* | string | 退款请求方向。 | **[refund_request_direction 枚举值](#enumeradores-refund_request_direction)** |
| `created_at` *              | string | 退款请求创建日期。 | 24 |

### refund_request_status 枚举值
| 字段 | 描述 |
| ----------- | ---------------------------------------------------------------------------- |
| `open`      | 退款请求已<strong>创建</strong>并在 BACEN 中开放。 |
| `cancelled` | 退款请求在 BACEN 中已<strong>取消</strong>。 |
| `closed`    | 退款请求在 BACEN 中已<strong>关闭</strong>。 |

### refund_request_type 枚举值
| 字段 | 描述 |
| ------------------ | ------------------------------------------------------ |
| `fraud`            | 退款请求源于欺诈行为。 |
| `operational_flaw` | 退款请求源于内部错误。 |

### analysis_result 枚举值
| 字段 | 描述 |
| -------------------- | ------------------------------------------------- |
| `totally_accepted`   | 退款请求已完全接受。 |
| `partially_accepted` | 退款请求已部分接受。 |
| `rejected`           | 退款请求已被拒绝。 |

### reject_reason 枚举值
| 字段 | 描述 |
| ----------------- | -------------------------------------------------------------------------- |
| `no_balance`      | 账户余额不足以进行退款。 |
| `account_closure` | 账户已关闭，因此无法进行退款。 |
| `other`           | 其他原因。 |

### refund_request_direction 枚举值
| 字段 | 描述 |
| ---------- | ------------------------------------------------- |
| `outgoing` | 参与者是退款请求的发起方。 |
| `incoming` | 参与者是退款请求的目标方。 |

---

# 关闭退款请求

URL: /zh-Hans/documentation/pix_indireto/devolucao/fechar_devolucao

如果间接参与者处于被争议参与者的角色，则可以**关闭**退款请求。

关闭时，状态必须为 OPEN 。

:::danger 重要
巴西中央银行规定，间接参与者收到退款请求后 1 天 内，退款请求必须被 关闭 。

如果间接参与者出现延误，QI Tech 将以 totally_accepted 状态关闭退款请求，以避免机构受到巴西中央银行的处罚。
:::

## 请求

ENDPOINT /pix/refund_request/ REFUND_REQUEST_KEY
MÉTODO PATCH

**请求体**

```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"
}

```

### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---| ---|
| `refund_request_key` *| string | 已创建退款的 UUID4。| 36 |

### 请求体参数

| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---| ---|
| `request_control_key` * | uuidv4 | 用于查询所发起请求的 UUID4。 | 36 |
| `request_request_status` * | enum | 状态。 | **[refund_request_status 枚举值](#enumeradores-refund_request_status)** |
| `analysis_result` * | enum | 分析结果。 | **[analysis_result 枚举值](#enumeradores-analysis_result)** |
| `analysis_details` | string | 分析说明。 | \<\= 2000 |
| `refund_transfer_key`  | string | 通过 "reversal" 路由发送的退款交易的 UUID4。当 "analysis_result" 为接受时使用。| 36 |
| `reject_reason`  | enum | 退款拒绝原因。当字段 'analysis_result' 为 'rejected' 时使用。 | **[reject_reason 枚举值](#enumeradores-reject_reason)** |

## 响应

STATUS 200

**响应体 - 拒绝**

```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"
}
```

**响应体 - 接受**

```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"
}
```

### 响应体参数
| 字段 | 类型 | 描述 | 字符数 |
| --------------------------- | ------ | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `pix_transfer_key`*         | string | PIX 交易唯一标识符。 | 36 |
| `refund_request_key`*       | string | 退款唯一标识符。 | 36 |
| `infraction_report_key`*    | string | 与退款相关的违规唯一标识符。仅当类型为欺诈时。 | 36 |
| `refund_request_type`       | enum   | 退款请求类型。 | **[refund_request_type 枚举值](#enumeradores-refund_request_type)** |
| `requested_amount`*         | float  | 退款金额。 | - |
| `refund_request_status`*    | enum   | 状态。 | **[refund_request_status 枚举值](#enumeradores-refund_request_status)** |
| `contested_participant`*    | string | 被贷记参与者（被争议方）的 ISPB。 | 8 |
| `requesting_participant`*   | string | 被借记参与者（请求方）的 ISPB。 | 8 |
| `refund_request_details`*   | string | 退款详情。 | - |
| `analysis_result`*          | enum   | 退款关闭分析结果。 | **[analysis_result 枚举值](#enumeradores-analysis_result)** |
| `analysis_details`*         | string | 退款关闭分析详情。 | - |
| `reject_reason`*            | string | 退款被拒绝的原因（以 REJECTED 关闭时）。 | **[reject_reason 枚举值](#enumeradores-reject_reason)** |
| `refund_transfer_key`*      | string | 退款交易的 pix_transfer_key（接受关闭时）。 | - |
| `refunded_amount`*          | float  | 退款交易中已退还的金额。 | - |
| `refund_request_direction`* | string | 退款请求方向。 | **[refund_request_direction 枚举值](#enumeradores-refund_request_direction)** |
| `created_at` *              | string | 退款请求创建日期。 | 24 |

### refund_request_status 枚举值
| 字段 | 描述 |
| ----------- | ---------------------------------------------------------------------------- |
| `open`      | 退款请求已<strong>创建</strong>并在 BACEN 中开放。 |
| `cancelled` | 退款请求在 BACEN 中已<strong>取消</strong>。 |
| `closed`    | 退款请求在 BACEN 中已<strong>关闭</strong>。 |

### refund_request_type 枚举值
| 字段 | 描述 |
| ------------------ | ------------------------------------------------------ |
| `fraud`            | 退款请求源于欺诈行为。 |
| `operational_flaw` | 退款请求源于内部错误。 |

### analysis_result 枚举值
| 字段 | 描述 |
| -------------------- | ------------------------------------------------- |
| `totally_accepted`   | 退款请求已完全接受。 |
| `partially_accepted` | 退款请求已部分接受。 |
| `rejected`           | 退款请求已被拒绝。 |

### reject_reason 枚举值
| 字段 | 描述 |
| ----------------- | -------------------------------------------------------------------------- |
| `no_balance`      | 账户余额不足以进行退款。 |
| `account_closure` | 账户已关闭，因此无法进行退款。 |
| `other`           | 其他原因。 |

### refund_request_direction 枚举值
| 字段 | 描述 |
| ---------- | ------------------------------------------------- |
| `outgoing` | 参与者是退款请求的发起方。 |
| `incoming` | 参与者是退款请求的目标方。 |

---

# 列出退款请求

URL: /zh-Hans/documentation/pix_indireto/devolucao/listar_solicitacoes

如果间接参与者需要列出退款请求，可通过以下路由实现。

:::danger 重要
巴西中央银行规定，间接参与者收到退款请求后 1 天 内，退款请求必须被 关闭 。

如果间接参与者出现延误，QI Tech 将以 totally_accepted 状态关闭退款请求，以避免机构受到巴西中央银行的处罚。
:::

## 请求

ENDPOINT /pix/refund_requests
MÉTODO GET

### 查询参数
| 字段 | 类型 | 描述 | 字符数 |
| ----------------------- | ------- | --------------------------------------- | ----------------------------------------------------------------------------- |
| `refund_request_status` | enum    | 退款请求状态。 | **[refund_request_status 枚举值](#enumeradores-refund_request_status)** |
| `refund_request_type`   | enum    | 退款请求类型。 | **[refund_request_type 枚举值](#enumeradores-refund_request_type)** |
| `initial_date`          | string  | 搜索起始日期。 | **[日期格式](#formato-de-data)** |
| `final_date`            | string  | 搜索结束日期。 | **[日期格式](#formato-de-data)** |
| `page_number`           | integer | 当前查询的页码。 | - |
| `page_size`             | integer | 每页结果数量。 | - |

### refund_request_status 枚举值
| 字段 | 类型 | 描述 | 字符数 |
| ----------- | ------ | ---------------------------------------------------------------------------- | ---------- |
| `open`      | string | 退款请求已<strong>创建</strong>并在 BACEN 中开放。 | 4 |
| `cancelled` | string | 退款请求在 BACEN 中已<strong>取消</strong>。 | 9 |
| `closed`    | string | 退款请求在 BACEN 中已<strong>关闭</strong>。 | 6 |

### refund_request_type 枚举值
| 字段 | 类型 | 描述 | 字符数 |
| ------------------ | ------ | ------------------------------------------------------ | ---------- |
| `fraud`            | string | 退款请求源于欺诈行为。 | 5 |
| `operational_flaw` | string | 退款请求源于内部错误。 | 16 |

### 日期格式

| 字段 | 类型 | 描述 | 字符数 |
| -------------- | ------ | --------------------------------------------------------------------------- | ---------- |
| `initial_date` | string | 搜索起始日期，格式为 "%Y-%m-%d"。示例："2023-10-09"。 | 10 |
| `final_date`   | string | 搜索结束日期，格式为 "%Y-%m-%d"。示例："2023-10-11"。 | 10 |

## 响应

STATUS 200

**响应体**

```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"
        }
      ]
    }
  ]
}
```

### 响应体参数
| 字段 | 类型 | 描述 | 字符数 |
| --------------------------- | ------ | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `pix_transfer_key`*         | string | PIX 交易唯一标识符。 | 36 |
| `refund_request_key`*       | string | 退款唯一标识符。 | 36 |
| `infraction_report_key`*    | string | 与退款相关的违规唯一标识符。仅当类型为欺诈时。 | 36 |
| `refund_request_type`       | enum   | 退款请求类型。 | **[refund_request_type 枚举值](#enumeradores-refund_request_type)** |
| `requested_amount`*         | float  | 退款金额。 | - |
| `refund_request_status`*    | enum   | 状态。 | **[refund_request_status 枚举值](#enumeradores-refund_request_status)** |
| `contested_participant`*    | string | 被贷记参与者（被争议方）的 ISPB。 | 8 |
| `requesting_participant`*   | string | 被借记参与者（请求方）的 ISPB。 | 8 |
| `refund_request_details`*   | string | 退款详情。 | - |
| `analysis_result`*          | enum   | 退款关闭分析结果。 | **[analysis_result 枚举值](#enumeradores-analysis_result)** |
| `analysis_details`*         | string | 退款关闭分析详情。 | - |
| `reject_reason`*            | string | 退款被拒绝的原因（以 REJECTED 关闭时）。 | **[reject_reason 枚举值](#enumeradores-reject_reason)** |
| `refund_transfer_key`*      | string | 退款交易的 pix_transfer_key（接受关闭时）。 | - |
| `refunded_amount`*          | float  | 退款交易中已退还的金额。 | - |
| `refund_events`*            | object | 退款请求事件对象。 | **[refund_events 对象](#objetos-refund_events)** |
| `refund_request_direction`* | string | 退款请求方向。 | **[refund_request_direction 枚举值](#enumeradores-refund_request_direction)** |
| `created_at` *              | string | 退款请求创建日期。 | 24 |

### refund_request_status 枚举值
| 字段 | 描述 |
| ----------- | ---------------------------------------------------------------------------- |
| `open`      | 退款请求已<strong>创建</strong>并在 BACEN 中开放。 |
| `cancelled` | 退款请求在 BACEN 中已<strong>取消</strong>。 |
| `closed`    | 退款请求在 BACEN 中已<strong>关闭</strong>。 |

### refund_request_type 枚举值
| 字段 | 描述 |
| ------------------ | ------------------------------------------------------ |
| `fraud`            | 退款请求源于欺诈行为。 |
| `operational_flaw` | 退款请求源于内部错误。 |

### analysis_result 枚举值
| 字段 | 描述 |
| -------------------- | ------------------------------------------------- |
| `totally_accepted`   | 退款请求已完全接受。 |
| `partially_accepted` | 退款请求已部分接受。 |
| `rejected`           | 退款请求已被拒绝。 |

### reject_reason 枚举值
| 字段 | 描述 |
| ----------------- | -------------------------------------------------------------------------- |
| `no_balance`      | 账户余额不足以进行退款。 |
| `account_closure` | 账户已关闭，因此无法进行退款。 |
| `other`           | 其他原因。 |

### refund_request_direction 枚举值
| 字段 | 描述 |
| ---------- | ------------------------------------------------- |
| `outgoing` | 参与者是退款请求的发起方。 |
| `incoming` | 参与者是退款请求的目标方。 |

### refund_events 对象
| 字段 | 描述 |
| --------------- | --------------------------------------------------------------------------------------------------------------------- |
| `event_type`    | 退款变更事件类型。**[refund_request_status 枚举值](#enumeradores-refund_request_status)** |
| `event_details` | 事件详情。 |
| `created_at`    | 事件创建日期。 |

---

# 退款流程简介

URL: /zh-Hans/documentation/pix_indireto/devolucao/maquina_estados

## 简介

巴西中央银行允许间接参与者在希望将通过 PIX 交易中 被扣款 的金额退回账户时，开立退款请求。

:::info 

需要注意的是，只有被 扣款 的参与者才能开立退款请求。正式地，开立退款请求的参与者被称为 requesting_participant 。

:::

| 枚举值 | 中文 | 描述 |
|---|---|---|
|  open  | 开放 | 退款请求<strong>创建</strong>处理完成后，在 BACEN 中处于开放状态。  
|  cancelled  | 已取消 | 退款请求的取消已由 QI Tech 处理，在 BACEN 中处于<strong>已取消</strong>状态。
|  closed  | 已关闭 | 退款请求的关闭已由 QI Tech 处理，在 BACEN 中处于<strong>已关闭</strong>状态。

## 状态机控制

即使流程是 同步 的，也需要了解退款请求可能具有的各种状态。以下描述了间接参与者在开立、取消、完成和接收退款请求后可以预期的情况。

### 参与者开立退款请求

间接参与者可以通过两种方式请求开立退款：

因操作错误（operational_flaw）。
因已关闭并接受的违规报告（refund_request）。

开立后，退款状态将为 open 。

### 参与者取消退款请求

参与者开立退款请求后，如果需要，可以对其进行 取消 。

间接参与者将收到状态为 cancelled 的响应。

### 参与者接收退款请求

由于其他参与者可以 开立 退款请求，涉及流程的另一方需要能够接收退款请求，以便 关闭 它。

与违规报告不同（后者有一个 acknowledged 的中间状态），间接参与者将通过 webhook 收到一个请求，告知存在状态为 open 的退款请求。

区别在于，对于此请求，被争议的参与者是间接参与者。

### 参与者关闭退款请求

QI Tech 通过 webhook 通知间接参与者存在可用的退款请求后，间接参与者可以 关闭 该报告。

当间接参与者执行此流程时，将向 QI Tech 发送 关闭 请求，并收到 closed 状态。

---

# 场景模拟

URL: /zh-Hans/documentation/pix_indireto/devolucao/simulacao_de_cenarios

模拟外部代理执行操作的分步说明。这些模拟包括接收和更新退款请求。

:::info 信息
这些请求没有返回负载（响应体），只有 201 响应状态。
:::

## 1 - 模拟接收退款请求

模拟接收另一机构开立的退款请求。

:::info 重要
必须拥有有效的 pix_transfer_key 才能发送请求，不需要关注转账另一方的信息，因为第二参与者的所有信息都将在模拟过程中被替换。
:::

### 请求

ENDPOINT /mock/pix/refund_request
MÉTODO POST

请求体

:::info 重要
如果退款类型为 FRAUD，则需要针对同一 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",
}
```

### 请求体对象

| 字段 | 类型 | 描述 | 最大字符数 |
| -------------------------- | ------ | ------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| `pix_transfer_key` *      | string | QI 系统中 PIX 转账的标识密钥（UUIDv4）。 | 36 |
| `refund_request_type` *   | enum   | 退款请求类型。 | **[refund_request_type 枚举值](#enumeradores-refund_request_type)** |
| `refund_request_status` * | string | 退款请求的初始状态。"open" | 36 |
| `refund_request_details`  | string | 退款请求报告的详情。 | 2000 |

### refund_request_type 枚举值
| 字段 | 类型 | 描述 | 字符数 |
| ------------------ | ------ | ------------------------------------------------------ | ---------- |
| `fraud`            | string | 退款请求源于欺诈行为。 | 5 |
| `operational_flaw` | string | 退款请求源于内部错误。 | 16 |

## 2 - 模拟更新退款请求

模拟间接参与者开立的退款请求的状态更新。

退款请求更新的模拟选项为：

1 - 取消：模拟"目标"参与者对其自身先前开立的退款请求进行取消（cancel）。

2 - 关闭：模拟"目标"参与者对间接参与者开立的退款请求进行关闭（close）。该报告必须已经以 open 状态被确认。

### 请求

ENDPOINT /mock/pix/refund_request
MÉTODO PATCH

请求体 - 取消

:::info 重要
由 refund_request_key 标识的退款请求必须已在退款请求创建模拟中预先创建。
:::

```json
{
    "refund_request_status": "cancelled",
    "refund_request_key": "c3e5664f-04bb-4625-9ef3-c8555d210c71"
}
```

请求体 - 完全接受关闭

:::info 重要
由 refund_request_key 标识的退款请求必须已由间接参与者预先创建。
:::
:::info 重要
退款转账密钥必须已通过退款接收模拟预先创建，金额等于原始交易金额。
:::

```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"
}
```

请求体 - 部分接受关闭

:::info 重要
由 refund_request_key 标识的退款请求必须已由间接参与者预先创建。此外，退款金额不得等于或超过原始交易的总金额。
:::
:::info 重要
退款转账密钥必须已通过退款接收模拟预先创建，金额小于原始交易金额。
:::

```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"
}
```

请求体 - 拒绝关闭

:::info 重要
由 refund_request_key 标识的退款请求必须已由间接参与者预先创建。
:::

```json
{
    "refund_request_key": "47633091-7d44-4d10-9d00-1f937104e537",
    "refund_request_status": "closed",
    "analysis_result": "rejected",
    "analysis_details": "Teste",
    "reject_reason": "no_balance"
}
```

### 请求体对象

| 字段 | 类型 | 描述 | 最大字符数 |
| -------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------- | ------------ |
| `refund_request_status` * | string | 退款请求的初始状态。"cancelled"、"closed" | 36 |
| `refund_request_key` *    | string | 退款请求的唯一密钥。 | 36 |
| `analysis_result` *       | string | 退款请求分析结果。"totally_accepted"、"partially_accepted"或"rejected"。 | 36 |
| `analysis_details`        | string | 退款请求分析详情。 | 2000 |
| `refund_transfer_key`      | float  | 退款转账标识符，接受情况下为必填项。 | 20 |
| `reject_reason`            | string | 退款拒绝原因（仅当 analysis_result 等于 rejected 时）。"no_balance"、"account_closure" 或 "other"。 | 15 |

---

# 接收退款请求

URL: /zh-Hans/documentation/pix_indireto/devolucao/webhooks_devolucao

:::danger 注意！
QI Tech 的 webhooks 不应被严格映射。
我们 API 返回的 webhook 负载中可能会包含额外字段。
:::

:::info 重新发送 Webhooks
您可以按照文档中的详细说明查询和重新发送 webhooks：[重新发送 Webhooks](/documentation/notificacoes/reenvio_de_notificacoes)。
:::

由于其他参与者可能以间接参与者为目标开立退款请求，QI Tech 需要通知间接参与者其他参与者开立的退款请求。

QI Tech 将通过 webhook 通知间接参与者。

:::danger 重要
巴西中央银行规定，间接参与者收到退款请求后 1 天 内，退款请求必须被 关闭 。

如果间接参与者出现延误，QI Tech 将以 totally_accepted 状态关闭退款请求，以避免机构受到巴西中央银行的处罚。
:::

## Webhook 接收退款（操作失误）
**请求体**

```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 接收退款（欺诈）
**请求体**

```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"
}
```

---

# 查询 Alias 实体

URL: /zh-Hans/documentation/pix_indireto/gerenciamento_de_alias/consultar_alias

查询已为现有账户注册的 Alias 实体。

## 请求

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY
MÉTODO GET

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|---------------|--------|-----------------------|------------|
| `account_key` | uuidv4 | 账户唯一密钥。 | 36 |
| `alias_key`   | uuidv4 | Alias 唯一密钥。 | 36 |

## 响应

STATUS 200

**响应体**

```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"
}
```

### 响应体参数

| 字段 | 类型 | 描述 | 最大字符数 |
|-------------------------|------------|----------------------------------------------------|---------------------------------------------------------|
| `alias_key`             | string     | Alias 唯一密钥。 | 36 |
| `ispb`                  | string     | 与 Alias 关联的金融机构 ISPB。 | 36 |
| `account_branch`        | string     | 支行号，不含校验位。 | 4 |
| `account_number`        | string     | 账号，不含校验位。 | 20 |
| `account_digit`         | string     | 账号校验位。 | 1 |
| `account_type`          | enumerador | 账户类型。 | **[account_type 枚举值](#enumerador-account_type)** |
| `account_created_at`    | string     | 账户创建日期。 | 20 |
| `owner_document_number` | string     | CPF 或 CNPJ 号码。 | 14 |
| `owner_name`            | string     | 账户所有者姓名。 | 120 |
| `owner_trading_name`    | string     | 账户所有者商业名称（仅限 CNPJ）。 | 100 |
| `created_at`            | string     | 请求创建日期。 | 20 |

### account_type 枚举值

| 枚举值 | 描述 |
|----------------------|---------------------|
| **checking_account** | 支票账户 |
| **salary_account**   | 工资账户 |
| **saving_account**   | 储蓄账户 |
| **payment_account**  | 支付账户 |

STATUS 404

响应体：未找到

```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"
}
```

响应体：未找到

```json

{
  "title": "Not found", 
  "description": "Alias \{alias_key\} not found", 
  "translation": "Alias \{alias_key\} não encontrado",
  "extra_fields": {}, 
  "code": "ACC000181"
}
```

---

# 通过 Request Control Key 查询 Alias

URL: /zh-Hans/documentation/pix_indireto/gerenciamento_de_alias/consultar_request_control_key

使用最初在原始请求体中分配的 request_control_key，返回创建 Alias 时获得的 alias_key。

## 请求

ENDPOINT /account/ ACCOUNT_KEY /alias
MÉTODO GET

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|---------------|--------|-----------------------|------------|
| `account_key` | uuidv4 | 账户唯一密钥。 | 36 |

### 查询参数

| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|--------|-------------------------------------------------------|------------|
| `request_control_key` * | uuidv4 | 用于查询所发起请求的 UUID4。 | 36 |

## 响应

STATUS 200

**响应体**

```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"
}
```

### 响应体参数

| 字段 | 类型 | 描述 | 最大字符数 |
|-------------------------|------------|----------------------------------------------------|---------------------------------------------------------|
| `alias_key`             | string     | Alias 唯一密钥。 | 36 |
| `ispb`                  | string     | 与 Alias 关联的金融机构 ISPB。 | 36 |
| `account_branch`        | string     | 支行号，不含校验位。 | 4 |
| `account_number`        | string     | 账号，不含校验位。 | 20 |
| `account_digit`         | string     | 账号校验位。 | 1 |
| `account_type`          | enumerador | 账户类型。 | **[account_type 枚举值](#enumerador-account_type)** |
| `account_created_at`    | string     | 账户创建日期。 | 20 |
| `owner_document_number` | string     | CPF 或 CNPJ 号码。 | 14 |
| `owner_name`            | string     | 账户所有者姓名。 | 120 |
| `owner_trading_name`    | string     | 账户所有者商业名称（仅限 CNPJ）。 | 100 |
| `created_at`            | string     | 请求创建日期。 | 20 |

### account_type 枚举值

| 枚举值 | 描述 |
|----------------------|---------------------|
| **checking_account** | 支票账户 |
| **salary_account**   | 工资账户 |
| **saving_account**   | 储蓄账户 |
| **payment_account**  | 支付账户 |

STATUS 404

响应体：未找到

```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

响应体：请求控制密钥未找到

```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ão possui entrada original associada",
  "extra_fields": {},
  "code": "ACC000186"
}
```

---

# 创建 Alias 实体

URL: /zh-Hans/documentation/pix_indireto/gerenciamento_de_alias/criacao_de_alias

此流程负责创建与已有账户关联的 Alias 实体。

## 请求

ENDPOINT /account/ ACCOUNT_KEY /alias
MÉTODO POST

**请求体**

```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"
}

```

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|---------------|--------|-----------------------|------------|
| `account_key` | uuidv4 | 账户唯一密钥。 | 36 |

### 请求体参数

| 字段 | 类型 | 描述 | 最大字符数 |
|---------------------------|------------|----------------------------------------------------------------------------------|---------------------------------------------------------|
| `request_control_key` *   | string     | 客户使用的请求唯一标识密钥，格式为 uuidv4。 | 36 |
| `account_branch` *        | string     | 支行号，不含校验位。 | 4 |
| `account_number` *        | string     | 账号，不含校验位。 | 20 |
| `account_digit` *         | string     | 账号校验位。 | 1 |
| `account_type`*           | enumerador | 账户类型。 | **[account_type 枚举值](#enumerador-account_type)** |
| `account_created_at` *    | string     | 账户创建日期。例如："2022-09-24T19:46:43.001Z" | 20 |
| `owner_document_number` * | string     | CPF 或 CNPJ 号码。 | 11（CPF）或 14（CNPJ） |
| `owner_person_type` *     | string     | 账户所有者类型。可以是 **legal** 或 **natural**。 | 7 |
| `owner_name` *            | string     | 账户所有者姓名。 | 120 |
| `owner_trading_name`      | string     | 账户所有者商业名称（可选，仅限 CNPJ）。 | 100 |

### account_type 枚举值

| 枚举值 | 描述 |
|----------------------|---------------------|
| **checking_account** | 支票账户 |
| **salary_account**   | 工资账户 |
| **saving_account**   | 储蓄账户 |
| **payment_account**  | 支付账户 |

## 响应

STATUS 201 created

**响应体**

```json
{
  "alias_key": "e04f496b-47be-4762-a6e2-8f2b05b46780",
  "created_at": "2022-09-24T19:46:43.001Z"
}
```

### 响应体参数

| 字段 | 类型 | 描述 | 最大字符数 |
|--------------|---------------|----------------------------------|-----------------|
| `alias_key`  | uuidv4        | Alias 唯一密钥。 | 36 |
| `created_at` | datetime Zulu | 请求执行日期。 | 20 |

STATUS 404

响应体：未找到

```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

响应体：重复的请求控制密钥

```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"
}
```

响应体：无效的所有者商业名称

```json

  {
  "title": "Bad Request", 
  "description": "The owner_trading_name can only be sent by a legal person type", 
  "translation": "O owner_trading_name só pode ser utilizado por uma pessoa jurídica",
  "extra_fields": {}, 
  "code": "ACC000180"
}
```

---

# 删除 Alias 实体

URL: /zh-Hans/documentation/pix_indireto/gerenciamento_de_alias/deletar_alias

删除已为现有账户注册的 Alias 实体。

## 请求

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY
MÉTODO DELETE

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `account_key` | uuidv4 | 账户唯一密钥。 | 36 |
| `alias_key` | uuidv4 | Alias 唯一密钥。 | 36 |

## 响应

STATUS 200

**响应体**

```json
{}
```

STATUS 404

响应体：未找到

```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

响应体：未找到

```json

  {
  "data": "{\"title\": \"Not found\", \"description\": \"Alias \{alias_key\} not found\", \"translation\": \"Alias \{alias_key\} não encontrado\", \"extra_fields\": {}, \"code\": \"ACC000181\"}",
  "title": "Not found", 
  "description": "Alias \{alias_key\} not found", 
  "translation": "Alias \{alias_key\} não encontrado",
  "extra_fields": {}, 
  "code": "ACC000181"
}
```

STATUS 400

响应体：Alias 密钥与账户密钥不匹配

```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"
}
```

---

# Alias 实体简介

URL: /zh-Hans/documentation/pix_indireto/gerenciamento_de_alias/introducao_alias

为了按照巴西中央银行的要求维护和对齐 PIX 密钥注册的相关数据，间接参与者必须在 QI Tech 注册 Alias。

每个 Alias 必然与间接参与者在 QI Tech 拥有的账户相关联。

:::info 信息

本简介部分所描述的所有内容，以及间接参与者应如何通过 API 进行处理，均在后续各节中详细说明。

:::

## Alias 实体代表什么？

Alias 实体是间接参与者的客户在间接参与者处注册的账户数据的"掩码"。需要注意的是，QI Tech 只会对间接参与者发送的数据进行格式验证。

例如：CPF 验证、CNPJ 验证、商业名称最大字符数等。

QI Tech 要求间接参与者发送的与其客户账户相关的数据，仅限于 PIX 功能范围内所需的数据。

## Alias 实践

在实践中，Alias 实体代表间接参与者的客户。

需要创建 Alias 的一个示例为：
间接参与者拥有一个在 QI Tech 注册的账户，其 account_key 为 a520b977-d6b2-4f27-bef5-29760ebfd6a7，
间接参与者希望将自己的某个客户关联到在 QI Tech 注册的该账户，
间接参与者发送客户数据（账号、支行、姓名、商业名称等）以关联到在 QI Tech 注册的该账户，
QI Tech 将间接参与者的客户关联到已注册的间接参与者账户。
间接参与者收到已注册 Alias 的唯一标识密钥。

通过这种方式，间接参与者可以请求创建 PIX 密钥，QI Tech 能够有效地与巴西中央银行沟通，提供注册所需的数据。

##### 1:N 关系中 Alias 使用示意图：
```mermaid
graph LR;
    Account_A-->Alias_A1;
    Account_A-->Alias_A2;
    Account_A-->Alias_A3;
    Account_A-->Alias_A4;
```

##### 1:1 关系中 Alias 使用示意图：

```mermaid
graph LR;
    Account_A-->Alias_A;
    Account_B-->Alias_B;
    Account_C-->Alias_C;
    Account_D-->Alias_D;
```

---

# Alias 列表

URL: /zh-Hans/documentation/pix_indireto/gerenciamento_de_alias/listagem_de_alias

列出账户的 Alias。

## 请求

ENDPOINT /account/ ACCOUNT_KEY /alias
MÉTODO GET

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|---------------|--------|-----------------------|------------|
| `account_key` | uuidv4 | 账户唯一密钥。 | 36 |

### 查询参数

| 字段 | 类型 | 描述 | 最大值 |
|---------------|---------|-----------------------------------------|-----------|
| `page_number` | integer | 当前查询的页码。 | - |
| `page_size`   | integer | 每页结果数量。 | 100 |

## 响应

STATUS 200

**响应体**

```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
  }
}
```

### 响应体参数

| 字段 | 类型 | 描述 | 最大字符数 |
|-------------------------|------------|----------------------------------------------------|---------------------------------------------------------|
| `alias_key`             | string     | Alias 唯一密钥。 | 36 |
| `ispb`                  | string     | 与 Alias 关联的金融机构 ISPB。 | 36 |
| `account_branch`        | string     | 支行号，不含校验位。 | 4 |
| `account_number`        | string     | 账号，不含校验位。 | 20 |
| `account_digit`         | string     | 账号校验位。 | 1 |
| `account_type`          | enumerador | 账户类型。 | **[account_type 枚举值](#enumerador-account_type)** |
| `account_created_at`    | string     | 账户创建日期。 | 20 |
| `owner_document_number` | string     | CPF 或 CNPJ 号码。 | 14 |
| `owner_name`            | string     | 账户所有者姓名。 | 120 |
| `owner_trading_name`    | string     | 账户所有者商业名称（仅限 CNPJ）。 | 100 |
| `created_at`            | string     | 请求创建日期。 | 20 |

### account_type 枚举值

| 枚举值 | 描述 |
|----------------------|---------------------|
| **checking_account** | 支票账户 |
| **salary_account**   | 工资账户 |
| **saving_account**   | 储蓄账户 |
| **payment_account**  | 支付账户 |

STATUS 404

响应体：未找到

```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

响应体：错误的分页查询参数集

```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

响应体：错误的分页查询参数格式

```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"
}
```

---

# 简介

URL: /zh-Hans/documentation/pix_indireto/introducao

在 QI Tech，我们很荣幸通过 PIX 间接参与者服务来扩展我们的服务范围。我们深知一些机构在尝试接入 PIX 时可能面临的挑战，因此，我们致力于让每个人都能轻松、便捷地实现这一目标。

作为高效、安全运营的 PIX 直接参与者，我们实施了一套高科技解决方案，使各种规模的银行、支付机构和金融科技公司都能成为间接参与者，让所有人都能享受 PIX 的优势，而无需承担高昂的运营和技术成本。

我们的 PIX 间接参与者服务提供简化的集成和无忧的操作，成本更低、合规更便捷。此外，您无需担心复杂的技术流程；我们会为您处理一切，让您专注于最重要的事情——您的客户。

通过 QI Tech，您将能够为客户提供快速、安全、每天 24 小时、每周 7 天可用的支付体验。我们的目标是促进您向 PIX 的过渡，使您能够为客户提供最优质的服务。

以下各节介绍了间接参与者可以通过 API 在 PIX 间接参与者框架内执行的功能。

---

# 沙盒环境中的模拟 PIX 密钥

URL: /zh-Hans/documentation/pix_indireto/movimentacoes/chaves_pix_mockadas

## 104 - CAIXA ECONOMICA FEDERAL

| PIX 密钥 | 类型 | 持有人姓名 | 持有人文档 | 账号 | 支行号 | 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.

| PIX 密钥 | 类型 | 持有人姓名 | 持有人文档 | 账号 | 支行号 | 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.

| PIX 密钥 | 类型 | 持有人姓名 | 持有人文档 | 账号 | 支行号 | 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.

| PIX 密钥 | 类型 | 持有人姓名 | 持有人文档 | 账号 | 支行号 | 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

| PIX 密钥 | 类型 | 持有人姓名 | 持有人文档 | 账号 | 支行号 | 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

| PIX 密钥 | 类型 | 持有人姓名 | 持有人文档 | 账号 | 支行号 | 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.

| PIX 密钥 | 类型 | 持有人姓名 | 持有人文档 | 账号 | 支行号 | 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.

| PIX 密钥 | 类型 | 持有人姓名 | 持有人文档 | 账号 | 支行号 | ISPB |
|---|---|---|---|---|---|---|
| 39284100000000 | cnpj | Parcela Mais | 39284100000000 | 1708315-8 | 1 | 37880206 | 

## 422 - BCO SAFRA S.A.

| PIX 密钥 | 类型 | 持有人姓名 | 持有人文档 | 账号 | 支行号 | 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.

| PIX 密钥 | 类型 | 持有人姓名 | 持有人文档 | 账号 | 支行号 | ISPB |
|---|---|---|---|---|---|---|
| 5301321099 | cpf | Vivo Test | 5301321099 | 622660113-8 | 1111 | 59588111 | 

## DOCK SOLUCOES EM MEIOS DE PAGAMENTO S A

| PIX 密钥 | 类型 | 持有人姓名 | 持有人文档 | 账号 | 支行号 | 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 | 

## COMPANHIA GLOBAL DE SOLUCOES E SERVICOS DE PAGAMENTOS S.A.

| PIX 密钥 | 类型 | 持有人姓名 | 持有人文档 | 账号 | 支行号 | ISPB |
|---|---|---|---|---|---|---|
| 96755229091 | cpf | Teste sem Compe | 96755229091 | 1444301-8 | 1 | 32024691 |

---

# 在巴西中央银行查询 PIX 密钥数据

URL: /zh-Hans/documentation/pix_indireto/movimentacoes/consultar_chave_pix

## 请求

ENDPOINT /pix_key/ PIX_KEY
MÉTODO GET

### 请求路径参数

| 字段 | 类型 | 描述 | 字符数 |
|-------------|--------|--------------------------------|------------|
| `pix_key` * | string | 将被查询的 PIX 密钥。 | 77 |

:::info PIX 密钥类型
"pix_key" 可以是 CPF、CNPJ、电子邮件、手机号码或随机密钥（UUID），格式如下：

**CPF**：11 位整数。

**CNPJ**：14 位整数。

**电子邮件**：包含至少一个"@"的文本。

**手机号码**：包含以下值的文本："+55" + "手机区号" + "至少 8 位、最多 9 位的手机号码整数"。例如："+5511987654321"。

**随机密钥**：UUID4。
:::

### 请求查询参数

| 字段 | 类型 | 描述 | 字符数 |
|---------------|--------|-----------------------|------------|
| `alias_key` * | uuidv4 | Alias 唯一密钥。 | 36 |

:::info 查询令牌使用说明
为确保 PIX 密钥查询令牌向正确的人收取费用，必须发送 `alias_key`。
:::

## 响应

STATUS 200

响应体：活跃密钥

```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"
}

```

| 字段 | 类型 | 描述 | 最大字符数 |
|--------------------------------|--------|----------------------------------------------------|-----------------|
| `pix_key`                      | string | 查询的 PIX 密钥。 | 4 |
| `account_branch`               | string | 支行号，不含校验位。 | 4 |
| `account_digit`                | string | 账号校验位。 | 1 |
| `account_number`               | string | 账号，不含校验位。 | 20 |
| `account_type`                 | string | 账户类型定义。 | 20 |
| `owner_person_type`            | string | 账户所有者类型。可以是 "legal" 或 "natural"。 | 7 |
| `owner_masked_document_number` | string | CPF 或 CNPJ 号码（已脱敏）。 | 14 |
| `end_to_end_id`                | string | PIX 交易唯一密钥。 | 32 |
| `owner_name`                   | string | 账户所有者姓名。 | 120 |
| `owner_trading_name`           | string | 账户所有者商业名称（仅限 CNPJ）。 | 100 |
| `ispb`                         | string | 密钥持有参与者的 ISPB。 | 8 |
| `bank_code`                    | string | 金融机构的 COMPE 代码。 | 3 |
| `financial_institution`        | string | 密钥持有金融机构名称。 | 100 |
| `account_created_at`           | string | 账户创建日期。 | 20 |

STATUS 4XX

响应体：错误

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

| HTTP 状态码 | QI 错误码<br/>`code` | 标题<br/>`title` | 英文描述<br/>`Description` | 葡文描述<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                                                   |

---

# 查询 PIX 交易

URL: /zh-Hans/documentation/pix_indireto/movimentacoes/consultar_pix

## 请求

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_transfer/ PIX_TRANSFER_KEY / PIX_TRANSFER_DIRECTION
MÉTODO GET

### 请求路径参数

| 字段 | 类型 | 描述 |
|----------------------------|--------|--------------------------------------------------------------------------------------------------|
| `pix_transfer_direction` * | string | 用于指示交易是入账还是出账的过滤器。值：**incoming** 和 **outgoing**。 |
| `account_key` *            | string | QI 账户唯一标识密钥。 |
| `alias_key` *              | string | Alias 唯一密钥。 |
| `pix_transfer_key` *       | string | PIX 转账唯一标识密钥。 |

:::caution 注意
只有当请求方在交易出账 Alias 上拥有权限时，才允许查看转账。否则将返回未找到错误。
:::

## 响应

STATUS 201

响应体：已发送转账（出账）

```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"
    }
  ]
}

```

响应体：已拒绝转账（出账）

```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": []
}

```

响应体：已发送退款（出账）

```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"
}

```

响应体：已接收转账（入账）

```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": []
}
```

响应体：已接收退款（入账）

```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"
}
```

响应体：已拒绝转账（入账）

```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

响应体：错误

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

| HTTP 状态码 | QI 错误码<br/>`code` | 标题<br/>`title` | 英文描述<br/>`Description` | 葡文描述<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                       |

---

# 执行 PIX 退款

URL: /zh-Hans/documentation/pix_indireto/movimentacoes/devolucao_pix

PIX 退款可在收款后 90 天内进行。

## 请求

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_transfer/ PIX_TRANSFER_KEY /reversal
MÉTODO POST

### 请求路径参数

| 字段 | 类型 | 描述 | 字符数 |
|--------------------|--------|--------------------------------------------------------------------|------------|
| `account_key`      | string | 账户唯一密钥（UUIDv4）。 | 36 |
| `alias_key`        | string | Alias 唯一密钥（UUIDv4）。 | 36 |
| `pix_transfer_key` | string | QI 系统中 PIX 转账的标识密钥（UUIDv4）。 | 36 |

请求体

```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_control_key`* | string | 请求唯一密钥（UUIDv4）。 | 36 |
| `reversal_amount`*     | number | 退款金额。 | 11 |
| `reversal_reason`*     | string | 退款原因。 | **[reversal_reason 枚举值](#enumerador-reversal_reason)** |
| `reversal_message`     | string | 退款消息。 | 140 |

### reversal_reason 枚举值

| 枚举值 | 描述 |
|--------------------|----------------------------------------------|
| **client_request** | 账户所有者要求退款时使用。 |
| **reconciliation** | 因操作错误进行对账时使用。 |

## 响应

### 响应体

| 字段 | 类型 | 描述 | 字符数 |
|-----------------------|--------|---------------------------------------------------------------------------------------------|------------|
| `reversal_status`     | string | 退款交易状态枚举值。可以是 'pending'、'sent' 和 'rejected'。 | 36 |
| `transfer_amount`     | number | 退款转账金额。 | 11 |
| `pix_transfer_key`    | string | 退款中执行的 PIX 交易密钥（UUIDv4）。 | 36 |
| `end_to_end_id`       | string | SPI（即时支付系统）中 PIX 交易的幂等性密钥。 | 32 |
| `request_control_key` | string | 客户使用的请求唯一标识密钥（UUIDv4）。 | 36 |
| `created_at`          | string | 退款日期和时间。 | --- |

STATUS 201 created

响应体：已发送退款

```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 信息

如果返回的 `pix_transfer_status` 为 **pending** 状态，则不应重试 PIX 请求。该转账将被重新处理。需要通过 PIX 转账查询来检查转账状态。

:::

响应体：待处理退款

```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

响应体：已拒绝退款

```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 信息

除以下所列错误外，PIX 退款还可能收到 [PIX 交易](./transacao/transacao_pix_manual_sync) 中定义的其他错误。

:::

| HTTP 状态码 | QI 错误码<br/>`code` | 标题<br/>`title` | 英文描述<br/>`Description` | 葡文描述<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                                        |

---

# PIX 范围内交易简介

URL: /zh-Hans/documentation/pix_indireto/movimentacoes/introducao_movimentacoes

间接参与者的客户（Alias）可以请求 PIX 范围内与交易相关的多种功能。其中包括：

手动 PIX 交易
通过密钥进行 PIX 交易
PIX QRCode 交易
PIX 退款

### PIX 转账类型（pix_transfer_type）

| 枚举值 | 描述 |
|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **manual**          | 使用目标账户数据的 PIX。必须发送 `target_account`。 |
| **key**             | 使用 PIX 密钥的 PIX。必须发送 `target_pix_key`。如果进行了 [PIX 密钥查询](/documentation/pix_indireto/movimentacoes/consultar_chave_pix)，建议发送查询返回的 `end_to_end_id`。 |
| **static_qr_code**  | 使用静态 QR 码的 PIX。必须发送 [QR 码解码](/documentation/pix/decodificar_qr_code) 返回的 `end_to_end_id`。 |
| **dynamic_qr_code** | 使用动态 QR 码的 PIX。必须发送 [QR 码解码](/documentation/pix/decodificar_qr_code) 返回的 `end_to_end_id`。 |
| **reversal**        | PIX 退款。 |

在这些功能中，间接参与者可以根据需求选择交易的"同步性"类型。

:::info 信息

本简介部分所描述的所有内容，以及间接参与者应如何通过 API 进行处理，均在后续各节中详细说明。

:::

## 端到端 ID

每笔 PIX 交易在中央银行都有一个唯一标识符。端到端 ID（End to End ID）是 PIX 转账的端到端标识符，用于控制巴西中央银行的速率限制。

```mermaid
sequenceDiagram
    Participante Indireto->>+Banco Central: Consulta de Chave Pix
    Banco Central-->>-Participante Indireto: Chave Pix + End to End ID da consulta <br> Token consumida do bucket
    Participante Indireto->>+Banco Central: Transferência com End to End ID
    Banco Central-->>-Participante Indireto: Sucesso na transação com chave pix <br> Token devolvido ao bucket
```

每个个人或法人注册都在巴西中央银行拥有一个令牌桶。PIX 密钥查询请求会消耗该桶中的令牌，当执行与查询关联的 PIX 交易时，令牌会被归还。PIX 密钥查询与交易之间的关联通过端到端 ID 建立。

## 交易同步性

间接参与者可以选择以同步或异步方式执行 PIX 交易。在两种模式下，PIX 交易都将在巴西中央银行规定的时间内执行。

:::info 信息

我们的团队将根据与客户商定的情况配置要使用的同步性模式。

:::

:::info 信息

同步和异步模式的端点、方法、负载和其他请求组件完全相同。区别仅在于，对于异步模式，如果通过初始验证，响应始终是状态为 **pending** 的 `pix_transfer`。随后将发送一个 webhook ，告知交易的最终状态（**sent** 或 **rejected**）。

:::

## 交易重试

由于巴西中央银行消息系统在处理 PIX 交易时可能出现延迟，QI Tech 对同步和异步模式的 PIX 交易都提供了重试机制。

如果出现此情况，间接参与者将收到 HTTP 202 状态码，表示交易已发送至 QI Tech，正等待巴西中央银行确认。重试完成后，间接参与者将通过 webhook 获知交易的执行情况。

---

# 场景模拟

URL: /zh-Hans/documentation/pix_indireto/movimentacoes/simulacao

模拟外部代理执行操作的分步说明。这些模拟包括入账交易和退款。

:::info 信息
这些请求没有返回负载（响应体）。
:::

## 1 - 模拟 PIX 入账

### 请求

ENDPOINT /mock/pix_transfer/incoming_pix_transfer
MÉTODO POST

请求体

```json
{
  "target_account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "target_alias_key": "c4332971-7cff-42eb-a117-7e6f0cd74db2",
  "amount": 100.01
}

```

### 请求体对象

| 字段 | 类型 | 描述 | 最大字符数 |
|-------------------------|--------|---------------------------------|--------------|
| **target_account_key*** | string | 目标账户唯一密钥。 | 36 |
| **target_alias_key**    | string | 目标 Alias 唯一密钥。 | 36 |
| **amount***             | number | 交易金额。 | 6 |

## 2 - 模拟 PIX QR 码付款

### 请求

ENDPOINT /mock/pix_transfer/incoming_pix_qrcode
MÉTODO POST

请求体

```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\>"
}

```

### 请求体对象

| 字段 | 类型 | 描述 | 最大字符数 | 示例 | 备注 |
|-------------------------------|---------|-------------------------------------------|--------------|----------------------------------------|-------------------------|
| **target_alias_key***         | string  | 目标 Alias 唯一密钥。 | 36           | "41112f46-0034-4007-85687-5e592173db2" | |
| **amount***                   | decimal | 交易金额。 | 6            | 1000.00                                | 最大值 100,000 |
| **receiver_conciliation_id*** | string  | QR 码接收方对账 ID。 | 36           | 1000                                   | |

## 3 - 模拟 PIX 退款

模拟 PIX 出账转账的退款。为此，所有退款的总金额不得超过原始转账的金额。要识别目标交易，请发送原始转账的 `end_to_end_id`。

### 请求

ENDPOINT /mock/pix_transfer/reversal
MÉTODO POST

请求体

```json
{
  "end_to_end_id": "E35713491202309182110sSCNh25ooX2",
  "amount": 100.00
}

```

### 请求体对象

| 字段 | 类型 | 描述 | 最大字符数 |
|--------------------|--------|---------------------------------------------|--------------|
| **end_to_end_id*** | string | 待退款交易的唯一密钥。 | 32 |
| **amount***        | number | 待退款金额。 | 6 |

## 4 - 模拟等待确认状态的交易

当巴西中央银行的 PIX 交易响应出现延迟时，PIX 交易可能进入 **pending_confirmation** 状态。要模拟此场景，请使用 PIX 密钥 `"target_pix_key": "0476f803-0129-430a-a66c-d2f0d7cf4aaa"` 执行交易；对于 **manual** 类型的 PIX 转账，请使用目标账户所有者文档号 `"owner_document_number": "35586870002"`。

要更新交易状态，请使用 `transaction_status` 为 **sent**（批准交易）或 **rejected**（拒绝交易）执行以下请求。

### 请求

ENDPOINT /mock/pix_transfer/pending_confirmation
MÉTODO POST

请求体

```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"
}
```

### 请求体参数

| 字段 | 类型 | 描述 | 最大字符数 |
|-----------------------------|--------|-----------------------------------------------------------------------|--------------|
| `end_to_end_id`*            | string | PIX 交易唯一密钥。 | 36 |
| `transaction_status`*       | enum   | [交易状态枚举值](#enumerador-transaction-status) | |
| `status_reason_information` | objeto | [状态原因信息对象](#objeto-status-reason-information) | |
| `error_code`                | string | 错误代码。 | |

### 交易状态枚举值

| 枚举值 | 描述 |
|--------------|-----------|
| **sent**     | 已完成。 |
| **rejected** | 已拒绝。 |

### 状态原因信息对象

| 字段 | 类型 | 描述 | 最大字符数 |
|---------------------------|--------|-----------------------------------|--------------|
| `error_description`       | string | 英文错误描述。 | 100 |
| `error_translation`       | string | 葡文错误描述。 | 100 |
| `error_short_description` | string | 英文简短错误描述。 | 100 |

## 5 - 模拟已拒绝交易

当巴西中央银行或收款 PSP 返回预期的拒绝响应时，PIX 交易可能进入 **rejected** 状态。要模拟此场景，请使用 PIX 密钥 `"target_pix_key": "b9380607-dac6-4e17-8ca7-eb761e3aa1dc"` 执行交易；对于 **manual** 类型的 PIX 转账，请使用目标账户所有者文档号 `"owner_document_number": "66972913039"` 或 `"owner_document_number": "50305556000164"`。

---

# 执行手动 PIX 异步转账

URL: /zh-Hans/documentation/pix_indireto/movimentacoes/transacao_async/transacao_pix_manual

## 请求

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_transfer
MÉTODO POST

请求体

```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"
}

```

### 请求体参数

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `request_control_key` *| uuidv4 | 用于查询所发请求的 UUID4。 | 36 |
| `pix_transfer_type` * | string | PIX 有不同的发起类型："manual" 表示用户需发送目标账户和来源账户字段；"key" 表示用户需发送收款方的 PIX 密钥（目标账户）和来源账户数据。 | 6 |
| `target_account` *| Object | 目标账户 - 仅在 "manual" 类型交易中发送。 | **[target_account 对象](#objeto-target_account)** |
| `pix_message`  | string | 随 PIX 发送的可选消息。 | 140 |
| `transaction_amount` * | float | 交易金额。 | 20 |
| `schedule_date` | date | 交易调度日期（如未发送，则在批准时立即执行转账）。 | 10 |

### target_account 对象

| 字段 | 类型 | 描述 | 字符数 |
|-------|------|-----------|------------|
| `account_branch` * | string | 支行号。 | 4 |
| `account_digit` * | string | 账号校验位。 | 1 |
| `account_number` *  | string | 账号。 | 8 |
| `owner_document_number` * | string | 账户持有人的 CPF 或 CNPJ（仅数字）。 | 14 |
| `owner_name` * | string | 账户持有人姓名。 | 120 |
| `account_type` * | string | 账户类型，可为 `checking_account`、`deposit_account`、`guaranteed_account`、`investment_account`、`saving_account`。 | 20 |
| `owner_trading_name` | string | 法人的商业名称。仅用于 CNPJ。 | 10 |
| `ispb` *| string | 在巴西中央银行储备转账系统中识别银行的八位代码。 | 8 |

:::info HTTP Status 202 Accepted
在异步 PIX 中，所有交易都返回 **http status 202 Accepted**，PIX 请求**不应重试**。在此场景中，交易将适时执行，并通过[交易更新 Webhook](/documentation/pix_indireto/movimentacoes/webhook/webhook_transacao) 进行更新。
还可以通过端点 [/account/ACCOUNT_KEY/alias/ALIAS_KEY/pix_transfer/PIX_TRANSFER_KEY](/documentation/pix_indireto/movimentacoes/consultar_pix) 查询交易状态。
:::

## 响应

STATUS 202 Accepted

响应体：手动转账

```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

响应体

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

```

---

# 通过 PIX 密钥执行异步转账

URL: /zh-Hans/documentation/pix_indireto/movimentacoes/transacao_async/transacao_pix_normal

## 请求

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_transfer
MÉTODO POST

请求体

```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"
}

```

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|---------------------|--------|-----------------------|------------|
| `account_key`       | uuidv4 | 账户的唯一密钥。 | 36 |
| `alias_key` | uuidv4 | Alias 的唯一密钥。 | 36 |

### 请求体参数

| 字段 | 类型 | 描述 | 最大字符数 |
|---------|------|-----------|------------|
| `request_control_key` *| uuidv4 | 用于查询所发请求的 UUID4。 | 36 |
| `pix_transfer_type` * | string | PIX 有不同的发起类型："manual" 表示用户需发送目标账户和来源账户字段；"key" 表示用户需发送收款方的 PIX 密钥（目标账户）和来源账户数据。 | 6 |
| `transfer_time` * | string | 交易同步性信息，用于定义交易的处理时机。若为 "synchronous"，交易将立即执行，但受每分钟最大交易数限制。若为 "asynchronous"，交易将适时处理。 | 200 |
| `target_pix_key` * | string | 将接收交易的 PIX 密钥。 | 200 |
| `pix_message` *  | string | 随 PIX 发送的可选消息。 | 140 |
| `transaction_amount` * | float | 交易金额。 | 20 |
| `end_to_end_id` | string | 在巴西中央银行中唯一标识交易或查询的密钥。示例：E3240250220210615135810450327042。 | 32 |
| `schedule_date` | date | 交易调度日期（如未发送，则在批准时立即执行转账）。 | 10 |

:::info HTTP Status 202 Accepted
在异步 PIX 中，所有交易都返回 **http status 202 Accepted**，PIX 请求**不应重试**。在此场景中，交易将适时执行，并通过[交易更新 Webhook](/documentation/pix_indireto/movimentacoes/webhook/webhook_transacao) 进行更新。
还可以通过端点 [/account/ACCOUNT_KEY/alias/ALIAS_KEY/pix_transfer/PIX_TRANSFER_KEY](/documentation/pix_indireto/movimentacoes/consultar_pix) 查询交易状态。
:::
## 响应

STATUS 202 Accepted

响应体

```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

响应体：无效请求体

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

```

---

# 执行 PIX QR 码异步转账

URL: /zh-Hans/documentation/pix_indireto/movimentacoes/transacao_async/transacao_pix_qr_code

## 请求

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_transfer
MÉTODO POST

请求体

```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"
}
```

### 请求体参数

| 字段 | 类型 | 描述 | 最大字符数 |
|---------|------|-----------|------------|
| `request_control_key` *| uuidv4 | 用于查询所发请求的 UUID4。 | 36 |
| `pix_transfer_type` * | string | PIX 有不同的发起类型："manual" 表示用户需发送目标账户和来源账户字段；"key" 表示用户需发送收款方的 PIX 密钥（目标账户）和来源账户数据。 | 6 |
| `target_pix_key` * | string | 将接收交易的 PIX 密钥。 | 200 |
| `pix_message`  | string | 随 PIX 发送的可选消息。 | 140 |
| `transaction_amount` * | float | 交易金额。 | 20 |
| `end_to_end_id` | string | 在巴西中央银行中唯一标识交易或查询的密钥。示例：E3240250220210615135810450327042。 | 32 |
| `schedule_date` | date | 交易调度日期（如未发送，则在批准时立即执行转账）。 | 10 |
| `receiver_conciliation_id` * | string | 接收方对账标识符，在解码 QR 码时生成。 | 10 |

:::info HTTP Status 202 Accepted
在异步 PIX 中，所有交易都返回 **http status 202 Accepted**，PIX 请求**不应重试**。在此场景中，交易将适时执行，并通过[交易更新 Webhook](/documentation/pix_indireto/movimentacoes/webhook/webhook_transacao) 进行更新。
还可以通过端点 [/account/ACCOUNT_KEY/alias/ALIAS_KEY/pix_transfer/PIX_TRANSFER_KEY](/documentation/pix_indireto/movimentacoes/consultar_pix) 查询交易状态。
:::

## 响应

STATUS 202 Accepted

响应体

```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

响应体：无效请求体

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

```

STATUS 202

响应体：待处理转账

```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
如果返回 **http status 202**，PIX 请求**不应重试**。需要通过 GET 请求路由 [/baas/pix/pix_transfer](/documentation/pix/pesquisar_por_transferencia_pix_de_saida) 检查 PIX 转账请求的状态。
:::

---

# 通过 PIX 密钥进行 PIX 交易

URL: /zh-Hans/documentation/pix_indireto/movimentacoes/transacao/transacao_pix_chave_sync

## 请求

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_transfer
MÉTODO POST

请求体

```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"
}

```

### 请求体参数

| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|------------|-------------------------------------------------------------------------------------------------------|------------|
| `request_control_key` * | string     | 客户使用的请求唯一标识密钥，格式为 uuid v4。 | 36 | 
| `pix_transfer_type` *   | enumerador | 要执行的 PIX 类型。对于密钥转账，必须为 **key**。 | "key" |
| `target_pix_key` *      | string     | 目标账户的 PIX 密钥。 | 100 |
| `transaction_amount` *  | number     | 转账金额。 | 10 |
| `end_to_end_id` *       | string     | PIX 交易的幂等性密钥 - 仅当转账类型为 "key" 时发送。 | 32 |
| `pix_message`           | string     | 随 PIX 转账发送的消息。 | 140 |

:::info 提示
必须发送与[密钥查询](/documentation/pix_indireto/movimentacoes/consultar_chave_pix)相关的 `end_to_end_id`。
:::

:::danger 提示
查询的 `end_to_end_id` 必须以将请求交易的 alias 名义完成！
:::

:::danger 提示
一个 `end_to_end_id` 只能用于一次转账，无论转账是否成功。
:::

## 响应

STATUS 201

响应体：已发送转账

```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 信息

如果返回的 `pix_transfer_status` 为 **pending** 状态，则不应重试 PIX 请求。该转账将被重新处理。需要通过 PIX 转账查询来检查转账状态。

:::

响应体：待处理转账

```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

响应体：已拒绝转账

```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

响应体：错误

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

| HTTP 状态码 | QI 错误码<br/>`code` | 标题<br/>`title` | 英文描述<br/>`Description` | 葡文描述<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         | 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                                                                        |

---

# 手动 PIX 交易

URL: /zh-Hans/documentation/pix_indireto/movimentacoes/transacao/transacao_pix_manual_sync

## 请求

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_transfer
MÉTODO POST

请求体

```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"
}

```

### 请求体参数

| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|------------|--------------------------------------------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | string     | 客户使用的请求唯一标识密钥，格式为 uuid v4。 | 36 | 
| `pix_transfer_type` *   | enumerador | 要执行的 PIX 类型。对于手动转账，必须为 **manual**。 | "manual" |
| `target_account` *      | Object     | 目标账户 - 仅在 "manual" 类型交易中发送。 | **[target_account 对象](#objeto-target_account)** |
| `transaction_amount` *  | number     | 转账金额。 | 10 |
| `pix_message`           | string     | 随 PIX 转账发送的消息。 | 140 |

:::warning 提示
一个 `end_to_end_id` 只能用于一次转账，无论转账是否成功。
:::

### target_account 对象

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|------------|---------------------------------------------------------------------------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string     | 账户支行号。 | 6 |
| `account_digit` *         | string     | 账号校验位。 | 1 |
| `account_number` *        | string     | 账号。 | 20 |
| `owner_document_number` * | string     | 账户持有人的 CPF 或 CNPJ（仅数字）。 | 14 |
| `owner_name` *            | string     | 账户持有人姓名。 | 150 |
| `account_type`*           | enumerador | 账户类型。 | **[account_type 枚举值](#enumerador-account_type)** |
| `ispb` *                  | string     | 在巴西中央银行储备转账系统中识别银行的八位代码。 | 8 |

### account_type 枚举值

| 枚举值 | 描述 |
|----------------------|---------------------|
| **checking_account** | 支票账户 |
| **salary_account**   | 工资账户 |
| **saving_account**   | 储蓄账户 |
| **payment_account**  | 支付账户 |

## 响应

STATUS 201

响应体：已发送转账

```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 信息

如果返回的 `pix_transfer_status` 为 **pending** 状态，则不应重试 PIX 请求。该转账将被重新处理。需要通过 PIX 转账查询来检查转账状态。

:::

响应体：待处理转账

```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

响应体：已拒绝转账

```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

响应体：错误

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

| HTTP 状态码 | QI 错误码<br/>`code` | 标题<br/>`title` | 英文描述<br/>`Description` | 葡文描述<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         | 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.                                                                         |
| 400         | PXT000109            | Bad Request                                        | request_control_key \{request_control_key\} already in use                                                              | request_control_key \{request_control_key\} já utilizada                                                               |
| 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         | 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.                                                                           |
| 403         | PXT000144            | Rejected Payment Order                             | Beneficiary's PSP has rejected payment order.                                                                           | Ordem de pagamento foi rejeitada pelo banco 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                                                          |

---

# 通过 QR 码进行 PIX 交易

URL: /zh-Hans/documentation/pix_indireto/movimentacoes/transacao/transacao_pix_qr_code_sync

## 请求

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_transfer
MÉTODO POST

请求体

```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"
}

```

### 请求体参数

| 字段 | 类型 | 描述 | 字符数 |
|----------------------------|------------|--------------------------------------------------------------------------------------------------------------------------|---------------------------------------|
| `request_control_key` *    | string     | 客户使用的请求唯一标识密钥，格式为 uuid v4。 | 36 | 
| `pix_transfer_type` *      | enumerador | 要执行的 PIX 类型。对于 QR 码转账，必须为 **static_qr_code** 或 **dynamic_qr_code**。 | "static_qr_code" 或 "dynamic_qr_code" |
| `target_pix_key` *         | string     | 目标账户的 PIX 密钥。 | 100 |
| `receiver_conciliation_id` | string     | 接收方对账标识符。 | 35 |
| `transaction_amount` *     | number     | 转账金额。 | 10 |
| `end_to_end_id` *          | string     | PIX 交易的幂等性密钥 - 仅当转账类型为 "key" 时发送。 | 32 |
| `pix_message`              | string     | 随 PIX 转账发送的消息。 | 140 |

:::info 提示
必须发送与 [QR 码解码](/documentation/pix/decodificar_qr_code) 相关的 `end_to_end_id`。
:::

:::danger 提示
查询的 `end_to_end_id` 必须以将请求交易的 alias 名义完成！
:::

:::danger 提示
一个 `end_to_end_id` 只能用于一次转账，无论转账是否成功。
:::

## 响应

STATUS 201

响应体：已发送转账

```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 信息

如果返回的 `pix_transfer_status` 为 **pending** 状态，则不应重试 PIX 请求。该转账将被重新处理。需要通过 PIX 转账查询来检查转账状态。

:::

响应体：待处理转账

```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

响应体：已拒绝转账

```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

响应体：错误

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

| HTTP 状态码 | QI 错误码<br/>`code` | 标题<br/>`title` | 英文描述<br/>`Description` | 葡文描述<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         | PXT000053            | Bad Request                                        | QrCode already paid                                                                                                     | Qr Code já Pago                                                                                                        |
| 404         | PXT000041            | Not Found                                          | Qr Code not found                                                                                                       | Qr Code não encontrado                                                                                                 |
| 400         | PXT000156            | QR Code Rejected                                   | QR Code rejected by beneficiary's PSP.                                                                                  | QR Code rejeitado pelo PSP do usuário recebedor.                                                                       |
| 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         | PXT000158            | Invalid Amount                                     | Paid amount diverges from expected amount of \{expected_amount\}                                                        | O valor do pagamento diverge do valor esperado de \{expected_amount\}                                                  |
| 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                                                          |

---

# PIX 退款 Webhook

URL: /zh-Hans/documentation/pix_indireto/movimentacoes/webhook/webhook_devolucao_outgoing_pix

用于通知到达某个 Alias 的 PIX 退款的 Webhook。

## Webhook 请求体

**请求体：已收到 PIX**

```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 请求体参数

| 字段 | 类型 | 描述 | 最大字符数 |
|----------------------------------|------------|-------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `webhook_type`                   | string     | 定义所报告事件类型的枚举值。 | 23 |
| `webhook_datetime`               | string     | Webhook 发送的日期和时间。 | 20 |
| `pix_transfer_type`              | enumerador | 执行的 PIX 类型。 | **[pix_transfer_type 枚举值](#enumerador-pix_transfer_type)** |
| `target_pix_key`                 | string     | 目标账户的 PIX 密钥。 | 100 |
| `source_account`                 | Object     | 来源账户 - 仅在 "manual" 类型交易中发送。 | **[source_account 对象](#objeto-source_account)** |
| `transfer_amount`                | number     | 转账金额。 | 10 |
| `receiver_conciliation_id`       | string     | 接收方对账标识符。 | 35 |
| `end_to_end_id`                  | string     | PIX 交易的幂等性密钥 - 仅当转账类型为 "key" 时发送。 | 32 |
| `pix_message`                    | string     | 随 PIX 转账发送的消息。 | 140 |
| `fee_amount`                     | number     | 手续费金额。 | 10 |
| `pix_transfer_status`            | string     | PIX 交易状态。 | 10 |
| `account_key`                    | string     | QI 账户的唯一标识密钥。 | 36 |
| `alias_key`                      | string     | Alias 的唯一密钥。 | 36 |
| `pix_transfer_key`               | string     | PIX 转账的唯一标识密钥。 | 36 |
| `original_outgoing_pix_transfer` | string     | 原始出站 PIX 转账的唯一标识密钥。 | 36 |

### pix_transfer_type 枚举值

| 枚举值 | 描述 |
|---------------------|------------------------------------------|
| **manual**          | 使用目标账户数据的 PIX。 |
| **key**             | 使用 PIX 密钥的 PIX。 |
| **static_qr_code**  | 使用静态 QR 码的 PIX。 |
| **dynamic_qr_code** | 使用动态 QR 码的 PIX。 |
| **reversal**        | PIX 退款。 |

### source_account 对象

| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|------------|---------------------------------------------------------------------------------------------------------|---------------------------------------------------------|
| `account_branch`        | string     | 账户支行号。 | 6 |
| `account_digit`         | string     | 账号校验位。 | 1 |
| `account_number`        | string     | 账号。 | 20 |
| `owner_document_number` | string     | 账户持有人的 CPF 或 CNPJ（仅数字）。 | 14 |
| `owner_name`            | string     | 账户持有人姓名。 | 150 |
| `account_type`          | enumerador | 账户类型。 | **[account_type 枚举值](#enumerador-account_type)** |
| `ispb`                  | string     | 在巴西中央银行储备转账系统中识别银行的八位代码。 | 8 |

### account_type 枚举值

| 枚举值 | 描述 |
|----------------------|---------------------|
| **checking_account** | 支票账户 |
| **salary_account**   | 工资账户 |
| **saving_account**   | 储蓄账户 |
| **payment_account**  | 支付账户 |

---

# 入站 PIX Webhook

URL: /zh-Hans/documentation/pix_indireto/movimentacoes/webhook/webhook_incoming_pix

用于通知到达某个 Alias 的 PIX 交易的 Webhook。

## Webhook 请求体

**请求体：已收到 PIX**

```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 请求体参数

| 字段 | 类型 | 描述 | 最大字符数 |
|----------------------------|------------|-------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `webhook_type`             | string     | 定义所报告事件类型的枚举值。 | 23 |
| `webhook_datetime`         | string     | Webhook 发送的日期和时间。 | 20 |
| `pix_transfer_type`        | enumerador | 执行的 PIX 类型。 | **[pix_transfer_type 枚举值](#enumerador-pix_transfer_type)** |
| `target_pix_key`           | string     | 目标账户的 PIX 密钥。 | 100 |
| `source_account`           | Object     | 来源账户 - 仅在 "manual" 类型交易中发送。 | **[source_account 对象](#objeto-source_account)** |
| `transfer_amount`          | number     | 转账金额。 | 10 |
| `receiver_conciliation_id` | string     | 接收方对账标识符。 | 35 |
| `end_to_end_id`            | string     | PIX 交易的幂等性密钥 - 仅当转账类型为 "key" 时发送。 | 32 |
| `pix_message`              | string     | 随 PIX 转账发送的消息。 | 140 |
| `fee_amount`               | number     | 手续费金额。 | 10 |
| `pix_transfer_status`      | string     | PIX 交易状态。 | 10 |
| `account_key`              | string     | QI 账户的唯一标识密钥。 | 36 |
| `alias_key`                | string     | Alias 的唯一密钥。 | 36 |
| `pix_transfer_key`         | string     | PIX 转账的唯一标识密钥。 | 36 |

### pix_transfer_type 枚举值

| 枚举值 | 描述 |
|---------------------|------------------------------------------|
| **manual**          | 使用目标账户数据的 PIX。 |
| **key**             | 使用 PIX 密钥的 PIX。 |
| **static_qr_code**  | 使用静态 QR 码的 PIX。 |
| **dynamic_qr_code** | 使用动态 QR 码的 PIX。 |
| **reversal**        | PIX 退款。 |

### source_account 对象

| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|------------|---------------------------------------------------------------------------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string     | 账户支行号。 | 6 |
| `account_digit` *         | string     | 账号校验位。 | 1 |
| `account_number` *        | string     | 账号。 | 20 |
| `owner_document_number` * | string     | 账户持有人的 CPF 或 CNPJ（仅数字）。 | 14 |
| `owner_name`              | string     | 账户持有人姓名。 | 150 |
| `account_type`*           | enumerador | 账户类型。 | **[account_type 枚举值](#enumerador-account_type)** |
| `ispb` *                  | string     | 在巴西中央银行储备转账系统中识别银行的八位代码。 | 8 |

### account_type 枚举值

| 枚举值 | 描述 |
|----------------------|---------------------|
| **checking_account** | 支票账户 |
| **salary_account**   | 工资账户 |
| **saving_account**   | 储蓄账户 |
| **payment_account**  | 支付账户 |

---

# 待处理交易 Webhook

URL: /zh-Hans/documentation/pix_indireto/movimentacoes/webhook/webhook_transacao

用于通知原本以待处理状态响应（返回 http status 202）的交易完成情况的 Webhook。

## Webhook 请求体
**请求体：已发送交易**

```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"
  }
}
```

**请求体：已拒绝交易**

```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 请求体参数

| 字段 | 类型 | 描述 | 最大字符数 |
|---------|---------|-----------------------------------------------------------|------------|
| `webhook_type` | string  | 定义所报告事件类型的枚举值。 | 23 |
| `webhook_datetime` | string  | Webhook 发送的日期和时间。 | 20 |
| `request_control_key` | string  | 用于查询所发请求的 UUID4。 | 36 |
| `pix_transfer_key` | string  | 在 QI 系统中识别 PIX 转账的密钥。 | 36 |
| `pix_transfer_status` | string  | 交易状态。 | 200 |
| `created_at` | string  | 交易创建的日期和时间。 | 20 |

---

# 取消可携性申请

URL: /zh-Hans/documentation/pix_indireto/portabilidade/cancelar_pedido_de_portabilidade

:::info
可携性申请取消须满足以下条件：

状态必须为 `waiting resolution`。

若取消原因为 `default`，则 `max_resolution_date` 字段规定的期限必须已过期。
:::
下表根据取消原因定义了谁可以取消可携性申请。

| 原因 | 捐赠方 | 申请方 |
| ----------------- | ------ | ------------- |
| `client_request`    | ✓      | ✓             |
| `account_closure`   | ✓      |               |
| `default` |        | ✓             |
| `fraud`             | ✓      | ✓             |

## 请求

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /claim/ CLAIM_REQUEST_KEY
MÉTODO PATCH

**请求体**

```json
{
    "request_control_key": "8a923886-afce-4116-ac1f-69bdffcf8da9",
    "claim_request_status": "cancelled",
    "cancellation_reason": "client_request",
}
```

| cancellation_reason | 描述 |
| ------------------- |---------------------------------------------------------------------------|
| `client_request`    | 申请方用户请求取消可携性申请。 |
| `account_closure`   | 账户在可携性流程中被关闭。 |
| `default` | 申请方用户的密钥所有权验证期限已过期。 |
| `fraud`             | 可携性申请的开启存在欺诈行为。 |

## 响应

STATUS 200

**响应体**

```json
{
	"request_control_key": "95968498-5ad0-465a-9174-969d0bd1e84a",
	"claim_request_status": "cancelled",
    "created_at": "2024-05-25T12:13:25"
}
```

| 字段 | 描述 | 类型 |
| ------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------- |
| `claim_request_status`    | 可携性申请的状态。 | string |
| `created_at`              | 可携性申请的创建日期。 | datetime string |
| `request_control_key`     | 请求的唯一 UUID4 标识符。 | uuid4 string |

| claim_request_status | 描述 |
| -------------------- | ---------------------------------------------------------------------------------------- |
| `waiting_resolution` | 通知已被对方接收。 |
| `confirmed`          | 捐赠方已确认申领，正在等待申请方完成流程。 |
| `cancelled`          | 捐赠方或申请方取消了可携性申请。 |
| `completed`          | DICT 和申请方均已以新绑定更新了各自的数据库。 |

---

# 完成可携性申请

URL: /zh-Hans/documentation/pix_indireto/portabilidade/completar_pedido_de_portabilidade

:::info
完成申领操作。其结果是创建密钥绑定。

## 请求

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /claim/ CLAIM_REQUEST_KEY
MÉTODO PATCH

**请求体**

```json
{
    "request_control_key": "8a923886-afce-4116-ac1f-69bdffcf8da9",
    "claim_request_status": "completed",
}
```

## 响应

STATUS 200

**响应体**

```json
{
	"request_control_key": "95968498-5ad0-465a-9174-969d0bd1e84a",
	"claim_request_status": "completed",
    "created_at": "2024-05-25T12:13:25"
}
```

| 字段 | 描述 | 类型 |
| ------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------- |
| `claim_request_status`    | 可携性申请的状态。 | string |
| `created_at`              | 可携性申请的创建日期。 | datetime string |
| `request_control_key`     | 请求的唯一 UUID4 标识符。 | uuid4 string |

| claim_request_status | 描述 |
| -------------------- | ---------------------------------------------------------------------------------------- |
| `waiting_resolution` | 通知已被对方接收。 |
| `confirmed`          | 捐赠方已确认申领，正在等待申请方完成流程。 |
| `cancelled`          | 捐赠方或申请方取消了可携性申请。 |
| `completed`          | DICT 和申请方均已以新绑定更新了各自的数据库。 |

---

# 确认可携性申请

URL: /zh-Hans/documentation/pix_indireto/portabilidade/confirmar_pedido_de_portabilidade

确认申领操作。其结果是移除密钥与捐赠方参与者的绑定。

状态必须为 `waiting_resolution`。

对于所有权申领，若原因为 `default`，解决期限（`max_resolution_date`）必须已过期。若所提供的原因为 `client_request`，则关闭期限（`max_conclusion_date`）将提前，以允许申请方立即完成流程。

以下表格根据原因和类型定义了谁可以确认申请。

| 所有权（Ownership）         | 捐赠方 | 申请方 |
|---------------------|--------|---------------|
| `client_request`    | ✓      |               |
| `account_closure`   |        |               |
| `default` | ✓      |               |

| 可携性（Portability）       | 捐赠方 | 申请方 |
|---------------------|--------|---------------|
| `client_request`    | ✓      |               |
| `account_closure`   | ✓      |               |
| `default` |        |               |

## 请求

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /claim/ CLAIM_REQUEST_KEY
MÉTODO PATCH

**请求体**

```json
{
    "request_control_key": "8a923886-afce-4116-ac1f-69bdffcf8da9",
    "claim_request_status": "confirmed",
    "confirmation_reason": "client_request",
}

```

## 响应

STATUS 200

**响应体**

```json
{
	"request_control_key": "95968498-5ad0-465a-9174-969d0bd1e84a",
	"claim_request_status": "confirmed",
    "created_at": "2024-05-25T12:13:25"
}
```

| 字段 | 描述 | 类型 |
| ---------------------- | ------------------------------------------ | --------------- |
| `claim_request_status` | 可携性申请的状态。 | string |
| `created_at`           | 可携性申请的创建日期。 | datetime string |
| `request_control_key`  | 请求的唯一 UUID4 标识符。 | uuid4 string |

---

# 查询可携性申请

URL: /zh-Hans/documentation/pix_indireto/portabilidade/consultar_pedido_de_portabilidade

描述

## 请求

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /claim_request/ CLAIM_REQUEST_KEY
MÉTODO GET

## 响应

STATUS 200

**响应体**

```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"
     },
    ],
  }
} 
```

| 字段 | 描述 | 类型 |
| ------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------- |
| `cancellation_reason`     | 取消原因。"client_request"、"account_closure"、"fraud"、"default"、"reconciliation"。 | string |
| `cancelled_by`            | 取消可携性申请的操作方。"donor"（捐赠方）或 "claimer"（申请方）。 | string |
| `claim_request_direction` | 表示可携性申请是收到的还是发出的。"incoming" 或 "outgoing"。 | string |
| `claim_request_key`       | 申领的唯一标识密钥。 | string |
| `claim_request_status`    | 可携性申请的状态。 | string |
| `claim_request_type`      | 可携性申请类型。"ownership" 或 "portability"。 | string |
| `confirmation_reason`     | 确认原因。"client_request"、"account_closure"、"fraud"、"default"、"reconciliation"。 | string |
| `created_at`              | 可携性申请的创建日期。 | datetime string |
| `max_conclusion_date`     | 关闭可携性申请的截止日期，仅适用于 "ownership" 类型的可携性。 | string |
| `max_resolution_date`     | 解决可携性申请的截止日期。 | string |
| `pix_key`                 | 可携性申请的 PIX 密钥。 | string |
| `pix_key_type`            | 可携性申请的 PIX 密钥类型。 | string |
| `request_control_key`     | 请求的唯一 UUID4 标识符。 | uuid4 string |
| `claim_request_events`    | 与可携性申请相关的事件组。 | uuid4 string |

| claim_request_status | 描述 |
| -------------------- | ---------------------------------------------------------------------------------------- |
| `waiting_resolution` | 通知已被对方接收。 |
| `confirmed`          | 捐赠方已确认申领，正在等待申请方完成流程。 |
| `cancelled`          | 捐赠方或申请方取消了可携性申请。 |
| `completed`          | DICT 和申请方均已以新绑定更新了各自的数据库。 |

---

# 创建可携性申请

URL: /zh-Hans/documentation/pix_indireto/portabilidade/criar_pedido_de_portabilidade

## 请求

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /claim_request
MÉTODO POST

**请求体**

```json
{
  "request_control_key": "4b61f25d-b8b5-49cb-a391-e4878091ac3f",
  "pix_key": "12345678000190",
  "claim_request_type": "ownership",
  "pix_key_type": "cnpj"
}
```

| 字段 | 类型 | 描述 | 最大字符数 |
| ----------------------- | ------ | ---------------------------------------------------------------------------------------- | --------------- |
| `request_control_key` * | string | 用于查询所发请求的 UUID4。 | 36 |
| `pix_key` *             | string | 与可携性申请相关的 PIX 密钥。 | 36 |
| `claim_request_type` *          | string | 可携性类型。"ownership" 表示申领，"portability" 表示可携性。 | 36 |
| `pix_key_type` *        | string | 密钥类型定义。可为 "cpf"、"cnpj"、"email"、"phone_number"。 | 10 |

## 响应

STATUS 201 created

**响应体**

```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"
}
```

---

# 可携性请求简介

URL: /zh-Hans/documentation/pix_indireto/portabilidade/introducao_portabilidade

PIX 密钥的申领和可携性是巴西中央银行提供的特殊机制，用于处理 PIX 密钥所有权的变更。

- 申领（Reivindicações）适用于密钥（**电话号码**或**电子邮件**）所有权发生变更，且新所有者希望将其绑定到自己账户，但前一所有者（前**电话号码**或**电子邮件**持有人）已在 DICT 中注册了该密钥绑定的情况。
- 可携性（Portabilidades）适用于密钥所有者希望将密钥绑定更改到其在不同参与方的另一个账户的情况。

对于每种所有权变更资源类型，只有部分密钥类型可用，具体如下：

| 兼容性 | 申领 | 可携性 |
|--------------|---------------|---------------|
| cpf          | ✓             |               |
| cnpj         | ✓             |               |
| phone_number | ✓             | ✓             |
| email        | ✓             | ✓             |
| random_key   |               |               |

在 PIX 间接参与者范畴内，所有权变更机制遵循相同原则。QI Tech 基础设施提供特殊路由，使有权使用 PIX 间接服务的账户能够发起请求并接收上述流程的响应。

### 1. 申请方流程
:::info
以下流程图代表 PIX 密钥**申领流程**的相关行为。
:::
##### 1.1. QI Tech 间接参与者请求开启可携性申请
```mermaid
flowchart LR
    PARTICIPANT(Participante Indireto\n QiTech);
    WAITING_RESOLUTION{{Portabilidade \n'waiting_resolution'}};
    
    PARTICIPANT -. pedido de \n portabilidade.-> WAITING_RESOLUTION 
```
##### 1.2. 捐赠方银行确认收到可携性申请
```mermaid
flowchart RL
    OTHER_BANK(Banco Doador);
    QI_PARTICIPANT(Participante Indireto\n QiTech);
    CONFIRMED{{Portabilidade \n 'confirmed'}};
    
    OTHER_BANK-. Confirma pedido de\n portabilidade.->CONFIRMED -- Webhook Atualização --> QI_PARTICIPANT;
```
##### 1.3. QI Tech 间接参与者完成可携性申请，PIX 密钥绑定创建
```mermaid
flowchart LR
    BACEN(Banco Central \n do Brasil);
    QI_PARTICIPANT(Participante Indireto\n QiTech);
    COMPLETED{{Portabilidade \n 'completed'}};
    
    QI_PARTICIPANT-. Completa pedido de\n portabilidade.->COMPLETED -- Criação de Vínculo\n de chave pix --> BACEN;
```
##### 1.4. QI Tech 间接参与者完成可携性申请，PIX 密钥绑定创建
:::warning 重要
状态为 **confirmed** 的可携性申请只有在类型为 **"fraud"** 时才能被取消。
:::
```mermaid
flowchart LR
    BACEN(Banco Central \n do Brasil);
    QI_PARTICIPANT(Participante Indireto\n QiTech);
    PORTABILITY{{Portabilidade \n 'waiting_resolution' ou 'confirmed'}};
    
    QI_PARTICIPANT-. Cancela pedido de\n portabilidade.->PORTABILITY -- Criação de Vínculo\n de chave pix --> BACEN;
```
### 2. 捐赠方流程
:::info
以下流程图代表 PIX 密钥**捐赠流程**的相关行为。
:::
#### 2.1. 申请方银行开启可携性申请
```mermaid
flowchart RL
    OTHER_BANK(Banco Reivindicador);
    QI_PARTICIPANT(Participante Indireto\n QiTech);
    CONFIRMED{{Portabilidade \n 'waiting_resolution'}};
    
    OTHER_BANK-. Confirma pedido de\n portabilidade.->CONFIRMED -- Webhook Recebimento de \nPedido de Portabilidade --> QI_PARTICIPANT;
```

#### 2.2. QI Tech 间接参与者确认收到可携性申请
```mermaid
flowchart LR
    PARTICIPANT(Participante Indireto\n QiTech);
    CONFIRMED{{Portabilidade \n'confirmed'}};
    
    PARTICIPANT -. Confirma recebimento \n e remove vinculo .-> CONFIRMED
```

#### 2.3. 申请方银行完成可携性申请
```mermaid
flowchart RL
    OTHER_BANK(Banco Reivindicador);
    QI_PARTICIPANT(Participante Indireto\n QiTech);
    CONFIRMED{{Portabilidade \n 'completed'}};
    
    OTHER_BANK-. Completa pedido de\n portabilidade.->CONFIRMED -- Webhook Atualização --> QI_PARTICIPANT;
```

#### 2.4. 申请方银行取消可携性申请
:::warning 重要
状态为 **confirmed** 的可携性申请只有在类型为 **"fraud"** 时才能被取消。
:::
```mermaid
flowchart RL
    OTHER_BANK(Banco Reivindicador);
    QI_PARTICIPANT(Participante Indireto\n QiTech);
    PORTABILITY{{Portabilidade \n 'waiting_resolution' ou 'confirmed'}};
    
    OTHER_BANK-. Cancela pedido de\n portabilidade.->PORTABILITY -- Webhook Atualização --> QI_PARTICIPANT;
```

---

# 查询某 Alias 的可携性申请列表

URL: /zh-Hans/documentation/pix_indireto/portabilidade/listar_pedidos_de_portabilidade_de_um_alias

描述

## 请求

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /claim_requests
MÉTODO GET

## 响应

STATUS 200

**响应体**

```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

URL: /zh-Hans/documentation/pix_indireto/portabilidade/webhook/webhook_atualizacao_do_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 请求体参数

| 字段 | 类型 | 描述 | 字符数 |
| ------------------------ | -------- | --------------------------------------------------------- | ---------- |
| `claim_request_status` * | string   | 代表交易目标账户的 PIX 密钥。 | - |
| `claim_request_key` *    | string   | QR 码的 UUID4 标识密钥。 | - |
| `updated_at` *           | datetime | QR 码支付的日期和时间。 | - |

| claim_request_status | 描述 |
| -------------------- | ---------------------------------------------------------------------------------------- |
| `waiting_resolution` | 通知已被对方接收。 |
| `confirmed`          | 捐赠方已确认申领，正在等待申请方完成流程。 |
| `cancelled`          | 捐赠方或申请方取消了可携性申请。 |
| `completed`          | DICT 和申请方均已以新绑定更新了各自的数据库。 |

---

# 外部可携性记录 Webhook

URL: /zh-Hans/documentation/pix_indireto/portabilidade/webhook/webhook_receber_registro_externo_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 请求体参数

| 字段 | 类型 | 描述 | 字符数 |
| ------------------------ | -------- | --------------------------------------------------------- | ---------- |
| `claim_request_status` * | string   | 代表交易目标账户的 PIX 密钥。 | - |
| `claim_request_key` *    | string   | QR 码的 UUID4 标识密钥。 | - |
| `updated_at` *           | datetime | QR 码支付的日期和时间。 | - |

| claim_request_status | 描述 | 值 |
| -------------------- | --------- | ---------- |
| waiting_resolution   | 描述 | 字符数 |
| confirmed            | 描述 | 字符数 |
| cancelled            | 描述 | 字符数 |
| completed            | 描述 | 字符数 |

---

# 查询 PIX QR 码

URL: /zh-Hans/documentation/pix_indireto/qr_code/consultar_qr_code

可以通过创建时生成的 qr_code_key 查询某个 Alias 的特定 QR 码。此端点将返回该 QR 码的所有信息，如状态、支付情况、事件等。

## 请求

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /qrcode/ QR_CODE_KEY
MÉTODO GET

## 响应

STATUS 200 Ok

响应体：通用

```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"
}
```

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `request_control_key` * | string | 生成该 QR 码的请求的唯一 UUID4 标识符。 | - |
| `pix_key` * | string | 代表交易目标账户的 PIX 密钥。 | - |
| `receiver_conciliation_id` * | string | 支付后用于对账的 QR 码标识符。 | - |
| `qr_code_key` * | string | QR 码的 UUID4 标识密钥。 | - |
| `qr_code_status` * | string | QR 码状态。 | - |
| `qr_code_type` * | string | QR 码类型。 | "dynamic_term" 或 "dynamic_instant" |
| `amount` * | float | QR 码在计算折扣或利息罚款前的金额。 | - |
| `expiration_seconds`  | string | QR 码的有效时间（秒），默认 1 天。 | - |
| `expiration_date` | date | 账单到期日（格式 "YYYY-MM-DD"）。 | - |
| `max_payment_days` | int32 | 到期后的最长付款天数。 | - |
| `payer_name` * | string | 付款方姓名。 | - |
| `payer_document_number` * | string | 付款方 CPF/CNPJ。 | - |
| `payer_request` * | string | 给付款方的消息。 | - |
| `rebate_amount` | float | 支付前的绝对折扣金额。 | - |
| `interest_amount` | float | 到期后每天逾期的绝对利息金额，若在到期后一天支付，总金额为原始金额加罚款。 | - |
| `fine_amount` | float | 到期后的绝对罚款金额。 | - |
| `discounts` | array of objects | 折扣配置。 | - |
| `additional_data` | array of objects | 将展示给付款方的信息。 | - |
| `pix_transfer_key` | string | 与 QR 码清算对应的 PIX 交易 UUID4 标识密钥。 | - |
| `paid_amount` | float | 考虑罚款、折扣等后的实际支付金额。 | - |
| `base_64_payload` | string | Base64 格式的 QR 码支付 URL。 | - |
| `qr_code_events` | array of objects | QR 码经历的状态变更列表。 | - |
| `created_at` | datetime | QR 码在系统中的创建日期和时间。 | - |

### qr_code_status 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `active`  | string | QR 码处于活跃状态，可用于支付。 | - |
| `finished` | string | QR 码已支付。 | - |
| `written_off` | string | QR 码已被客户撤销。 | - |
| `bank_written_off` | string | QR 码因期限过期被自动撤销。 | - |

### discount 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `discount_value` * | float | 折扣金额。 | - |
| `discount_number` | int32 | 折扣应用的顺序。 | - |
| `discount_limit_date` | string | 折扣截止日期。 | - |

### additional_data 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `key_name` * | string | 字段名称。 | - |
| `value` | string | 字段值。 | - |

### qr_code_events 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `request_control_key` * | string | 生成该事件的请求的唯一 UUID4 标识符。 | - |
| `event_type` * | string | 事件类型。 | "registration"、"write_off"、"payment" |
| `created_at` * | datetime | 事件创建的日期和时间。 | - |

STATUS 400

响应体

```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

响应体：未找到 QR 码密钥

```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"
}
```

---

# 创建有效期动态 PIX QR 码

URL: /zh-Hans/documentation/pix_indireto/qr_code/Criar QR Code/criar_qr_code_dinamico_com_vencimento

有效期动态 QR 码适用于发起方已知且希望便利支付的场景，可添加截止日期、折扣、罚款和利息。此类 QR 码通常用于替代银行条形码（boleto bancário）。

## 请求

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /qrcode
MÉTODO POST

请求体：有效期动态 QR 码

```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."
    }
  ],
}
```

### 请求体参数

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `request_control_key` * | string | 请求的唯一 UUID4 标识符。 | - |
| `qr_code_type` * | string | 动态 QR 码类型。 | "dynamic_term" 或 "dynamic_instant" |
| `amount` * | float | QR 码在计算折扣或利息罚款前的金额。 | - |
| `receiver_conciliation_id` * | string | 支付后用于对账的 QR 码标识符。 | - |
| `payer_document_number` * | string | 付款方 CPF/CNPJ。 | - |
| `payer_name` * | string | 付款方姓名。 | - |
| `payer_request` * | string | 给付款方的消息。 | - |
| `pix_key` * | string | 代表交易目标账户的 PIX 密钥。 | - |
| `expiration_date` * | date | 账单到期日（格式 "YYYY-MM-DD"）。 | - |
| `max_payment_days` * | int32 | 账单到期后的最长付款天数。 | - |
| `fine_amount` * | float | 到期后的绝对罚款金额。 | - |
| `interest_amount` * | float | 到期后每天逾期的绝对利息金额，若在到期后一天支付，总金额为原始金额加罚款。 | - |
| `rebate_amount` * | float | 支付前的绝对折扣金额。 | - |
| `discounts` | array of objects | 折扣配置。 | - |
| `additional_data` | array of objects | QR 码的额外信息，用于对账。 | - |

### additional_data 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `key_name` * | string | 字段名称。 | - |
| `value` * | string | 字段值。 | - |

### discount 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `discount_value` * | float | 折扣金额。 | - |
| `discount_number` | int32 | 折扣应用的顺序。 | - |
| `discount_limit_date` * | string | 折扣截止日期。 | - |

## 响应

STATUS 201 Created

响应体：创建有效期动态 QR 码

```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",
}
```

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `request_control_key` * | string | 请求的唯一 UUID4 标识符。 | - |
| `qr_code_key` * | string | 用于后续请求的 QR 码标识符。 | - |
| `qr_code_status` * | string | 系统中的 QR 码状态。 | "active"：创建时的默认值。 |
| `base_64_payload` * | string | Base64 格式的 QR 码支付 URL。 | - |
| `created_at` * | datetime | QR 码在系统中的创建日期和时间。 | - |

### qr_code_status 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `active`  | string | QR 码处于活跃状态，可用于支付。 | - |
| `finished` | string | QR 码已支付。 | - |
| `written_off` | string | QR 码已被客户撤销。 | - |
| `bank_written_off` | string | QR 码因期限过期被自动撤销。 | - |

STATUS 400

响应体

```json
{
    "title": "Bad Request",
    "description": "Invalid payload for QR Code creation.",
    "translation": "Payload inválido para a criação de QR Code.",
    "code": "QRI000003"
}

```

---

# 创建即时支付动态 PIX QR 码

URL: /zh-Hans/documentation/pix_indireto/qr_code/Criar QR Code/criar_qr_code_dinamico_imediato

即时支付动态 QR 码适用于支付期限较短（通常以秒计）的场景，用于日常即时收款操作。

## 请求

请求体：即时支付动态 QR 码

```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"
    }
  ],
}
```

### 请求体参数

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `request_control_key` * | string | 请求的唯一 UUID4 标识符。 | - |
| `qr_code_type` * | string | 动态 QR 码类型。 | "dynamic_term" 或 "dynamic_instant" |
| `amount` * | float | QR 码在计算折扣或利息罚款前的金额。 | - |
| `receiver_conciliation_id` * | string | 支付后用于对账的 QR 码标识符。 | - |
| `payer_document_number` * | string | 付款方 CPF/CNPJ。 | - |
| `payer_name` * | string | 付款方姓名。 | - |
| `payer_request` * | string | 给付款方的消息。 | - |
| `pix_key` * | string | 代表交易目标账户的 PIX 密钥。 | - |
| `expiration_seconds`  | string | QR 码的有效时间（秒），默认 1 天。 | - |
| `additional_data` | array of objects | 将展示给付款方的信息。 | - |

### additional_data 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `key_name` * | string | 字段名称。 | - |
| `value` | string | 字段值。 | - |

## 响应

STATUS 201 Created

响应体：创建即时支付动态 QR 码

```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",
}
```

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `request_control_key` * | string | 请求的唯一 UUID4 标识符。 | - |
| `qr_code_key` * | string | 用于后续请求的 QR 码标识符。 | - |
| `qr_code_status` * | string | 系统中的 QR 码状态。 | "active"：创建时的默认值。 |
| `base_64_payload` * | string | Base64 格式的 QR 码支付 URL。 | - |
| `created_at` * | datetime | QR 码在系统中的创建日期和时间。 | - |

### qr_code_status 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `active`  | string | QR 码处于活跃状态，可用于支付。 | - |
| `finished` | string | QR 码已支付。 | - |
| `written_off` | string | QR 码已被客户撤销。 | - |
| `bank_written_off` | string | QR 码因期限过期被自动撤销。 | - |

STATUS 400

响应体

```json
{
    "title": "Bad Request",
    "description": "Invalid payload for QR Code creation.",
    "translation": "Payload inválido para a criação de QR Code.",
    "code": "QRI000003"
}

```

---

# 创建静态 PIX QR 码

URL: /zh-Hans/documentation/pix_indireto/qr_code/Criar QR Code/criar_qr_code_estatico

静态 QR 码适用于不知道付款方身份、付款时间和付款人数量的支付场景。基本上，它由经过编码的密钥（可选含金额）组成，因为只引用密钥，所以可以被多次支付。

## 请求

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /qrcode
MÉTODO POST

请求体：静态 QR 码

```json
{
    "request_control_key": "8a923886-afce-4116-ac1f-69bdffcf8da9",
    "qr_code_type": "static",
    "pix_key": "joaosilva@gmail.com",
    "amount": 10.25,
}
```

### 请求体参数

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `request_control_key` * | string | 请求的唯一 UUID4 标识符。 | - |
| `qr_code_type` * | string | QR 码类型。 | "static" |
| `pix_key` * | string | 代表交易目标账户的 PIX 密钥。 | - |
| `amount` | float | QR 码金额。 | 如未提供，由付款方填写。 |

## 响应

STATUS 201 Created

响应体：创建静态 QR 码

```json
{
  "request_control_key": "037b46b1-0c67-4c0d-aac3-1e395dfdcb10",
  "base_64_payload": "<BASE64 DA URI DO PIX COPIA E COLA>"
}
```

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `request_control_key` * | string | 请求的唯一 UUID4 标识符。 | - |
| `base_64_payload` * | string | Base64 格式的 QR 码支付 URL。 | - |

STATUS 400

响应体

```json
{
    "title": "Bad Request",
    "description": "Invalid payload for QR Code creation.",
    "translation": "Payload inválido para a criação de QR Code.",
    "code": "QRI000003"
}

```

---

# 列出某 Alias 的 QR 码

URL: /zh-Hans/documentation/pix_indireto/qr_code/decodificar_qr_code

PIX QR 码（图片或 URL 格式）遵循标准规范，需按特定逻辑解码以提取支付信息。拥有 QR 码 URL 后，即可解码提取生成该 QR 码的所有信息。解码会生成 `end_to_end_id`，该值与 receiver_conciliation_id 一起用于支付 QR 码，以识别 QR 码支付。

## 请求

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /qrcode/decode
MÉTODO POST

请求体：解码 QR 码

```json
{
   "qr_code_payload": "00020126580014br.gov.bcb.pix0136a23bf0e9-5175-4829-bf89-e8fe6ac09aa1520400005303986540530.005802BR5914TywinLannister6008saopaulo62070503***6304D4FD",
}
```

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `qr_code_payload` | string | QR 码支付 URL（PIX 复制粘贴格式）。 | - |

## 响应

STATUS 200 Ok

响应体：静态 QR 码

```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

响应体：有效期动态 QR 码

```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

响应体：有效期动态 QR 码

```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"
}
```

### 响应体

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `request_control_key` * | string | 生成该 QR 码的请求的唯一 UUID4 标识符。 | - |
| `end_to_end_id` * | string | PIX 交易的唯一端对端标识符。 | - |
| `account_type` * | string | 来源账户类型。 | - |
| `amount` * | float | QR 码当前金额。 | - |
| `category_code` * | string | 支付后用于对账的 QR 码标识符。 | - |
| `expiration_seconds`  | string | QR 码的有效时间（秒），默认 1 天。 | - |
| `ispb_number` * | string | 银行标识符。 | - |
| `payer_document_number` * | string | 付款方 CPF/CNPJ。 | - |
| `payer_name` * | string | 付款方姓名。 | - |
| `payer_request` * | string | 给付款方的消息。 | - |
| `receiver_conciliation_id` * | string | 支付后用于对账的 QR 码标识符。 | - |
| `receiver_url` * | string | 动态 QR 码数据查询 URL。 | - |
| `qr_code_status` * | string | QR 码状态。 | - |
| `target_account_branch` * | string | 目标账户支行号。 | - |
| `target_account_digit` * | string | 目标账户校验位。 | - |
| `target_account_number` * | string | 目标账号。 | - |
| `target_bank_code` * | string | 目标银行代码。 | - |
| `target_bank_name` * | string | 目标银行名称。 | - |
| `target_document_number` * | string | 收款方 CPF/CNPJ。 | - |
| `target_name` * | string | 收款方姓名。 | - |
| `target_trading_name` * | string | 收款方商业名称 - 仅用于 CNPJ。 | - |
| `target_pix_key` * | string | 收款方 PIX 密钥。 | - |
| `qr_code_key` * | string | QR 码的 UUID4 标识密钥。 | - |
| `qr_code_payload` * | string | QR 码复制粘贴 URL。 | - |
| `qr_code_type` * | string | QR 码类型。 | "static"、"dynamic_term" 或 "dynamic_instant" |
| `max_payment_days` | int32 | 到期后的最长付款天数。 | - |
| `expiration_date` | date | 账单到期日（格式 "YYYY-MM-DD"）。 | - |
| `fine_amount` | float | 到期后的绝对罚款金额。 | - |
| `interest_amount` | float | 到期后每天逾期的绝对利息金额。 | - |
| `discount_amount` | float | 折扣金额。 | - |
| `original_amount` | float | QR 码原始金额。 | - |
| `additional_data` | array of objects | 将展示给付款方的信息。 | - |
| `presented_at` * | datetime | QR 码被解码的日期和时间。 | - |
| `created_at` * | datetime | QR 码在系统中的创建日期和时间。 | - |
| `rebate_amount` | float | 支付前的绝对折扣金额。 | - |

### qr_code_status 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `active`  | string | QR 码处于活跃状态，可用于支付。 | - |
| `finished` | string | QR 码已支付。 | - |
| `written_off` | string | QR 码已被客户撤销。 | - |
| `bank_written_off` | string | QR 码因期限过期被自动撤销。 | - |

### additional_data 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `key_name` * | string | 字段名称。 | - |
| `value` | string | 字段值。 | - |

STATUS 400

响应体：无法解码 QR 码

```json
{
    "title": "Bad Request",
    "description": "Could not decode QR Code.",
    "translation": "Não foi possível decodificar o QR Code.",
    "code": "QRI000001"
}
```

STATUS 404

响应体：未找到 QR 码

```json
{
    "title": "Not found",
    "description": "Could not find the queried QR Code.",
    "translation": "Não possível encontrar o QR Code buscado.",
    "code": "QRI000002"
}
```

---

# 修改 PIX QR 码

URL: /zh-Hans/documentation/pix_indireto/qr_code/desativar_qr_code

只能修改动态类型的 PIX QR 码。修改操作通过创建时生成的 qr_code_key 识别，执行后该 QR 码将对后续支付无效。请求修改 PIX QR 码的原因多种多样，但在内部系统中，QR 码的停用可通过 Alias 申请的撤销（write_off）来完成。

## 请求

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /qrcode/ QR_CODE_KEY
MÉTODO PATCH

请求体：撤销 QR 码

```json
{
  "request_control_key": "76d4506d-31a4-48db-bc71-61068b138ffd",
  "qr_code_status": "written_off",
}
```

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `request_control_key` * | string | 请求的唯一 UUID4 标识符。 | - |
| `qr_code_status` * | string | QR 码状态。 | - |

### qr_code_status 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `active`  | string | QR 码处于活跃状态，可用于支付。 | - |
| `finished` | string | QR 码已支付。 | - |
| `written_off` | string | QR 码已被客户撤销。 | - |
| `bank_written_off` | string | QR 码因期限过期被自动撤销。 | - |

## 响应

STATUS 204 No content

响应体

```json
{}
```

STATUS 404

响应体

```json
{
    "title": "Not found",
    "description": "Could not find the queried QR Code.",
    "translation": "Não possível encontrar o QR Code buscado.",
    "code": "QRI000002"
}

```

---

# PIX QR 码简介

URL: /zh-Hans/documentation/pix_indireto/qr_code/introducao_qr_code

间接参与者的任何客户（Alias）都可以执行 PIX QR 码的创建、查询和撤销操作。

- 创建：可以生成静态或动态类型的 QR 码。对于动态类型，可以生成即时支付动态码或长期到期动态码。各类型将在创建流程中详细说明。

- 查询：拥有 QR 码或其 URL（PIX 复制粘贴格式），即可查询其信息以便后续支付。查询过程称为 QR 码解码，并生成一个用于后续支付的 `end_to_end_id`。

- 撤销：撤销 QR 码将使其无效，无法再用于支付。主要撤销原因包括：到期、Alias 主动取消，或已完成支付。

## QR 码类型
QR 码类型在创建时通过 qr_code_type 字段定义。

| 名称 | 枚举值 | 描述 |
|---|---|---|
| 静态 | `static` | 包含目标 PIX 密钥，可选填金额。只要密钥处于活跃状态，随时可以支付。无有效期限制，可重复使用。|
| 即时支付动态码 | `dynamic_instant` | 包含支付信息，含已定义付款方、金额和对账密钥。支付期限以秒计。仅限一次性使用。|
| 有效期动态码 | `dynamic_term` | 包含支付信息，含已定义付款方、金额和对账密钥。支付期限以天计，含罚款和利息信息。仅限一次性使用。|

## 支付 QR 码

解码 QR 码和查询密钥后，将生成 `end_to_end_id`，用于支付指令以完成交易。此外，对于动态 QR 码，`receiver_conciliation_id` 字段用于识别正在支付的具体 QR 码，收款方在支付后用其推进操作流程。

解码 QR 码后，应发送带有 `end_to_end_id` 和 `receiver_conciliation_id` 的 PIX 支付指令，接收方银行即可继续处理。同样，当收到 `static_qr_code` 或 `dynamic_qr_code` 类型的 PIX 支付时，将发送一个 webhook，本 QR 码章节末尾也有相关说明。

---

# 列出某 Alias 的 QR 码

URL: /zh-Hans/documentation/pix_indireto/qr_code/listar_alias_qr_codes

QR 码搜索用于管理动态 QR 码的状态、核查支付情况、撤销情况等。

## 请求

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /qrcodes
MÉTODO GET

### 路径参数

| 字段 | 类型 | 描述 | 字符数 |
|----------------------------|---------|------------------------------------------------------------------|------------|
| `page`                     | integer | 查询的页码（默认 = 0）。 | - |
| `page_size`                | integer | 每页条目数（默认 = 15）。 | - |
| `qr_code_status`           | string  | 查询的 QR 码状态。 | - |
| `qr_code_type`             | string  | 查询的 QR 码类型。 | - |
| `request_control_key`      | string  | 生成该 QR 码的 request control key。 | - |

## 响应

STATUS 200 Ok

响应体：通用

```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
   },
},
```

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `request_control_key` * | string | 生成该 QR 码的请求的唯一 UUID4 标识符。 | - |
| `pix_key` * | string | 代表交易目标账户的 PIX 密钥。 | - |
| `receiver_conciliation_id` * | string | 支付后用于对账的 QR 码标识符。 | - |
| `qr_code_key` * | string | QR 码的 UUID4 标识密钥。 | - |
| `qr_code_status` * | string | QR 码状态。 | - |
| `qr_code_type` * | string | QR 码类型。 | "dynamic_term" 或 "dynamic_instant" |
| `amount` * | float | QR 码在计算折扣或利息罚款前的金额。 | - |
| `expiration_seconds`  | string | QR 码的有效时间（秒），默认 1 天。 | - |
| `expiration_date` | date | 账单到期日（格式 "YYYY-MM-DD"）。 | - |
| `max_payment_days` | int32 | 到期后的最长付款天数。 | - |
| `payer_name` * | string | 付款方姓名。 | - |
| `payer_document_number` * | string | 付款方 CPF/CNPJ。 | - |
| `payer_request` * | string | 给付款方的消息。 | - |
| `rebate_amount` | float | 支付前的绝对折扣金额。 | - |
| `interest_amount` | float | 到期后每天逾期的绝对利息金额。 | - |
| `fine_amount` | float | 到期后的绝对罚款金额。 | - |
| `discounts` | array of objects | 折扣配置。 | - |
| `additional_data` | array of objects | 将展示给付款方的信息。 | - |
| `pix_transfer_key` | string | 与 QR 码清算对应的 PIX 交易 UUID4 标识密钥。 | - |
| `paid_amount` | float | 考虑罚款、折扣等后的实际支付金额。 | - |
| `base_64_payload` | string | Base64 格式的 QR 码支付 URL。 | - |
| `qr_code_events` | array of objects | QR 码经历的状态变更列表。 | - |
| `created_at` | datetime | QR 码在系统中的创建日期和时间。 | - |

### qr_code_status 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `active`  | string | QR 码处于活跃状态，可用于支付。 | - |
| `finished` | string | QR 码已支付。 | - |
| `written_off` | string | QR 码已被客户撤销。 | - |
| `bank_written_off` | string | QR 码因期限过期被自动撤销。 | - |

### discount 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `discount_value` * | float | 折扣金额。 | - |
| `discount_number` | int32 | 折扣应用的顺序。 | - |
| `discount_limit_date` | string | 折扣截止日期。 | - |

### additional_data 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `key_name` * | string | 字段名称。 | - |
| `value` | string | 字段值。 | - |

### qr_code_events 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `request_control_key` * | string | 生成该事件的请求的唯一 UUID4 标识符。 | - |
| `event_type` * | string | 事件类型。 | "registration"、"write_off"、"payment" |
| `created_at` * | datetime | 事件创建的日期和时间。 | - |

STATUS 404

响应体

```json
{
    "title": "Not found",
    "description": "Could not find the queried QR Code.",
    "translation": "Não possível encontrar o QR Code buscado.",
    "code": "QRI000002"
}

```

---

# QR 码支付入站 PIX Webhook

URL: /zh-Hans/documentation/pix_indireto/qr_code/webhook_incoming_pix

用于通知到达某个 Alias 的与已关联 QR 码支付相关的 PIX 交易的 Webhook。

## Webhook 请求体

**请求体：已收到 QR 码支付**

```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 请求体参数

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `request_control_key` * | string | 生成该 QR 码的请求的唯一 UUID4 标识符。 | - |
| `pix_transfer_key` * | string | 代表交易目标账户的 PIX 密钥。 | - |
| `qr_code_key` * | string | QR 码的 UUID4 标识密钥。 | - |
| `qr_code_type` * | string | QR 码类型。 | "static"、"dynamic_term" 或 "dynamic_instant" |
| `receiver_conciliation_id` * | string | 支付后用于对账的 QR 码标识符。 | - |
| `amount` * | string | 支付金额。 | - |
| `updated_at` * | datetime | QR 码支付的日期和时间。 | - |

---

# 取消违规举报

URL: /zh-Hans/documentation/pix_indireto/relato_de_infracao/cancelar_relato_infracao

如果违规举报请求系错误生成，间接参与者希望取消，可通过以下端点操作。

:::danger 重要
需要注意的是，只有 创建 了违规举报的参与者才能取消它，即使违规状态为 closed，也可以进行取消操作。
:::

:::info 重要
已取消的违规举报可以使用[列出违规举报](#列出违规举报)端点进行查询。
:::

## 请求

ENDPOINT /pix/infraction_report/ INFRACTION_REPORT_KEY
MÉTODO PATCH

**请求体**

```json
{
    "infraction_report_status": "cancelled",
    "request_control_key": "750cbfa0-f628-4944-a76c-9053bf1ebc87",
}
```

### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
| ----------------------- | ------ | ------------------------------------------------------------- | ---------- |
| `infraction_report_key` | string | 要取消的已创建违规举报的 UUID4。 | 36 |

### 请求体参数

| 字段 | 类型 | 描述 | 字符数 |
| ---------------------------- | ------ | ---------------------------------------------------------------------------------- | ---------- |
| `infraction_report_status` * | string | 要更新违规举报的目标状态。 | 36 |
| `request_control_key` *      | string | 客户使用的请求唯一标识密钥，格式为 uuid v4。 | 36 |

## 响应

STATUS 200

**响应体**

```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"
}
```

### 响应体参数
| 字段 | 类型 | 描述 | 字符数 |
| ------------------------------- | ------ | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `infraction_report_key` *       | string | 违规举报的唯一标识符。 | 36 |
| `pix_transfer_key` *            | string | PIX 交易的唯一标识符。 | 36 |
| `end_to_end_id` *               | string | BACEN 中 PIX 交易的唯一标识符。 | 36 |
| `infraction_report_status` *    | enum   | 违规举报的状态。 | **[infraction_report_status 枚举值](#enumeradores-infraction_report_status)** |
| `infraction_report_situation` * | enum   | 违规发生的情形。 | **[infraction_report_situation 枚举值](#enumeradores-infraction_report_situation)** |
| `infraction_report_type` *      | enum   | 违规举报类型。 | **[infraction_report_type 枚举值](#enumeradores-infraction_report_type)** |
| `infraction_report_details`     | string | 关于已创建违规举报的详细信息。 | \<\= 2000 |
| `credited_participant` *        | string | 贷记方参与者的 ISPB。 | 8 |
| `debited_participant` *         | string | 借记方参与者的 ISPB。 | 8 |
| `infraction_report_direction` * | enum   | 表示举报是由间接参与者开启还是由其他参与者开启的枚举值。 | **[infraction_report_direction 枚举值](#enumeradores-infraction_report_direction)** |
| `created_at` *                  | string | 违规举报的创建日期。 | 24 |
| `updated_at` *                  | string | 违规举报的更新日期。 | 24 |

### infraction_report_status 枚举值
| 字段 | 类型 | 描述 | 字符数 |
| -------------- | ------ | ----------------------------------------------------------------------------- | ---------- |
| `open`         | string | 违规举报已<strong>创建</strong>并在 BACEN 中处于开启状态。 | - |
| `acknowledged` | string | 违规举报已被被申诉参与者<strong>接收</strong>。 | - |
| `cancelled`    | string | 违规举报在 BACEN 中已<strong>取消</strong>。 | - |
| `closed`       | string | 违规举报在 BACEN 中已<strong>关闭</strong>。 | - |

### infraction_report_situation 枚举值
| 字段 | 类型 | 描述 | 字符数 |
| ------------------- | ------ | ------------------------------------------------------- | ---------- |
| `scam`              | string | 诈骗或欺诈行为。 | - |
| `account_takeover`  | string | 来源账户未授权的交易。 | - |
| `coercion`          | string | 胁迫犯罪。 | - |
| `fraudulent_access` | string | 对来源账户的欺诈性访问。 | - |
| `other`             | string | 不适用于上述列举的其他任何原因。 | - |

### infraction_report_type 枚举值
| 字段 | 类型 | 描述 | 字符数 |
| ------------------ | ------ | ---------------------------------------------------------------------- | ---------- |
| `refund_request`   | string | 为申请退款而生成的违规举报。 | - |
| `refund_cancelled` | string | 因退款取消而生成的违规举报。 | - |

### infraction_report_direction 枚举值
| 字段 | 类型 | 描述 | 字符数 |
| ---------- | ------ | ------------------------------------------------------------- | ---------- |
| `incoming` | string | 以间接参与者为目标的违规举报。 | - |
| `outgoing` | string | 以间接参与者为发起方的违规举报。 | - |

---

# 查询违规举报

URL: /zh-Hans/documentation/pix_indireto/relato_de_infracao/consultar_relato_infracao

间接参与者可以查询违规举报的数据，包括其所有变更记录。

## 请求

ENDPOINT /pix/infraction_report/ INFRACTION_REPORT_KEY
MÉTODO GET

### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
| ----------------------- | ------ | ---------------------------- | ---------- |
| `infraction_report_key` | string | 违规举报的 UUID4。 | 36 |

## 响应

STATUS 200

**响应体**

```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"
}
```

### 响应体参数
| 字段 | 类型 | 描述 | 字符数 |
| ------------------------------- | ------ | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `infraction_report_key` *       | string | 违规举报的唯一标识符。 | 36 |
| `pix_transfer_key` *            | string | PIX 交易的唯一标识符。 | 36 |
| `end_to_end_id` *               | string | BACEN 中 PIX 交易的唯一标识符。 | 36 |
| `infraction_report_status` *    | enum   | 状态。 | **[infraction_report_status 枚举值](#enumeradores-infraction_report_status)** |
| `infraction_report_situation` * | enum   | 违规发生的情形。 | **[infraction_report_situation 枚举值](#enumeradores-infraction_report_situation)** |
| `infraction_report_type` *      | enum   | 违规举报类型。 | **[infraction_report_type 枚举值](#enumeradores-infraction_report_type)** |
| `infraction_report_details`     | string | 关于已创建违规举报的详细信息。 | \<\= 2000 |
| `credited_participant` *        | string | 贷记方参与者的 ISPB。 | 8 |
| `debited_participant` *         | string | 借记方参与者的 ISPB。 | 8 |
| `infraction_report_direction` * | enum   | 表示举报是由间接参与者开启还是由其他参与者开启的枚举值。 | **[infraction_report_direction 枚举值](#enumeradores-infraction_report_direction)** |
| `infraction_report_events`*     | object | 与违规举报相关的事件。 | **[infraction_report_events 对象](#objetos-infraction_report_events)** |
| `created_at` *                  | string | 违规举报的创建时间。 | 24 |
| `updated_at`                    | string | 违规举报的更新时间。 | 24 |

### infraction_report_status 枚举值

| 字段 | 类型 | 描述 | 字符数 |
| -------------- | ------ | ----------------------------------------------------------------------------- | ---------- |
| `open`         | string | 违规举报已<strong>创建</strong>并在 BACEN 中处于开启状态。 | 4 |
| `acknowledged` | string | 违规举报已被被申诉参与者<strong>接收</strong>。 | 12 |
| `cancelled`    | string | 违规举报在 BACEN 中已<strong>取消</strong>。 | 9 |
| `closed`       | string | 违规举报在 BACEN 中已<strong>关闭</strong>。 | 6 |

### infraction_report_situation 枚举值
| 字段 | 类型 | 描述 | 字符数 |
| ------------------- | ------ | ------------------------------------------------------- | ---------- |
| `scam`              | string | 诈骗或欺诈行为。 | - |
| `account_takeover`  | string | 来源账户未授权的交易。 | - |
| `coercion`          | string | 胁迫犯罪。 | - |
| `fraudulent_access` | string | 对来源账户的欺诈性访问。 | - |
| `other`             | string | 不适用于上述列举的其他任何原因。 | - |

### infraction_report_type 枚举值
| 字段 | 类型 | 描述 | 字符数 |
| ------------------ | ------ | ---------------------------------------------------------------------- | ---------- |
| `refund_request`   | string | 为申请退款而生成的违规举报。 | - |
| `refund_cancelled` | string | 因退款取消而生成的违规举报。 | - |

### infraction_report_direction 枚举值
| 字段 | 类型 | 描述 | 字符数 |
| ---------- | ------ | ------------------------------------------------------------- | ---------- |
| `incoming` | string | 以间接参与者为目标的违规举报。 | - |
| `outgoing` | string | 以间接参与者为发起方的违规举报。 | - |

### infraction_report_events 对象
| 字段 | 类型 | 描述 | 字符数 |
| --------------- | ------ | ---------------------------------------- | ----------------------------------------------------------------------------------- |
| `event_type`    | enum   | 与事件相关的状态变更。 | **[infraction_report_status 枚举值](#enumeradores-infraction_report_status)** |
| `event_details` | string | 事件描述。 | - |
| `created_at` *  | string | 事件创建时间。 | 24 |

---

# 发起违规举报

URL: /zh-Hans/documentation/pix_indireto/relato_de_infracao/criar_relato_infracao

违规举报是巴西中央银行定义的特殊退款机制（MED）的服务之一。

当发现可疑的欺诈性交易、退款请求或退款取消时，可以创建违规举报，以通知 BACEN 和另一个参与者该操作存在违规行为。

借记方 和 贷记方 参与者均可创建违规举报。

:::caution **注意**

要理解违规举报流程，需要了解创建举报的间接参与者可以使用哪些 接口端点 。

当间接参与者 开启 违规举报时，如果举报生成有误，可以（如有必要）取消该举报。

当间接参与者 收到 违规举报时，必须提供分析结果并关闭该举报。

以上两种流程将在以下章节中详细说明。

:::

:::danger 重要
巴西中央银行规定，间接参与者收到违规举报后的 7天 内，必须 关闭 该举报。

如果间接参与者有延迟，QI Tech 将以 agreed 状态关闭违规举报，以避免机构被巴西中央银行处罚。
:::

:::info 重要
只有转账的 发起方 参与者才能对该转账创建违规举报。
:::

## 请求

ENDPOINT /pix/infraction_report
MÉTODO POST

**请求体**

```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"
}
```

### 请求体参数

| 字段 | 类型 | 描述 | 字符数 |
| ----------------------------- | ------ | ----------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `request_control_key` *       | uuidv4 | 用于查询所发请求的 UUID4。 | 36 |
| `pix_transfer_key` *          | uuidv4 | PIX 交易的唯一标识符。 | 36 |
| `infraction_report_type` *    | enum   | 要创建的违规举报类型。 | **[infraction_report_type 枚举值](#enumeradores-infraction_report_type)** |
| `infraction_report_details`   | string | 关于要创建的违规举报的详细信息。 | 10 |
| `infraction_report_situation` | string | 违规发生的情形。 | **[infraction_report_situation 枚举值](#enumeradores-infraction_report_situation)** |

### infraction_report_type 枚举值

| 字段 | 类型 | 描述 | 字符数 |
| ------------------ | ------ | --------------------------------------------------------------------- | ---------- |
| `refund_cancelled` | string | 因退款取消而生成的违规举报。 | 16 |
| `refund_request`   | string | 为申请退款而生成的违规举报。 | 14 |

### infraction_report_situation 枚举值

| 字段 | 类型 | 描述 | 字符数 |
| ------------------- | ------ | ------------------------------------------------------- | ---------- |
| `scam`              | string | 诈骗或欺诈行为。 | - |
| `account_takeover`  | string | 来源账户未授权的交易。 | - |
| `coercion`          | string | 胁迫犯罪。 | - |
| `fraudulent_access` | string | 对来源账户的欺诈性访问。 | - |
| `other`             | string | 不适用于上述列举的其他任何原因。 | - |

## 响应

STATUS 200

**响应体**

```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"
}
```

### 响应体参数

| 字段 | 类型 | 描述 | 字符数 |
| ------------------------------- | ------ | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `infraction_report_key` *       | string | 违规举报的唯一标识符。 | 36 |
| `pix_transfer_key` *            | string | PIX 交易的唯一标识符。 | 36 |
| `end_to_end_id` *               | string | BACEN 中 PIX 交易的唯一标识符。 | 36 |
| `infraction_report_status` *    | enum   | 状态。 | **[infraction_report_status 枚举值](#enumeradores-infraction_report_status)** |
| `infraction_report_situation` * | enum   | 违规发生的情形。 | **[infraction_report_situation 枚举值](#enumeradores-infraction_report_situation)** |
| `infraction_report_type` *      | enum   | 违规举报类型。 | **[infraction_report_type 枚举值](#enumeradores-infraction_report_type)** |
| `infraction_report_details`     | string | 关于已创建违规举报的详细信息。 | \<\= 2000 |
| `credited_participant` *        | string | 贷记方参与者的 ISPB。 | 8 |
| `debited_participant` *         | string | 借记方参与者的 ISPB。 | 8 |
| `infraction_report_direction` * | enum   | 表示举报是由间接参与者开启还是由其他参与者开启的枚举值。 | **[infraction_report_direction 枚举值](#enumeradores-infraction_report_direction)** |
| `created_at` *                  | string | 违规举报的创建时间。 | 24 |
| `updated_at`                    | string | 违规举报的更新时间。 | 24 |

### infraction_report_status 枚举值

| 字段 | 类型 | 描述 | 字符数 |
| -------------- | ------ | ----------------------------------------------------------------------------- | ---------- |
| `open`         | string | 违规举报已<strong>创建</strong>并在 BACEN 中处于开启状态。 | - |
| `acknowledged` | string | 违规举报已被被申诉参与者<strong>接收</strong>。 | - |
| `cancelled`    | string | 违规举报在 BACEN 中已<strong>取消</strong>。 | - |
| `closed`       | string | 违规举报在 BACEN 中已<strong>关闭</strong>。 | - |

### infraction_report_direction 枚举值
| 字段 | 类型 | 描述 | 字符数 |
| ---------- | ------ | ------------------------------------------------------------- | ---------- |
| `incoming` | string | 以间接参与者为目标的违规举报。 | - |
| `outgoing` | string | 以间接参与者为发起方的违规举报。 | - |

---

# 关闭违规举报

URL: /zh-Hans/documentation/pix_indireto/relato_de_infracao/fechar_relato_infracao

QI Tech 负责对巴西中央银行进行 轮询 ，以验证是否有其他参与者为间接参与者创建的违规举报，并将通过 webhook（已附带 acknowledged 状态）通知间接参与者。

为通知间接参与者有需要其响应的违规举报，QI Tech 将发送一个 接收 webhook 。

:::danger 重要
需要注意的是，只有 收到 违规举报的参与者才能关闭它。
:::

:::danger 重要
巴西中央银行规定，间接参与者收到违规举报后的 7天 内，必须 关闭 该举报。

如果间接参与者有延迟，QI Tech 将在发送接收违规 webhook 后的 6个自然日 后，以 agreed 状态关闭违规举报，以避免机构被巴西中央银行处罚。
:::

关闭违规举报时，状态必须为 acknowledged 。

## 请求

ENDPOINT /pix/infraction_report/ INFRACTION_REPORT_KEY
MÉTODO PATCH

**请求体 - 接受**

```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.",
}
```

**请求体 - 拒绝**

```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.",
}
```

### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
| ----------------------- | ------ | ----------------------------------------------------------- | ---------- |
| `infraction_report_key` | string | 要关闭的已创建违规举报的 UUID4。 | 36 |

### 请求体参数

| 字段 | 类型 | 描述 | 字符数 |
| ---------------------------- | ------ | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| `analysis_result` *          | enum   | 分析结果。 | **[analysis_result 枚举值](#enumeradores-analysis_result)** |
| `request_control_key` *      | uuidv4 | 用于查询所发请求的 UUID4。 | 36 |
| `infraction_report_status` * | enum   | 要设置的违规举报状态。 | **[infraction_report_status 枚举值](#enumeradores-infraction_report_status)** |
| `fraud_type`                 | enum   | 查明的欺诈类型。不属于违规举报实体，但关闭时需要填写。 | **[fraud_type 枚举值](#enumeradores-fraud_type)** |
| `analysis_details`           | string | 关于分析结果的描述。 | 250 |

### analysis_result 枚举值

| 字段 | 类型 | 描述 | 字符数 |
| ----------- | ------ | ---------------------------------------------------------------------------------------------------------- | ---------- |
| `agreed`    | string | 间接参与者<strong>同意</strong>其他参与者创建的违规举报。 | - |
| `disagreed` | string | 间接参与者<strong>不同意</strong>其他参与者创建的违规举报。 | - |

### infraction_report_status 枚举值

| 字段 | 类型 | 描述 | 字符数 |
| -------------- | ------ | ---------------------------------------------------------------------- | ---------- |
| `open`         | string | 违规举报已<strong>创建</strong>并在 BACEN 中处于开启状态。 | - |
| `acknowledged` | string | 违规举报已被参与者<strong>接收</strong>。 | - |
| `cancelled`    | string | 违规举报在 BACEN 中已<strong>取消</strong>。 | - |
| `closed`       | string | 违规举报在 BACEN 中已<strong>关闭</strong>。 | - |

### fraud_type 枚举值

| 字段 | 类型 | 描述 | 字符数 |
| ------------------- | ------ | -------------------------------------------------------------------- | ---------- |
| `application_fraud` | string | 以他人文件伪造身份的欺诈。 | - |
| `mule_account`      | string | 通过合法开设的空壳账户进行欺诈。 | - |
| `scammer_account`   | string | 目标账户以真实欺诈者名义开设的欺诈。 | - |
| `other`             | string | 不属于上述枚举的其他性质欺诈。 | - |

## 响应

STATUS 200

**响应体**

```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",
}
```

### 响应体参数
| 字段 | 类型 | 描述 | 字符数 |
| ------------------------------- | ------ | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `infraction_report_key` *       | string | 违规举报的唯一标识符。 | 36 |
| `pix_transfer_key` *            | string | PIX 交易的唯一标识符。 | 36 |
| `end_to_end_id` *               | string | BACEN 中 PIX 交易的唯一标识符。 | 36 |
| `infraction_report_status` *    | enum   | 违规举报的状态。 | **[infraction_report_status 枚举值](#enumeradores-infraction_report_status)** |
| `infraction_report_situation` * | enum   | 违规发生的情形。 | **[infraction_report_situation 枚举值](#enumeradores-infraction_report_situation)** |
| `infraction_report_type` *      | enum   | 违规举报类型。 | **[infraction_report_type 枚举值](#enumeradores-infraction_report_type)** |
| `infraction_report_details`     | string | 关于已创建违规举报的详细信息。 | \<\= 2000 |
| `credited_participant` *        | string | 贷记方参与者的 ISPB。 | 8 |
| `debited_participant` *         | string | 借记方参与者的 ISPB。 | 8 |
| `analysis_result` *             | string | 分析结果。 | **[analysis_result 枚举值](#enumeradores-analysis_result)** |
| `analysis_details` *            | string | 关于分析结果的描述。 | 250 |
| `infraction_report_direction` * | enum   | 表示举报是由间接参与者开启还是由其他参与者开启的枚举值。 | **[infraction_report_direction 枚举值](#enumeradores-infraction_report_direction)** |
| `created_at` *                  | string | 违规举报的创建日期。 | 24 |
| `updated_at` *                  | string | 违规举报的更新日期。 | 24 |

### infraction_report_situation 枚举值

| 字段 | 类型 | 描述 | 字符数 |
| ------------------- | ------ | ------------------------------------------------------- | ---------- |
| `scam`              | string | 诈骗或欺诈行为。 | - |
| `account_takeover`  | string | 来源账户未授权的交易。 | - |
| `coercion`          | string | 胁迫犯罪。 | - |
| `fraudulent_access` | string | 对来源账户的欺诈性访问。 | - |
| `other`             | string | 不适用于上述列举的其他任何原因。 | - |

### infraction_report_type 枚举值

| 字段 | 类型 | 描述 | 字符数 |
| ------------------ | ------ | ---------------------------------------------------------------------- | ---------- |
| `refund_request`   | string | 为申请退款而生成的违规举报。 | - |
| `refund_cancelled` | string | 因退款取消而生成的违规举报。 | - |

### infraction_report_direction 枚举值

| 字段 | 类型 | 描述 | 字符数 |
| ---------- | ------ | ------------------------------------------------------------- | ---------- |
| `incoming` | string | 以间接参与者为目标的违规举报。 | - |
| `outgoing` | string | 以间接参与者为发起方的违规举报。 | - |

---

# 列出违规举报

URL: /zh-Hans/documentation/pix_indireto/relato_de_infracao/listar_relatos

如果间接参与者请求列出违规举报，可通过以下路由操作。

## 请求

ENDPOINT /pix/infraction_reports
MÉTODO GET

### 查询参数
| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---| ---|
| `infraction_report_status` | enum | 违规举报的状态。 | **[infraction_report_status 枚举值](#enumeradores-infraction_report_status)** |
| `infraction_report_type` | enum | 违规举报的类型。 | **[infraction_report_type 枚举值](#enumeradores-infraction_report_type)** |
| `initial_date` | string | 查询开始日期。 | **[日期格式](#formato-de-data)** |
| `final_date` | string | 查询结束日期。 | **[日期格式](#formato-de-data)** |
| `page_number` | integer | 当前查询的页码。 | - |
| `page_size` | integer | 每页结果数量。 | - |

### 日期格式

| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---| ---|
| `initial_date` | string | 查询开始日期，格式为 "%Y-%m-%d"。例如："2023-10-09"。| 10 |
| `final_date` | string | 查询结束日期，格式为 "%Y-%m-%d"。例如："2023-10-11"。| 10 |

## 响应

STATUS 200

**响应体**

```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
    }
}
```

### 响应体参数
| 字段 | 类型 | 描述 | 字符数 |
| ------------------------------- | ------ | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `infraction_report_key` *       | string | 违规举报的唯一标识符。 | 36 |
| `pix_transfer_key` *            | string | PIX 交易的唯一标识符。 | 36 |
| `end_to_end_id` *               | string | BACEN 中 PIX 交易的唯一标识符。 | 36 |
| `infraction_report_status` *    | enum   | 状态。 | **[infraction_report_status 枚举值](#enumeradores-infraction_report_status)** |
| `infraction_report_situation` * | enum   | 违规发生的情形。 | **[infraction_report_situation 枚举值](#enumeradores-infraction_report_situation)** |
| `infraction_report_type` *      | enum   | 违规举报类型。 | **[infraction_report_type 枚举值](#enumeradores-infraction_report_type)** |
| `infraction_report_details`     | string | 关于已创建违规举报的详细信息。 | \<\= 2000 |
| `credited_participant` *        | string | 贷记方参与者的 ISPB。 | 8 |
| `debited_participant` *         | string | 借记方参与者的 ISPB。 | 8 |
| `infraction_report_direction` * | enum   | 表示举报是由间接参与者开启还是由其他参与者开启的枚举值。 | **[infraction_report_direction 枚举值](#enumeradores-infraction_report_direction)** |
| `infraction_report_events`*     | object | 与违规举报相关的事件。 | **[infraction_report_events 对象](#objetos-infraction_report_events)** |
| `created_at` *                  | string | 违规举报的创建时间。 | 24 |
| `updated_at`                    | string | 违规举报的更新时间。 | 24 |

### infraction_report_status 枚举值

| 字段 | 类型 | 描述 | 字符数 |
| -------------- | ------ | ----------------------------------------------------------------------------- | ---------- |
| `open`         | string | 违规举报已<strong>创建</strong>并在 BACEN 中处于开启状态。 | 4 |
| `acknowledged` | string | 违规举报已被被申诉参与者<strong>接收</strong>。 | 12 |
| `cancelled`    | string | 违规举报在 BACEN 中已<strong>取消</strong>。 | 9 |
| `closed`       | string | 违规举报在 BACEN 中已<strong>关闭</strong>。 | 6 |

### infraction_report_situation 枚举值
| 字段 | 类型 | 描述 | 字符数 |
| ------------------- | ------ | ------------------------------------------------------- | ---------- |
| `scam`              | string | 诈骗或欺诈行为。 | - |
| `account_takeover`  | string | 来源账户未授权的交易。 | - |
| `coercion`          | string | 胁迫犯罪。 | - |
| `fraudulent_access` | string | 对来源账户的欺诈性访问。 | - |
| `other`             | string | 不适用于上述列举的其他任何原因。 | - |

### infraction_report_type 枚举值
| 字段 | 类型 | 描述 | 字符数 |
| ------------------ | ------ | ---------------------------------------------------------------------- | ---------- |
| `refund_request`   | string | 为申请退款而生成的违规举报。 | - |
| `refund_cancelled` | string | 因退款取消而生成的违规举报。 | - |

### infraction_report_direction 枚举值
| 字段 | 类型 | 描述 | 字符数 |
| ---------- | ------ | ------------------------------------------------------------- | ---------- |
| `incoming` | string | 以间接参与者为目标的违规举报。 | - |
| `outgoing` | string | 以间接参与者为发起方的违规举报。 | - |

### infraction_report_events 对象
| 字段 | 类型 | 描述 | 字符数 |
| --------------- | ------ | ---------------------------------------- | ----------------------------------------------------------------------------------- |
| `event_type`    | enum   | 与事件相关的状态变更。 | **[infraction_report_status 枚举值](#enumeradores-infraction_report_status)** |
| `event_details` | string | 事件描述。 | - |
| `created_at` *  | string | 事件创建时间。 | 24 |

---

# 违规举报流程简介

URL: /zh-Hans/documentation/pix_indireto/relato_de_infracao/maquina_estados

## 简介

巴西中央银行允许在 PIX 交易（无论是普通交易还是退款）中发生 违规 时，间接参与者可以通知流程中涉及的另一个参与者存在违规行为。

:::info 

需要注意的是，对于 PIX 交易，只有 贷记方 参与者才能发起违规举报。

:::

:::danger 重要

巴西中央银行规定，间接参与者收到违规举报后的 7天 内，必须 关闭 该举报。

如果间接参与者有延迟，QI Tech 将在发送接收违规 webhook 后的 6个自然日 后，以 agreed 状态关闭违规举报，以避免机构被巴西中央银行处罚。

:::

## Infraction_Report_Status 状态机

| 枚举值 | 翻译 | 描述 |
|---|---|---|
| `open` | 开启 | 违规举报<strong>创建</strong>处理完成后，将在 BACEN 中处于开启状态。 |
| `acknowledged` | 已接收 | QI Tech 收到了一份以间接参与者为目标的违规举报，并将通过 webhook 转发该举报。 |
| `cancelled` | 已取消 | 开启举报的参与者发送了取消请求，该举报在 BACEN 中已<strong>取消</strong>。 |
| `closed` | 已关闭 | 违规举报关闭已由 QI Tech 处理，并在 BACEN 中已<strong>关闭</strong>。 |

## Infraction_Report_Status 状态机控制

即使流程是同步的，间接参与者也需要了解违规举报可能具有的各种状态。以下描述了参与者开启、取消、完成和接收违规举报后可预期的情况。

### 参与者开启违规举报

间接参与者可在巴西中央银行 开启 违规举报。开启举报的唯一要求是已通过 PIX 完成了一笔 交易 。

即使第一份举报已关闭，间接参与者也不能对同一笔交易开启第二份违规举报。

### 参与者取消违规举报

间接参与者开启违规举报后，如有需要，可申请 取消 ，无论该举报的当前状态如何。

### 参与者接收违规举报

在入站违规流程中，接收（acknowledged 状态）由 QI Tech 自动处理，并通过 webhook 将收到的违规举报发送给间接参与者。

在出站流程中，对方接收举报不会导致内部状态更新，因为该操作不会改变违规实体。

间接参与者将以 acknowledged 状态接收违规举报。

### 参与者关闭违规举报

间接参与者被通知收到状态为 acknowledged 的违规举报后，必须予以关闭。

间接参与者在关闭时需提供分析结果，可以拒绝违规举报，也可以在收到 webhook 后 6 个自然日内接受。超过该期限若无响应，QI Tech 将自动接受该举报，以履行与 BACEN 和 SPI 关于响应时间的承诺。

## Infraction_Report_Direction 状态机控制

| 枚举值 | 翻译 | 描述 |
|---|---|---|
| `incoming` | 传入 | 间接参与者收到了来自另一个参与者的违规举报。 |
| `outgoing` | 传出 | 间接参与者向另一个参与者发送了违规举报。 |

## 间接参与者接收/关闭违规举报

在此情况下，"infraction_report_direction" 字段值为 "incoming"。

## 间接参与者发送/取消违规举报

在此情况下，"infraction_report_direction" 字段值为 "outgoing"。

需要注意的是，这些字段均不由间接参与者发送，仅出现在请求的响应中。

---

# 场景模拟

URL: /zh-Hans/documentation/pix_indireto/relato_de_infracao/simulacao_de_cenarios

逐步模拟外部代理执行操作的过程。这些模拟包括违规举报的接收和更新。

:::info 信息
这些请求没有返回载荷（响应体），只有状态码 204 的响应状态。由模拟生成的内容需通过 webhook 接收。
:::

## 1 - 模拟接收违规举报

模拟接收由其他机构开启的违规举报。

:::info 重要
发送请求时必须有一个有效的 `pix_transfer_key`，不必特别关注转账另一方的信息，因为在模拟过程中第二个参与者的所有信息都将被替换。
:::

### 请求

ENDPOINT /mock/pix/infraction_report
MÉTODO POST

请求体

```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.",
}
```

### 请求体对象

| 字段 | 类型 | 描述 | 最大字符数 |
| --------------------------------- | ------ | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
| **infraction_report_status\***    | string | 违规举报的接收状态："acknowledged"。 | **[infraction_report_status 枚举值](#enumeradores-infraction_report_status)** |
| **pix_transfer_key\***            | string | UUID4，标识相关交易的唯一密钥。 | 36 |
| **infraction_report_type\***      | string | 违规举报类型。 | **[infraction_report_type 枚举值](#enumeradores-infraction_report_type)** |
| **infraction_report_situation\*** | string | 违规发生的情形。 | **[infraction_report_situation 枚举值](#enumeradores-infraction_report_situation)** |
| **infraction_report_details\***   | string | 违规举报详细信息。 | 2000 |

### infraction_report_status 枚举值

| 字段 | 类型 | 描述 | 字符数 |
| -------------- | ------ | ---------------------------------------------------------------------- | ---------- |
| `open`         | string | 违规举报已<strong>创建</strong>并在 BACEN 中处于开启状态。 | - |
| `acknowledged` | string | 违规举报已被参与者<strong>接收</strong>。 | - |
| `cancelled`    | string | 违规举报在 BACEN 中已<strong>取消</strong>。 | - |
| `closed`       | string | 违规举报在 BACEN 中已<strong>关闭</strong>。 | - |

### infraction_report_type 枚举值

| 字段 | 类型 | 描述 | 字符数 |
| ------------------ | ------ | ---------------------------------------------------------------------- | ---------- |
| `refund_request`   | string | 为申请退款而生成的违规举报。 | - |
| `refund_cancelled` | string | 因退款取消而生成的违规举报。 | - |

### infraction_report_situation 枚举值

| 字段 | 类型 | 描述 | 字符数 |
| ------------------- | ------ | ------------------------------------------------------- | ---------- |
| `scam`              | string | 诈骗或欺诈行为。 | - |
| `account_takeover`  | string | 来源账户未授权的交易。 | - |
| `coercion`          | string | 胁迫犯罪。 | - |
| `fraudulent_access` | string | 对来源账户的欺诈性访问。 | - |
| `other`             | string | 不适用于上述列举的其他任何原因。 | - |

## 2 - 模拟更新违规举报

模拟由间接参与者开启的违规举报的状态更新。

违规举报更新的模拟选项包括：

1 - 取消：模拟由另一参与者对其之前自行开启的违规举报执行取消（cancel）操作。

2 - 关闭：模拟由另一参与者对间接参与者开启的违规举报执行关闭（close）操作。

### 请求

ENDPOINT /mock/pix/infraction_report
MÉTODO PATCH

请求体 - 取消

:::info 重要
由 `infraction_report_key` 标识的违规举报必须已在接收违规举报模拟中预先创建。
:::

```json
{
  "infraction_report_status": "cancelled",
  "infraction_report_key": "28290ff2-2ba7-4e85-9a5e-862c92259b34"
}
```

请求体 - 关闭

:::info 重要
由 `infraction_report_key` 标识的违规举报必须已由间接参与者预先创建，并在违规举报更新模拟中完成确认。
:::

```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."
}
```

### 请求体对象

| 字段 | 类型 | 描述 | 最大字符数 | 备注 |
| ------------------------------ | ------ | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------- |
| **infraction_report_status\*** | string | 违规举报的新状态："cancelled"、"closed"。 | **[infraction_report_status 枚举值](#enumeradores-infraction_report_status)** | ---- |
| **infraction_report_key\***    | string | 违规举报的唯一密钥。 | 36 | ---- |
| **analysis_result\***          | string | 违规举报的分析结果："agreed" 或 "disagreed"。 | **[analysis_result 枚举值](#enumeradores-analysis_result)** | 状态为 "closed" 时必填 |
| **analysis_details\***         | string | 违规举报分析详细信息。 | 2000 | 状态为 "closed" 时必填 |

### analysis_result 枚举值

| 字段 | 类型 | 描述 | 字符数 |
| ----------- | ------ | ---------------------------------------------------------------------------------------------------------- | ---------- |
| `agreed`    | string | 间接参与者<strong>同意</strong>其他参与者创建的违规举报。 | - |
| `disagreed` | string | 间接参与者<strong>不同意</strong>其他参与者创建的违规举报。 | - |

---

# 接收违规举报

URL: /zh-Hans/documentation/pix_indireto/relato_de_infracao/webhooks_relato_infracao

由于其他参与者可能以间接参与者为目标开启违规举报，QI Tech 有必要将其他参与者开启的举报通知间接参与者。

QI Tech 将对受管理的间接参与者的新举报进行定期轮询，并通过 webhook 以 acknowledged 状态通知对应参与者。

:::danger 重要
巴西中央银行规定，间接参与者收到违规举报后的 7天 内，必须 关闭 该举报。

如果间接参与者有延迟，QI Tech 将在发送接收违规 webhook 后的 6个自然日 后，以 agreed 状态关闭违规举报，以避免机构被巴西中央银行处罚。
:::

违规举报的状态始终为 acknowledged ，表示 QI Tech 已收到该举报并将发送给间接参与者。

:::info 信息

本介绍部分所描述的所有内容，也在与违规通知相关的章节中进行了详细说明，包括间接参与者应如何通过 API 处理。

:::

## 违规举报接收 Webhook
**请求体**

```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"
}
```

### 响应体参数

| 字段 | 类型 | 描述 | 字符数 |
| ------------------------------- | ------ | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `infraction_report_key` *       | string | 违规举报的唯一标识符。 | 36 |
| `pix_transfer_key` *            | string | PIX 交易的唯一标识符。 | 36 |
| `end_to_end_id` *               | string | BACEN 中 PIX 交易的唯一标识符。 | 36 |
| `infraction_report_status` *    | enum   | 状态。 | **[infraction_report_status 枚举值](#enumeradores-infraction_report_status)** |
| `infraction_report_situation` * | enum   | 违规发生的情形。 | **[infraction_report_situation 枚举值](#enumeradores-infraction_report_situation)** |
| `infraction_report_type` *      | enum   | 违规举报类型。 | **[infraction_report_type 枚举值](#enumeradores-infraction_report_type)** |
| `infraction_report_details`     | string | 关于已创建违规举报的详细信息。 | \<\= 2000 |
| `credited_participant` *        | string | 贷记方参与者的 ISPB。 | 8 |
| `debited_participant` *         | string | 借记方参与者的 ISPB。 | 8 |
| `infraction_report_direction` * | enum   | 表示举报是由间接参与者开启还是由其他参与者开启的枚举值。 | **[infraction_report_direction 枚举值](#enumeradores-infraction_report_direction)** |
| `created_at` *                  | string | 违规举报的创建时间。 | 24 |
| `updated_at`                    | string | 违规举报的更新时间。 | 24 |

### infraction_report_status 枚举值

| 字段 | 类型 | 描述 | 字符数 |
| -------------- | ------ | ----------------------------------------------------------------------------- | ---------- |
| `open`         | string | 违规举报已<strong>创建</strong>并在 BACEN 中处于开启状态。 | - |
| `acknowledged` | string | 违规举报已被被申诉参与者<strong>接收</strong>。 | - |
| `cancelled`    | string | 违规举报在 BACEN 中已<strong>取消</strong>。 | - |
| `closed`       | string | 违规举报在 BACEN 中已<strong>关闭</strong>。 | - |

### infraction_report_type 枚举值

| 字段 | 类型 | 描述 | 字符数 |
| ------------------ | ------ | --------------------------------------------------------------------- | ---------- |
| `refund_cancelled` | string | 因退款取消而生成的违规举报。 | 16 |
| `refund_request`   | string | 为申请退款而生成的违规举报。 | 14 |

### infraction_report_situation 枚举值

| 字段 | 类型 | 描述 | 字符数 |
| ------------------- | ------ | ------------------------------------------------------- | ---------- |
| `scam`              | string | 诈骗或欺诈行为。 | - |
| `account_takeover`  | string | 来源账户未授权的交易。 | - |
| `coercion`          | string | 胁迫犯罪。 | - |
| `fraudulent_access` | string | 对来源账户的欺诈性访问。 | - |
| `other`             | string | 不适用于上述列举的其他任何原因。 | - |

### infraction_report_direction 枚举值
| 字段 | 类型 | 描述 | 字符数 |
| ---------- | ------ | ------------------------------------------------------------- | ---------- |
| `incoming` | string | 以间接参与者为目标的违规举报。 | - |
| `outgoing` | string | 以间接参与者为发起方的违规举报。 | - |

## 违规举报变更接收 Webhook
**请求体**

```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"
}
```

### 响应体参数

| 字段 | 类型 | 描述 | 字符数 |
| ------------------------------- | ------ | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `infraction_report_key` *       | string | 违规举报的唯一标识符。 | 36 |
| `pix_transfer_key` *            | string | PIX 交易的唯一标识符。 | 36 |
| `end_to_end_id` *               | string | BACEN 中 PIX 交易的唯一标识符。 | 36 |
| `infraction_report_status` *    | enum   | 状态。 | **[infraction_report_status 枚举值](#enumeradores-infraction_report_status)** |
| `infraction_report_situation` * | enum   | 违规发生的情形。 | **[infraction_report_situation 枚举值](#enumeradores-infraction_report_situation)** |
| `infraction_report_type` *      | enum   | 违规举报类型。 | **[infraction_report_type 枚举值](#enumeradores-infraction_report_type)** |
| `infraction_report_details`     | string | 关于已创建违规举报的详细信息。 | \<\= 2000 |
| `credited_participant` *        | string | 贷记方参与者的 ISPB。 | 8 |
| `debited_participant` *         | string | 借记方参与者的 ISPB。 | 8 |
| `analysis_result` *             | string | 分析结果。 | **[analysis_result 枚举值](#enumeradores-analysis_result)** |
| `analysis_details` *            | string | 关于分析结果的描述。 | 250 |
| `infraction_report_direction` * | enum   | 表示举报是由间接参与者开启还是由其他参与者开启的枚举值。 | **[infraction_report_direction 枚举值](#enumeradores-infraction_report_direction)** |
| `created_at` *                  | string | 违规举报的创建时间。 | 24 |
| `updated_at`                    | string | 违规举报的更新时间。 | 24 |

### analysis_result 枚举值

| 字段 | 类型 | 描述 | 字符数 |
| ----------- | ------ | ---------------------------------------------------------------------------------------------------------- | ---------- |
| `agreed`    | string | 间接参与者<strong>同意</strong>其他参与者创建的违规举报。 | - |
| `disagreed` | string | 间接参与者<strong>不同意</strong>其他参与者创建的违规举报。 | - |

---

# Pix

URL: /zh-Hans/documentation/pix_v2

## 发起 Pix 交易

### Request

ENDPOINT /account/ ACCOUNT_KEY /pix_transfer
MÉTODO POST

### 路径参数

| 字段           | 类型   | 描述                   | 字符数 |
|--------------|--------|------------------------|--------|
| `account_key` | uuidv4 | 账户唯一标识密钥。     | 36     |

**Chave**

Request Body: 通过 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

| 字段                    | 类型        | 描述                                                                                                                                                                         | 字符数     |
|-------------------------|-------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuidv4      | 客户请求唯一标识密钥，格式为 uuid v4。                                                                                                                                        | 36         |
| `pix_transfer_type` *   | enumerator  | 要执行的 Pix 类型。对于密钥转账，应为 **key**。                                                                                                                               | "key"      |
| `target_pix_key` *      | string      | 接收交易的账户 Pix 密钥。                                                                                                                                                    | 100        |
| `transaction_amount` *  | number      | 转账金额。                                                                                                                                                                    | 10         |
| `end_to_end_id` *       | string      | Pix 交易在 SPI（即时支付系统）内的幂等键。此密钥在 Pix 密钥查询中返回。仅当 `pix_transfer_type` 为 **key**、**static_qr_code** 或 **dynamic_qr_code** 时才应发送。             | 32         |
| `pix_message`           | string      | 随 Pix 转账发送的消息。                                                                                                                                                       | 140        |

**Manual**
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

| 字段                    | 类型        | 描述                                                                                                | 字符数                                              |
|-------------------------|-------------|-----------------------------------------------------------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | uuidv4      | 客户请求唯一标识密钥，格式为 uuid v4。                                                               | 36                                                  |
| `pix_transfer_type` *   | enumerator  | Pix 转账类型。                                                                                      | **manual**                                          |
| `target_account` *      | Object      | 目标账户 - 仅在 `pix_transfer_type` 为 **manual** 时发送。                                          | **[target_account 对象](#objeto-target_account)**   |
| `transaction_amount` *  | number      | 转账金额。                                                                                          | 10                                                  |
| `pix_message`           | string      | 随 Pix 转账发送的消息。                                                                             | 140                                                 |

### target_account 对象

| 字段                       | 类型        | 描述                             | 字符数                                                    |
|--------------------------|-------------|----------------------------------|-----------------------------------------------------------|
| `account_branch` *       | string      | 账户支行号。                      | 6                                                         |
| `account_digit` *        | string      | 账户验证码。                      | 1                                                         |
| `account_number` *       | string      | 账户号码。                        | 20                                                        |
| `owner_document_number` * | string     | 账户持有人 CPF 或 CNPJ（仅数字）。| 14                                                        |
| `owner_name` *           | string      | 账户持有人姓名。                  | 150                                                       |
| `account_type`*          | enumerator  | 账户类型。                        | **[account_type 枚举值](#enumerador-account_type)**       |
| `ispb` *                 | string      | 金融机构 CNPJ 的前八位数字。      | 8                                                         |

### account_type 枚举值

| 枚举值               | 描述       |
|----------------------|------------|
| **checking_account** | 活期账户   |
| **salary_account**   | 工资账户   |
| **saving_account**   | 储蓄账户   |
| **payment_account**  | 支付账户   |

**Qr Code**

Request Body: 通过 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

| 字段                       | 类型        | 描述                                                                                                                                                                           | 字符数                                    |
|----------------------------|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|
| `request_control_key` *    | uuidv4      | 客户请求唯一标识密钥，格式为 uuid v4。                                                                                                                                          | 36                                        |
| `pix_transfer_type` *      | enumerator  | Pix 转账类型。                                                                                                                                                                  | **static_qr_code** 或 **dynamic_qr_code** |
| `target_pix_key` *         | string      | 接收交易的账户 Pix 密钥。                                                                                                                                                      | 100                                       |
| `receiver_conciliation_id` | string      | 收款方对账标识。                                                                                                                                                                | 35                                        |
| `transaction_amount` *     | number      | 转账金额。                                                                                                                                                                      | 10                                        |
| `end_to_end_id` *          | string      | Pix 交易在 SPI（即时支付系统）内的幂等键。此密钥在 Pix 密钥查询中返回。仅当 `pix_transfer_type` 为 **key**、**static_qr_code** 或 **static_qr_code** 时才应发送。               | 32                                        |
| `pix_message`              | string      | 随 Pix 转账发送的消息。                                                                                                                                                         | 140                                       |

:::info 提示
`end_to_end_id` 在[解码 Pix QR Code](/documentation/pix/decodificar_qr_code) 时返回，使用 Pix 复制粘贴的 URI。
:::

:::danger 注意
查询使用的 `end_to_end_id` 必须是以将发起转账的账户名义查询的！
:::

:::danger 注意
一个 `end_to_end_id` 只能用于一笔转账，无论该转账是否成功。
:::

### Response

STATUS 201

Response Body: 转账已发送

```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: 转账待处理

```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 说明
若返回 **HTTP Status 202** 且 `pix_transfer_status` 值为 **pending**，则不应重试 Pix 请求。

该转账将被重新处理。需通过[查询 Pix 转账](#consultar-transação-pix)验证转账状态。
:::

STATUS 4xx

Response Body: 转账已拒绝

```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: 错误

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

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                   | 英文描述<br/>`description`                                                                                              | 葡语描述<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                      | 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                      | 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 -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------)

## 在巴西中央银行查询 Pix 密钥

### Request

ENDPOINT /pix_key/ PIX_KEY ?account_key= ACCOUNT_KEY
MÉTODO GET

### 路径参数

| 字段         | 类型   | 描述                | 字符数 |
|------------|--------|---------------------|--------|
| `pix_key` * | string | 将被查询的 Pix 密钥。 | 77     |

:::info Pix 密钥类型
`pix_key` 可以是 CPF、CNPJ、电子邮件、手机号或随机密钥（UUID），格式如下：

**CPF**：11 位整数。

**CNPJ**：14 位整数。

**电子邮件**：包含至少一个"@"的文本。

**手机号**：包含以下值的文本："+55" + "手机区号" + "至少 8 位至多 9 位的整数手机号码"。例如："+5511987654321"。

**随机密钥**：UUID4。
:::

### 查询参数

| 字段             | 类型   | 描述                   | 字符数 |
|----------------|--------|------------------------|--------|
| `account_key` * | uuidv4 | 账户唯一标识密钥。     | 36     |

:::info 查询 token 的使用
为确保 Pix 密钥查询 token 向正确的人收费，必须发送 `account_key`。
:::

### Response

STATUS 200

Response Body: 密钥有效

```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: 错误

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

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`        | 英文描述<br/>`description`                | 葡语描述<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 -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------)

## 退还一笔 Pix

Pix 退还可在收款后 90 天内进行。

### Request

ENDPOINT /account/ ACCOUNT_KEY /pix_transfer/ PIX_TRANSFER_KEY /reversal
MÉTODO POST

### 路径参数

| 字段                  | 类型   | 描述                               | 字符数 |
|---------------------|--------|------------------------------------|--------|
| `account_key` *     | uuidv4 | 账户唯一标识密钥。                  | 36     |
| `pix_transfer_key` * | uuidv4 | QI 系统中 Pix 转账的唯一标识密钥。 | 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_control_key` * | uuidv4 | 请求的唯一性密钥。  | 36                                                             |
| `reversal_amount` *     | number | 退还金额。          | 11                                                             |
| `reversal_reason` *     | string | 退还原因。          | **[reversal_reason 枚举值](#enumerador-reversal_reason)**      |
| `reversal_message`      | string | 退还消息。          | 140                                                            |

### reversal_reason 枚举值

| 枚举值             | 描述                     |
|--------------------|--------------------------|
| **client_request** | 由账户持有人提出的要求。 |
| **reconciliation** | 因操作错误进行对账。     |

### Response

STATUS 201

Response Body: 退还已发送

```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: 退还待处理

```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 说明
若返回 **HTTP Status 202** 且 `pix_transfer_status` 值为 **pending**，则不应重试 Pix 请求。

该转账将被重新处理。需通过[查询 Pix 转账](#consultar-transação-pix)验证转账状态。
:::

### 响应体

| 字段                    | 类型        | 描述                                                                | 字符数                                                          |
|-------------------------|-------------|---------------------------------------------------------------------|-----------------------------------------------------------------|
| `reversal_status`       | enumerator  | 退还交易状态枚举值。                                                 | [reversal_status 枚举值](#enumerador-reversal_status)           |
| `transfer_amount`       | number      | 退还转账金额。                                                       | 11                                                              |
| `pix_transfer_key`      | uuidv4      | 退还执行的 Pix 交易密钥。                                           | 36                                                              |
| `end_to_end_id`         | string      | Pix 交易在 SPI（即时支付系统）内的幂等键                             | 32                                                              |
| `request_control_key`   | uuidv4      | 客户使用的请求唯一标识密钥。                                         | 36                                                              |
| `created_at`            | string      | 退还日期和时间。                                                     | 10                                                              |

### reversal_status 枚举值

| 枚举值       | 描述                   |
|--------------|------------------------|
| **sent**     | Pix 转账执行成功。      |
| **pending**  | Pix 转账待处理。        |
| **rejected** | Pix 转账已拒绝。        |

STATUS 4xx

Response Body: 退还已拒绝

```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 说明
除上述 Pix 转账错误外，Pix 退还还可能返回以下错误。
:::

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                      | 英文描述<br/>`description`                                              | 葡语描述<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 -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------)

## 通过 pix_transfer_key 查询 Pix 交易

### Request

ENDPOINT /account/ ACCOUNT_KEY /pix_transfer/ PIX_TRANSFER_KEY / PIX_TRANSFER_DIRECTION
MÉTODO GET

### 路径参数

| 字段                       | 类型        | 描述                               | 字符数                                                                       |
|--------------------------|-------------|-------------------------------------|------------------------------------------------------------------------------|
| `pix_transfer_direction` * | enumerator | 交易方向指示符（入账或出账）。      | [pix_transfer_direction 枚举值](#enumeradores-pix_transfer_direction)        |
| `account_key` *          | uuidv4      | QI 账户唯一标识密钥。              | 36                                                                           |
| `pix_transfer_key` *     | uuidv4      | Pix 转账唯一标识密钥。             | 36                                                                           |

### pix_transfer_direction 枚举值

| 枚举值       | 描述                   |
|--------------|------------------------|
| **incoming** | Pix 转账执行成功。     |
| **outgoing** | Pix 转账执行成功。     |

### Response

STATUS 201

Response Body: 转账已发送（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: 转账已拒绝（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: 退还已发送（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: 转账已收到（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: 退还已收到（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: 转账已拒绝（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: 错误

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

| HTTP 状态码 | QI 代码<br/>`code` | 标题<br/>`title`                             | 英文描述<br/>`Description`                           | 葡语描述<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 -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------)

## 查询多笔 Pix 交易

### Request

ENDPOINT /account/ ACCOUNT_KEY /pix_transfers
MÉTODO GET

### 路径参数

| 字段              | 类型   | 描述                   | 字符数 |
|-----------------|--------|------------------------|--------|
| `account_key` * | uuidv4 | QI 账户唯一标识密钥    | 36     |

### 查询参数

| 字段                      | 类型        | 描述                                                                                   | 字符数                                                                       |
|---------------------------|-------------|----------------------------------------------------------------------------------------|------------------------------------------------------------------------------|
| `pix_transfer_direction`  | enumerator  | 交易方向指示符（入账或出账）。若未发送，默认为 **outgoing**                            | [pix_transfer_direction 枚举值](#enumeradores-pix_transfer_direction)        |
| `request_control_key`     | uuidv4      | 客户使用的请求唯一标识密钥。                                                           | 36                                                                           |
| `end_to_end_id`           | string      | Pix 交易幂等键                                                                         | 32                                                                           |
| `transaction_key`         | uuidv4      | 账户变动标识密钥                                                                       | 36                                                                           |
| `date_from`               | string      | 起始日期。格式："YYYY-MM-DD"                                                           |                                                                              |
| `date_to`                 | string      | 结束日期。格式："YYYY-MM-DD"                                                           |                                                                              |
| `page`                    | integer     | 请求的页码，默认为 1                                                                   |                                                                              |
| `page_size`               | integer     | 查询请求的页面大小，默认值和最大值为 30                                                | 最大值 30                                                                    |

### pix_transfer_direction 枚举值

| 枚举值       | 描述         |
|--------------|--------------|
| **incoming** | Pix 入账转账 |
| **outgoing** | Pix 出账转账 |

### 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

此 Webhook 用于通知最初响应为待处理（返回 HTTP 状态码 202）的交易完成情况。

### Webhook 请求体

Request Body: 交易已发送

```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: 交易已拒绝

```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 参数

| 字段                    | 类型   | 描述                               | 最大字符数 |
|-------------------------|--------|-------------------------------------|------------|
| `webhook_type`          | string | 定义正在报告的事件类型的枚举值      | 23         |
| `webhook_datetime`      | string | Webhook 发送的日期和时间            | 20         |
| `request_control_key`   | string | 用于查询所发出请求的 UUID4          | 36         |
| `pix_transfer_key`      | string | QI 系统中 Pix 转账的标识密钥        | 36         |
| `pix_transfer_status`   | string | 交易状态。                          | 200        |
| `created_at`            | string | 交易创建日期和时间。                | 20         |

[//]: # (Break here for new page -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------)

## 入账 Pix 的 Webhook

此 Webhook 用于通知到达某账户的 Pix 交易。

### Webhook 请求体

Request Body: 已收到 Pix

```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 参数

| 字段                       | 类型        | 描述                                                                                     | 最大字符数                                                         |
|--------------------------|-------------|------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
| `webhook_type`           | string      | 定义正在报告的事件类型的枚举值                                                           | 23                                                                  |
| `webhook_datetime`       | string      | Webhook 发送的日期和时间                                                                 | 20                                                                  |
| `pix_transfer_type`      | enumerator  | 已执行的 Pix 类型                                                                        | **[pix_transfer_type 枚举值](#enumerador-pix_transfer_type)**       |
| `target_pix_key`         | string      | 接收交易的账户 Pix 密钥                                                                  | 100                                                                 |
| `source_account`         | Object      | 目标账户 - 仅在 "manual" 类型交易中发送                                                  | **[source_account 对象](#objeto-source_account)**                   |
| `transfer_amount`        | number      | 转账金额                                                                                 | 10                                                                  |
| `receiver_conciliation_id` | string    | 收款方对账标识                                                                           | 35                                                                  |
| `end_to_end_id`          | string      | Pix 交易幂等键 - 仅在转账类型为 "key" 时发送                                             | 32                                                                  |
| `pix_message`            | string      | 随 Pix 转账发送的消息                                                                    | 140                                                                 |
| `fee_amount`             | number      | 转账金额                                                                                 | 10                                                                  |
| `pix_transfer_status`    | string      | Pix 交易状态                                                                             | 10                                                                  |
| `account_key`            | string      | QI 账户唯一标识密钥                                                                      | 36                                                                  |
| `pix_transfer_key`       | string      | Pix 转账唯一标识密钥                                                                     | 36                                                                  |

### pix_transfer_type 枚举值

| 枚举值               | 描述                     |
|----------------------|--------------------------|
| **manual**           | 使用目标账户数据的 Pix   |
| **key**              | 使用 Pix 密钥的 Pix      |
| **static_qr_code**   | 使用静态 QR Code 的 Pix  |
| **dynamic_qr_code**  | 使用动态 QR Code 的 Pix  |
| **reversal**         | Pix 退还                 |

### source_account 对象

| 字段                       | 类型        | 描述                                                   | 字符数                                                    |
|--------------------------|-------------|--------------------------------------------------------|-----------------------------------------------------------|
| `account_branch` *       | string      | 账户支行号                                             | 6                                                         |
| `account_digit` *        | string      | 账户验证码                                             | 1                                                         |
| `account_number` *       | string      | 账户号码                                               | 20                                                        |
| `owner_document_number` * | string     | 账户持有人 CPF 或 CNPJ（仅数字）                       | 14                                                        |
| `owner_name`             | string      | 账户持有人姓名                                         | 150                                                       |
| `account_type`*          | enumerator  | 账户类型                                               | **[account_type 枚举值](#enumerador-account_type)**       |
| `ispb` *                 | string      | 在巴西中央银行储备转账系统中识别银行的八位数代码       | 8                                                         |

### account_type 枚举值

| 枚举值               | 描述       |
|----------------------|------------|
| **checking_account** | 活期账户   |
| **salary_account**   | 工资账户   |
| **saving_account**   | 储蓄账户   |
| **payment_account**  | 支付账户   |

[//]: # (Break here for new page -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------)

## Pix 退还的 Webhook

此 Webhook 用于通知到达某账户的 Pix 退还。

### Webhook 请求体

Request Body: 已收到 Pix

```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 参数

| 字段                              | 类型        | 描述                                                                                     | 最大字符数                                                         |
|---------------------------------|-------------|------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
| `webhook_type`                  | string      | 定义正在报告的事件类型的枚举值                                                           | 23                                                                  |
| `webhook_datetime`              | string      | Webhook 发送的日期和时间                                                                 | 20                                                                  |
| `pix_transfer_type`             | enumerator  | 已执行的 Pix 类型                                                                        | **[pix_transfer_type 枚举值](#enumerador-pix_transfer_type)**       |
| `target_pix_key`                | string      | 接收交易的账户 Pix 密钥                                                                  | 100                                                                 |
| `source_account`                | Object      | 目标账户 - 仅在 "manual" 类型交易中发送                                                  | **[source_account 对象](#objeto-source_account)**                   |
| `transfer_amount`               | number      | 转账金额                                                                                 | 10                                                                  |
| `receiver_conciliation_id`      | string      | 收款方对账标识                                                                           | 35                                                                  |
| `end_to_end_id`                 | string      | Pix 交易幂等键 - 仅在转账类型为 "key" 时发送                                             | 32                                                                  |
| `pix_message`                   | string      | 随 Pix 转账发送的消息                                                                    | 140                                                                 |
| `fee_amount`                    | number      | 转账金额                                                                                 | 10                                                                  |
| `pix_transfer_status`           | string      | Pix 交易状态                                                                             | 10                                                                  |
| `account_key`                   | string      | QI 账户唯一标识密钥                                                                      | 36                                                                  |
| `pix_transfer_key`              | string      | Pix 转账唯一标识密钥                                                                     | 36                                                                  |
| `original_outgoing_pix_transfer` | string     | 原始出账 Pix 转账的唯一标识密钥                                                          | 36                                                                  |

### pix_transfer_type 枚举值

| 枚举值               | 描述                     |
|----------------------|--------------------------|
| **manual**           | 使用目标账户数据的 Pix   |
| **key**              | 使用 Pix 密钥的 Pix      |
| **static_qr_code**   | 使用静态 QR Code 的 Pix  |
| **dynamic_qr_code**  | 使用动态 QR Code 的 Pix  |
| **reversal**         | Pix 退还                 |

### source_account 对象

| 字段                      | 类型        | 描述                                                   | 字符数                                                    |
|--------------------------|-------------|--------------------------------------------------------|-----------------------------------------------------------|
| `account_branch`         | string      | 账户支行号                                             | 6                                                         |
| `account_digit`          | string      | 账户验证码                                             | 1                                                         |
| `account_number`         | string      | 账户号码                                               | 20                                                        |
| `owner_document_number`  | string      | 账户持有人 CPF 或 CNPJ（仅数字）                       | 14                                                        |
| `owner_name`             | string      | 账户持有人姓名                                         | 150                                                       |
| `account_type`           | enumerator  | 账户类型                                               | **[account_type 枚举值](#enumerador-account_type)**       |
| `ispb`                   | string      | 在巴西中央银行储备转账系统中识别银行的八位数代码       | 8                                                         |

### account_type 枚举值

| 枚举值               | 描述       |
|----------------------|------------|
| **checking_account** | 活期账户   |
| **salary_account**   | 工资账户   |
| **saving_account**   | 储蓄账户   |
| **payment_account**  | 支付账户   |

---

# 审批转账

URL: /zh-Hans/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

| 字段                          | 类型   | 描述                                                          | 字符数                                                        |
|-------------------------------|--------|---------------------------------------------------------------|---------------------------------------------------------------|
| `contact_type` *              | string | 认证令牌的发送方式，可以通过电子邮件（"email"）或短信（"sms"）| 10                                                            |
| `agent_document_number` *     | Object | 接收令牌的用户 CPF。                                          | 11                                                            | 
| `receiver_conciliation_id`    | string | 收款人对账标识 - QrCode 付款必填。                             | 32                                                            |
| `end_to_end_id` *             | string | Pix 交易的幂等密钥 -                                          | 32                                                            |
| `movement_payload` *          | Object | 包含转账信息的载荷                                            | **[Objeto movement_payload](#objeto-movement_payload)**       | - |

### Objeto movement_payload

| 字段                          | 类型   | 描述                                              | 字符数 |
|-------------------------------|--------|---------------------------------------------------|--------|
| `pix_transfer_key` *          | string | Pix 转账唯一密钥，在申请转账端点中返回             | 10     |
| `approver_document_number` *  | Object | 接收令牌的用户 CPF。                              | 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"
} 
```

---

# 申请 Pix 退款

URL: /zh-Hans/documentation/pix/2fa/solicitar_chargeback_pix

Pix 退款可在收款后 90 天内申请。

## Request

ENDPOINT /baas/pix_transfer
MÉTODO POST

:::info 说明
提交退款申请后，需要进行 [ 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: 退款被拒绝

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                    | 描述（英文）<br/>`description`                                         | 描述（葡萄牙语）<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                        |

---

# 申请转账审批令牌

URL: /zh-Hans/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

| 字段                          | 类型   | 描述                                                          | 字符数                                                        |
|-------------------------------|--------|---------------------------------------------------------------|---------------------------------------------------------------|
| `contact_type` *              | string | 认证令牌的发送方式，可以通过电子邮件（"email"）或短信（"sms"）| 10                                                            |
| `agent_document_number` *     | string | 接收令牌的用户 CPF。                                          | 11                                                            | 
| `movement_payload`            | Object | 包含转账信息的载荷                                            | **[Objeto movement_payload](#objeto-movement_payload)**       | 

### Objeto movement_payload

| 字段                          | 类型   | 描述                                              | 字符数 |
|-------------------------------|--------|---------------------------------------------------|--------|
| `pix_transfer_key` *          | string | Pix 转账唯一密钥，在申请转账端点中返回             | 10     |
| `approver_document_number` *  | string | 接收令牌的用户 CPF。                              | 11     | 

### Response

STATUS 201

Response Body

```json
{} 
```

---

# 申请 Pix 转账

URL: /zh-Hans/documentation/pix/2fa/solicitar_transferencia

## Request

ENDPOINT /baas/pix_transfer
MÉTODO POST

## 手动 Pix - 使用银行数据的转账

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

| 字段                    | 类型   | 描述                                                                                                                                                                                              | 字符数                                                 |
|-------------------------|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------|
| `pix_transfer_type` *   | string | Pix 有不同的发起类型，"manual"模式下用户需发送目标账户和来源账户字段，"key"模式下用户需发送收款人 Pix 密钥（目标账户）和来源账户信息。                                                            | 10                                                     |
| `source_account` *      | Object | 来源账户。                                                                                                                                                                                        | **[Objeto source_account](#objeto-source_account)**    | 
| `target_account`        | Object | 目标账户 - 仅在"manual"类型的交易中发送。                                                                                                                                                          | **[Objeto target_account](#objeto-target_account)**    | 10 |
| `transaction_amount` *  | string | 转账金额。                                                                                                                                                                                        | 10                                                     |

### Objeto source_account

| 字段                        | 类型   | 描述                                     | 字符数 |
|-----------------------------|--------|------------------------------------------|--------|
| `account_branch` *          | string | 机构号。                                 | 0      |
| `branch_digit`              | string | 机构校验位。                             | 0      |
| `account_digit` *           | string | 账户校验位。                             | 0      |
| `account_number` *          | string | 账号。                                   | 0      |
| `owner_document_number` *   | string | 账户持有人 CPF 或 CNPJ（仅数字）。       | 0      |

### Objeto target_account

| 字段                        | 类型   | 描述                                               | 字符数 |
|-----------------------------|--------|----------------------------------------------------|--------|
| `account_branch` *          | string | 机构号。                                           | 10     |
| `account_digit` *           | string | 账户校验位                                         | 10     |
| `account_number` *          | string | 账号。                                             | 10     |
| `owner_document_number` *   | string | 账户持有人 CPF 或 CNPJ（仅数字）。                 | 10     |
| `owner_name` *              | string | 账户持有人姓名。                                   | 10     |
| `account_type` *            | string | 账户持有人 CPF 或 CNPJ（仅数字）。                 | 10     |
| `ispb`                      | string | 八位代码，用于标识巴西央行储备转账系统中的银行。   | 10     |

### Response

STATUS 200

Response Body: 手动转账

```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"
}

``` 

## 使用 Pix 密钥进行 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

| 字段                     | 类型   | 描述                                                                     | 字符数                                              |
|--------------------------|--------|--------------------------------------------------------------------------|-----------------------------------------------------|
| `pix_transfer_type` *    | string | Pix 转账类型（key）                                                      | -                                                   |
| `source_account` *       | Object | 来源账户。                                                               | **[Objeto source_account](#objeto-source_account)** | 
| `pix_key`                | Object | Pix 密钥                                                                 | -                                                   |
| `transaction_amount` *   | string | 转账金额。                                                               | 10                                                  |
| `end_to_end_id`          | string | Pix 交易的幂等密钥 - 在 Pix 密钥查询中返回。                             | 32                                                  |

 
### Objeto source_account

| 字段                        | 类型   | 描述                                    | 字符数 |
|-----------------------------|--------|-----------------------------------------|--------|
| `account_branch` *          | string | 机构号。                                | 0      |
| `branch_digit`              | string | 机构校验位。                            | 0      |
| `account_digit` *           | string | 账户校验位。                            | 0      |
| `account_number` *          | string | 账号。                                  | 0      |
| `owner_document_number` *   | string | 账户持有人 CPF 或 CNPJ（仅数字）。      | 0      |

### Response

STATUS 200

Response Body: 使用 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
  }
}

``` 

## Pix QRCode 转账

用于支付 Pix QR Code 的交易数据必须通过 [Pix QR Code 解码](/documentation/pix/decodificar_qr_code) 获取，使用 Pix 复制粘贴 URI。
I - "end_to_end_id"字段必须与动态 QR Code 解码返回的值相同。
II - "transaction_amount"字段填写动态 QR Code 解码的"qr_code_data.amount"字段返回的相同值；
III - 将"pix_transfer_type"字段更改为相应的枚举值（**static_qr_code** 或 **dynamic_qr_code**），以请求付款。
  IV - "receiver_conciliation_id"字段必须与动态 QR Code 解码返回的值相同。

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

| 字段                         | 类型   | 描述                                                                  | 字符数                                              |
|------------------------------|--------|-----------------------------------------------------------------------|-----------------------------------------------------|
| `pix_transfer_type` *        | string | 转账类型指示符（qrcode）                                              | 10                                                  |
| `source_account` *           | Object | 来源账户。                                                            | **[Objeto source_account](#objeto-source_account)** | 
| `pix_key`                    | Object | Pix 密钥                                                              | -                                                   |
| `transaction_amount` *       | string | 转账金额。                                                            | 10                                                  |
| `receiver_conciliation_id`   | string | 收款人对账标识 - 通过 QrCode 解码获取。                               | 32                                                  |
| `end_to_end_id`              | string | Pix 交易的幂等密钥 - 通过 QrCode 解码返回。                           | 32                                                  |
| `pix_transfer_key`           | string | Pix 交易的幂等密钥 - 仅在转账类型为"key"时发送。                      | 10                                                  |

 
### Objeto source_account

| 字段                        | 类型   | 描述                                    | 字符数 |
|-----------------------------|--------|-----------------------------------------|--------|
| `account_branch` *          | string | 机构号。                                | 0      |
| `branch_digit`              | string | 机构校验位。                            | 0      |
| `account_digit` *           | string | 账户校验位。                            | 0      |
| `account_number` *          | string | 账号。                                  | 0      |
| `owner_document_number` *   | string | 账户持有人 CPF 或 CNPJ（仅数字）。      | 0      |

### Response

STATUS 200

Response Body: 使用 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
  }
}

```

---

# 批准转账申请

URL: /zh-Hans/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

| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---| ---|
| `pix_transfer_type` * | string | 交易标识键，在转账申请时收到 | uuid 键 |
| `approver_document_number` * | string | 授权转账用户的 CPF | string |

## Response

STATUS 200

Response Body: 批准手动转账

```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: 批准密钥转账

```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
如果返回 **http error 422**，则 **不应重试** Pix 申请。需要通过 GET 请求 [/baas/pix/pix_transfer](/documentation/pix/pesquisar_por_transferencia_pix_de_saida) 路由检查 Pix 转账申请的状态。
:::

---

# 在巴西中央银行查询 Pix 密钥数据

URL: /zh-Hans/documentation/pix/baas_v2/consultar_chave_pix

## Request

ENDPOINT /pix_key/ PIX_KEY
MÉTODO GET

### Request Path Params

| 字段        | 类型   | 描述                    | 字符数 |
|-------------|--------|-------------------------|--------|
| `pix_key` * | string | 待查询的 PIX 密钥         | 77     |

:::info Pix 密钥类型
"pix_key" 可以是 CPF、CNPJ、电子邮件、手机号或随机密钥（UUID），格式如下：

**CPF**：11 位整数。

**CNPJ**：14 位整数。

**电子邮件**：包含至少一个"@"的文本。

**手机号**：包含以下格式的文本："+55" + "手机区号" + "手机号（最少8位、最多9位整数）"。例如："+5511987654321"。

**随机密钥**：UUID4。
:::

### Request Query Params

| 字段               | 类型   | 描述                                                                                                                                                                | 字符数 |
|--------------------|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------|
| `account_key` *    | uuidv4 | 别名唯一密钥。                                                                                                                                                      | 36     |
| `document_number`  | int    | Pix 密钥持有人的 CPF/CNPJ。传递此参数时，`is_pix_key_owner` 字段将返回一个布尔值，标识所提供的 CPF/CNPJ 是否与 Pix 密钥持有人的相同。                              | 14     |

:::info 查询令牌的使用
若要将 Pix 密钥查询令牌计费给账户持有人，必须发送 `account_key`。
若不发送 account_key，则令牌将计费给合作伙伴的文件编号。
:::

## Response

STATUS 200

Response Body: 有效密钥

```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"
}
```

| 字段                             | 类型    | 描述                                                                                                                                                                                                   | 最大字符数                                                        |
|----------------------------------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `account_branch`                 | string  | 与 Pix 密钥绑定的账户机构号，不含校验位。                                                                                                                                                              | 4                                                                 |
| `account_created_at`             | string  | 与 Pix 密钥绑定的账户开户日期，由账户托管机构提供。                                                                                                                                                    | 21                                                                |
| `account_digit`                  | string  | 与 Pix 密钥绑定的账户校验位。                                                                                                                                                                          | 1                                                                 |
| `account_number`                 | string  | 与 Pix 密钥绑定的账号，不含校验位。                                                                                                                                                                    | 20                                                                |
| `account_type`                   | enum    | Pix 密钥账户类型定义。                                                                                                                                                                                 | [枚举值 Account Type](#enumeradores-account_type)                 |
| `bank_code`                      | string  | Pix 密钥注册银行代码。对于没有银行代码的机构可能返回空值。                                                                                                                                             | 3                                                                 |
| `end_to_end_id`                  | string  | 在巴西央行查询 Pix 密钥的唯一标识符。应在 Pix 转账中发送，以便恢复查询时消耗的令牌。                                                                                                                  | 32                                                                |
| `financial_institution`          | string  | Pix 密钥注册金融机构名称。                                                                                                                                                                             | 200                                                               |
| `is_pix_key_owner`               | boolean | 如果在请求中传递了 `document_number` 参数，则返回布尔值。此字段表示 `document_number` 参数中提供的 CPF/CNPJ 是否与 Pix 密钥持有人的相同。如果未提供 `document_number` 参数，则返回空值。               | -                                                                 |
| `ispb`                           | string  | Pix 密钥持有参与者的 ISPB。                                                                                                                                                                            | 8                                                                 |
| `owner_masked_document_number`   | string  | Pix 密钥持有人的 CPF 或 CNPJ 号码。                                                                                                                                                                    | 14                                                                |
| `owner_name`                     | string  | Pix 密钥持有人姓名。                                                                                                                                                                                   | 120                                                               |
| `owner_person_type`              | enum    | Pix 密钥持有人的法律性质。                                                                                                                                                                             | [枚举值 Owner Person Type](#enumeradores-owner_person_type)       |
| `owner_trading_name`             | string  | Pix 密钥持有人商号（仅适用于 `owner_person_type=legal`）。                                                                                                                                             | 100                                                               |
| `pix_key`                        | string  | Pix 密钥。                                                                                                                                                                                             | -                                                                 |

### 枚举值 account_type
| 枚举值              | 描述       |
|---------------------|------------|
| `payment`           | 支付账户   |
| `checking`          | 活期账户   |
| `savings`           | 储蓄账户   |
| `saving`            | 储蓄账户   |
| `salary`            | 工资账户   |
| `saving_account`    | 储蓄账户   |
| `payment_account`   | 支付账户   |
| `checking_account`  | 活期账户   |
| `salary_account`    | 工资账户   |
| `escrow`            | 关联账户   |

:::info
不同的枚举值可能代表相同的账户类型，这是由不同机构返回的信息所致。
:::

### 枚举值 owner_person_type
| 枚举值     | 描述   |
|------------|--------|
| `natural`  | string |
| `legal`    | string |

STATUS 4XX

Response Body

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

| HTTP 代码 | QI 代码<br/>`code` | 标题<br/>`title`              | 描述（英文）<br/>`Description`                                                   | 描述（葡萄牙语）<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                                    |

---

# 注销动态 Pix QR Code

URL: /zh-Hans/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

| 字段                 | 类型   | 描述                                                                                                                                                          | 字符数 |
|--------------------|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|--------|
| `occurrence_type` * | string | 事件类型。payment：付款类型事件，registration：登记类型事件，write_off：生成方取消类型事件，bank_written_off：银行取消类型事件。 | -      |
| `qr_code_type` *    | string | 动态 QR Code 类型                                                                                                                                              | -      |
| `qr_code_key` *     | string | 生成时返回的 QR Code 密钥。                                                                                                                                    | 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\"}"
}

```

---

# 查询 Pix 限额申请

URL: /zh-Hans/documentation/pix/busca_por_solicitacao_de_limite_pix

## Request

ENDPOINT /baas/pix/limits_request
MÉTODO GET

### Query String

| 字段               | 类型    | 描述                                                                                                                                                                                    | 字符数 |
|--------------------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------|
| `account_key`      | string  | QIConta 账户标识键                                                                                                                                                                     | 36     |
| `request_status`   | string  | 限额申请状态。有效状态：**"pending_approval"**、**"approved"**、**"rejected"**、**"executed"**。可以以列表形式发送，例如：**"pending_approval,approved"**                              |        |
| `page`             | integer | 查询页码                                                                                                                                                                               | -      |
| `page_size`        | integer | 每页条目数                                                                                                                                                                             | -      |

## 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: 用户没有凭据

```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"
}
```

---

# 查询 Pix 限额使用情况

URL: /zh-Hans/documentation/pix/busca_por_uso_de_limite_pix

## Request

ENDPOINT /baas/pix/limits/ ACCOUNT_KEY /usage
MÉTODO GET

### Path Params

| 字段           | 类型   | 描述                   | 字符数 |
|----------------|--------|------------------------|--------|
| `account_key`  | string | 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: 用户没有凭据

```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: /zh-Hans/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.        |

---

# 交易凭证

URL: /zh-Hans/documentation/pix/comprovante_de_transferencia

## Request

ENDPOINT /transaction_receipt/TRANSACTION_KEY
MÉTODO GET

:::info

此请求的响应将包含所查询交易的相关数据，如果 PDF 参数为 true，则 "pdf_encoded_string" 字段将以 base-64 编码的 PDF 字符串形式提供。

:::

### Path params

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `TRANSACTION_KEY` * | string | 所查询交易的密钥 | uuid 键 |

### Query params

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `pdf` | boolean | 定义响应是否应生成 PDF 的布尔值 | true/false |

STATUS 200

Response Body: 密钥交易凭证

```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: 手动交易凭证

```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\"}"
}
```

---

# 定期转账收据

URL: /zh-Hans/documentation/pix/comprovante_de_transferencia_agendada

## Request

ENDPOINT /schedule_receipt/SCHEDULE_KEY
MÉTODO GET

### Path params

| 字段              | 类型   | 描述           | 字符数     |
|-------------------|--------|----------------|------------|
| `SCHEDULE_KEY` *  | string | 定期交易密钥   | uuid 密钥  |

STATUS 200

Response Body: 使用密钥的交易收据

```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: 手动交易收据

```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\"}"
}
```

---

# 查询 Pix 密钥

URL: /zh-Hans/documentation/pix/consultar_chave

## Request

ENDPOINT /baas/pix/keys/ PIX_KEY
MÉTODO GET

### 路径参数

| 字段        | 类型   | 描述                  |
|------------|--------|-----------------------|
| `pix_key` * | string | 需要查询的 PIX 密钥。 |

:::info Pix 密钥类型
"pix_key" 可以是 CPF、CNPJ、电子邮件、手机号或随机密钥（UUID），格式如下：

CPF：11 位整数。

CNPJ：14 位整数。

电子邮件：包含至少一个"@"的文本。

手机号：包含以下内容的文本："+55" + "手机区号" + "至少 8 位、至多 9 位的手机号码整数"。例如："+5511987654321"。

随机密钥：UUID。
:::

## Response

STATUS 200

Response Body: 活跃密钥

```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: 非活跃密钥

```json
{
  "exists": false,
  "pix_key": "teste@gmail.com"
}
```

STATUS 422
Response Body: 密钥查询超时

```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: 查询 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: 达到请求速率限制

```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"
}
```

---

# 查询 Pix 密钥

URL: /zh-Hans/documentation/pix/consultar_chave_v2

## Request

ENDPOINT /pix_key/ PIX_KEY ?authenticated_user_key= CPF/CNPJ
MÉTODO GET

### Request Path Params

| 字段        | 类型   | 描述                    | 
|-------------|--------|-------------------------|
| `pix_key` * | string | 待查询的 PIX 密钥        |

:::info Pix 密钥类型
"pix_key" 可以是 CPF、CNPJ、电子邮件、手机号或随机密钥（UUID），格式如下：

**CPF**：11 位整数。

**CNPJ**：14 位整数。

**电子邮件**：包含至少一个"@"的文本。

**手机号**：包含以下格式的文本："+55" + "手机区号" + "手机号（最少8位、最多9位整数）"。例如："+5511987654321"。

**随机密钥**：UUID4。
:::

### Request Query String Params

| 字段                       | 类型   | 描述             |
|----------------------------|--------|------------------|
| `authenticated_user_key` * | string | 账户持有人文件号  |

## Response

STATUS 200

Response Body: 有效密钥

```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."
}

```

| 字段                           | 类型          | 描述                                            | 最大字符数 |
|--------------------------------|---------------|-------------------------------------------------|------------|
| `account_branch` *             | string        | 机构号，不含校验位                               | 4          |
| `account_digit` *              | string        | 账户校验位                                       | 1          |
| `account_number` *             | string        | 账号，不含校验位                                 | 20         |
| `account_type` *               | string        | 账户类型定义                                     | 20         |
| `owner_person_type` *          | string        | 账户所有者类型。可以是 "legal" 或 "natural"      | 7          |
| `owner_masked_document_number`*| string        | CPF 或 CNPJ 号码                                 | 14         |
| `owner_name` *                 | string        | 账户所有者姓名                                   | 120        |
| `owner_trading_name`           | string        | 账户所有者商号（仅适用于 CNPJ）                  | 100        |
| `ispb` *                       | string        | 密钥持有参与者的 ISPB                            | 8          |
| `financial_institution` *      | string        | 持有密钥的金融机构名称                           | 200        |
| `created_at` *                 | datetime Zulu | 请求创建日期                                     | 20         |

STATUS 404

Response Body: 无效密钥

```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"
}
```

| HTTP 代码 | QI 代码<br/>`code` | 标题<br/>`title`          | 描述（英文）<br/>`Description`                                                   | 描述（葡萄牙语）<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                                    |

---

# 创建 Pix 密钥

URL: /zh-Hans/documentation/pix/criar_chave

## 创建 CPF、CNPJ 或随机 Pix 密钥

### 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 Pix 密钥类型
"pix_key" 可以是 CPF、CNPJ、电子邮件、手机号或随机密钥（UUID），格式如下：

CPF：11 位整数。

CNPJ：14 位整数。

电子邮件：包含至少一个"@"的文本。

手机号：包含以下内容的文本："+55" + "手机区号" + "至少 8 位、至多 9 位的手机号码整数"。例如："+5511987654321"。

随机密钥：UUID。
:::

:::info 沙盒环境中的 CPF/CNPJ 规则
为模拟批准和拒绝场景，可使用待创建 Pix 密钥持有人 CPF/CNPJ 的第一位数字：

1, 2, 3, 4, 5 -> 自动拒绝
0, 6, 7, 8, 9 -> 自动批准
:::

### 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: Pix 密钥已存在。

  ```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: 账户未找到

    ```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: 人员未找到

    ```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: Pix 密钥创建未完成

    ```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: Pix 密钥数量已达上限

    ```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: 账户未开立

    ```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: 权限无效

    ```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: 尝试创建的 CPF Pix 密钥无效

    ```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 注意
对于创建**随机**密钥的响应，"***pix_key***"字段将返回空值。要获取生成的随机密钥值，需要查询账户已注册密钥列表，或通过激活 Webhook 获取。
:::

:::caution 注意
密钥创建是异步的，因此密钥只有在收到 [Pix 密钥包含 Webhook](#webhook-de-inclusao-de-chave-pix) 后才可使用。
:::

## 创建电子邮件和手机号 Pix 密钥

**创建密钥：** 向端点 "**/baas/pix/keys**" 发送 POST 请求。此时，将向"***pix_key***"字段中填写的电子邮件或手机号发送一个 Token。

### 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: Pix 密钥已存在。

  ```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: 账户未找到

    ```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: 人员未找到

    ```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: Pix 密钥创建未完成

    ```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: Pix 密钥数量已达上限

    ```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: 账户未开立

    ```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: 权限无效

    ```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: 尝试创建的 CPF Pix 密钥无效

    ```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"
    }
    ```

**重要：** 响应中"pix_key_request_key"字段返回的值必须用于批准 Pix 密钥创建请求的 URL。

## 批准电子邮件或手机号 Pix 密钥

### 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: Pix 密钥请求未找到

    ```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: 权限验证器错误

    ```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: 创建请求没有验证

    ```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: 创建请求不处于待验证状态

    ```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 已过期

    ```json
    {
        "title": "Gone",
        "description": {
            "description": "Expired Code.",
            "translation": "Código de verificação expirado."
        },
        "translation": {},
        "extra_fields": {},
        "code": "2FA000410"
    }
    ```

STATUS 403

Response Body: Token 已过期

    ```json
    {
        "title": "Forbidden",
        "description": {
            "description": "Code already verified.",
            "translation": "Este código já foi utilizado."
        },
        "translation": {},
        "extra_fields": {},
        "code": "2FA000403"
    }
    ```

## 重新发送批准 Token

### 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: Pix 密钥请求未找到

    ```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: 权限验证器错误

    ```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: 创建请求没有验证

    ```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: 创建请求不处于待验证状态

    ```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"
    }
    ```

### Pix 密钥包含 Webhook

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 请求失败原因代码
- DCT200012：该密钥已存在绑定关系，但归另一个人所有。建议发起所有权认领。
- DCT200013：该密钥已由同一所有者绑定，但关联至另一个参与者。建议发起可携性认领。
- DCT200014：该绑定密钥存在状态不为已完成或已取消的认领。在此情况下，绑定关系不可删除。
- DCT200015：请求中提供的参数验证失败。
- DCT200016：密钥持有人（CPF/CNPJ）的登记状态异常。在正常化之前，不允许添加 PIX 密钥。
:::

---

# 创建动态 Pix QR Code

URL: /zh-Hans/documentation/pix/criar_qr_code_dinamico

## Request

ENDPOINT /baas/qrcode/dynamic
MÉTODO POST

Request Body: 带到期日

```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: 即时付款

```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

| 字段                       | 类型            | 描述                                                                                                                                                               | 字符数 |
|--------------------------|-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------|
| `amount` *               | float           | 计算折扣、利息和罚款之前的 QR Code 金额。                                                                                                                          | -      |
| `occurrence_type` *      | string          | 事件类型。payment：付款类型事件，registration：登记类型事件，write_off：生成方取消类型事件，bank_written_off：银行取消类型事件。                                 | -      |
| `qr_code_type` *         | string          | 动态 QR Code 类型                                                                                                                                                  | -      |
| `pix_key` *              | string          | 代表交易目标账户的 Pix 密钥。                                                                                                                                     | -      |
| `receiver_conciliation_id` * | string      | 对账唯一标识符                                                                                                                                                    | 32     |
| `expiration_date`        | date            | 账单到期日期（格式为 "YYYY-MM-DD"）                                                                                                                                | -      |
| `expiration_seconds`     | string          | 表示 QR Code 的有效时间（秒），默认为 1 天。                                                                                                                      | -      |
| `payer_name` *           | string          | 付款方姓名。                                                                                                                                                       | -      |
| `payer_document_number` * | string         | 付款方 CPF。                                                                                                                                                       | -      |
| `payer_person_type` *    | string          | 人员类型（natural = 自然人 或 legal = 法人）。                                                                                                                    | -      |
| `payer_request` *        | string          | 给付款方的消息。                                                                                                                                                   | -      |
| `additional_data` *      | array of objects | 将呈现给付款方的信息。                                                                                                                                            | -      |
| `max_payment_days` *     | int32           | 账单最大付款天数。                                                                                                                                                 | -      |
| `rebate_amount` *        | float           | 付款前的绝对折让金额。                                                                                                                                             | -      |
| `interest_amount` *      | float           | 到期后每日逾期的绝对利息值，若到期后一天付款，总金额将为基础金额加罚款。                                                                                         | -      |
| `fine_amount` *          | float           | 到期后绝对值罚款。                                                                                                                                                 | -      |
| `discounts` *            | array of objects | 折扣配置。                                                                                                                                                        | -      |

### additional_data 对象

| 字段        | 类型   | 描述     | 字符数 |
|------------|--------|----------|--------|
| `key_name` * | string | 字段名称 | -      |
| `value`     | string | 字段值   | -      |

### discount 对象

| 字段                   | 类型   | 描述               | 字符数 |
|-----------------------|--------|-------------------|--------|
| `discount_value` *    | float  | 折扣值。           | -      |
| `discount_number`     | int32  | 折扣应用顺序。     | -      |
| `discount_limit_date` | string | 折扣截止日期。     | -      |

## Response

STATUS 200

Response Body: 带到期日

```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: 即时付款

```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\"}"
}

```

---

# 创建静态 QR Code

URL: /zh-Hans/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

| 字段              | 类型   | 描述                                                                          | 字符数 |
|----------------|--------|------------------------------------------------------------------------------|--------|
| `qrcode_format` | string | 表示生成 QR Code 后的返回类型（image、payload、both：默认）。               | -      |
| `pix_key` *    | string | 使用 QR Code 付款时关联的收款账户 Pix 密钥。                                 | 10     |
| `receiver_name` * | string | 账户持有人姓名。                                                             | -      |
| `amount`       | float  | QR Code 金额。若未填写，付款方需在转账时自行输入总金额。                     | -      |

## 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\"}"
}

```

---

# 解码 Pix QR Code

URL: /zh-Hans/documentation/pix/decodificar_qr_code

解码 Pix QR Code，返回 payload 中包含的数据。不会对目标账户执行 DICT 查询，也不会持久化所查询的 QR Code — 适用于支付决策前的预览流程。

## Request

ENDPOINT /pix/decode_qrcode_payload
METHOD POST

Request Body

```json
{
   "qr_code_payload": "00020126580014br.gov.bcb.pix0136a23bf0e9-5175-4829-bf89-e8fe6ac09aa1520400005303986540530.005802BR5914TywinLannister6008saopaulo62070503***6304D4FD"
}
```

### Body 参数

| 字段                 | 类型   | 描述                  | 字符数 |
|---------------------|--------|-----------------------|--------|
| `qr_code_payload` * | string | Pix 复制粘贴          | -      |

## Response

STATUS 200

Response Body: 静态 QR Code

```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 — 即时支付

```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 — 带到期日

```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"
  }
}
```

### 响应字段

| 字段                                | 类型            | 描述                                                                       | 存在于            |
|-------------------------------------|-----------------|----------------------------------------------------------------------------|-------------------|
| `qr_code_type`                      | string          | QR Code 类型：`static`、`dynamic_instant` 或 `dynamic_term`               | 所有              |
| `qr_code_payload`                   | string          | 请求中发送的原始 EMV payload                                              | 所有              |
| `qr_code_data.target_pix_key`       | string          | 收款人 Pix 密钥                                                            | 所有              |
| `qr_code_data.amount`               | string/decimal  | 账单金额。`dynamic_term` 表示罚息/利息/折扣后的最终金额                   | 所有              |
| `qr_code_data.receiver_conciliation_id` | string      | 收款人对账标识符（txid）                                                   | 所有              |
| `qr_code_data.additional_data`      | array           | 附加信息列表 `{name, value}`                                               | 所有              |
| `qr_code_data.category_code`        | string          | 商户类别代码（MCC）                                                        | 所有              |
| `qr_code_data.city`                 | string          | 收款人所在城市                                                             | 所有              |
| `qr_code_data.postal_code`          | string          | 收款人邮政编码                                                             | 所有              |
| `qr_code_data.reusable_qrcode`      | string          | `yes` 表示 QR Code 可多次支付，`no` 表示不可                              | 所有              |
| `qr_code_data.receiver_url`         | string          | 收款人 PSP 的 URL（BR Code 的 `loc` 字段）                                 | `dynamic_*`       |
| `qr_code_data.status`               | string          | 账单状态（见下方枚举值）                                                   | `dynamic_*`       |
| `qr_code_data.revision`             | integer         | 账单当前版本号                                                             | `dynamic_*`       |
| `qr_code_data.created_at`           | string (ISO)    | 收款人 PSP 上账单的创建时间                                                | `dynamic_*`       |
| `qr_code_data.presented_at`         | string (ISO)    | 账单向付款人展示的时间                                                     | `dynamic_*`       |
| `qr_code_data.question_to_payer`    | string          | 收款人对付款人的留言（`solicitacaoPagador`）                               | `dynamic_*`       |
| `qr_code_data.payer_name`           | string          | 收款人指定的预期付款人姓名                                                 | `dynamic_*`       |
| `qr_code_data.payer_document_number` | string         | 预期付款人 CPF/CNPJ                                                        | `dynamic_*`       |
| `qr_code_data.payer_person_type`    | string          | `natural` 或 `legal`                                                       | `dynamic_*`       |
| `qr_code_data.target_name`          | string          | 收款人姓名                                                                 | `dynamic_*`       |
| `qr_code_data.expiration_seconds`   | integer         | 账单有效期（秒），从 `created_at` 起算                                     | `dynamic_instant` |
| `qr_code_data.can_change`           | string          | `yes` 表示付款人可修改金额，`no` 表示不可                                  | `dynamic_instant` |
| `qr_code_data.original_amount`      | string/decimal  | 罚息/利息/折扣前的原始账单金额                                             | `dynamic_term`    |
| `qr_code_data.due_date`             | string (date)   | 账单到期日                                                                 | `dynamic_term`    |
| `qr_code_data.days_after_due_accepted` | integer      | 到期后仍可接受付款的天数                                                   | `dynamic_term`    |
| `qr_code_data.fine_amount`          | string/decimal  | 到期后产生的罚款                                                           | `dynamic_term`    |
| `qr_code_data.fee_amount`           | string/decimal  | 到期后产生的利息                                                           | `dynamic_term`    |
| `qr_code_data.discount_amount`      | string/decimal  | 到期前的折扣                                                               | `dynamic_term`    |
| `qr_code_data.reduction_amount`     | string/decimal  | 账单减免金额                                                               | `dynamic_term`    |
| `qr_code_data.target_trading_name`  | string          | 收款人商户名                                                               | `dynamic_*`       |
| `qr_code_data.address`              | string          | 收款人街道地址                                                             | `dynamic_*`       |
| `qr_code_data.state`                | string          | 收款人所在州                                                               | `dynamic_*`       |

:::caution 响应根级别的已弃用字段
以下字段仅为向后兼容而在响应根级别返回，将在未来版本中移除。请使用 `qr_code_data` 中的对应字段。

| 字段                        | 对应字段                                  | 存在于       |
|----------------------------|------------------------------------------|--------------|
| `pix_key`                  | `qr_code_data.target_pix_key`            | 所有         |
| `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
按 BR Code 规范，静态 QR Code 不包含预期付款人数据、到期日、罚款、利息、折扣或减免。这些字段仅存在于动态 QR Code 中。
:::

:::info 状态
对于动态 QR Code 类型，将根据以下枚举表返回 QR Code 状态。
:::

#### 动态 QR Code 状态枚举值

| 枚举值                          | 描述                     |
|---------------------------------|--------------------------|
| **ATIVA**                       | 账单可用，尚未付款       |
| **CONCLUIDA**                   | 账单已付款并结束         |
| **REMOVIDA_PELO_USUARIO_RECEBEDOR** | 收款方用户申请移除账单 |
| **REMOVIDA_PELO_PSP**           | 收款银行申请移除账单     |

## 错误

STATUS 400

QR Code 格式无效

```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\"}"
}

```

未在 payload 中识别到 QR Code 类型

```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\"}"
}

```

处理动态 QR Code 时出错

```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\"}"
}

```

---

# 删除 Pix 密钥

URL: /zh-Hans/documentation/pix/excluir_chave

## Request

ENDPOINT /baas/pix/keys/ PIX_KEY
MÉTODO DELETE

### Path params

| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `pix_key` * | string | 待删除的 PIX 密钥 | 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\"}"
}

```

---

# 简介

URL: /zh-Hans/documentation/pix/introducao

Pix 是巴西的即时支付方式。这一由巴西中央银行（BACEN）创建的支付手段可在几秒内随时随地在账户之间转移资金。它便捷、快速且安全。

QI Tech 作为巴西中央银行认证的机构，是巴西支付系统（SPB）的成员，能够为客户提供这一便利。

## 优势与潜力
除了提高付款或转账的速度外，Pix 还具有以下潜力：

- 提升市场竞争力和效率；
- 降低成本，提高安全性，改善客户体验；
- 推动零售支付市场的电子化；
- 促进金融普惠；以及
- 填补目前向公众提供的支付工具中存在的一系列缺口。

## 错误

### 错误响应示例：

**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"
}
```

### 错误代码表：

| Code | Message | HTTP Status | Description | 翻译描述 |
|---|---|---|---|---|
| QIT000403 | Forbidden | 403 | Participant has not rights to this operation. | 参与者无权执行此操作 |
| 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). | 服务器因客户端明显错误无法处理请求（如请求语法错误、请求体过大、无效的请求消息格式或欺骗性的请求路由）|
| PXP000046 | Gone | 410 | Expired QR code. | QR Code 已过期 |
| PXP000046 | Gone | 410 | Expired QR code. | QR Code 已过期 |
| QIT000404 | NotFound | 404 | The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible. | 请求的资源未找到，但未来可能可用。客户端后续请求是允许的 |
| QIT000500 | InternalServerError | 500 | An internal error has occurred and its being investigated. | 发生了内部错误，正在调查中 |
| PXP000040 | ClaimKeyNotFound | 408 | Claim Key Not Found. | 待申领的密钥未找到 |
| QIT000403 | Forbidden | AB03 | Participant has not rights to this operation. | 参与者无权执行此操作 |
| PXP000007 | AB03 | 408 | SPI Timeout Control. | SPI 超时控制 |
| PXP000037 | AB09 | 502 | Cancelled transaction due to receiver's internal error. | 因接收方内部错误导致交易被取消 |
| PXP000037 | AB11 | 408 | Target PSP Timeout. | 目标支付服务商超时 |
| PXP000009 | AC03 | 400 | Target account number is invalid. | 目标账号不存在或无效 |
| PXP000010 | AC06 | 400 | Target account is blocked. | 目标账户已被锁定 |
| PXP000011 | AC07 | 400 | Target account is closed. | 目标账户已关闭 |
| PXP000032 | AC14 | 400 | Incorrect type for target account. | 指定交易账户类型不正确 |
| PXP000012 | AG03 | 400 | Unsupported transaction for given target account. | 目标账户不支持此类交易 |
| PXP000013 | AGNT | 400 | SPI participant is not PSP settler agent of payer nor receiver. | SPI 直接参与者既不是付款方也不是收款方的 PSP 清算代理 |
| PXP000014 | AM01 | 400 | Zero value payment order. | 零金额支付指令 |
| PXP000015 | AM04 | 400 | Insufficient funds in PI account from payer. | 付款方 PI 账户余额不足 |
| PXP000016 | AM09 | 400 | Return value greater than corresponding payment order. | 退款金额超过对应支付指令金额 |
| PXP000017 | AM18 | 400 | Invalid transactions number. | 交易数量无效 |
| PXP000018 | BE01 | 400 | Beneficiary document number is not that of target account owner. | 收款人的 CPF/CNPJ 与目标账户持有人不符 |
| PXP000019 | CH11 | 400 | Invalid beneficiary document number. | 目标账户的 CPF/CNPJ 不正确 |
| PXP000020 | CH16 | 400 | Incorrect message element. | 消息元素不正确 |
| PXP000021 | DS04 | 400 | Beneficiary's PSP has rejected payment order. | 收款行拒绝了支付指令 |
| PXP000022 | DS0G | 403 | Signing participant is unauthorized to make a payment order for paying account. | 签署消息的参与者无权对借记 PI 账户进行操作 |
| PXP000023 | DT02 | 400 | Invalid datetime for message delivery. | 消息发送的日期和时间无效 |
| PXP000024 | ED05 | 400 | Error while processing payment (generic error). | 支付处理错误（通用错误） |
| PXP000025 | FF08 | 400 | Badly formatted operation's identifier. | 操作标识符格式错误 |
| PXP000026 | RC09 | 400 | Invalid or non-existent payer's PSP ISPB number. | 付款方 PSP 的 ISPB 编号无效或不存在 |
| PXP000027 | RC10 | 400 | Invalid or non-existent beneficiary's PSP ISPB number. | 收款行的 ISPB 编号无效或不存在 |
| PXP000043 | DS27 | 400 | Invalid or non-existent ISPB number. | ISPB 编号无效或不存在 |
| PXP000044 | AM02 | 400 | Amount too great for credited account. | 付款/退款金额超过目标贷记账户的限额 |
| PXP000028 | JDPISPI001 | 500 | Insufficient funds on JDPI managed PI account. | JDPI 管理的 PI 账户余额不足 |
| PXP000029 | JDPISPI002 | 500 | SPI has returned admi.002 message. N/A. | SPI 返回了 admi.002 消息。消息中返回的错误：N/A |
| PXP000030 | JDPISPI003 | 500 | Insufficient funds on PSP sub-account. | PSP 子账户余额不足 |
| PXP000031 | JDPISPI004 | 500 | General failure during debt on JDPI managed PI account. | 在 JDPI 管理的 PI 账户中进行扣款时发生一般性故障 |
| PXP000001 | JDPICHV001 | 404 | Pix key not found. | Pix 密钥未找到 |
| PXP000002 | JDPICHV002 | 404 | Account has no pix keys linked. | 账户没有绑定任何 Pix 密钥 |
| PXP000003 | JDPICHV003 | 404 | CPF/CNPJ has no pix keys linked. | 提供的 CPF/CNPJ 没有绑定任何 Pix 密钥 |
| PXP000004 | JDPICHV004 | 400 | Pix key already linked on DICT. | Pix 密钥已绑定 |
| PXP000005 | JDPICHV005 | 400 | Pix key is linked to another person. Claim recommended. | Pix 密钥存在但属于另一人。建议提出所有权申领 |
| PXP000006 | JDPICHV006 | 400 | Pix key is linked on another account of the same owner. Key alteration recommended. | Pix 密钥已绑定到同一所有者的另一账户。建议进行密钥变更 |
| PXP000033 | JDPICHV007 | 400 | Missing new account or client name on pix key alteration request. | Pix 密钥变更申请中缺少新账户或客户姓名 |
| PXP000034 | JDPICHV008 | 400 | Wrong field for trading name on natural person pix key alteration. | 自然人 Pix 密钥变更的商业名称字段不正确 |
| PXP000035 | JDPICHV009 | 400 | Missing account type, account number, account created at, name or trading name on key alteration request. | 密钥变更申请中缺少账户类型、账号、开户日期、姓名或商业名称 |
| PXP000042 | JDPIRVN011 | 400 | Claim current status does not allow conclusion. | 申领当前状态不允许结束 |
| PXP000041 | JDPIRVN014 | 400 | Claim Key Not Found. | 待申领的密钥未找到 |
| 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. | 该密钥已存在相同所有者的绑定，但关联到另一参与者。建议提出可携性申领 |
| PXP000047 | RateLimited | 429 | Connection was refused by BACEN. Max requests per minute has been exceeded. | BACEN 拒绝了请求。每分钟最大请求数已超出 |

---

# 列出账户的 Pix 密钥

URL: /zh-Hans/documentation/pix/listar_chaves_pix

## Request

ENDPOINT /baas/pix/keys
MÉTODO GET

## Query Params

| 字段             | 类型   | 描述                                                                    | 字符数   |
|------------------|--------|-------------------------------------------------------------------------|----------|
| `account_key`*   | string | 账户 uuid 键                                                            | uuid 键  |
| `pix_key_status` | enum   | **[Pix Key Status 枚举值](#Pix-Key-Status)** 指示应返回的 Pix 密钥状态 | -        |

### 枚举值 _Pix Key Status_

| 枚举值                                   | 描述                      |
|------------------------------------------|---------------------------|
| **pending_confirmation**                 | 等待确认                  |
| **active**                               | 有效                      |
| **inactivated**                          | 无效                      |
| **pending_claim_request_confirmation**   | 等待 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 — 查询资金追回

URL: /zh-Hans/documentation/pix/med/consultar_recuperacao_de_valores

除了后续的 webhook 之外，您还可以查询针对您发起的资金追回：列表接口返回所有已收到的资金追回，单项查询接口通过 `funds_recovery_id`（与 webhook 中收到的标识符相同）返回某个资金追回的详细信息。

## 列出资金追回

ENDPOINT /internal/pix/funds_recovery/incoming
方法 GET

### Query params

| 字段                    | 类型    | 描述                                                                                       |
| ----------------------- | ------- | -------------------------------------------------------------------------------------------- |
| `funds_recovery_status` | string  | 按资金追回状态过滤：`awaiting_analysis`、`pending_approval`、`completed` 或 `cancelled`。 |
| `initial_date`          | string  | 过滤从该日期起创建的资金追回。格式 `YYYY-MM-DD`。                                          |
| `final_date`            | string  | 过滤截至该日期创建的资金追回。格式 `YYYY-MM-DD`。                                          |
| `page_number`           | integer | 列表页码。默认：`1`。                                                                      |
| `page_size`             | integer | 每页条目数。默认：`10`，最大：`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": "交易被发起方标记为欺诈。",
      "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
  }
}
```

| 字段     | 类型  | 描述                                                                                                                                  |
| -------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `data` * | array | 针对您发起的资金追回列表，从最新到最旧排序。**[funds_recovery 对象](./recebimento_recuperacao_de_valores.md#funds_recovery-对象)** |
| `pagination` * | object | 分页数据：`current_page`、`next_page`（最后一页为 null）和 `rows_per_page`。 |

## 查询单个资金追回

ENDPOINT /internal/pix/funds_recovery/incoming/ FUNDS_RECOVERY_ID
方法 GET

### Path params

| 字段                  | 类型   | 描述                                                        | 字符数 |
| --------------------- | ------ | ------------------------------------------------------------ | ------ |
| `FUNDS_RECOVERY_ID` * | string | 资金追回在巴西央行（Bacen）的标识符（`funds_recovery_id`）。 | 32     |

### Response

STATUS 200

响应为 **[funds_recovery 对象](./recebimento_recuperacao_de_valores.md#funds_recovery-对象)**，包含状态事件历史（`funds_recovery_status_events`），且当资金追回已被回复时，还包含 `client_awnser` 字段。

---

# PIX 特殊退款机制（MED）

URL: /zh-Hans/documentation/pix/med/introducao

巴西中央银行开发了一套银行间集成系统，旨在减少 PIX 范围内货币交易欺诈事件的发生率和严重性。该系统由两个实体组成：违规报告和退款申请。出于安全原因，QI Tech 内部客户的相关管理由内部完成，以避免可能的欺诈行为。

通常遵循的流程是：识别欺诈交易后，发起参与方应提交违规报告，目标参与方必须在 7 天内进行核查并回复是否接受。若接受，发起参与方可以再次就违规提出退款申请，目标参与方必须接受该申请。

---

# 接收退款申请

URL: /zh-Hans/documentation/pix/med/recebimento_pedidos_de_devolucao

与违规报告不同，退款申请在符合某些准则的情况下，应尽可能以接受方式关闭，除非账户已关闭或余额不足。因此，客户只会收到有关退款申请状态更新的 webhooks 通知，这不是可争议的，因为通过 MED 提出退款申请的原因要么是已接受的违规报告，要么是其他参与方因运营故障而提出的。

## incoming refund request 的 Webhook

incoming refund request 是由另一家银行提出的退款，账户所有者是被争议交易的目标。

## 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"
}

```

| 字段               | 类型   | 描述                         | 字符数                                                                        |
| ------------------ | ------ | ---------------------------- | ----------------------------------------------------------------------------- |
| `event_datetime` * | string | 交易创建日期和时间。          | 20                                                                            |
| `key` *            | string | 事件发送的唯一标识键。        | 32                                                                            |
| `data` *           | string | incoming refund request 数据对象。| **[Objeto incoming_refund_request](#objeto-incoming_refund_request)**         |
| `status` *         | string | 退款状态。                   | **[枚举值 refund_request_status](#enumeradores-refund_request_status)**       |

### 枚举值 refund_request_status
| 枚举值      | 描述                           |
| ----------- | ------------------------------ |
| `open`      | 申请已收到，待分析。           |
| `closed`    | 分析完成，申请已关闭。         |
| `cancelled` | 申请被发起方取消。             |

### Objeto incoming_refund_request
| 字段                       | 类型   | 描述                                       | 字符数                                                                                        |
| -------------------------- | ------ | ------------------------------------------ | --------------------------------------------------------------------------------------------- |
| `refund_request_key` *     | string | 巴西央行中退款的 UUID4 标识符。            | 32                                                                                            |
| `infraction_report_key`    | string | 巴西央行中相关违规的 UUID4 标识符。        | 32                                                                                            |
| `target_account_key` *     | string | 原始交易目标账户的 Account key。           | 32                                                                                            |
| `refund_request_type` *    | string | 退款申请类型。                             | **[枚举值 refund_request_type](#enumeradores-refund_request_type)**                           |
| `pix_transfer_key` *       | string | 原始交易的 Pix transfer key。              | 32                                                                                            |
| `end_to_end_id` *          | string | 原始交易的 end_to_end_id。                 | 32                                                                                            |
| `requesting_participant` * | string | 发起交易的参与者。                         | 8                                                                                             |
| `contested_participant` *  | string | 接收交易的参与者。                         | 8                                                                                             |
| `refund_request_details`   | string | 由另一参与方发送的退款详情。               | 2000                                                                                          |
| `refund_payment_event`     | string | 退款执行事件。                             | **[Objeto refund_payment_event](#objeto-refund_payment_event)**                               |
| `requested_amount` *       | float  | 退款申请金额。                             | 2000                                                                                          |
| `refunded_amount` *        | float  | 已退款总金额。                             | 2000                                                                                          |
| `refund_request_status` *  | string | 退款状态。                                 | **[枚举值 refund_request_status](#enumeradores-refund_request_status)**                       |
| `analysis_result`          | string | 分析结果。由 QI Tech 决定。                | **[枚举值 refund_request_analysis_result](#enumeradores-refund_request_analysis_result)**     |
| `analysis_details`         | string | 分析结果的理由。                           | 200                                                                                           |
| `reject_reason`            | string | 申请拒绝原因。                             | **[枚举值 refund_request_reject_reason](#enumeradores-refund_request_reject_reason)**         |
| `blocked_balance_status` * | string | 目标账户余额冻结状态。                     | **[枚举值 blocked_balance_status](#enumeradores-blocked_balance_status)**                     |
| `created_at` *             | string | 交易更改日期和时间。                       | 20                                                                                            |
| `updated_at` *             | string | 交易创建日期和时间。                       | 20                                                                                            |

### Objeto refund_payment_event
| 字段                   | 类型   | 描述                           | 字符数 |
| ---------------------- | ------ | ------------------------------ | ------ |
| `refund_end_to_end_id` | string | 退款交易的 end_to_end_id。     | 32     |
| `refund_transfer_key`  | string | 退款交易的 Pix transfer key。  | 32     |
| `refund_amount`        | string | 退款交易金额。                 |        |
| `created_at`           | string | 交易创建日期和时间。           | 20     |

### 枚举值 refund_request_analysis_result
| 枚举值               | 描述                                                           |
| -------------------- | -------------------------------------------------------------- |
| `totally_accepted`   | 已退还全部申请金额。                                           |
| `partially_accepted` | 因余额不足进行部分退款。正在监控账户以进行后续退款。           |
| `rejected`           | 退款被拒绝，未退还任何资金。若原因为余额不足，将监控该账户。   |

### 枚举值 refund_request_type
| 枚举值             | 描述                                               |
| ------------------ | -------------------------------------------------- |
| `fraud`            | 在违规报告被接受后开启。                           |
| `operational_flaw` | 无需违规报告，用于纠正参与者的运营故障。           |
| `refund_cancelled` | 纠正错误执行的退款。                               |

### 枚举值 blocked_balance_status
| 枚举值                | 描述                                               |
| --------------------- | -------------------------------------------------- |
| `no_balance`          | 客户账户无余额。正在监控待处理余额。               |
| `completelly_blocked` | 与交易等额的资金已完全冻结。                       |
| `partially_blocked`   | 与交易等额的资金已部分冻结。正在监控余额。         |
| `settled`             | 违规已接受，退款申请付款已完成。                   |
| `partially_settled`   | 违规已接受，退款申请付款已部分完成。               |
| `released`            | 资金已释放，原因是违规取消或以不同意方式关闭。     |

### 枚举值 refund_request_reject_reason
| 枚举值            | 描述                                               |
| ----------------- | -------------------------------------------------- |
| `no_balance`      | 客户账户无余额。正在监控待处理余额。               |
| `account_closure` | 客户关系已终止。无法执行退款。                     |
| `other`           | 其他不适用于上述列表的原因。                       |

:::info
对部分退款账户的余额监控有效期限为原始交易发生后 90 天。
:::

## outgoing refund request 的 Webhook

### outgoing refund request 是 QI 提出的退款申请，目标是另一参与者。

## 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"
}
```

| 字段               | 类型   | 描述                         | 字符数                                                                        |
| ------------------ | ------ | ---------------------------- | ----------------------------------------------------------------------------- |
| `event_datetime` * | string | 交易创建日期和时间。          | 20                                                                            |
| `key` *            | enum   | 事件发送的唯一标识键。        | 32                                                                            |
| `data` *           | string | outgoing refund request 数据对象。| **[Objeto outgoing_refund_request](#objeto-outgoing_refund_request)**         |
| `status` *         | string | 退款状态。                   | **[枚举值 refund_request_status](#enumeradores-refund_request_status)**       |

### Objeto outgoing_refund_request
| 字段                       | 类型   | 描述                                       | 字符数                                                                                        |
| -------------------------- | ------ | ------------------------------------------ | --------------------------------------------------------------------------------------------- |
| `refund_request_key` *     | string | 巴西央行中退款的 UUID4 标识符。            | 32                                                                                            |
| `infraction_report_key`    | string | 巴西央行中相关违规的 UUID4 标识符。        | 32                                                                                            |
| `source_account_key` *     | string | 交易来源账户的 Account key。               | 32                                                                                            |
| `refund_request_type` *    | string | 退款申请类型。                             | **[枚举值 refund_request_type](#enumeradores-refund_request_type)**                           |
| `pix_transfer_key` *       | string | 原始交易的 Pix transfer key。              | 32                                                                                            |
| `end_to_end_id` *          | string | 原始交易的 end_to_end_id。                 | 32                                                                                            |
| `requesting_participant` * | string | 发起交易的参与者。                         | 8                                                                                             |
| `contested_participant` *  | string | 接收交易的参与者。                         | 8                                                                                             |
| `refund_request_details`   | string | 由另一参与方发送的退款详情。               | 2000                                                                                          |
| `refund_payment_event`     | string | 退款执行事件。                             | **[Objeto refund_payment_event](#objeto-refund_payment_event)**                               |
| `requested_amount` *       | float  | 退款申请金额。                             | 2000                                                                                          |
| `refund_request_status` *  | string | 退款状态。                                 | **[枚举值 refund_request_status](#enumeradores-refund_request_status)**                       |
| `analysis_result`          | string | 分析结果。由 QI Tech 决定。                | **[枚举值 refund_request_analysis_result](#enumeradores-refund_request_analysis_result)**     |
| `analysis_details`         | string | 分析结果的理由。                           | 200                                                                                           |
| `reject_reason`            | string | 申请拒绝原因。                             | **[枚举值 refund_request_reject_reason](#enumeradores-refund_request_reject_reason)**         |
| `created_at` *             | string | 交易更改日期和时间。                       | 20                                                                                            |
| `updated_at` *             | string | 交易创建日期和时间。                       | 20                                                                                            |

---

# MED 2.0 — 接收资金追回

URL: /zh-Hans/documentation/pix/med/recebimento_recuperacao_de_valores

MED 2.0 引入了**资金追回**（funds recovery），它将被质疑的 PIX 交易的违规报告和退款请求统一为一个流程。当针对某个账户收到资金追回时，QI Tech 会自动对与被质疑交易等值的资金进行预防性冻结，并通过 webhook 通知您，使您有机会在关闭前证明交易的合法性。

收到的资金追回的生命周期如下：

1. **`awaiting_analysis`** — 已收到资金追回并冻结余额；等待您的回复，您最多有 **5 天**时间进行回复。
2. **`pending_approval`** — 回复已发送（说明 + 证据文件）；由 QI Tech 进行分析。
3. **`completed`** — 由 QI Tech 关闭，接受（`agreed`）或拒绝（`disagreed`）该资金追回。
4. **`cancelled`** — 由发起参与方取消。

所有后续沟通均通过 webhook 进行。

## incoming funds recovery 的 Webhook

Incoming funds recovery 是由另一参与方发起的资金追回，其中您的账户是被质疑交易的目标。

:::info 说明
资金追回的 webhook 以 `webhook_type` **`incoming.internal_infraction_report`** 发送。要将其与违规报告区分开，请检查 `data` 对象中是否存在 `funds_recovery_key` 字段。
:::

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": "交易被发起方标记为欺诈。",
    "infraction_amount": 150.50,
    "contact_email": "contact@participant.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"
}
```

### funds_recovery 对象

| 字段                      | 类型   | 描述                                                                | 字符数                                                                                      |
| ------------------------- | ------ | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `funds_recovery_key` *    | string | 资金追回在 QI Tech 的 UUID4 标识符。                                | 32                                                                                          |
| `funds_recovery_id` *     | string | 资金追回在巴西央行（Bacen）的标识符。用于查询和回复。               | 32                                                                                          |
| `infraction_report_id` *  | string | 引发该资金追回的违规在巴西央行的标识符。                            | 32                                                                                          |
| `pix_transfer_key` *      | string | 原始交易的 Pix transfer key。                                       | 32                                                                                          |
| `target_account_key` *    | string | 原始交易目标账户的 account key。                                    | 32                                                                                          |
| `target_person_key` *     | string | 资金追回目标的 person key。                                         | 32                                                                                          |
| `end_to_end_id` *         | string | 原始交易的 end_to_end_id。                                          | 32                                                                                          |
| `funds_recovery_status` * | string | 资金追回的状态。                                                    | **[funds_recovery_status 枚举](#funds_recovery_status-枚举)**                               |
| `situation_type` *        | string | 发起方报告的情形。                                                  | **[situation_type 枚举](#situation_type-枚举)**                                             |
| `report_details`          | string | 发起参与方发送的详细信息。                                          | 2000                                                                                        |
| `infraction_amount`       | number | 被质疑的金额。缺省时视为交易的全部金额。                            | -                                                                                           |
| `contact_email`           | string | 发起参与方的联系邮箱。                                              | 255                                                                                         |
| `contact_phone_number`    | string | 发起参与方的联系电话。                                              | 20                                                                                          |
| `credited_participant` *  | string | 接收交易的参与方。                                                  | 8                                                                                           |
| `debited_participant` *   | string | 发起交易的参与方。                                                  | 8                                                                                           |
| `client_awnser`           | string | 回复中发送的说明。回复后出现。                                        | 2000                                                                                        |
| `analysis_result`         | string | 分析结果。由 QI Tech 决定。                                         | **[analysis_result 枚举](#analysis_result-枚举)**                                           |
| `analysis_details`        | string | 分析结果的说明。                                                    | 2000                                                                                        |
| `blocked_balance_status` * | string | 目标账户的余额冻结状态。                                            | **[blocked_balance_status 枚举](#blocked_balance_status-枚举)**                             |
| `tracking_graph`          | object | 被质疑资金流转的追踪图（如有）。                                    | -                                                                                           |
| `created_at` *            | string | 创建日期和时间。                                                    | 20                                                                                          |
| `updated_at` *            | string | 更新日期和时间。                                                    | 20                                                                                          |

### funds_recovery_status 枚举

| 枚举值              | 描述                                             |
| ------------------- | ------------------------------------------------- |
| `awaiting_analysis` | 已收到资金追回并冻结余额，等待您的回复。         |
| `pending_approval`  | 说明已发送，等待 QI Tech 内部分析。              |
| `completed`         | 分析后由 QI Tech 关闭。                          |
| `cancelled`         | 由发起参与方取消。                               |

### situation_type 枚举

| 枚举值              | 描述                                   |
| ------------------- | --------------------------------------- |
| `scam`              | 诈骗或欺诈原因。                       |
| `account_takeover`  | 未经源账户授权的交易原因。             |
| `coercion`          | 胁迫犯罪原因。                         |
| `fraudulent_access` | 欺诈性访问源账户原因。                 |
| `other`             | 不适用于上述所列的任何原因。           |

### analysis_result 枚举

| 枚举值      | 描述                                     |
| ----------- | ----------------------------------------- |
| `agreed`    | 资金追回被接受，被冻结的资金将被退回。   |
| `disagreed` | 资金追回被拒绝，被冻结的资金将被释放。   |

### blocked_balance_status 枚举

| 枚举值                | 描述                                                     |
| --------------------- | --------------------------------------------------------- |
| `completelly_blocked` | 与被质疑金额等值的资金已完全冻结。                       |
| `partially_blocked`   | 与被质疑金额等值的资金已部分冻结。正在监控余额。         |
| `no_balance`          | 账户无余额。正在监控待处理余额。                     |
| `account_closed`      | 账户已关闭。未冻结任何资金。                         |

---

# 接收违规报告

URL: /zh-Hans/documentation/pix/med/recebimento_relatos_de_infracao

收到违规报告后，QI Tech 将自动冻结目标账户中与被争议交易等额的资金，并发送整个违规周期的跟踪通知，甚至给予客户解释交易的机会。但需要注意的是，最终是否接受违规报告的决定权归 QI Tech 所有。所有与违规相关的通信均通过 webhooks 进行。

## incoming infraction report 的 Webhook

incoming infraction report 是由另一家银行提出的违规，账户所有者是被争议交易的目标。

## 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"
}
```

| 字段               | 类型   | 描述                         | 字符数                                                                                              |
| ------------------ | ------ | ---------------------------- | --------------------------------------------------------------------------------------------------- |
| `event_datetime` * | string | 交易创建日期和时间。          | 20                                                                                                  |
| `key` *            | enum   | 事件发送的唯一标识键。        | 32                                                                                                  |
| `data` *           | string | incoming infraction report 数据对象。| **[Objeto incoming_infraction_report](#objeto-incoming_infraction_report)**                   |
| `status` *         | string | 违规状态。                   | **[枚举值 incoming_infraction_report_status](#enumeradores-incoming_infraction_report_status)**     |

### Objeto incoming_infraction_report
| 字段                            | 类型   | 描述                                         | 字符数                                                                                              |
| ------------------------------- | ------ | -------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `target_person_key` *           | string | 违规目标的 Person key。                      | 32                                                                                                  |
| `end_to_end_id` *               | string | 原始交易的 end_to_end_id。                   | 32                                                                                                  |
| `pix_transfer_key` *            | string | 原始交易的 Pix transfer key。                | 32                                                                                                  |
| `target_account_key` *          | string | 原始交易目标账户的 Account key。             | 32                                                                                                  |
| `infraction_report_status` *    | string | 违规状态。                                   | **[枚举值 incoming_infraction_report_status](#enumeradores-incoming_infraction_report_status)**     |
| `infraction_report_situation` * | string | 违规情况。                                   | **[枚举值 infraction_report_situation](#enumeradores-infraction_report_situation)**                 |
| `analysis_result`               | string | 分析结果。由 QI Tech 决定。                  | **[枚举值 infraction_report_analysis_result](#enumeradores-infraction_report_analysis_result)**     |
| `analysis_details`              | string | 分析结果的理由。                             | 200                                                                                                 |
| `infraction_report_type` *      | string | 违规报告类型。                               | **[枚举值 infraction_report_type](#enumeradores-infraction_report_type)**                           |
| `debited_participant` *         | string | 发起交易的参与者。                           | 8                                                                                                   |
| `credited_participant` *        | string | 接收交易的参与者。                           | 8                                                                                                   |
| `blocked_balance_status` *      | string | 目标账户余额冻结状态。                       | **[枚举值 blocked_balance_status](#enumeradores-blocked_balance_status)**                           |
| `infraction_report_key` *       | string | 巴西央行中交易的 UUID4 标识符。              | 32                                                                                                  |
| `infraction_report_details`     | string | 由另一参与方发送的违规详情。                 | 2000                                                                                                |
| `client_details`                | string | 客户提供的有关原始交易的详情。               | 2000                                                                                                |
| `created_at` *                  | string | 交易更改日期和时间。                         | 20                                                                                                  |
| `updated_at` *                  | string | 交易创建日期和时间。                         | 20                                                                                                  |

### 枚举值 incoming_infraction_report_status
| 枚举值                  | 描述                                           |
| ----------------------- | ---------------------------------------------- |
| `pending_client_awnser` | 违规已收到，等待客户提供解释。                 |
| `pending_approval`      | 已发送解释，等待内部审批。                     |
| `automatically_closed`  | 因客户未响应而自动关闭。                       |
| `manually_closed`       | QI Tech 在分析客户响应后手动关闭。             |
| `cancelled`             | 被发起方取消。                                 |

### 枚举值 infraction_report_situation
| 枚举值              | 描述                             |
| ------------------- | -------------------------------- |
| `scam`              | 诈骗或欺诈原因。                 |
| `account_takeover`  | 来源账户未授权的交易原因。       |
| `coercion`          | 胁迫犯罪原因。                   |
| `fraudulent_access` | 欺诈性访问来源账户的原因。       |
| `other`             | 不适用于上述列表的任何其他原因。 |

### 枚举值 infraction_report_analysis_result
| 枚举值      | 描述                                                               |
| ----------- | ------------------------------------------------------------------ |
| `agreed`    | 间接参与者同意另一参与者创建的违规报告。                           |
| `disagreed` | 间接参与者不同意另一参与者创建的违规报告。                         |

### 枚举值 infraction_report_type
| 枚举值             | 描述                                               |
| ------------------ | -------------------------------------------------- |
| `refund_cancelled` | 因退款取消而生成违规报告。                         |
| `refund_request`   | 为申请退款而生成违规报告。                         |

### 枚举值 blocked_balance_status
| 枚举值                | 描述                                               |
| --------------------- | -------------------------------------------------- |
| `no_balance`          | 客户账户无余额。正在监控待处理余额。               |
| `completelly_blocked` | 与交易等额的资金已完全冻结。                       |
| `partially_blocked`   | 与交易等额的资金已部分冻结。正在监控余额。         |
| `settled`             | 违规已接受，退款申请付款已完成。                   |
| `partially_settled`   | 违规已接受，退款申请付款已部分完成。               |
| `released`            | 资金已释放，原因是违规取消或以不同意方式关闭。     |

:::info
如果客户在 5 天内未回应违规，则违规将自动以接受方式关闭。
:::

## outgoing infraction report 的 Webhook

### outgoing infraction report 是 QI 提出的违规，目标是另一参与者。

## 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"
}
```

| 字段               | 类型   | 描述                         | 字符数                                                                                       |
| ------------------ | ------ | ---------------------------- | -------------------------------------------------------------------------------------------- |
| `event_datetime` * | string | 交易创建日期和时间。          | 20                                                                                           |
| `key` *            | enum   | 事件发送的唯一标识键。        | 32                                                                                           |
| `data` *           | string | outgoing infraction report 数据对象。| **[Objeto outgoing_infraction_report](#objeto-outgoing_infraction_report)**             |
| `status` *         | string | 违规状态。                   | **[枚举值 infraction_report_status](#enumeradores-outgoing_infraction_report_status)**       |

### Objeto outgoing_infraction_report
| 字段                            | 类型   | 描述                                       | 字符数                                                                                              |
| ------------------------------- | ------ | ------------------------------------------ | --------------------------------------------------------------------------------------------------- |
| `infraction_report_key` *       | string | 巴西央行中交易的 UUID4 标识符。            | 32                                                                                                  |
| `end_to_end_id` *               | string | 原始交易的 end_to_end_id。                 | 32                                                                                                  |
| `pix_transfer_key` *            | string | 原始交易的 Pix transfer key。              | 32                                                                                                  |
| `source_account_key` *          | string | 原始交易来源账户的 Account key。           | 32                                                                                                  |
| `infraction_report_status` *    | string | 违规状态。                                 | **[枚举值 outgoing_infraction_report_status](#enumeradores-outgoing_infraction_report_status)**     |
| `infraction_report_situation` * | string | 违规情况。                                 | **[枚举值 infraction_report_situation](#enumeradores-infraction_report_situation)**                 |
| `infraction_report_type` *      | string | 违规报告类型。                             | **[枚举值 infraction_report_type](#enumeradores-infraction_report_type)**                           |
| `infraction_report_details`     | string | 由 QI Tech 发送的违规详情。                | 2000                                                                                                |
| `debited_participant` *         | string | 发起交易的参与者。                         | 8                                                                                                   |
| `credited_participant` *        | string | 接收交易的参与者。                         | 8                                                                                                   |
| `analysis_result`               | string | 分析结果。由另一参与者决定。               | **[枚举值 infraction_report_analysis_result](#enumeradores-infraction_report_analysis_result)**     |
| `analysis_details`              | string | 分析结果的理由。                           | 200                                                                                                 |
| `created_at` *                  | string | 交易更改日期和时间。                       | 20                                                                                                  |
| `updated_at` *                  | string | 交易创建日期和时间。                       | 20                                                                                                  |

### 枚举值 outgoing_infraction_report_status
| 枚举值      | 描述                           |
| ----------- | ------------------------------ |
| `open`      | 违规已开启并发送给另一参与者。 |
| `closed`    | 违规已由另一参与者回复。       |
| `cancelled` | 违规已由 QI Tech 取消。        |

---

# MED 2.0 — 回复资金追回

URL: /zh-Hans/documentation/pix/med/responder_recuperacao_de_valores

当资金追回处于 `awaiting_analysis` 状态时，您可以对其进行回复，证明交易的合法性。回复由一段**文字说明**和一个 **.zip 证据文件**（发票、凭证、对话记录等）组成，以 **`multipart/form-data`** 形式发送。

回复后，资金追回将进入 **`pending_approval`** 状态，进入分析阶段。

:::caution 警告
回复 MED 的最长期限为 **5 天**。
:::

## 资金追回标识符

路由中使用的标识符是 **`funds_recovery_id`** 字段，在资金追回创建时通过 **[incoming funds recovery webhook](./recebimento_recuperacao_de_valores.md#incoming-funds-recovery-的-webhook)** 接收：

```json
{
  "event_datetime": "2026-07-16T16:48:43Z",
  "key": "0dedf537-a75e-4945-be1d-5d278c623022",
  "data": {
    "funds_recovery_id": "b8d19bd4-51dc-4784-a2ad-52807c6dfc80",
    "funds_recovery_status": "awaiting_analysis",
    "...": "..."
  },
  "status": "awaiting_analysis",
  "webhook_type": "incoming.internal_infraction_report"
}
```

同一标识符也可以通过**[资金追回列表](./consultar_recuperacao_de_valores.md#列出资金追回)**获取。

## Request

ENDPOINT /internal/pix/funds_recovery/incoming/ FUNDS_RECOVERY_ID
方法 PATCH

### Path params

| 字段                  | 类型   | 描述                                                        | 字符数 |
| --------------------- | ------ | ------------------------------------------------------------ | ------ |
| `FUNDS_RECOVERY_ID` * | string | 资金追回在巴西央行（Bacen）的标识符（`funds_recovery_id`）。 | 32     |

### Form data

| 字段              | 类型   | 描述                                                            | 字符数 |
| ----------------- | ------ | ---------------------------------------------------------------- | ------ |
| `client_awnser` * | string | 您对被标记为欺诈的交易的说明。                                | 2000   |
| `file` *          | file   | 包含支持说明的证据的 **.zip** 文件。最大大小：**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": "交易被发起方标记为欺诈。",
  "infraction_amount": 150.50,
  "credited_participant": "32402502",
  "debited_participant": "12345678",
  "client_awnser": "合法交易，发票 XXXXXXXXXX 可证明该商品的销售。",
  "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"
}
```

响应为更新后的 **[funds_recovery 对象](./recebimento_recuperacao_de_valores.md#funds_recovery-对象)**，其中 `funds_recovery_status` = `pending_approval`，说明在 `client_awnser` 字段中。

### 错误

| 代码        | 状态 | 描述                                                    |
| ----------- | ---- | --------------------------------------------------------- |
| `QIT000001` | 400  | 请求中缺少 `client_awnser` 或 `file`。                  |
| `MED000042` | 400  | 资金追回不处于 `awaiting_analysis` 状态。               |
| `MED000043` | 400  | 发送的文件不是 **.zip** 文件。                          |
| `MED000044` | 400  | 发送的文件超过 **50MB** 的最大大小。                    |
| `MED000039` | 404  | 未找到给定 `FUNDS_RECOVERY_ID` 对应的资金追回。         |

---

# 回复违规报告

URL: /zh-Hans/documentation/pix/med/resposta_relatos_de_infracao

巴西中央银行规定分析违规报告的期限为 7 天，旨在维持服务质量和退款机制的运作。QI Tech 为客户保留最多 5 天的时间，以回复收到的违规报告并说明交易的合法性或非法性；同时保留 2 天用于内部分析和事实核查。值得注意的是，关于是否接受违规报告的最终决定权完全归 QI Tech 所有。

:::caution 警告
5 天后，若客户未响应，违规将自动以接受方式关闭。
:::

## 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

| 字段               | 类型   | 描述                                         | 字符数 |
| ----------------- | ------ | -------------------------------------------- | ------ |
| `client_awnser` * | string | 客户对被标记为欺诈交易的解释。               | 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",
}
```

| 字段                             | 类型   | 描述                                         | 字符数                                                                                              |
| ------------------------------ | ------ | -------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `target_person_key`*           | string | 违规目标的 Person key。                      | 32                                                                                                  |
| `end_to_end_id`*               | string | 原始交易的 end_to_end_id。                   | 32                                                                                                  |
| `pix_transfer_key`*            | string | 原始交易的 Pix transfer key。                | 32                                                                                                  |
| `target_account_key`*          | string | 原始交易目标账户的 Account key。             | 32                                                                                                  |
| `infraction_report_status`*    | string | 违规状态。                                   | **[枚举值 incoming_infraction_report_status](#enumeradores-incoming_infraction_report_status)**     |
| `infraction_report_situation`* | string | 违规情况。                                   | **[枚举值 infraction_report_situation](#enumeradores-infraction_report_situation)**                 |
| `analysis_result`              | string | 分析结果。由 QI Tech 决定。                  | **[枚举值 infraction_report_analysis_result](#enumeradores-infraction_report_analysis_result)**     |
| `analysis_details`             | string | 分析结果的理由。                             | 200                                                                                                 |
| `infraction_report_type`*      | string | 违规报告类型。                               | **[枚举值 infraction_report_type](#enumeradores-infraction_report_type)**                           |
| `debited_participant`*         | string | 发起交易的参与者。                           | 8                                                                                                   |
| `credited_participant`*        | string | 接收交易的参与者。                           | 8                                                                                                   |
| `blocked_balance_status`*      | string | 目标账户余额冻结状态。                       | **[枚举值 blocked_balance_status](#enumeradores-blocked_balance_status)**                           |
| `infraction_report_key`*       | string | 巴西央行中交易的 UUID4 标识符。              | 32                                                                                                  |
| `infraction_report_details`    | string | 由另一参与方发送的违规详情。                 | 2000                                                                                                |
| `client_details`*              | string | 客户提供的有关原始交易的详情。               | 2000                                                                                                |
| `created_at`*                  | string | 交易更改日期和时间。                         | 20                                                                                                  |
| `updated_at`*                  | string | 交易创建日期和时间。                         | 20                                                                                                  |

### 枚举值 incoming_infraction_report_status
| 枚举值                  | 描述                                           |
| ----------------------- | ---------------------------------------------- |
| `pending_client_awnser` | 违规已收到，等待客户提供解释。                 |
| `pending_approval`      | 已发送解释，等待内部审批。                     |
| `automatically_closed`  | 因客户未响应而自动关闭。                       |
| `manually_closed`       | QI Tech 在分析客户响应后手动关闭。             |
| `cancelled`             | 被发起方取消。                                 |

### 枚举值 infraction_report_situation
| 枚举值              | 描述                             |
| ------------------- | -------------------------------- |
| `scam`              | 诈骗或欺诈原因。                 |
| `account_takeover`  | 来源账户未授权的交易原因。       |
| `coercion`          | 胁迫犯罪原因。                   |
| `fraudulent_access` | 欺诈性访问来源账户的原因。       |
| `other`             | 不适用于上述列表的任何其他原因。 |

### 枚举值 infraction_report_analysis_result
| 枚举值      | 描述                                                               |
| ----------- | ------------------------------------------------------------------ |
| `agreed`    | 间接参与者同意另一参与者创建的违规报告。                           |
| `disagreed` | 间接参与者不同意另一参与者创建的违规报告。                         |

### 枚举值 infraction_report_type
| 枚举值             | 描述                                               |
| ------------------ | -------------------------------------------------- |
| `refund_cancelled` | 因退款取消而生成违规报告。                         |
| `refund_request`   | 为申请退款而生成违规报告。                         |

### 枚举值 blocked_balance_status
| 枚举值                | 描述                                               |
| --------------------- | -------------------------------------------------- |
| `no_balance`          | 客户账户无余额。正在监控待处理余额。               |
| `completelly_blocked` | 与交易等额的资金已完全冻结。                       |
| `partially_blocked`   | 与交易等额的资金已部分冻结。正在监控余额。         |
| `settled`             | 违规已接受，退款申请付款已完成。                   |
| `partially_settled`   | 违规已接受，退款申请付款已部分完成。               |
| `released`            | 资金已释放，原因是违规取消或以不同意方式关闭。     |

---

# 查询自有动态 Pix QR Code

URL: /zh-Hans/documentation/pix/pesquisar_por_qr_code_dinamico

## Request

ENDPOINT /baas/qrcode/dynamic
MÉTODO GET

### 查询参数

| 字段                       | 类型    | 描述                                           | 字符数          |
|--------------------------|---------|----------------------------------------------|-----------------|
| `account_key`              | string  | 与 Pix 密钥关联的 QI 账户标识密钥（UUIDv4）  | 36              |
| `pix_key`                  | string  | 与 QRCode 关联的 PIX 密钥                    | -               |
| `receiver_conciliation_id` | string  | 收款方对账标识                               | 最大长度 = 35   |
| `page`                     | integer | 查询页码（默认 = 0）                          | -               |
| `page_size`                | integer | 每页条目数量（默认 = 15）                     | -               |
| `first_result`             | boolean | 仅返回第一条结果（默认 = desc）               | -               |
| `order_by`                 | string  | 确定结果的返回顺序（默认 = desc）             | asc, desc       |

:::info
`account_key` 或 `pix_key` 必须发送其中之一，两者选其一即可。
::: 

:::caution 注意
若要查询特定 QR Code，应使用 `receiver_conciliation_id` 和 `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: 缺少必填参数

```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: 用户无凭证

```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: 用户不是账户持有人

```json
{
    "title": "Unauthorized",
    "description": "Person is not account owner.",
    "translation": "A pessoa não é dona da conta.",
    "code": "PQR000005"
}
```

STATUS 404

Response Body: Pix 密钥未找到

```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"
}
```

### QR Code 状态枚举值

| 枚举值            | 描述                           |
|-----------------|-------------------------------|
| `active`        | QR Code 活跃                   |
| `finished`      | QR Code 已付款                 |
| `written_off`   | QR Code 因收款方/合作伙伴申请停用 |
| `bank_written_off` | QR Code 被 QI 停用           |

---

# 查询出站 Pix 转账

URL: /zh-Hans/documentation/pix/pesquisar_por_transferencia_pix_de_saida

## Request

ENDPOINT /baas/pix/pix_transfer
MÉTODO GET

### 路径参数

| 字段                | 类型   | 描述                                                                                           | 字符数 |
|--------------------|--------|------------------------------------------------------------------------------------------------|--------|
| `end_to_end_id`    | string | 巴西中央银行中某笔交易或查询的唯一标识密钥。例如：E3240250220210615135810450327042            | 32     |
| `pix_transfer_key` | string | QI 系统中 Pix 转账的识别密钥（UUIDv4）                                                        | 36     |

:::info
必须发送 `end_to_end_id` 或 `pix_transfer_key`，两者中只需提供一个。
::: 

:::caution 注意
仅当请求方对交易出账账户拥有权限时，才允许查看该笔转账。否则将返回错误。
:::

## 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: 缺少必填参数

```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: 通过 end_to_end_id 未找到 Pix 转账

```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: 通过 pix_transfer_key 未找到 Pix 转账

```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: 用户无凭证

```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"
}
```

### PixTransfer Status 枚举值

| 枚举值                  | 描述         |
|------------------------|--------------|
| `sent`                 | 转账已发送   |
| `rejected`             | 转账已拒绝   |
| `pending_confirmation` | 转账待确认   |
| `pending_approval`     | 转账待审批   |
| `error`                | 转账出错     |

---

# 可携性完成

URL: /zh-Hans/documentation/pix/portabilidade/conclusao_de_portabilidade

:::danger 注意！
QI Tech 的 webhooks 不应以严格的方式映射。
额外字段可能会被添加到我们 API 返回的 webhook 载荷中。
:::

确认或拒绝可携性申请后，QI 将继续推进密钥可携性流程。用户应在几分钟内收到目标银行的可携性更新通知。

一旦可携性申请完成或取消，QI 将通过以下 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"
}
```

#### 枚举值 claim_request_status

| 枚举值                | 说明        |
|-----------------------|-------------|
| **concluded**         | 已完成      |
| **cancelled**         | 已取消      |
| **failed**            | 失败        |
| **pending_confirmation** | 待确认   |

---

# 按账户查询可携性

URL: /zh-Hans/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

| 字段           | 类型   | 描述                       | 字符数 |
|----------------|--------|----------------------------|--------|
| `account_key`  | string | QIConta 标识键。           | 36     |

### Query Params

| 字段           | 类型    | 描述                                                                              | 字符数                                         |
|----------------|---------|-----------------------------------------------------------------------------------|------------------------------------------------|
| `page_number`  | integer | 当前查询的页码。                                                                  | -                                              |
| `page_size`    | integer | 每页结果数量。                                                                    | -                                              |
| `claim_status` | string  | 可携性状态。若未发送，将列出所有未完成的可携性记录                                | **[枚举值](#enumeradores-pix_key_type)**       |

#### 枚举值 pix_key_type

| 枚举值                         | 说明           |
|--------------------------------|----------------|
| **pending**                    | 待处理         |
| **opened**                     | 已开启         |
| **pending_confirmation**       | 待确认         |
| **confirmed**                  | 已确认         |
| **cancelled**                  | 已取消         |
| **concluded**                  | 已完成         |
| **failed**                     | 失败           |
| **pending_donator_validation** | 待捐赠者验证   |
| **pending_claimer_validation** | 待申请者验证   |

## 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": {}
}
```

| HTTP 代码 | QI 代码<br/>`code` | 标题<br/>`title`              | 描述（英文）<br/>`Description`                                                    | 描述（葡萄牙语）<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\}. |

---

# 创建可携性申请

URL: /zh-Hans/documentation/pix/portabilidade/criando_um_pedido_de_portabilidade

:::caution **注意**
如果申请可携性的密钥类型是手机号或电子邮件，则需要进行双因素验证，令牌将发送到所申请的手机号或电子邮件。如果需要双因素验证，"claim_request_status"将为"pending_claimer_validation"。

令牌发送的说明见 2.5.3.5.2 双因素验证
:::

:::danger **注意!!**
创建可携性申请必须使用沙盒环境中的模拟 Pix 密钥。
[模拟 Pix 密钥](/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

| 字段           | 类型   | 描述                               | 字符数                                         |
|----------------|--------|------------------------------------|------------------------------------------------|
| `account_key`  | string | QIConta 标识键。                   | 36                                             |
| `pix_key`      | enum   | 申请可携性的密钥。                 | -                                              |
| `pix_key_type` | enum   | 可携性 Pix 密钥类型。              | **[枚举值](#enumeradores-pix_key_type)**       |

#### 枚举值 pix_key_type

| 枚举值           | 说明      |
|------------------|-----------|
| **random_key**   | 随机密钥  |
| **email**        | 电子邮件  |
| **phone_number** | 手机号    |
| **cpf**          | cpf       |
| **cnpj**         | cnpj      |

:::info Pix 密钥类型
"pix_key" 可以是 CPF、CNPJ、电子邮件、手机号或随机密钥（UUID），格式如下：

CPF：11 位整数。

CNPJ：14 位整数。

电子邮件：包含至少一个"@"的文本。

手机号：包含以下格式的文本："+55" + "手机区号" + "手机号（最少8位、
最多9位整数）"。例如："+5511987654321"。

随机密钥：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": {}
}
```

| HTTP 代码 | QI 代码<br/>`code` | 标题<br/>`title`                              | 描述（英文）<br/>`Description`                                                                                                   | 描述（葡萄牙语）<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.                                                     |

---

# 删除可携性申请

URL: /zh-Hans/documentation/pix/portabilidade/deletando_um_pedido_de_portabilidade

若可携性申请处于"pending_claimer_validation"状态，则可以删除该可携性申请。

### 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": {}
}
```

| HTTP 代码 | QI 代码<br/>`code` | 标题<br/>`title`                                          | 描述（英文）<br/>`Description`                                                               | 描述（葡萄牙语）<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. |

---

# 可携性

URL: /zh-Hans/documentation/pix/portabilidade/recebendo_pedido_de_portabilidade

:::danger 注意！
QI Tech 的 webhooks 不应以严格的方式映射。
额外字段可能会被添加到我们 API 返回的 webhook 载荷中。
:::

## 接收可携性申请

在另一家银行创建可携性申请后，QI 将通过以下 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"
}
```

#### 枚举值 claim_request_status

| 枚举值                | 说明        |
|-----------------------|-------------|
| concluded             | 已完成      |
| cancelled             | 已取消      |
| failed                | 失败        |
| pending_confirmation  | 待确认      |

---

# 重新发送双因素验证

URL: /zh-Hans/documentation/pix/portabilidade/reenviando_a_2fa

若可携性申请处于"pending_claimer_validation"状态，则可以重新发送双因素验证码。

### 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": {}
}
```

| HTTP 代码 | QI 代码<br/>`code` | 标题<br/>`title`                                          | 描述（英文）<br/>`Description`                                                               | 描述（葡萄牙语）<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. |

---

# 可携性

URL: /zh-Hans/documentation/pix/portabilidade/respondendo_pedido_de_portabilidade

### Request

ENDPOINT /baas/pix/key_claim_request/ CLAIM_REQUEST_KEY/
CLAIM_ACTION
MÉTODO PATCH

#### Path params

| 字段                 | 类型   | 描述                                   |
|----------------------|--------|----------------------------------------|
| `claim_request_key`  | string | 可携性申请密钥。                       |
| `claim_action`       | enum   | **[枚举值](#enumeradores-claim_action)** |

#### 枚举值 claim_action

| 枚举值                         | 说明                     | 描述                                     |
|---|---|---|
| confirmed                      | 已确认                   | 使用此操作确认可携性申请                 |
| cancelled                      | 已取消                   | 使用此操作取消可携性申请                 |
| pending_donator_validation     | pending_donator_validation | 使用此操作接收双因素认证                |

:::caution **注意**
在取消"claim_request_type"为"ownership"的申请之前，需要执行"pending_donator_validation"操作以接收双因素认证并在载荷中提交。此类申请取消时唯一接受的"cancelation_reason"是"ownership"和"fraud"。
:::
:::caution **注意**
执行取消操作后，申请流程结束，不会再有 webhooks 接收。
:::

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

| 字段                  | 类型   | 描述                                                 | 字符数 |
|---|---|---|---|
| `confirmation_reason` | enum   | **[枚举值](#enumeradores-confirmation_reason)**。    | 14     |
| `cancellation_reason` | enum   | **[枚举值](#enumeradores-cancellation_reason)**。    | 14     |
| `verification_code`   | string | 在手机号或电子邮件中收到的令牌。                     | 6      |

#### 枚举值 confirmation_reason

| 枚举值           | 说明       |
|---|---|
| client_request   | 客户申请   |

#### 枚举值 cancellation_reason

| 枚举值           | 说明       |
|---|---|
| **client_request** | 客户申请 |
| **fraud**          | 欺诈     |

:::caution **注意**
取消"ownership"类型的可携性申请时，"cancelation_reason"必须始终为"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"
}
```

| HTTP 代码 | QI 代码<br/>`code` | 标题<br/>`title`                                      | 描述（英文）<br/>`Description`                                                                                                   | 描述（葡萄牙语）<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            | 确认理由不允许                                          | 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            | 取消理由不允许                                          | 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.                                                                                                    |

---

# 模拟可携性状态变更

URL: /zh-Hans/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

| 字段                 | 类型   | 描述                               |
|----------------------|--------|------------------------------------|
| `claim_request_key`  | uuidv4 | 可携性申请的唯一标识键。            |
| `claim_action`       | string | **[枚举值](#enumeradores-claim_action)** |

#### 枚举值 claim_action

| 枚举值        | 说明   | 描述                                                                                                                        |
|---------------|--------|-----------------------------------------------------------------------------------------------------------------------------|
| **failed**    | 失败   | 可携性申请失败                                                                                                              |
| **confirmed** | 已确认 | 可携性申请已确认，需要捐赠银行的批准才能完成，或需要拒绝才能取消                                                            |
| **cancelled** | 已取消 | 可携性申请已取消，因此要对该密钥提出申请，必须重新提交可携性申请                                                            |
| **concluded** | 已完成 | 可携性申请已完成                                                                                                            |

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": {}
}
```

| HTTP 代码 | QI 代码<br/>`code` | 标题<br/>`title`                              | 描述（英文）<br/>`Description`                                                          | 描述（葡萄牙语）<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  |

---

# 模拟可携性申请完成 Webhook

URL: /zh-Hans/documentation/pix/portabilidade/simular_webhook_de_conclusao

### Request

ENDPOINT /mock/pix_keys/key_claim_simulation/ CLAIM_REQUEST_KEY
/complete
MÉTODO PATCH

#### Path params

| 字段                 | 类型   | 描述                     |
|----------------------|--------|--------------------------|
| `claim_request_key`  | string | 可携性申请密钥。         |

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": {}
}
```

| HTTP 代码 | QI 代码<br/>`code` | 标题<br/>`title`                              | 描述（英文）<br/>`Description`                                                                                                                  | 描述（葡萄牙语）<br/>`translation`                    |
|-----------|----------------------|-----------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------|
| 404       | PIX000034            | 可携性申请未找到                               | 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 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 sobre claim request não permitida para reivindicador. Somente o doador pode executar esta ação                                             | Ação não permitida para requerente.                  |

---

# 模拟接收可携性申请 Webhook

URL: /zh-Hans/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

| 字段           | 类型 | 描述                                         | 字符数                                         |
|----------------|------|----------------------------------------------|------------------------------------------------|
| `pix_key`      | enum | 用于模拟接收可携性申请的密钥。               | -                                              |
| `pix_key_type` | enum | 可携性 Pix 密钥类型。                        | **[枚举值](#enumeradores-pix_key_type)**       |

#### 枚举值 pix_key_type

| 枚举值           | 说明      |
|------------------|-----------|
| **random_key**   | 随机密钥  |
| **email**        | 电子邮件  |
| **phone_number** | 手机号    |
| **cpf**          | cpf       |
| **cnpj**         | cnpj      |

:::info Pix 密钥类型
载荷中发送的 Pix 密钥必须在沙盒环境中处于激活状态，并且属于您创建的账户。
:::

### 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": {}
}
```

| HTTP 代码 | QI 代码<br/>`code` | 标题<br/>`title`           | 描述（英文）<br/>`Description`                                          | 描述（葡萄牙语）<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    |

---

# 双因素验证

URL: /zh-Hans/documentation/pix/portabilidade/validacao_de_dois_fatores

:::info 沙盒环境中的令牌
为方便在沙盒环境中进行测试，令牌值将始终为 `329329`。

此行为仅适用于沙盒环境。
:::

### Request

ENDPOINT /baas/pix/key_claim_request/ CLAIM_REQUEST_KEY /twofa_validation
MÉTODO PATCH

#### Path params

| 字段                 | 类型   | 描述                     |
|----------------------|--------|--------------------------|
| `claim_request_key`  | string | 可携性申请密钥。         |

Request Body

```json
{
  "verification_code": "432371"
}
```

#### Body Params

| 字段                  | 类型   | 描述                           | 字符数 |
|---------------------|--------|---------------------------------|--------|
| `verification_code` | string | 在手机号或电子邮件中收到的令牌。 | 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": {}
}
```

| HTTP 代码 | QI 代码<br/>`code` | 标题<br/>`title`                                   | 描述（英文）<br/>`Description`                                              | 描述（葡萄牙语）<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.    |

---

# 场景模拟

URL: /zh-Hans/documentation/pix/simulacao

逐步模拟外部代理人所执行操作的生效过程。这些模拟包括：PIX 入账、退款以及 PIX 密钥迁移。

## 1 - PIX 入账模拟

### Request

ENDPOINT /mock/pix_transfer/incoming_pix_transfer
MÉTODO POST

Request Body

```json
{
  "target_account_key": "\<目标账户唯一密钥\>",
  "amount": "\<交易金额\>"
}
```

### Body 参数

| 字段                | 类型   | 描述             | 最大字符数 | 示例                                   | 备注                   |
|--------------------|--------|------------------|------------|----------------------------------------|------------------------|
| `target_account_key` | string | 目标账户唯一密钥 | 36         | "41112f46-0034-4007-85687-5e592173db2" |                        |
| `amount`           | number | 交易金额         | 6          | 1000                                   | 最大值 100,000         |

## Response

STATUS 201

Response Body

```json
{
  "end_to_end_id": "E60701190202601291553Zrxq8RRUwS1"
}
```

## 2 - 模拟 PIX 入账分析结果

若要模拟 PIX 入账进入人工审核的场景，需要模拟金额超过 R$ 2,000,000.00（两百万）的入账。此情况下，PIX 将处于人工审核状态，客户将收到相应的 Webhook。

:::caution 注意
两百万的规则仅适用于沙盒环境，**不反映生产环境的情况**。
:::

收到人工审核 Webhook 后，需使用以下模拟路由对资金入账进行批准或拒绝。客户还将收到包含分析结果的相应 Webhook。

### 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 参数

| 字段               | 类型   | 描述                                                             | 最大字符数 | 示例                             | 备注 |
|------------------|--------|------------------------------------------------------------------|------------|----------------------------------|------|
| `end_to_end_id`  | string | PIX 交易唯一密钥                                                  | 32         | "E60701190202601291537yo1ZxpvVzJn" |      |
| `analysis_status` | enum  | [Analysis Status 枚举值](#enumerador-analysis-status)           |            | "manually_reproved"              |      |

### Analysis Status 枚举值

| 枚举值                | 描述         |
|-----------------------|--------------|
| **manually_approved** | 人工批准     |
| **manually_reproved** | 人工拒绝     |

## 3 - 模拟 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 参数

| 字段           | 类型   | 描述               | 最大字符数 | 示例                                   | 备注 |
|--------------|--------|--------------------|------------|----------------------------------------|------|
| `qr_code_key` | string | QR Code 唯一识别密钥 | 36         | "41112f46-0034-4007-85687-5e592173db2" |      |

## 4 - 模拟 PIX 退款

### Request

ENDPOINT /mock/pix_transfer/chargeback
MÉTODO POST

Request Body

```json
{
  "end_to_end_id": "\<交易唯一密钥\>",
  "amount": "\<交易金额\>"
}
```

### Body 参数

| 字段             | 类型   | 描述              | 最大字符数 | 示例                              | 备注           |
|----------------|--------|-------------------|------------|-----------------------------------|----------------|
| `amount`       | number | 交易金额          | 6          | 1000                              | 最大值 100,000 |
| `end_to_end_id` | string | PIX 交易唯一密钥  | 32         | "E3240250220210723142712312751267" |                |

## 5 - 模拟 PIX 密钥迁移 IN Webhook

### Request

ENDPOINT /mock/pix_keys/key_claim_request/webhook
MÉTODO POST

Request Body

```json
{
  "claim_request_key": "\<申请方唯一密钥\>",
  "claim_request_status": "\<状态枚举值\>"
}
```

### Body 参数

| 字段                    | 类型   | 描述                                                                 | 最大字符数 | 示例                                   | 备注 |
|-----------------------|--------|----------------------------------------------------------------------|------------|----------------------------------------|------|
| `claim_request_key`   | string | 申请方唯一密钥                                                       | 36         | "ced00dc6-000a-0bd4-a111-85710a46ec05" |      |
| `claim_request_status` | enum  | [Claim Request Status 枚举值](#enumerador-claim-request-status)     |            | "concluded"                            |      |

### Claim Request Status 枚举值

| 枚举值                   | 描述       |
|--------------------------|------------|
| **concluded**            | 已完成     |
| **cancelled**            | 已取消     |
| **failed**               | 失败       |
| **pending_confirmation** | 待确认     |

## 6 - 模拟待确认状态的交易

当巴西中央银行的 Pix 交易响应出现延迟时，交易可能进入 **pending_confirmation** 状态。若要模拟此场景，请使用 Pix 密钥 `"target_pix_key": "0476f803-0129-430a-a66c-d2f0d7cf4aaa"` 发起交易，或对于 **manual** 类型的 Pix 转账，使用 `"owner_document_number": "35586870002"` 作为目标账户持有人的文件号。

若要更新交易状态，请使用 **sent** 作为 `transaction_status` 批准交易，或使用 **rejected** 拒绝交易。

### 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 参数

| 字段                        | 类型   | 描述                                                                   | 最大字符数 |
|-----------------------------|--------|------------------------------------------------------------------------|------------|
| `end_to_end_id`*            | string | PIX 交易唯一密钥                                                        | 36         |
| `transaction_status`*       | enum   | [Transaction Status 枚举值](#enumerador-transaction-status)            |            |
| `status_reason_information` | object | [Status Reason Information 对象](#objeto-status-reason-information)    |            |
| `error_code`                | string | 错误代码                                                               |            |

### Transaction Status 枚举值

| 枚举值       | 描述   |
|------------|--------|
| **sent**   | 已完成 |
| **rejected** | 已拒绝 |

### Status Reason Information 对象

| 字段                      | 类型   | 描述               | 最大字符数 |
|--------------------------|--------|--------------------|------------|
| `error_description`      | string | 英文错误描述        | 100        |
| `error_translation`      | string | 葡语错误描述        | 100        |
| `error_short_description` | string | 英文简短错误描述   | 100        |

## 7 - 模拟被拒绝的交易

当巴西中央银行或收款 PSP 预期拒绝 Pix 交易时，交易可能进入 **rejected** 状态。若要模拟此场景，请使用 Pix 密钥 `"target_pix_key": "b9380607-dac6-4e17-8ca7-eb761e3aa1dc"` 发起交易，或对于 **manual** 类型的 Pix 转账，使用 `"owner_document_number": "66972913039"` 或 `"owner_document_number": "50305556000164"` 作为目标账户持有人的文件号。

## 8 - 获取双因素认证发送的 Token

对于配置了双因素认证的集成商伙伴的个人和批量 Pix 交易，`token` 将发送给账户变动批准人。通过此端点可获取用于集成测试的 Token。

ENDPOINT /mock/2fa/transaction_request/ TRANSACTION_REQUEST_KEY
MÉTODO GET

## 路径参数

| 字段                       | 类型  | 描述                                                                                                                       | 字符数 |
|--------------------------|-------|--------------------------------------------------------------------------------------------------------------------------|--------|
| `transaction_request_key` | uuid4 | 交易唯一识别密钥。Pix 交易对应 `pix_transfer_key`，批量 Pix 交易对应 `pix_transfer_batch_key`                           | 36     |

Response Body

```json
{
  "token": "1a2b3c"
}
```

---

# 申请修改 Pix 限额

URL: /zh-Hans/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

| 字段                        | 类型  | 描述                                                       |
|-----------------------------|-------|------------------------------------------------------------|
| `daily_amount_limit`        | float | 不同账户持有人日间 Pix 转账限额                             |
| `nightly_amount_limit`      | float | 不同账户持有人夜间 Pix 转账限额                             |
| `self_daily_amount_limit`   | float | 相同账户持有人日间 Pix 转账限额                             |
| `self_nightly_amount_limit` | float | 相同账户持有人夜间 Pix 转账限额                             |

:::info 日间时段
**日间**时段计算的是 **06:00** 至 **20:00** 之间的转账。
:::

:::danger 注意
提高 Pix 限额的申请需要 **48 小时** 的 SLA 来审批。

降低 Pix 限额的申请将立即审批并执行。

如果达到 **48 小时** 的 SLA 仍未获批准，该申请将以原因 `Tempo de avaliação expirado.`（评估时间已过期）自动拒绝，并向申请人发送拒绝 webhook（参见 [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: 发送的数值无效

```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: 用户没有凭据

```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 Webhook 触发事件
当限额申请执行时，webhook 将发送给账户申请人
:::

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"
   }
}
```

### 枚举值 limit_type
| 枚举值          | 描述                                               |
|-----------------|----------------------------------------------------|
| `daily`         | 不同账户持有人日间 Pix 转账限额                     |
| `nightly`       | 不同账户持有人夜间 Pix 转账限额                     |
| `self_daily`    | 相同账户持有人日间 Pix 转账限额                     |
| `self_nightly`  | 相同账户持有人夜间 Pix 转账限额                     |

---

# 申请 Pix 退款

URL: /zh-Hans/documentation/pix/solicitar_chargeback_pix

Pix 退款可在收款后 90 天内申请。

## Request

ENDPOINT /baas/pix_transfer
MÉTODO POST

:::info 说明
提交退款申请后，需要进行 [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: 退款被拒绝

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

| HTTP 代码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                    | 描述（英文）<br/>`description`                                         | 描述（葡萄牙语）<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: /zh-Hans/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

| 字段                                   | 类型   | 描述                                                                                                                                                 | 字符数                                                          |
|--------------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------|
| `pix_transfer_type` *                | string | Pix 有不同的发起类型："manual" 类型中用户需发送目标账户和来源账户字段；"key" 类型中用户需发送收款方 Pix 密钥（目标账户）和来源账户数据。 | 10                                                             |
| `source_account` *                   | Object | 来源账户。                                                                                                                                           | **[source_account 对象](#objeto-source_account)**              |
| `target_account`                     | Object | 目标账户 - 仅在 "manual" 类型交易中发送。                                                                                                           | **[target_account 对象](#objeto-target_account)**              |
| `transaction_amount` *               | string | 转账金额。                                                                                                                                           | 10                                                             |
| `receiver_conciliation_id`           | string | 收款方对账标识。                                                                                                                                     | 10                                                             |
| `is_chargeback`                      | string | Pix 退款交易标识标志（布尔值 True 或 False）。                                                                                                       | 10                                                             |
| `requester_document_identification` * | string | 申请转账的用户 CPF。                                                                                                                                | 10                                                             |
| `pix_transfer_key`                   | string | Pix 交易幂等密钥 - 仅在转账类型为 "key" 时发送。                                                                                                    | 10                                                             |
| `chargeback_amount`                  | string | 退款金额 - 仅在退款情况下发送，并排除 "transaction_amount" 字段的必填要求。                                                                         | 10                                                             |
| `chargeback_other_reason`            | string | 退款原因（仅在退款情况下发送）。                                                                                                                    | 10                                                             |
| `chargeback_message`                 | string | 退款时用户输入的消息字段（仅在退款情况下发送）。                                                                                                    | 10                                                             |
 
### source_account 对象

| 字段                       | 类型   | 描述                        | 字符数 |
|--------------------------|--------|-----------------------------|--------|
| `account_branch` *       | string | 机构号。                    | 0      |
| `branch_digit`           | string | 机构检验位。                | 0      |
| `account_digit` *        | string | 账户检验位。                | 0      |
| `account_number` *       | string | 账户号。                    | 0      |
| `owner_document_number` * | string | 账户持有人 CPF 或 CNPJ（仅数字）。 | 0 |

### target_account 对象

| 字段                       | 类型   | 描述                                                             | 字符数 |
|--------------------------|--------|------------------------------------------------------------------|--------|
| `account_branch` *       | string | 机构号。                                                         | 10     |
| `account_digit` *        | string | 账户检验位                                                       | 10     |
| `account_number` *       | string | 账户号。                                                         | 10     |
| `owner_document_number` * | string | 账户持有人 CPF 或 CNPJ（仅数字）。                              | 10     |
| `owner_name` *           | string | 账户持有人姓名。                                                 | 10     |
| `account_type` *         | string | 账户持有人 CPF 或 CNPJ（仅数字）。                              | 10     |
| `ispb`                   | string | 八位数代码，用于在巴西中央银行储备转账系统中识别银行。          | 10     |

## Response

STATUS 200

Response Body: 手动转账

```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\"}"
}

```

---

# 动态 Pix QR Code 过期 Webhook

URL: /zh-Hans/documentation/pix/webhook_por_qr_code_expirado

:::danger 注意！
QI Tech 的 Webhook 不应被严格映射。
返回的 Webhook 载荷中可能会包含额外字段。
:::

:::info Webhook 重发
您可以按照文档中的详细说明查询和重发 Webhook：[Webhook 重发](/documentation/notificacoes/reenvio_de_notificacoes)。
:::

## Webhook

:::info 触发 Webhook 的事件
Webhook 将发送给与动态 QR Code 关联的 Pix 密钥持有人。此事件在 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"
   }
}
```

---

# 配置 Webhooks

URL: /zh-Hans/documentation/primeiros_passos/configurando_webhooks

:::info 另请参阅
- [Webhook 验证](/documentation/primeiros_passos/teste_de_autenticacao/webhook_v2)
:::

要配置通知接收 URL，请登录 QI Tech 平台。点击左侧菜单中的"**我的个人资料**"，进入"集成"选项卡。然后，在页面的"**Webhook 配置**"部分输入您的 URL，并点击"**保存**"按钮。若需要为发送的通知配置 headers，可按下图所示使用以下字段。

:::danger 注意！
QI Tech 的 Webhook 不应进行严格映射。
我们 API 返回的 Webhook 载荷中可能会新增额外字段。
:::

:::info 重新发送 Webhook
您可以按照文档中的详细说明查询和重新发送 Webhook：[重新发送 Webhook](/documentation/notificacoes/reenvio_de_notificacoes)。
:::

:::info 信息
我们 Webhook 的响应超时时间为 10 秒。
:::

---

# 配置集成 IP 白名单

URL: /zh-Hans/documentation/primeiros_passos/configurar_ip_de_integracao

:::info 另请参阅
- [配置 Webhooks](/documentation/primeiros_passos/configurando_webhooks)
- [Webhook 验证](/documentation/primeiros_passos/teste_de_autenticacao/webhook_v2)
:::

QI Tech 允许您将对集成的调用限制为一组预先授权的**公网 IP 地址**（或 CIDR 范围）。该过滤在签名校验之前生效：来自不在您活跃名单中的 IP 的请求将以 `403 Forbidden`（`GDF000029`）拒绝。

## 如何配置

登录 QI Tech 平台，点击左侧菜单中的"**我的个人资料**"，进入"**集成**"选项卡。滚动到"**Whitelist de IPs da API**"区域，在"**IP / CIDR**"字段中逐个添加 IP，每次添加后点击"**ADICIONAR IP**"按钮。

支持的格式：

- 公网 IPv4 地址（例如：`189.10.20.30`）
- 前缀为 `/24` 或更大的 IPv4 CIDR 范围（例如：`200.100.50.0/24`）
- 公网 IPv6 地址
- 前缀为 `/48` 或更大的 IPv6 CIDR 范围

私有/保留地址范围（`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`）不被接受。

## 激活等待期（48 小时）

:::warning 注意！
出于安全考虑，**通过控制面板新增的 IP 都会先停留在 `Pendente`（待激活）状态 48 小时**，之后才会自动激活。在此期间该 IP 已被记录但**不会授权任何请求** —— 您当前活跃白名单中的 IP 继续有效。

IP 创建时您会收到一封确认邮件，IP 进入 `Ativo`（已激活）状态时会再收到一封通知邮件。
:::

48 小时后，IP 会自动转为 `Ativo`，开始被授权调用 API。

## 紧急激活

:::info 立即放行
如果您需要在 48 小时之前就放行某个 IP（例如：未计划的服务器迁移、生产事件），请通过官方渠道联系我们的支持团队，请求手动激活并提供以下信息：

- 已注册的 `IP / CIDR`
- 您集成的 `client_integration_key`
- 紧急原因

我们的运营团队会进行手动激活，IP 将立即生效。
:::

## 常见错误

| 错误码 | 原因 | 解决方法 |
|---|---|---|
| `403` / `GDF000029` | 请求来自不在白名单 `Ativo` 状态的 IP | 在"集成"页面查看哪些 IP 是激活状态。如果刚注册的 IP 仍为 `Pendente`，请等待 48 小时或申请手动激活。 |
| IP 注册被拒绝 | IP/CIDR 无效、私有地址、或范围过大（IPv4 前缀小于 `/24`、IPv6 前缀小于 `/48`） | 仅使用公网地址，并遵守最小前缀大小要求。 |

---

# 简介

URL: /zh-Hans/documentation/primeiros_passos/inicio

我们是巴西首家创建专属 Bank-as-a-Service（BaaS）模式的金融机构。我们的目标是帮助所有 Fintech/信贷管理公司或企业，以其所希望的方式，快速、灵活且安全地获取金融服务。了解更多请访问 https://qitech.com.br。

本文档旨在描述我们 API 的各个端点。

注：如在任何流程阶段存有疑问，请发送邮件至 [api@qitech.com.br](mailto:api@qitech.com.br) 详细说明您的问题/疑问，我们将为您提供帮助。

## 入门步骤

在开始通过 API 发送请求以使用 QI Tech 服务之前，代表发起公司的操作员代表必须在 **沙盒环境** 中完成以下步骤。

## 创建访问权限

1. 向邮箱 api@qitech.com.br 发送创建访问权限的请求，并提供以下信息：
   1. 公司 CNPJ
   2. 主用户全名
   3. 主用户 CPF
   4. 主用户邮箱
   5. 主用户手机号码
2. QI Tech 团队创建访问权限后，主用户将收到一封包含沙盒平台访问链接和临时密码的电子邮件。
3. 首次访问平台时，主用户必须重置访问密码。

## 开始集成之旅

可根据合作伙伴需求使用多种端点组合，但前三个步骤是无论使用何种服务都通用的：

步骤 1：通过 QI Tech 门户进行 Token 验证
步骤 2：[进行密钥交换并生成集成凭证](/documentation/primeiros_passos/troca_de_chaves)
步骤 3：[进行身份验证测试](/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2)
步骤 4：[配置 Webhook 接收 URL](/documentation/primeiros_passos/configurando_webhooks)

## 重要信息

要在生产环境中使用我们的 API，需要联系 [comercial@qitech.com.br](mailto:comercial@qitech.com.br) 进行商务洽谈和集成配置。

---

# 测试端点

URL: /zh-Hans/documentation/primeiros_passos/teste_de_autenticacao/endpoints_de_teste

以下是可用于测试身份验证的端点示例：

ENDPOINT /test/{`API_KEY`}
方法 GET

ENDPOINT /test/{`API_KEY`}
方法 POST

## 代码示例

**cURL**

```bash
curl --location --request GET 'https://api-auth.sandbox.qitech.app/test/{{API_KEY}}' \
--header 'API-CLIENT-KEY: {{API_KEY}}' \
--header 'Authorization: {{JWT_TOKEN}}'
```

**Python**

```python
import requests

url = "https://api-auth.sandbox.qitech.app/test/{{API_KEY}}"
headers = {
    "API-CLIENT-KEY": "{{API_KEY}}",
    "Authorization": "{{JWT_TOKEN}}"
}
response = requests.get(url, headers=headers)
```

**JavaScript**

```javascript
const response = await fetch('https://api-auth.sandbox.qitech.app/test/{{API_KEY}}', {
  method: 'GET',
  headers: {
    'API-CLIENT-KEY': '{{API_KEY}}',
    'Authorization': '{{JWT_TOKEN}}'
  }
});
```

**Java**

```java
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
  .url("https://api-auth.sandbox.qitech.app/test/{{API_KEY}}")
  .addHeader("API-CLIENT-KEY", "{{API_KEY}}")
  .addHeader("Authorization", "{{JWT_TOKEN}}")
  .build();
Response response = client.newCall(request).execute();
```

---

# 常见错误

URL: /zh-Hans/documentation/primeiros_passos/teste_de_autenticacao/possiveis_erros

以下是身份验证过程中可能遇到的常见错误：

## JWT 令牌无效

当 JWT 令牌格式不正确或签名无效时返回。

```json
{
  "title": "Unauthorized",
  "description": "Invalid JWT token",
  "code": "AUTH000001"
}
```

## API_KEY 缺失或不正确

当请求头中未包含 `API-CLIENT-KEY` 或其值不正确时返回。

```json
{
  "title": "Unauthorized",
  "description": "Missing or invalid API KEY",
  "code": "AUTH000002"
}
```

## 未授权的端点或方法

当请求的端点或 HTTP 方法未被授权时返回。

```json
{
  "title": "Unauthorized",
  "description": "Unauthorized endpoint or method",
  "code": "AUTH000003"
}
```

---

# 完整身份验证示例

URL: /zh-Hans/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_completo

以下是完整的多语言代码示例，演示如何对 API 请求进行签名和加密，包括 payload 的 MD5 哈希计算和 JWT 编码。

**Python**

```python
import hashlib
import json
import jwt
import datetime
import requests

# 定义变量
API_KEY = "your_api_key"
PRIVATE_KEY = open("jwtECDSASHA512.key").read()

# 请求 payload
body = {"test": "data"}
body_string = json.dumps(body)

# 计算 payload 的 MD5 哈希值
md5_body = hashlib.md5(body_string.encode()).hexdigest()

# 获取当前时间戳（UTC）
now = datetime.datetime.utcnow()
timestamp = now.strftime("%Y-%m-%dT%H:%M:%S.000Z")

# 定义 JWT 头部
headers = {
    "alg": "ES512",
    "typ": "JWT"
}

# 构建 JWT payload
payload = {
    "sub": API_KEY,
    "signature": f"POST\n/test/{API_KEY}\n{md5_body}\napplication/json\n{timestamp}"
}

# 编码 JWT
token = jwt.encode(payload, PRIVATE_KEY, algorithm="ES512", headers=headers)

# 发送请求
response = requests.post(
    f"https://api-auth.sandbox.qitech.app/test/{API_KEY}",
    headers={
        "API-CLIENT-KEY": API_KEY,
        "Authorization": token,
        "Content-Type": "application/json"
    },
    json=body
)
```

**PHP**

```php
<?php
use Firebase\JWT\JWT;

$apiKey = "your_api_key";
$privateKey = file_get_contents("jwtECDSASHA512.key");

$body = json_encode(["test" => "data"]);
$md5Body = md5($body);
$timestamp = gmdate("Y-m-d\TH:i:s.000\Z");

$payload = [
    "sub" => $apiKey,
    "signature" => "POST\n/test/{$apiKey}\n{$md5Body}\napplication/json\n{$timestamp}"
];

$token = JWT::encode($payload, $privateKey, "ES512");
```

**Node.js**

```javascript
const jwt = require('jsonwebtoken');
const crypto = require('crypto');
const fs = require('fs');

const apiKey = 'your_api_key';
const privateKey = fs.readFileSync('jwtECDSASHA512.key');

const body = JSON.stringify({ test: 'data' });
const md5Body = crypto.createHash('md5').update(body).digest('hex');
const timestamp = new Date().toISOString();

const payload = {
  sub: apiKey,
  signature: `POST\n/test/${apiKey}\n${md5Body}\napplication/json\n${timestamp}`
};

const token = jwt.sign(payload, privateKey, { algorithm: 'ES512' });
```

---

# 身份验证测试

URL: /zh-Hans/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2

:::info 另请参阅
- [完整身份验证示例](./teste_de_autenticacao_completo)
- [测试端点](./endpoints_de_teste)
- [可能遇到的错误](./possiveis_erros)
:::

## 1. 简介与初始配置

### 概述
本文档详细说明了用于安全 API 请求身份验证的请求头签名和加密过程。该过程确保请求的可信性和安全性，防止未授权访问并保障数据完整性。

### 导入库
以下是身份验证过程中所需库的导入。

**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;
```

### 定义变量

我们将使用 _base_url_、_endpoint_、_method_ 和 _request_body_ 变量。在本示例中，我们将对 "/test" 端点执行 POST 请求。

**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. 签名数据准备

### 输入加密数据

本示例中的密钥仅供演示使用，请使用您自己的密钥。

**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-----"; 
```
  

### 格式化日期
提供的日期时间对象必须为 UTC 格式，并遵循国际标准 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");
```
  

### 定义 JWT 请求头
定义 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
// 不需要
```
  

**C#**

```c#
var jwt_header = new Dictionary<string, object>
{ 
  { "typ", "JWT" },
  { "alg", "ES512" }
};
```
  

### 为 JSON 请求头签名构建 MD5 哈希值

使用载荷为请求头（header）签名构建 MD5 哈希值

**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 注意！

GET 和 DELETE 方法请求的 md5 哈希值必须使用空载荷生成
:::

### 为文件请求头签名构建 MD5 哈希值

使用文件为请求头（header）签名构建 MD5 哈希值

**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);
    }
}
```

### 定义 JWT 正文
以下是请求头签名所需的信息

**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#
// 调整：删除私钥中间的空格和换行符
client_private_key = client_private_key.Replace("-----BEGIN EC PRIVATE KEY-----", "")
                                       .Replace("-----END EC PRIVATE KEY-----", "")
                                       .Replace("\n", "")
                                       .Replace("\r", "");
// 将私钥转换为 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 }
    };
```
  

### 对请求头进行加密

**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);
```
  

### 构建已签名的请求头

**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);
```
  

### 构建请求 URL

**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. 发送请求

**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;
```

---

# Webhook 验证

URL: /zh-Hans/documentation/primeiros_passos/teste_de_autenticacao/webhook_v2

本文档说明如何验证接收到的 QI Tech webhook 请求的真实性和完整性。

## Webhook 请求格式

### 请求头

| 字段 | 描述 |
|---|---|
| `Authorization` | 包含 JWT 令牌的签名头部 |

### 请求体

标准 JSON 格式的 webhook 数据。

## 验证步骤

### 1. 导入所需库

根据您使用的编程语言，导入处理 JWT 和加密哈希的库。

### 2. 定义 QI Tech 公钥

使用 QI Tech 提供的公钥对请求进行验证。

### 3. 解密 Authorization 头部

`AUTHORIZATION` 头部包含一个 JWT 令牌，需要使用 QI Tech 公钥进行解密和验证。

### 4. 执行验证

解密 JWT 后，请验证以下内容：

- **方法（Method）**：确认请求使用的 HTTP 方法正确
- **URI**：确认请求的 URI 与预期一致
- **Payload MD5**：对接收到的 body 计算 MD5 哈希值，并与 JWT 中的值进行对比
- **时间戳（Timestamp）**：确认时间戳在合理范围内，以防止重放攻击

**Python**

```python
import hashlib
import json
import jwt

QI_TECH_PUBLIC_KEY = """-----BEGIN PUBLIC KEY-----
<YOUR_QI_TECH_PUBLIC_KEY>
-----END PUBLIC KEY-----"""

def validate_webhook(authorization_header, request_body, method, uri):
    # 解密 JWT
    decoded = jwt.decode(
        authorization_header,
        QI_TECH_PUBLIC_KEY,
        algorithms=["ES512"]
    )
    
    # 计算 payload 的 MD5 哈希值
    body_string = json.dumps(request_body)
    md5_hash = hashlib.md5(body_string.encode()).hexdigest()
    
    # 解析签名字符串
    signature = decoded["signature"].split("\n")
    
    # 验证各字段
    assert signature[0] == method
    assert signature[1] == uri
    assert signature[2] == md5_hash
    
    return True
```

---

# 密钥交换

URL: /zh-Hans/documentation/primeiros_passos/troca_de_chaves

## 生成密钥对（公钥和私钥）

**Unix**

在 **Unix** 计算机上，通过终端或命令行生成私钥：

```bash
$ ssh-keygen -t ecdsa -b 521 -m PEM -f jwtECDSASHA512.key
```

然后从该私钥生成公钥。

```bash
$ openssl ec -in jwtECDSASHA512.key -pubout -outform PEM -out jwtECDSASHA512.key.pub
```

**Mac OS**

在 **Mac OS** 计算机上，通过终端生成私钥：

```bash
openssl ecparam -name secp521r1 -genkey -noout -out ec512-private.pem
```

然后从该私钥生成公钥。

```bash
openssl ec -in ec512-private.pem -pubout -out ec512-public.pem
```

**Windows**

在 **Windows** 计算机上生成密钥对（私钥和公钥），需要在 PowerShell 或 GitBash 中使用 `ssh-keygen` 和 `openssl` 工具。

执行以下命令创建私钥文件（`jwtECDSASHA512.key`）。

```bash
ssh-keygen -t ecdsa -b 521 -m PEM -f jwtECDSASHA512.key
```

然后从该私钥生成公钥（`jwtECDSASHA512.key.pub`）。

```bash
openssl ec -in jwtECDSASHA512.key -pubout -outform PEM -out jwtECDSASHA512.key.pub
```

在记事本中查看密钥：

```bash
notepad jwtECDSASHA512.key.pub
```

在终端中查看密钥：

```bash
cat jwtECDSASHA512.key.pub
```

若您在私钥中添加了加密密码并希望查看它，需使用以下命令和密码进行解密：

```bash
openssl ec -in jwtECDSASHA512.key -out chave_descriptografada.pem
```

---

# 查询操作的当前价值

URL: /zh-Hans/documentation/refinanciamento/consulta_de_valor_presente_de_uma_operacao

要了解再融资操作中将使用的当前价值，可以使用债务查询端点，并指定以下 4 个关键查询参数。

## Request

ENDPOINT /debt
MÉTODO GET

## Query Params
| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---| ---|
| `key` * | string | 创建信贷操作时返回的债务密钥。 | - |
| `eval_present_value` * | string | 表示应计算并显示每期的当前价值。 | - |
| `calculate_delay` * | string | 表示如果分期付款已到期，应将逾期利息和罚款计入当前价值。 | - |
| `calculate_spread` * | boolean | 表示是否将操作的利差值添加到当前价值中（再融资操作应为 false）。 | - |

## Response

STATUS 200

Response Body

```json
{
	"data": {
		"additional_iof": 11.547136,
		"balance_due": 3150.62,
		"base_iof": 27.17569413,
		"cet": 2.91,
		"installments": [
			{
				"due_date": "2022-11-18",
				"due_principal": 3038.72,
				"installment_number": 1,
				"total_amount": 565.33,
				"present_amount": 1000.11
			}
		]
	},
	"operation_key": "438ceaa3-2906-4ee3-85f9-0dcacd5f2581",
	"status": "opened",
	"webhook_type": "signed_debt"
}
```

:::caution 注意！

在分期付款数组中，将返回每期的计算当前价值（**"present_amount"**），其总和将是再融资申请时合同所考虑的当前价值。
:::

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: /zh-Hans/documentation/refinanciamento/introducao

再融资是指生成一份新的信贷合同以偿还之前的合同。因此，其流程与简单债务发行方式相同，但在提供操作金额时，将扣留之前合同当前价值的总和，若存在超出部分，则将其释放到借款人账户。

---

# 模拟再融资

URL: /zh-Hans/documentation/refinanciamento/simulando_refinanciamento

## 针对不存在的再融资操作的 Request

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 注意！

**"refinanced_credit_operations"** 中的 **"disbursement_date"** 和 **"monthly_interest_rate"** 字段，仅在需要为多种放款选项计算再融资操作结清金额时为必填项。
:::

## 针对已存在的再融资操作的 Request

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 注意！

再融资模拟使用的载荷与简单债务模拟相同，但需在 **"refinanced_credit_operations"** 中附加将被结清的操作列表及其结清计算数据。
:::

## 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
                }
            ],
            "final_disbursement_amount": -17733.89,
            "installments": [],
            "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
                }
            ],
            "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\"}"
}
```

## 定义

### Request Body
| 字段                  | 类型    | 描述                                                                                                     | 
|-----------------------|---------|----------------------------------------------------------------------------------------------------------|
| **complex_operation** | boolean | _true_ - 表示可在同一请求中执行多个模拟                                                                   |
| **operation_batch**   | object  | 模拟请求列表 - **[Operation Batch 列表对象](#objeto-da-lista-operation_batch)** |

### Operation Batch 列表对象
| 字段          | 类型   | 描述                                                                      | 
|---------------|--------|---------------------------------------------------------------------------|
| **borrower**  | object | **[Borrower 对象](#objeto-borrower)** - 信贷操作的债务人                  |
| **financial** | object | **[Financial 对象](#objeto-financial)** - 操作财务数据                    |

### Borrower 对象
| 字段            | 类型   | 描述                                                                                           |
|-----------------|--------|------------------------------------------------------------------------------------------------|
| **person_type** | object | **[Person Type 枚举值](#enumerador-person_type)** - 债务人的法律性质                           |

### Financial 对象
| 字段                      | 类型   | 描述                                                                                                      |
|---------------------------|--------|-----------------------------------------------------------------------------------------------------------|
| **amout**                 | float  | 信贷操作的发行/名义价值                                                                                   |
| **interest_type**         | object | **[Interest Type 枚举值](#enumerador-interest-type)** - 摊销方法和利息计算方式                            |
| **credit_operation_type** | object | **[Credit Operation Type 枚举值](#enumerador-credit-operation-type)** - 信贷合同类型                      |
| **annual_interest_rate**  | float  | 以十进制表示的年预固定利率                                                                                |
| **disbursement_date**     | date   | 操作放款日期                                                                                              |
| **interest_grace_period** | int    | 利息宽限期（以月为单位）                                                                                  |
| **principal_grace_period**| int    | 本金宽限期                                                                                                |
| **number_of_installments**| int    | 信贷操作分期数                                                                                            |
| **fine_configuration**    | object | **[fine_configuration 对象](#objeto-fine-configuration)** - 逾期利息和罚款配置                            |
| **refinanced_credit_operations** | array of objects | 包含将被再融资操作信息的对象列表                                                             |

### Refinanced Credit Operations 对象

#### 当再融资操作不存在时的对象
| 字段                       | 类型   | 描述                                                                  |
|----------------------------|--------|-----------------------------------------------------------------------|
| **due_balance**            | number | 结清再融资操作所需的金额。                                            |
| **original_deadline**      | int    | 再融资信贷操作的总期限（天数）。                                      |
| **monthly_interest_rate**  | float  | 再融资操作的月利率。                                                  |
| **disbursement_date**      | date   | 再融资操作的放款日期。                                                |

#### 当再融资操作已存在时的对象
| 字段                       | 类型           | 描述                                                    |
|----------------------------|----------------|---------------------------------------------------------|
| **operation_key**          | string uuid    | 将被再融资的操作密钥。                                  |

### Fine Configuration 对象
| 字段                   | 类型  | 描述                                                                             | 
|------------------------|-------|----------------------------------------------------------------------------------|
| **contract_fine_rate** | float | 以十进制表示的逾期罚款百分比                                                     |
| **interest_base**      | enum  | **[Interest Base 枚举值](#enumerador-interest-base)** - 利息计算基准             |
| **monthly_rate**       | float | 以十进制表示的月逾期利率                                                         |

---

# 创建再融资

URL: /zh-Hans/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 注意！

再融资发行使用的载荷与简单债务发行相同，但需在 **"refinanced_credit_operations"** 中附加将被结清的操作列表。
:::

### Body Params

| 字段                              | 类型             | 描述                                                                                                                    | 最大字符数 | 
|-----------------------------------|------------------|-------------------------------------------------------------------------------------------------------------------------|------------|
| **borrower** *                    | object           | **[Borrower 对象](#objeto-borrower)** - 信贷操作的债务人。                                                               | -          | 
| **disbursement_bank_account** *   | object           | **[Disbursement Bank Account 对象](#objeto-disbursement_bank_accounts)** - 操作放款的银行账户数据。                       | -          |
| **financial** *                   | object           | **[Financial 对象](#objeto-financial)** - 操作放款的银行账户数据。自然人 borrower PF 必须始终填写 "natural"。             | -          |
| **purchaser_document_number** *   | string           | 信贷操作受让方（买方）的 CNPJ。                                                                                          | -          |
| **refinanced_credit_operations** *| array of objects | **[Refinanced Credit Operations 对象](#objeto-refinanced_credit_operations)** 列表，包含被再融资的操作。                   | -          |

## 定义

### Request Body 对象
| 字段                              | 类型             | 描述                                                                                                                    | 最大字符数 | 
|-----------------------------------|------------------|-------------------------------------------------------------------------------------------------------------------------|------------|
| **borrower** *                    | object           | **[Borrower 对象](#objeto-borrower)** - 信贷操作的债务人                                                                | -          | 
| **disbursement_bank_account** *   | object           | **[Disbursement Bank Account 对象](#objeto-disbursement_bank_accounts)** - 操作放款的银行账户数据                        | -          |
| **financial** *                   | object           | **[Financial 对象](#objeto-financial)** - 操作放款的银行账户数据                                                        | -          |
| **purchaser_document_number** *   | string           | 信贷操作受让方（买方）的 CNPJ                                                                                            | -          |

### Borrower 对象
| 字段                               | 类型    | 描述                                                                              | 最大字符数 | 
|------------------------------------|---------|-----------------------------------------------------------------------------------|------------|
| **name** *                         | string  | 债务人姓名                                                                        | 100        |
| **email**                          | string  | 债务人邮箱                                                                        | 254        |
| **phone**                          | object  | **[Phone 对象](#objeto-phone)** - 债务人联系电话                                  | -          | 
| **is_pep** *                       | boolean | PEP 标识符 (http://www.portaldatransparencia.gov.br/download-de-dados/pep)        | -          |
| **address** *                      | object  | **[Address 对象](#objeto-address)** - 债务人地址                                  | -          | 
| **role_type** *                    | enum    | 默认值：_issuer_                                                                  | -          |
| **birth_date** *                   | date    | 债务人出生日期（格式"YYYY-MM-DD"）                                                | -          |
| **mother_name** *                  | string  | 债务人母亲姓名                                                                    | 100        |
| **nationality**                    | string  | 债务人国籍                                                                        | 50         |
| **person_type** *                  | string  | 自然人标识符 - 默认值：_natural_                                                  | -          |
| **individual_document_number** *   | string  | 债务人 CPF（仅数字）                                                              | 11         |
| **document_identification** *      | string  | 债务人附有照片的身份证件（RG 或 CNH）PDF 的 DOCUMENT_KEY                          | -          |
| **document_identification_back**   | string  | 附有照片的身份证件背面 PDF 的 DOCUMENT_KEY（RG 或 CNH）（预先发送）。              | 11         |
| **wedding_certificate**            | string  | 婚姻证书 PDF 的 DOCUMENT_KEY（预先发送）。如果婚姻状况为"single"，此字段值应为 NULL。| 11         |
| **proof_of_residence** *           | string  | 所填地址的居住证明 PDF 的 DOCUMENT_KEY（预先发送）。                              | 11         |

### Address 对象
| 字段               | 类型   | 描述                                                                     | 最大字符数 | 
|--------------------|--------|--------------------------------------------------------------------------|-----------| 
| **city** *         | string | 地址所在城市                                                             | 100        |
| **state** *        | string | 地址所在州（两位大写字母）                                               | 2          |
| **number** *       | string | 门牌号                                                                   | 10         |
| **street** *       | string | 街道名称                                                                 | 100        |
| **complement** *   | string | 地址补充信息（自由文本）                                                 | 100        |
| **postal_code** *  | string | 邮政编码 (http://www.buscacep.correios.com.br/sistemas/buscacep/)        | 8          |
| **neighborhood** * | string | 街区/社区名称                                                            | 100        |

### Phone 对象
| 字段               | 描述   | 示例                                                 | 最大字符数 | 
|--------------------|--------|------------------------------------------------------|-----------| 
| **number** *       | string | 电话号码                                             | 10         |
| **area_code** *    | string | 区号 (https://ddd.guiamais.com.br/)                  | 2          |
| **country_code** * | string | 国际区号 (https://ddi.guiamais.com.br/)              | 3          |

### Disbursement Bank Account 对象

债务发行必须包含放款的银行信息，通常为债务人名下的账户。

| 字段                   | 类型   | 描述                                                                                               | 最大字符数 | 
|------------------------|--------|----------------------------------------------------------------------------------------------------|------------|
| name                   | string | 账户持有人姓名                                                                                     | 50         |
| document_number        | string | 账户持有人 CPF                                                                                     | 11         |
| bank_code *            | string | 金融机构 COMPE 代码 (https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf)                 | 3          |
| branch_number *        | string | 机构号（不填写机构检验位！）                                                                       | 4          |
| account_number *       | string | 账户号（不含账户检验位！）                                                                         | 10         |
| account_digit *        | string | 账户检验位（如为字母则填写零）                                                                     | 1          |
| account_type           | enum   | [Account Type 枚举值](#enumerador-account-type) 账户类型                                           | 1          |

### Financial 对象

Financial 对象描述信贷操作的财务信息。

| 字段                       | 类型   | 描述                                                                                                      | 最大字符数 |
|----------------------------|--------|-----------------------------------------------------------------------------------------------------------|------------|
| **amout**                  | float  | 信贷操作的发行/名义价值                                                                                   | -          |
| **interest_type**          | object | **[Interest Type 枚举值](#enumerador-interest-type)** - 摊销方法和利息计算方式                            | -          |
| **credit_operation_type**  | object | **[Credit Operation Type 枚举值](#enumerador-credit-operation-type)** - 信贷合同类型                      | -          |
| **annual_interest_rate**   | float  | 以十进制表示的年预固定利率                                                                                | -          |
| **disbursement_date**      | date   | 操作放款日期                                                                                              | -          |
| **interest_grace_period**  | int    | 利息宽限期（以月为单位）                                                                                  | -          |
| **principal_grace_period** | int    | 本金宽限期                                                                                                | -          |
| **number_of_installments** | int    | 信贷操作分期数                                                                                            | -          |
| **fine_configuration**     | object | **[Fine Configuration 对象](#objeto-fine-configuration)** - 逾期利息和罚款配置                            | -          |

### Fine Configuration 对象

Fine Configuration 对象包含信贷操作的逾期罚款和利息信息。

| 字段                    | 类型  | 描述                                                                             | 最大字符数 |
|-------------------------|-------|----------------------------------------------------------------------------------|------------|
| **contract_fine_rate**  | float | 逾期罚款百分比                                                                   | -          |
| **interest_base**       | enum  | **[Interest Base 枚举值](#enumerador-interest-base)** - 利息计算基准             | -          |
| **monthly_rate**        | float | 月逾期利率                                                                       | -          |

### Refinanced Credit Operations 对象 

| 字段            | 类型   | 描述                          | 字符数        |
|-----------------|--------|-------------------------------|---------------|
| `operation_key` | string | 将被再融资的操作密钥          | uuid 密钥     |

# 枚举值

### _Person Type_ 枚举值
| 枚举值          | 描述          |
|-----------------|---------------|
| **legal**       | 法人          |
| **natural**     | 自然人        |

### _Account Type_ 枚举值
| 枚举值                | 描述          |
|-----------------------|---------------|
| **checking_account**  | 支票账户      |
| **deposit_account**   | 存款账户      |
| **guaranteed_account**| 担保账户      |
| **investment_account**| 投资账户      |
| **payment_account**   | 支付账户      |
| **saving_account**    | 储蓄账户      |
| **salary_account**    | 工资账户      |

### _Interest Type_ 枚举值
| 枚举值                | 描述                                                                                                                                                                       |
|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **pre_price_days**    | Price 摊销法（等额分期），按日计算预固定利息                                                                                                                               |
| **pre_price**         | Price 摊销法（等额分期），按固定周期（30天）计算预固定利息                                                                                                                 |
| **pre_sac**           | SAC 摊销法（等额本金），按日计算预固定利息                                                                                                                                  |
| **post_sac**          | SAC 摊销法（等额本金），基于预固定利率+后固定指数（CDI、IPCA 或 IGPM）按日计算利息                                                                                          |
| **post_price**        | Price 摊销法（等额分期），基于预固定利率+后固定指数（CDI、IPCA 或 IGPM）按固定周期（30天）计算利息                                                                          |
| **post_price_days**   | Price 摊销法（等额分期），基于预固定利率+后固定指数（CDI、IPCA 或 IGPM）按日计算利息                                                                                        |

### _Credit Operation Type_ 枚举值
| 枚举值        | 描述                      |
|---------------|---------------------------|
| **ccb**       | 银行信用证明（CCB）       |
| **cce**       | 出口信用证明（CCE）       |
| **cci**       | 不动产信用证明（CCI）     |
| **nce**       | 出口信用票据（NCE）       |

### _Interest Base_ 枚举值
| 枚举值                | 描述                                                                  |
|-----------------------|-----------------------------------------------------------------------|
| **workdays**          | 以工作日为计算基准，按252天/年                                        |
| **calendar_days**     | 以自然日为计算基准，按360天/年                                        |
| **calendar_days_365** | 以自然日为计算基准，按365天/年                                        |

### _Fee Type_ 枚举值
每种费用类型须由 QI Tech 预先启用和配置

| 枚举值                | 描述                                                                   |
|-----------------------|------------------------------------------------------------------------|
| **tac**               | 账户开立手续费                                                         |
| **spread**            | 信贷操作收购价格中收取的溢价                                           |
| **warranty_analysis** | 担保分析费用                                                           |
| **ted_fee**           | TED 费用                                                               |
| **spread_ted_fee**    | 信贷操作收购价格中收取的 TED 费用溢价                                  |

## Response

STATUS 200

Response Body

```json
{
  "data": {
    "additional_iof": 469.1328,
    "annual_cet": "283,3821%",
    "assignment_amount": 124690.56,
    "borrower": {
      "document_number": "96969879003",
      "name": "Alan Mathison Turing"
    },
    "cet": "11,8500%",
    "contract": {
      "number": "0000067563/AMT",
      "urls": [
        "https://storage.googleapis.com/sandbox-doc-api/documents/5af36fcd-8e4c-4421-ad45-7bcba899c0d3/SYNGENTASANDBOX-ALAN_MATHISON_TURING-CCB-0000067563-20230302234816.pdf"
      ]
    },
    "installments": [],
    "issue_amount": 123456,
    "number_of_installments": 2
  },
  "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\"}"
}
```

---

# 更新自动划转规则

URL: /zh-Hans/documentation/regras_de_movimentacao/atualizar_regra_movimentacao

## Request

ENDPOINT /baas/automatic_transfer/transfer_configuration
MÉTODO PUT

:::danger 停用自动转账：
- 要停用自动转账，只需将 'is_active' 参数设置为 false
:::

**按比例分配规则**

**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

| 字段                    | 类型   | 描述                                                                                      | 字符数                                                        |
|-------------------------|--------|-------------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `transfer_cronstring`*  | string | 以 CRON 格式表示的转账频率，这是一种用于表达循环周期的标准格式。                           | **[CRON Guru](https://crontab.guru/#0_9_*_*_*)**             |
| `rule`*                 | enum   | 要遵循的规则（split_equal 或 split_percentage）。                                          | **[枚举值](#enumeradores-rule)**                              |
| `rule_configuration`*   | object | 所选规则的配置对象。                                                                       | **[rule_configuration 对象](#objeto-rule_configuration)**     |
| `account_key`*          | uuid   | 作为转账来源账户的密钥。                                                                   | -                                                             |
| `automatic_transfer_key`*| uuid  | 要修改的配置密钥。                                                                         | -                                                             |

### rule_configuration 对象

| 字段                | 类型   | 描述                         | 字符数                                           |
|---------------------|--------|------------------------------|--------------------------------------------------|
| `destinations`      | object | 目标账户及其他数据。          | **[destinations 数组](#objeto-destinations)**    |
| `remaining_balance` | float  | 将保留在账户中的余额金额。    | -                                                |

### destinations 对象

| 字段                                   | 类型    | 描述                                                                                                    | 字符数 |
|----------------------------------------|---------|---------------------------------------------------------------------------------------------------------|--------|
| `account_branch`*                      | string  | 目标账户机构号。                                                                                        | 3      |
| `account_number`*                      | string  | 目标账户号。                                                                                            | 3      |
| `account_digit`*                       | string  | 目标账户检验位。                                                                                        | 3      |
| `document_number`*                     | string  | 账户持有人证件号。                                                                                      | 3      |
| `name`*                                | string  | 自然人姓名或法人公司名称。                                                                              | 3      |
| `financial_institutions_code_number`*  | string  | 金融机构 COMPE 代码 (https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf)                     | 3      |
| `financial_institutions_ispb`*         | string  | 金融机构 ISPB 号码。                                                                                    | 8      |
| `is_pix_transfer`*                     | boolean | 定义转账是否通过 PIX 进行。                                                                             | -      |
| `percentage`*                          | float   | 分配给该账户的百分比。                                                                                  | -      |

### rule 枚举值

| 枚举值                | 说明                                              |
|-----------------------|---------------------------------------------------|
| **split_percentage**  | [按比例分配](./regras_de_movimentacao.md)         |
| **split_equal**       | [均等分配](./regras_de_movimentacao.md)           |
| **single_beneficiary**| [单一受益人](./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 * * * *"
}

```

**均等分配规则**

**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

| 字段                    | 类型   | 描述                                                                                       | 字符数                                                        |
|-------------------------|--------|--------------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `transfer_cronstring`*  | string | 以 CRON 格式表示的转账频率，这是一种用于表达循环周期的标准格式。                            | **[CRON Guru](https://crontab.guru/#0_9_*_*_*)**             |
| `rule`*                 | enum   | 要遵循的规则（split_equal 或 split_percentage）。                                           | **[枚举值](#enumeradores-rule)**                              |
| `rule_configuration`*   | object | 所选规则的配置对象。                                                                        | **[rule_configuration 对象](#objeto-rule_configuration)**     |
| `account_key`*          | uuid   | 作为转账来源账户的密钥。                                                                    | -                                                             |
| `automatic_transfer_key`*| uuid  | 要修改的配置密钥。                                                                          | -                                                             |

### rule_configuration 对象

| 字段                | 类型   | 描述                         | 字符数                                           |
|---------------------|--------|------------------------------|--------------------------------------------------|
| `destinations`      | object | 目标账户及其他数据。          | **[destinations 数组](#objeto-destinations)**    |
| `remaining_balance` | float  | 将保留在账户中的余额金额。    | -                                                |

### destinations 对象

| 字段                                  | 类型   | 描述                                                                                                    | 字符数 |
|---------------------------------------|--------|---------------------------------------------------------------------------------------------------------|--------|
| `account_branch`*                     | string | 目标账户机构号。                                                                                        | 3      |
| `account_number`*                     | string | 目标账户号。                                                                                            | -      |
| `account_digit`*                      | string | 目标账户检验位。                                                                                        | 3      |
| `document_number`*                    | string | 账户持有人证件号。                                                                                      | -      |
| `name`*                               | string | 自然人姓名或法人公司名称。                                                                              | 3      |
| `financial_institutions_code_number`* | string | 金融机构 COMPE 代码 (https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf)                     | 3      |
| `financial_institutions_ispb`*        | string | 金融机构 ISPB 号码。                                                                                    | 8      |

### rule 枚举值

| 枚举值                | 说明                                              |
|-----------------------|---------------------------------------------------|
| **split_percentage**  | [按比例分配](./regras_de_movimentacao.md)         |
| **split_equal**       | [均等分配](./regras_de_movimentacao.md)           |
| **single_beneficiary**| [单一受益人](./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 * * * *"
}

```

**单一受益人规则**

**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

| 字段                    | 类型   | 描述                                                                                       | 字符数                                                        |
|-------------------------|--------|--------------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `transfer_cronstring`*  | string | 以 CRON 格式表示的转账频率，这是一种用于表达循环周期的标准格式。                            | **[CRON Guru](https://crontab.guru/#0_9_*_*_*)**             |
| `rule`*                 | enum   | 要遵循的规则（split_equal 或 split_percentage）。                                           | **[枚举值](#enumeradores-rule)**                              |
| `rule_configuration`*   | object | 所选规则的配置对象。                                                                        | **[rule_configuration 对象](#objeto-rule_configuration)**     |
| `account_key`*          | uuid   | 作为转账来源账户的密钥。                                                                    | -                                                             |
| `automatic_transfer_key`*| uuid  | 要修改的配置密钥。                                                                          | -                                                             |

### rule_configuration 对象

| 字段                | 类型   | 描述                         | 字符数                                         |
|---------------------|--------|------------------------------|------------------------------------------------|
| `destination`       | object | 目标账户及其他数据。          | **[destination](#objeto-destinations)**        |
| `remaining_balance` | float  | 将保留在账户中的余额金额。    | -                                              |

### destination 对象

| 字段                                  | 类型   | 描述                                                                                                    | 字符数 |
|---------------------------------------|--------|---------------------------------------------------------------------------------------------------------|--------|
| `account_branch`*                     | string | 目标账户机构号。                                                                                        | 3      |
| `account_number`*                     | string | 目标账户号。                                                                                            | 3      |
| `account_digit`*                      | string | 目标账户检验位。                                                                                        | 3      |
| `document_number`*                    | string | 账户持有人证件号。                                                                                      | 3      |
| `name`*                               | string | 自然人姓名或法人公司名称。                                                                              | 3      |
| `financial_institutions_code_number`* | string | 金融机构 COMPE 代码 (https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf)                     | 3      |
| `financial_institutions_ispb`*        | string | 金融机构 ISPB 号码。                                                                                    | 8      |

### rule 枚举值

| 枚举值                | 说明                                              |
|-----------------------|---------------------------------------------------|
| **split_percentage**  | [按比例分配](./regras_de_movimentacao.md)         |
| **split_equal**       | [均等分配](./regras_de_movimentacao.md)           |
| **single_beneficiary**| [单一受益人](./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\"}"
}
```

---

# 创建自动划转规则

URL: /zh-Hans/documentation/regras_de_movimentacao/criar_regra_de_movimentacao

## Request

ENDPOINT /baas/automatic_transfer/transfer_configuration
MÉTODO POST
**按比例分配规则**

**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

| 字段                   | 类型   | 描述                                                                                      | 字符数                                                        |
|------------------------|--------|-------------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `transfer_cronstring`* | string | 以 CRON 格式表示的转账频率，这是一种用于表达循环周期的标准格式。                           | **[CRON Guru](https://crontab.guru/#0_9_*_*_*)**             |
| `rule`*                | enum   | 要遵循的规则（split_equal 或 split_percentage）。                                          | **[枚举值](#enumeradores-rule)**                              |
| `rule_configuration`*  | object | 所选规则的配置对象。                                                                       | **[rule_configuration 对象](#objeto-rule_configuration)**     |
| `account_key`*         | uuid   | 作为转账来源账户的密钥。                                                                   | -                                                             |

### rule_configuration 对象

| 字段                | 类型   | 描述                         | 字符数                                           |
|---------------------|--------|------------------------------|--------------------------------------------------|
| `destinations`      | object | 目标账户及其他数据。          | **[destinations 数组](#objeto-destinations)**    |
| `remaining_balance` | float  | 将保留在账户中的余额金额。    | -                                                |

### destinations 对象

| 字段                                   | 类型    | 描述                                                                                                    | 字符数 |
|----------------------------------------|---------|---------------------------------------------------------------------------------------------------------|--------|
| `account_branch`*                      | string  | 目标账户机构号。                                                                                        | 3      |
| `account_number`*                      | string  | 目标账户号。                                                                                            | 3      |
| `account_digit`*                       | string  | 目标账户检验位。                                                                                        | 3      |
| `document_number`*                     | string  | 账户持有人证件号。                                                                                      | 3      |
| `name`*                                | string  | 自然人姓名或法人公司名称。                                                                              | 3      |
| `financial_institutions_code_number`*  | string  | 金融机构 COMPE 代码 (https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf)                     | 3      |
| `financial_institutions_ispb`*         | string  | 金融机构 ISPB 号码。                                                                                    | 8      |
| `is_pix_transfer`*                     | boolean | 定义转账是否通过 PIX 进行。                                                                             | -      |
| `percentage`*                          | float   | 分配给该账户的百分比。                                                                                  | -      |

### rule 枚举值

| 枚举值                | 说明                                              |
|-----------------------|---------------------------------------------------|
| **split_percentage**  | [按比例分配](./regras_de_movimentacao.md)         |
| **split_equal**       | [均等分配](./regras_de_movimentacao.md)           |
| **single_beneficiary**| [单一受益人](./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 * * * *"
}

```

**均等分配规则**

**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

| 字段                   | 类型   | 描述                                                                                       | 字符数                                                        |
|------------------------|--------|--------------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `transfer_cronstring`* | string | 以 CRON 格式表示的转账频率，这是一种用于表达循环周期的标准格式。                            | **[CRON Guru](https://crontab.guru/#0_9_*_*_*)**             |
| `rule`*                | enum   | 要遵循的规则（split_equal 或 split_percentage）。                                           | **[枚举值](#enumeradores-rule)**                              |
| `rule_configuration`*  | object | 所选规则的配置对象。                                                                        | **[rule_configuration 对象](#objeto-rule_configuration)**     |
| `account_key`*         | uuid   | 作为转账来源账户的密钥。                                                                    | -                                                             |

### rule_configuration 对象

| 字段                | 类型   | 描述                         | 字符数                                           |
|---------------------|--------|------------------------------|--------------------------------------------------|
| `destinations`      | object | 目标账户及其他数据。          | **[destinations 数组](#objeto-destinations)**    |
| `remaining_balance` | float  | 将保留在账户中的余额金额。    | -                                                |

### destinations 对象

| 字段                                  | 类型   | 描述                                                                                                    | 字符数 |
|---------------------------------------|--------|---------------------------------------------------------------------------------------------------------|--------|
| `account_branch`*                     | string | 目标账户机构号。                                                                                        | 3      |
| `account_number`*                     | string | 目标账户号。                                                                                            | -      |
| `account_digit`*                      | string | 目标账户检验位。                                                                                        | 3      |
| `document_number`*                    | string | 账户持有人证件号。                                                                                      | -      |
| `name`*                               | string | 自然人姓名或法人公司名称。                                                                              | 3      |
| `financial_institutions_code_number`* | string | 金融机构 COMPE 代码 (https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf)                     | 3      |
| `financial_institutions_ispb`*        | string | 金融机构 ISPB 号码。                                                                                    | 8      |

### rule 枚举值

| 枚举值                | 说明                                              |
|-----------------------|---------------------------------------------------|
| **split_percentage**  | [按比例分配](./regras_de_movimentacao.md)         |
| **split_equal**       | [均等分配](./regras_de_movimentacao.md)           |
| **single_beneficiary**| [单一受益人](./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 * * * *"
}

```

**单一受益人规则**

**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

| 字段                   | 类型   | 描述                                                                                       | 字符数                                                        |
|------------------------|--------|--------------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `transfer_cronstring`* | string | 以 CRON 格式表示的转账频率，这是一种用于表达循环周期的标准格式。                            | **[CRON Guru](https://crontab.guru/#0_9_*_*_*)**             |
| `rule`*                | enum   | 要遵循的规则（split_equal 或 split_percentage）。                                           | **[枚举值](#enumeradores-rule)**                              |
| `rule_configuration`*  | object | 所选规则的配置对象。                                                                        | **[rule_configuration 对象](#objeto-rule_configuration)**     |
| `account_key`*         | uuid   | 作为转账来源账户的密钥。                                                                    | -                                                             |

### rule_configuration 对象

| 字段                | 类型   | 描述                         | 字符数                                         |
|---------------------|--------|------------------------------|------------------------------------------------|
| `destination`       | object | 目标账户及其他数据。          | **[destination](#objeto-destinations)**        |
| `remaining_balance` | float  | 将保留在账户中的余额金额。    | -                                              |

### destination 对象

| 字段                                  | 类型   | 描述                                                                                                    | 字符数 |
|---------------------------------------|--------|---------------------------------------------------------------------------------------------------------|--------|
| `account_branch`*                     | string | 目标账户机构号。                                                                                        | 3      |
| `account_number`*                     | string | 目标账户号。                                                                                            | 3      |
| `account_digit`*                      | string | 目标账户检验位。                                                                                        | 3      |
| `document_number`*                    | string | 账户持有人证件号。                                                                                      | 3      |
| `name`*                               | string | 自然人姓名或法人公司名称。                                                                              | 3      |
| `financial_institutions_code_number`* | string | 金融机构 COMPE 代码 (https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf)                     | 3      |
| `financial_institutions_ispb`*        | string | 金融机构 ISPB 号码。                                                                                    | 8      |

### rule 枚举值

| 枚举值                | 说明                                              |
|-----------------------|---------------------------------------------------|
| **split_percentage**  | [按比例分配](./regras_de_movimentacao.md)         |
| **split_equal**       | [均等分配](./regras_de_movimentacao.md)           |
| **single_beneficiary**| [单一受益人](./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\"}"
}
```

---

# 资金划转规则

URL: /zh-Hans/documentation/regras_de_movimentacao/

在开设 QI Tech 账户时，我们为客户提供为账户创建资金划转规则的功能。这些规则旨在简化重复性操作，例如，在每日结束时将账户余额全部或部分转移。以下将举例说明我们系统中主要规则的区别："split_equal"（均等分配）和"split_percentage"（按比例分配）。如果客户有不符合这两种规则的需求，可在集成期间向我们的团队申请创建满足其需求的自定义规则。

### 按比例分配规则（SPLIT_PERCENTAGE）

按比例分配规则按照设定的比例，将账户可用余额定期（频率在"transfer_cronstring"中设置）分配到目标账户。每个目标账户的百分比之和可以小于或等于100。如果百分比之和小于100，剩余部分将作为余额保留在账户中。例如，客户可以选择将80%的资金在账户间转移，并始终保留20%的余额。

### 均等分配规则（SPLIT_EQUAL）

均等分配规则将账户可用余额定期（频率在"transfer_cronstring"中设置）均等分配到目标账户，仅保留"remaining_balance"字段中定义的金额作为余额。如果未填写"remaining_balance"字段，则转移账户100%的余额。如果账户可用余额等于或小于"remaining_balance"，则不发生交易。

### 单一受益人规则（SINGLE_BENEFICIARY）

单一受益人分配规则允许在"transfer_cronstring"中设置的频率下，向单一受益人进行转账。

---

# 取消重组方案

URL: /zh-Hans/documentation/renegociacao/cancelar_uma_renegociacao

## 请求

ENDPOINT /renegotiation/proposal/ PROPOSAL-KEY
方法 DELETE

### Path Params

| 字段 | 类型 | 描述 | 字符 |
|---|---|---|---|
| `proposal_key` * | string | 重组方案的 key | uuid 格式 |

## 响应

状态 200

Response Body

```json
{

}
```

状态 400

Response Body

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

---

# 查询重组方案

URL: /zh-Hans/documentation/renegociacao/consultar_uma_renegociacao

## 通过 Proposal Key 查询

ENDPOINT /renegotiation/proposal/ PROPOSAL-KEY
方法 GET

### Path params

| 字段 | 类型 | 描述 | 字符 |
|---|---|---|---|
| `proposal_key` * | string | 重组方案的 key | uuid 格式 |

### 响应

状态 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": [...],
  "remaining_installments": [...]
}
```

状态 400

Response Body

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

## 通过 Request Control Key 查询

ENDPOINT /renegotiation/proposal/request_control_key/ REQUEST-CONTROL-KEY
方法 GET

### Path params

| 字段 | 类型 | 描述 | 字符 |
|---|---|---|---|
| `request_control_key` * | string | 用于追踪和唯一标识的请求控制 key | UUID |

---

# 创建重组方案

URL: /zh-Hans/documentation/renegociacao/criacao_de_uma_renegociacao

## 请求

ENDPOINT /renegotiation/proposal
方法 POST

Request Body

 使用不同 amortization_types 的 payload 示例

**使用分期 key**

```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,
  "discount_amount": 100,
  "request_control_key": "3571e292-3a83-4011-904d-20ee963022ef",
  "installments": [
    {
      "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88"
    },
    {
      "installment_key": "0ff87136-b084-44fb-8fc2-d2e3beed483b"
    },
    {
      "installment_key": "e4101c6a-51b3-435f-a2b7-4a65a005cc15"
    }
  ]
}
```

**使用分期数量**

```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",
  "discount_percentage": 0.2,
  "discount_amount": 100,
  "request_control_key": "3571e292-3a83-4011-904d-20ee963022ef",
  "number_of_installments": 4
}
```

**使用最终金额**

```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",
  "discount_percentage": 0.2,
  "discount_amount": 100,
  "request_control_key": "3571e292-3a83-4011-904d-20ee963022ef",
  "payment_amount": 900
}
```

:::warning 注意
`discount_amount` 和 `discount_percentage` 字段**不能**在同一 payload 中同时发送。
:::

### Body Params

| 字段 | 类型 | 描述 | 字符 |
|---|---|---|---|
| `debt_key` | string | QI 内信贷操作的唯一 key | UUID |
| `amortization_type` | string | 摊销类型 | **[摊销类型枚举](#enumeradores-amortization-type)** |
| `reference_date` | string | 重组现值计算的参考日期（需为 D+1）| 10 |
| `proposal_due_date` | string | 重组方案到期日期 | 10 |
| `payment_type` | string | 支付类型 | **[支付类型枚举](#enumeradores-payment-type)** |
| `payment_amount` | float | 方案中协商的最终金额 | - |
| `number_of_installments` | int | 方案中协商的分期数量 | 10 |
| `discount_percentage` | float | 基于重组现值计算的折扣百分比（(1 - 折扣百分比) * 现值）| 10 |
| `discount_amount` | float | 基于重组现值的折扣金额（现值 - 总折扣金额）| 10 |
| `request_control_key` | string | 用于追踪和唯一标识的请求控制 key | UUID |
| `installments` | array of objects | 重组的分期列表 | **[Installments 对象](#installments-object)** |

### 摊销类型枚举（Amortization Type）

| 字段 | 描述 |
|---------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **installment_payment** | 创建用于支付 payload 中指定分期的重组方案。<br/><br/> 使用此摊销类型时，需传入分期的 `installment_key`。|
| **overdue_installment_payment** | 创建专门针对逾期分期支付的重组方案。<br/><br/> 使用此摊销类型时，需传入分期的 `installment_key`。|
| **first_installments** | 创建用于支付最前面若干期（状态为开放）的重组方案。<br/> <br/> 此摊销类型可通过传入希望结清的分期数量（`number_of_installments`）或借款人希望支付的金额（`payment_amount`）来使用。|

### 支付类型枚举（Payment Type）

| 字段 | 描述 |
|----------|---------------------------------------------------------------|
| bankslip | 通过银行划款支付（同时生成划款和 Pix 支付）|
| pix | 通过 Pix 支付（仅生成 Pix）|
| manual | 手动支付（不生成支付方式）|

### Installments 对象

| 字段 | 类型 | 描述 | 字符 |
|---|---|---|---|
| `installment_key` | string | 待重组分期的 key | uuid 格式 |

## 响应

状态 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": [...],
  "remaining_installments": [...]
}
```

状态 400

Response Body

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

---

# Renegociação internal e external

URL: /zh-Hans/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"
    }
  ]
}
```

## 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.

## 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

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.

## 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\"}"
}
```

---

# 查询重组方案列表

URL: /zh-Hans/documentation/renegociacao/listar_renegociacoes

## 请求

ENDPOINT /renegotiation/proposal
方法 GET

### Query Params

| 字段 | 类型 | 描述 | 字符 |
|---|---|---|---|
| `proposal_status` | string | 方案状态 | 10 |
| `contract_number` | string | 合同编号 | 10 |
| `issuer_document_number` | string | 借款人的证件号码 | 10 |

## 响应

状态 200

Response Body

```json
{
  "data": [],
  "pagination": {
    "current_page": 1,
    "next_page": 2,
    "rows_per_page": 30,
    "total_pages": 5,
    "total_rows": 140
  }
}
```

状态 400

Response Body

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

---

# 重组方案支付

URL: /zh-Hans/documentation/renegociacao/pagamento_renegociacao

## Webhooks：

WEBHOOK_TYPE renegotiation.proposal
状态 paid

#### paid_method_type 枚举值

| 枚举值 | 描述 |
|------------------------------|-----------------------------------------------|
| **bank_slip** | 通过银行划款支付 |
| **pix** | 通过 Pix 支付 |

#### 重组方案支付 Webhook 示例

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

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"
}
```

---

# 批量重组

URL: /zh-Hans/documentation/renegociacao/renegociacao_em_lote

:::caution 注意
批量重组只能由同一发行人和相同集成 key 的操作创建。
:::

:::caution 注意
每次批量重组最多包含 50 个操作。
:::

## 1. 模拟批量重组

### 请求

ENDPOINT /renegotiation/batch_proposal_simulation
方法 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"
        }]
      }
  ]
}
```

### 折扣字段

在请求中添加以下任一字段，可为重组方案的创建或模拟设置百分比或绝对值折扣。

百分比折扣

```json
{
  "discount_percentage": 0.5
}
```

绝对值折扣

```json
{
  "discount_amount": 200
}
```

## 2. 创建批量重组

:::caution 注意
`request_control_key` 字段为可选字段，用于保证请求的唯一性。
:::

### 请求

ENDPOINT /renegotiation/batch_proposal
方法 POST

:::warning 注意
`discount_amount` 和 `discount_percentage` 字段**不能**在同一 payload 中同时发送。
:::

### Body Params

| 字段 | 类型 | 描述 | 字符 |
|-----------------------|---|---|---|
| `debt_key` | string | QI 内信贷操作的唯一 key | UUID |
| `amortization_type` | string | 摊销类型 | **[摊销类型枚举](#enumeradores-amortization-type)** |
| `reference_date` | string | 重组现值计算的参考日期（需为 D+1）| 10 |
| `proposal_due_date` | string | 重组方案到期日期 | 10 |
| `payment_type` | string | 支付类型 | **[支付类型枚举](#enumeradores-payment-type)** |
| `discount_percentage` | float | 折扣百分比 | 10 |
| `discount_amount` | float | 折扣金额 | 10 |
| `installments` | array of objects | 重组的分期列表 | **[Installments 对象](#installments-object)** |

### 摊销类型枚举（Amortization Type）

| 字段 | 描述 |
|---------------------------------|------------------------------------------------------------------------------------------|
| **installment_payment** | 创建用于支付 payload 中指定分期的重组方案。<br/><br/> 使用此摊销类型时，需传入分期的 `installment_key`。|
| **overdue_installment_payment** | 创建专门针对逾期分期支付的重组方案。<br/><br/> 使用此摊销类型时，需传入分期的 `installment_key`。|

### 支付类型枚举（Payment Type）

| 字段 | 描述 |
|----------|---------------------------------------------------------------|
| bankslip | 通过银行划款支付（同时生成划款和 Pix 支付）|
| pix | 通过 Pix 支付（仅生成 Pix）|
| manual | 手动支付（不生成支付方式）|

### Installments 对象

| 字段 | 类型 | 描述 | 字符 |
|---|---|---|---|
| `installment_key` | string | 待重组分期的 key | uuid 格式 |

## 3. 查询批量重组列表

### Path params

| 字段 | 类型 | 描述 | 字符 |
|---|---|---|---|
| `batch_proposal_status` * | string | 批量重组方案状态 | - |
| `issuer_document_number` * | string | 发行人证件号码 | - |
| `request_control_key` * | string | 请求者标识 key | - |

### 请求

ENDPOINT /renegotiation/batch_proposal
方法 GET

## 4. 查询单个批量重组

### 请求

ENDPOINT /renegotiation/batch_proposal/BATCH-PROPOSAL-KEY
方法 GET

## 5. 取消批量重组

ENDPOINT /renegotiation/batch_proposal/BATCH-PROPOSAL-KEY
方法 DELETE

### 响应

HTTP 状态 204

## 6. Webhooks

## 6.1. 批量重组支付 Webhook

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

:::caution 注意
批量重组可能因支付超时或在重组外单独支付了分期而被拒绝。
:::

Webhook Body

```json
{
    "webhook_type": "renegotiation.batch_proposal",
    "key": "\<BATCH-PROPOSAL-KEY\>",
    "event_datetime": "\<DATA E HORA DO ENVIO DO WEBHOOK\>",
    "status": "rejected",
    "data": {}
}
```

---

# 按分期金额模拟

URL: /zh-Hans/documentation/renegociacao/simulacao_com_valor_por_parcela

## 请求

ENDPOINT /renegotiation/simulation
方法 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

| 字段 | 类型 | 描述 | 字符 |
|---|---|---|---|
| `contract_number` | string | 合同编号 | 10 |
| `amortization_type` | string | 摊销类型 | 10 |
| `reference_date` | date | 重组参考日期 | 10 |
| `installments` | array of objects | 重组的分期列表 | **[Installments 对象](#installments-object)** |

### Installments 对象

| 字段 | 描述 |
|---|---|
| `installment_key` * | string | 待重组分期的 key | 10 |
| `paid_amount` * | float | 该分期的支付金额 | 10 |

## 响应

状态 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": [...],
  "remaining_installments": [...]
}
```

状态 400

Response Body

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

---

# 模拟重组方案

URL: /zh-Hans/documentation/renegociacao/simulacao_de_uma_renegociacao

## 请求

ENDPOINT /renegotiation/simulation
方法 POST

Request Body

 使用不同 amortization_types 的 payload 示例

**使用分期 key**

```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"
    }
  ]
}
```

**使用分期数量**

```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
}
```

**使用最终金额**

```json
{
  "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
  "amortization_type": "first_installments",
  "reference_date": "2022-07-20",
  "discount_percentage": 0.2,
  "discount_amount": 100,
  "payment_amount": 900
}
```

:::warning 注意
`discount_amount` 和 `discount_percentage` 字段**不能**在同一 payload 中同时发送。
:::

### Body Params

| 字段 | 类型 | 描述 | 字符 |
|---|---|---|---|
| `debt_key` | string | QI 内信贷操作的唯一 key | UUID |
| `amortization_type` | string | 摊销类型 | **[摊销类型枚举](#enumeradores-amortization-type)** |
| `reference_date` | string | 重组现值计算的参考日期（需为 D+1）| 10 |
| `proposal_due_date` | string | 重组方案到期日期 | 10 |
| `payment_type` | string | 支付类型 | **[支付类型枚举](#enumeradores-payment-type)** |
| `payment_amount` | float | 方案中协商的最终金额 | - |
| `number_of_installments` | int | 方案中协商的分期数量 | 10 |
| `discount_percentage` | float | 折扣百分比 | 10 |
| `discount_amount` | float | 折扣金额 | 10 |
| `installments` | array of objects | 重组的分期列表 | **[Installments 对象](#installments-object)** |

### Installments 数组对象

| 字段 | 类型 | 描述 | 字符 |
|---|---|---|---|
| `installment_key` | string | 待重组分期的 key | uuid 格式 |

### 摊销类型枚举（Amortization Type）

| 字段 | 描述 |
|---------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **installment_payment** | 创建用于支付 payload 中指定分期的重组方案。<br/><br/> 使用此摊销类型时，需传入分期的 `installment_key`。|
| **overdue_installment_payment** | 创建专门针对逾期分期支付的重组方案。<br/><br/> 使用此摊销类型时，需传入分期的 `installment_key`。|
| **first_installments** | 创建用于支付最前面若干期（状态为开放）的重组方案。<br/><br/> 此摊销类型可通过传入希望结清的分期数量（`number_of_installments`）或借款人希望支付的金额（`payment_amount`）来使用。|

## 响应

状态 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": [...],
  "remaining_installments": [...]
}
```

状态 400

Response Body

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

---

# 更新手动支付记录

URL: /zh-Hans/documentation/renegociacao/update_de_um_pagamento_manual

## 请求

- ENDPOINT /renegotiation/proposal/proposal_key}/payment
- 方法 PATCH

Body.json

```json
{
   "paid_method_type": "bank_slip"
}

```

### Query params

| 字段 | 类型 | 描述 | 字符 |
|---|---|---|---|
| `proposal_status` | 类型 | 重组方案的 key | 10 |

### Body params

| 字段 | 类型 | 描述 | 字符 |
|---|---|---|---|
| `paid_method_type` | 类型 | 支付方式 | **[枚举值](#enumeradores-paid_method_type)** |

### paid_method_type 枚举值

| 字段 | 描述 |
|---|---|
| banklisp | 通过银行划款支付 |
| manual | 手动支付 |
| pix | 通过 Pix 支付 |

## 响应

状态 200

Response Body

```json
{

}
```

状态 400

Response Body

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

---

# 测试指南 - 购物回路

URL: /zh-Hans/documentation/roteiros_de_homologacao/circuito_dd46f8d3-f078-41ba-a311-55be848f1c69

测试指南描述了集成合作伙伴在进入生产环境之前，需要在 QI Tech 沙盒环境（测试环境）中测试的所有资源和功能。

本指南描述了该产品所涉及的所有资源和功能。
:::info 注意
标有 * 的步骤是进入生产环境的必须步骤
:::

⚠️ **所有测试必须强制在 QI Tech 沙盒环境（测试环境）中进行。在沙盒环境中进行的操作均为虚拟金融操作，仅用于测试 API 功能。**

## BaaS API 注册与认证
| 代码  | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| CAB0001* | 在沙盒环境注册 | 在 QI Tech 平台 Sandbox 环境（sandbox.qitech.app）完成注册 | [文档链接](/documentation/primeiros_passos/inicio) 
| CAB0002* | 在沙盒验证 token | 在 Sandbox 环境验证 QI Token | [下载 Token 使用手册](https://docs.qitech.com.br/assets/pdfs/QI%20Tech%20Manual%20Inclus%C3%A3o%20de%20Token.pdf) | CAB0001 |
| CAB0003* | 交换公钥 | 在 QI Tech 平台 Sandbox 环境（sandbox.qitech.app）完成公钥交换 | [文档链接](/documentation/primeiros_passos/troca_de_chaves) | CAB0001 e CAB0002 |
| CAB0004* | 完成 API 调用认证测试 | 完成 API 调用认证测试 | [步骤说明](/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2) <br/><br/> [文档链接](/documentation/primeiros_passos/teste_de_autenticacao/endpoints_de_teste) | CAB0003 |
| CAB0005* | 配置 webhook | 通过 QI Tech 平台 Sandbox 环境（sandbox.qitech.app）配置 QI 发送 webhook 的 URL | [文档链接](/documentation/primeiros_passos/configurando_webhooks) | CAB0001 e CAB0002 |

## 交易
| 代码  | 步骤 | 描述 | 文档链接 | 前置条件 |
|---------|--|---|---|---|
| QIC0008* | 查询交易记录 | 查询账户交易记录 | [查询交易记录](/documentation/movimentacao_de_contas/consulta_de_transacoes) ||
| QIC0009 | 申请转账凭证 | 申请转账凭证 | [申请转账凭证](/documentation/movimentacao_de_contas/comprovante_de_transferencia) | PIX0002 |
| QIC0010* | 读取交易 webhook | 成功接收所有交易 webhook | [Webhook account_transaction](/documentation/movimentacao_de_contas/webhook_movimentacoes) | CAB0005 e PIX0002 |
| QIC0011 | 查询金融机构列表 | 查询可接收 TED 和 Pix 的金融机构列表 | [查询金融机构](/documentation/lista_de_instituicoes_financeiras/consulta_de_instituicoes_financeiras) ||

# TED

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| TED0001* | TED 转出 | 向其他金融机构进行 TED 转账 | [文档链接](/documentation/baas/ted/realizar_transferencia) | CAB0002 ou CAB0003 |
| TED0002* | 模拟 TED 转出退回 | 模拟从 QI 账户发出的 TED 转出退款 | 第 3 项: <br/>[文档链接](/documentation/movimentacao_de_contas/transacao#3---simula%C3%A7%C3%A3o-de-devolu%C3%A7%C3%A3o-de-ted) | TED0001 |
| TED0003* | 模拟 TED 转入 | 模拟 TED 转入到 QI 账户 | 第 2 项: <br/>[文档链接](/documentation/movimentacao_de_contas/transacao#2---simula%C3%A7%C3%A3o-de-entrada-de-ted) | CAB0002 ou CAB0003 |
| TED0004* | 查询 TED 交易 | 查询一笔 TED 交易 | [文档链接](/documentation/movimentacao_de_contas/consulta_de_transacoes) | CAB0002 ou CAB0003 |
| TED000* | 读取 TED webhook | 成功接收 TED webhook | [文档链接](/documentation/baas/ted/webhooks) | CAB0002 ou CAB0003 |

---

# 票据

## 票据管理

| 编号 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| BOL0002* | 登记收款票据 | 登记一张收款票据 | [文档链接](/documentation/boletos/emissao/emissao_via_json) | CAB0002 ou CAB0003, |
| BOL0003 | 查询收款钱包 | 查询可用于登记票据的收款钱包 | [文档链接](/documentation/boletos/consultar/consulta_de_carteira) | CAB0002 ou CAB0003 |
| BOL0004* | 票据指令 | 对已登记的票据发出指令 | [文档链接](/documentation/boletos/enviar_instrucao_de_boleto) | BOL0002 |
| BOL0005 | 模拟票据清算 | 模拟一张票据的清算 | [文档链接](/documentation/boletos/pagamento/liquidacao) | BOL0002 |
| BOL0006* | 读取票据 webhook | 成功接收所有与票据状态变更相关的 webhook | [文档链接](/documentation/webhooks/boletos) | BOL0004 |

## 票据支付

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| BOL0009* | 查询可打印条形码 | 查询银行票据或协议票据的可打印条形码 | [文档链接](/documentation/boletos/pagamento/consulta_linha_digitavel) |  |
| BOL0010* | 支付票据 | 支付银行票据或协议票据 | 第 7.5 项 <br/>[文档链接](/documentation/boletos/pagamento/realizar_pagamento) | CAB0002 ou CAB0003 |

---

## Pix

## Pix 转账
| 代码  | 步骤 | 描述 | 文档链接 | 前置条件 |
|---------|--|---|---|---|
| PIX0002* | Pix 转出 | 从 QI 账户使用银行数据（手动 Pix）或 Pix 密钥进行 Pix 转账 | [进行 Pix 转账](/documentation/baas/pix/realizar_transferencia)||
| PIX0035 | 查询 Pix 转账 | 获取一笔转账的数据 | [查询 Pix 转账](/documentation/baas/pix/consultar_transferencias) | PIX0002 |
| PIX0003* | 模拟 Pix 转出退款 | 模拟 Pix 转出退款 | [模拟 Pix 转出退款 -> 第 2 项](/documentation/pix/simulacao)| PIX0002 |
| PIX0004* | 模拟 Pix 转入 | 模拟 Pix 转入到 QI 账户 | [模拟 Pix 转入 -> 第 1 项](/documentation/pix/simulacao)||
| PIX0005* | Pix 转入退款 | 从 QI 账户退还 Pix 转入 | [Pix 转入退款](/documentation/baas/pix/solicitar_devolucao)| PIX0004 |
| PIX0037* | 读取待处理交易 webhook | 成功接收待处理交易 webhook | [待处理交易 webhook](/documentation/baas/pix/webhooks/index.html#webhook-para-transa%C3%A7%C3%B5es-pendentes) | PIX0002 |
| PIX0038* | 读取 Pix 转入 webhook | 成功接收 Pix 转入 webhook | [Pix 转入 webhook](/documentation/baas/pix/webhooks/index.html#webhook-para-pix-de-entrada) | PIX0004 |
| PIX0039 | 读取 Pix 退款 webhook | 成功接收 Pix 退款 webhook | [Pix 退款 webhook](/documentation/baas/pix/webhooks/index.html#webhook-para-devolu%C3%A7%C3%B5es-de-pix) | PIX0003 |

## Pix QR 码支付

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0029* | 支付静态 Pix QR 码 | 支付静态 Pix QR 码 | 第 4.1 项: [文档链接](/documentation/baas/pix/realizar_transferencia#transfer%C3%AAncia-por-qr-code-pix) | PIX0022 |
| PIX0030* | 支付动态 Pix QR 码 | 支付动态 Pix QR 码 | 第 4.2 项: [文档链接](/documentation/baas/pix/realizar_transferencia#transfer%C3%AAncia-por-qr-code-pix) | PIX0022 |

---

# 测试指南 - BaaS 数字账户

URL: /zh-Hans/documentation/roteiros_de_homologacao/conta_digital

测试指南描述了集成合作伙伴在进入生产环境之前，需要在 QI Tech 沙盒环境（测试环境）中测试的所有资源和功能。

本指南描述了该产品所涉及的所有资源和功能。

⚠️ **所有测试必须强制在 QI Tech 沙盒环境（测试环境）中进行。在沙盒环境中进行的操作均为虚拟金融操作，仅用于测试 API 功能。**

## BaaS API 注册与认证
| 代码  | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| CAB0001* | 在沙盒环境注册 | 在 QI Tech 平台 Sandbox 环境（sandbox.qitech.app）完成注册 | cs@qitech.com.br |
| CAB0002* | 在沙盒验证 token | 在 Sandbox 环境验证 QI Token | [文档链接](https://docs.qitech.com.br/assets/pdfs/QI%20Tech%20Manual%20Inclus%C3%A3o%20de%20Token.pdf) | CAB0001 |
| CAB0003* | 交换公钥 | 在 QI Tech 平台 Sandbox 环境（sandbox.qitech.app）完成公钥交换 | [文档链接](/documentation/primeiros_passos/troca_de_chaves) | CAB0001 e CAB0002 |
| CAB0004* | 完成 API 调用认证测试 | 完成 API 调用认证测试 | [文档链接](/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2) <br/><br/> [文档链接](/documentation/primeiros_passos/teste_de_autenticacao/endpoints_de_teste) | CAB0003 |
| CAB0005* | 配置 webhook | 通过 QI Tech 平台 Sandbox 环境（sandbox.qitech.app）配置 QI 发送 webhook 的 URL | [文档链接](/documentation/primeiros_passos/configurando_webhooks) | CAB0001 e CAB0002 |

## 反欺诈

## 注册与认证

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| ATF0002* | 获取 onboarding API 密钥 | 向 QI Tech 集成团队获取用于 /onboarding API 的 API 密钥 | suporte.caas@qitech.com.br |  
| ATF0003* | 获取 OCR 移动令牌 | 向 QI Tech 集成团队获取用于 OCR SDK 的移动令牌 | suporte.caas@qitech.com.br |  
| ATF0004* | 获取人脸识别移动令牌 | 向 QI Tech 集成团队获取用于人脸识别 SDK 的移动令牌 | suporte.caas@qitech.com.br |  
| ATF0005* | 获取设备扫描移动令牌 | 向 QI Tech 集成团队获取用于设备扫描 SDK 的移动令牌 | suporte.caas@qitech.com.br |  

## SDK OCR

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| ATF0007* | 构建 SDK | 定义文件采集的模板和自定义选项，并在您的应用中（QI Tech 客户应用）成功构建 SDK | Android: [文档链接](/documentation/caas/ocr/android/introduction) <br/> iOS:[ 文档链接](/documentation/caas/ocr/ios/introduction) |  |
| ATF0008* | 发送文件 | 在您的应用中（QI Tech 客户应用）使用 SDK 完成文件采集 |  | ATF0003 e ATF0007 |
| ATF0009* | 存储 ocr_key | 存储 SDK 返回的密钥，识别采集文件的类型（例如：cnh_front、cnh_back 等） | Android: [文档链接](/documentation/caas/ocr/android/collecting_response) <br/>iOS:[ 文档链接](/documentation/caas/ocr/ios/collecting_response)| ATF0008 |

## SDK 人脸识别

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| ATF0011* | 构建 SDK | 定义自定义选项并在您的应用中（QI Tech 客户应用）成功构建 SDK | Android: [文档链接](/documentation/caas/face_recognition/android/introduction) <br/>iOS:[ 文档链接](/documentation/caas/face_recognition/ios/introduction)  |  |
| ATF0012* | 活体检测流程 | 在您的应用中（QI Tech 客户应用）使用 SDK 完成活体检测流程 | | ATF0004 e ATF0011* |
| ATF0013* | 存储图像密钥 | 完成活体检测流程后，存储 SDK 返回的 image_key | Android: [文档链接](/documentation/caas/face_recognition/android/collecting_response) iOS:[ 文档链接](/documentation/caas/face_recognition/ios/collecting_response) | ATF0012 |

## SDK 设备扫描

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| ATF0015* | 构建 SDK | 定义您的应用（QI Tech 客户应用）向用户请求的权限，并在您的应用中成功构建 SDK | Android: [文档链接](/documentation/caas/device_scan/android/introduction)<br/>iOS:[ 文档链接](/documentation/caas/device_scan/ios/introduction)|  
| ATF0016* | 存储用户会话 | 存储待扫描设备的用户会话（sessionId） | Android: [文档链接](/documentation/caas/device_scan/android/example)<br/>iOS:[ 文档链接](/documentation/caas/device_scan/ios/example) | ATF0015 e ATF0017 |
| ATF0017* | 采集信息 | 使用已存储的 sessionId 实例化 SDK，并在您的应用中（QI Tech 客户应用）调用信息采集方法 | Android: [文档链接](/documentation/caas/face_recognition/android/collecting_response)<br/>iOS:[ 文档链接](/documentation/caas/face_recognition/ios/collecting_response) | ATF0005 e ATF0015 |

## 反欺诈

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| ATF0019* | 个人客户反欺诈 | 成功完成个人客户的反欺诈流程 | [文档链接](/documentation/caas/onboarding/natural_person) | ATF0002 |
| ATF0020* | 企业客户反欺诈 | 成功完成企业客户的反欺诈流程 | [文档链接](/documentation/caas/onboarding/legal_person) | ATF0002 |
| ATF0021* | 读取异步流程中的分析派生 webhook | 成功接收异步响应流程中的分析派生 webhook | [文档链接](/documentation/caas/onboarding/webhook) | ATF0019 ou ATF0020 |

## 平台注册

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| ATF0022* | 注册主用户 | 在 CaaS 平台注册主用户，用于处理转到"人工分析"的派生请求 | suporte.caas@qitech.com.br | ATF0019 ou ATF0020 |

---

# **QI Conta**

## 开户

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| QIC0002* | 预留个人账户 | 申请预留持有人为自然人的账户 | [文档链接](/documentation/baas/account/reservar_conta_pf) | CAB0005 e CAB0006 |
| QIC0003* | 开设个人账户 | 完成持有人为自然人的账户开户 | [文档链接](/documentation/baas/account/abrir_conta_pf) | QIC0002 |
| QIC0004* | 预留企业账户 | 申请预留持有人为法人的账户 | [文档链接](/documentation/baas/account/reservar_conta_pj) | CAB0005 e CAB0006 |
| QIC0005* | 开设企业账户 | 完成持有人为法人的账户开户 | [文档链接](/documentation/baas/account/abrir_conta_pj) | QIC0004 |
| QIC0006* | 读取开户 webhook | 正确读取开户 webhook | 第 1.2 或 1.3 项:<br/>[文档链接](/documentation/baas/account/webhooks) |  QIC0002 ou QIC0002  |
| QIC0007* | 列出账户 | 列出已开设账户 | [文档链接](/documentation/contas/consultar_conta) |  QIC0002 ou QIC0002  |
| QIC0008* | 查询账户数据 | 查询账户余额、持有人数据、开户日期等信息 | [文档链接](/documentation/contas/consultar_conta) |  QIC0002 ou QIC0002  |

## 交易

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| QIC0008* | 查询对账单 | 查询账户对账单 | [文档链接](/documentation/movimentacao_de_contas/consulta_de_transacoes) |  QIC0002 ou QIC0002  |
| QIC0009* | 申请转账凭证 | 申请转账凭证 | [文档链接](/documentation/movimentacao_de_contas/comprovante_de_transferencia)|  |
| QIC0010* | 读取交易 webhook | 成功接收所有交易 webhook |  [文档链接](/documentation/movimentacao_de_contas/webhook_movimentacoes/index.html) |  QIC0002 ou QIC0002  |
| QIC0011* | 查询金融机构列表 | 查询可接收 TED 和 Pix 的金融机构列表 |  [文档链接](/documentation/lista_de_instituicoes_financeiras/consulta_de_instituicoes_financeiras) |  QIC0002 ou QIC0002  |

---

# 文件上传

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| UDD0001* | 上传文件 | 通过文件 API 上传文件 |  [文档链接](/documentation/upload_de_documentos/) |  |

---

# TED

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- |-------------------------------------------------------------------------------------------------------------| --- |
| TED0001* | TED 转出 | 进行 TED 转账 | [文档链接](/documentation/baas/ted/realizar_transferencia) | QIC0002 ou QIC0002 |
| TED0002* | 模拟 TED 转出退回 | 模拟从 QI 账户发出的 TED 转出退款 | 第 3 项: <br/>[文档链接](/documentation/movimentacao_de_contas/transacao) |  |
| TED0003* | 模拟 TED 转入 | 模拟 TED 转入到 QI 账户 | 第 2 项: <br/>[文档链接](/documentation/movimentacao_de_contas/transacao) | QIC0002 ou QIC0002 |
| TED0004* | 列出 TED 交易 | 列出 TED 入账/出账交易 | [文档链接](/documentation/baas/ted/listar_teds)  | QIC0002 ou QIC0002 |
| TED0004* | 查询 TED 交易 | 查询一笔 TED 交易 | [文档链接](/documentation/baas/ted/consultar_ted)           | QIC0002 ou QIC0002 |
| TED0006* | 读取 TED webhook | 成功接收 TED webhook | [文档链接](/documentation/baas/ted/webhooks/index.html)| QIC0002 ou QIC0002 |
---

# 内部转账

| 编号 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| TFI0001 | 账户借记内部转账 | 从 QI 账户发起转账，目标为另一个 QI 账户 | [文档链接](/documentation/baas/ted/realizar_transferencia) |  QIC0002 ou QIC0002  |
| TFI0002 | 模拟账户贷记内部转账 | 模拟目标 QI 账户从另一个 QI 账户收款 | 第 1 项: <br/> [文档链接](/documentation/movimentacao_de_contas/transacao) |  QIC0002 ou QIC0002  |

---

# 票据

## 票据管理

| 编号 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| 编号      | 步骤 | 描述 | 链接  | 前置条件 |
|---|---|---|---|---|
| BOL0001 | 登记单张标准收款票据 | 登记一张收款票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao/index.html) | CAB0002 ou CAB0003   |
| BOL0002 | 登记单张即时收款票据 | 登记一张收款票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) | CAB0002 ou CAB0003   |
| BOL0003 | 批量登记收款票据 | 批量登记收款票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_em_lote) | CAB0002 ou CAB0003   |
| BOL0004 | 开具标准单张票据 | 开具标准单张票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao)  | CAB0002 ou CAB0003   |
| BOL0005 | 开具即时单张票据 | 开具即时单张票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) | CAB0002 ou CAB0003   |
| BOL0006 | 批量开具票据 | 批量开具票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_em_lote)| CAB0002 ou CAB0003   |
| BOL0007 | 对票据进行折扣减额 | 对票据进行折扣减额 | [文档链接](/documentation/boletos/v2/instrucoes/abatimento/criar_abatimento) | BOL0001, BOL0002 ou BOL0003 |
| BOL0008 | 取消票据折扣减额 | 取消票据折扣减额 | [文档链接](/documentation/boletos/v2/instrucoes/abatimento/cancelar_abatimento) | BOL0001, BOL0002 ou BOL0003  |
| BOL0009 | 延长票据到期日 | 延长票据到期日 | [文档链接](/documentation/boletos/v2/instrucoes/extensao)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0010 | 添加票据折扣 | 添加票据折扣 | [文档链接](/documentation/boletos/v2/instrucoes/desconto)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0011 | 添加票据利息 | 添加票据利息 | [文档链接](/documentation/boletos/v2/instrucoes/juros)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0012 | 添加票据罚金 | 添加票据罚金 | [文档链接](/documentation/boletos/v2/instrucoes/multa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0013 | 核销票据 | 核销票据 | [文档链接](/documentation/boletos/v2/instrucoes/baixa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0014 | 通过密钥查询票据 | 通过密钥查询票据 | [文档链接](/documentation/boletos/v2/consulta/consulta_por_chave) | BOL0001, BOL0002 ou BOL0003   |
| BOL0015 | 列出票据 | 列出票据 | [文档链接](/documentation/boletos/v2/consulta/listar_boletos) | BOL0001, BOL0002 ou BOL0003   |
| BOL0016 | 查询收款钱包 | 查询收款钱包 | [文档链接](/documentation/boletos/v2/carteira/listar_carteiras/index.html) | BOL0001, BOL0002 ou BOL0003   |
| BOL0017 | 票据 webhook | 读取票据 webhook | [文档链接](/documentation/boletos/v2/webhooks/boleto) | BOL0001, BOL0002 ou BOL0003   |

## 票据支付

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| BOL0009* | 查询可打印条形码 | 查询银行票据的可打印条形码 | [文档链接](/documentation/baas/cobranca/consultar_boleto_bancario) |  |
| BOL0010* | 支付票据 | 支付银行票据 | [文档链接](/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_boleto_bancario) |  QIC0002 ou QIC0002  |
| BOL0012* | 查询协议票据条形码 | 查询协议票据的可打印条形码 | [文档链接](/documentation/baas/cobranca/consultar_fatura_de_recolhimento) |  |
| BOL0013* | 支付协议票据 | 支付协议票据 | [文档链接](/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_fatura_de_recolhimento) |  QIC0002 ou QIC0002  |

---

## Pix

## Pix 转账
| 代码  | 步骤 | 描述 | 文档链接 | 前置条件 |
|---------|--|---|---|---|
| PIX0002* | Pix 转出 | 从 QI 账户使用银行数据（手动 Pix）或 Pix 密钥进行 Pix 转账 | [文档链接](/documentation/baas/pix/realizar_transferencia) | CAB0001 |
| PIX0035 | 查询 Pix 转账 | 获取一笔转账的数据 | [文档链接](/documentation/baas/pix/consultar_transferencias) | PIX0002 |
| PIX0003* | 模拟 Pix 转出退款 | 模拟 Pix 转出退款 | [文档链接 - 第 2 项](/documentation/pix/simulacao)| PIX0002 |
| PIX0004* | 模拟 Pix 转入 | 模拟 Pix 转入到 QI 账户 | [文档链接 -> 第 1 项](/documentation/pix/simulacao)||
| PIX0037* | 读取待处理交易 webhook | 成功接收待处理交易 webhook | [文档链接][(/documentation/baas/pix/webhooks) | PIX0002 |
| PIX0038* | 读取 Pix 转入 webhook | 成功接收 Pix 转入 webhook | [文档链接](/documentation/baas/pix/webhooks#webhook-para-pix-de-entrada)| PIX0004 |
| PIX0039 | 读取 Pix 退款 webhook | 成功接收 Pix 退款 webhook | [文档链接](/documentation/baas/pix/webhooks#webhook-para-devolu%C3%A7%C3%B5es-de-pix) | PIX0003 |
| PIX0040 | 申请退还已收 Pix | 申请退还已收 Pix | [文档链接](/documentation/baas/pix/solicitar_devolucao) | PIX0003 |
| PIX0041 | 列出账户的 Pix 转账 | 列出账户的 Pix 转账 | [文档链接](/documentation/baas/pix/listar_transferencias) | PIX0003 |

## Pix 密钥管理

### Pix 密钥的创建与删除

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0008* | 创建 Pix 密钥 | 创建 CPF、CNPJ、随机、邮件和电话类型的 Pix 密钥 | [文档链接](/documentation/pix/criar_chave) | 
|QIC0002 ou QIC0002  |](/documentation/baas/pix/consultar_chave_pix)
| PIX0009 | 删除 Pix 密钥 | 删除一个 Pix 密钥 | [文档链接](/documentation/pix/excluir_chave) | PIX0008 |
| PIX0010* | 列出 QI 账户的 Pix 密钥 | 列出绑定到 QI 账户的 Pix 密钥 | [文档链接](/documentation/pix/listar_chaves_pix) | PIX0008 |

### Pix 密钥可携带性

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0013* | 创建 Pix 密钥转入可携带性申请 | 创建 CPF、CNPJ、邮件、电话和随机类型 Pix 密钥的转入可携带性申请 | [文档链接](/documentation/pix/portabilidade#criando-um-pedido-de-portabilidade) |  QIC0002 ou QIC0002  |
| PIX0014* | 重新发送电话/邮箱类型 Pix 密钥转入可携带性申请的双因素认证 | 重新发送待处理 Pix 密钥转入可携带性申请（pending_claimer_validation）的短信（电话类型）或邮件（邮箱类型） | [文档链接](/documentation/pix/portabilidade#reenviando-a-valida%C3%A7%C3%A3o-de-dois-fatores) | PIX0013 |
| PIX0015* | 删除 Pix 密钥转入可携带性申请 | 删除待处理的 Pix 密钥转入可携带性申请 | [文档链接](/documentation/pix/portabilidade#deletando-um-pedido-de-portabilidade) | PIX0013 |
| PIX0016* | 读取 Pix 密钥转入可携带性申请完成 webhook | 正确读取 Pix 密钥转入可携带性申请完成 webhook，测试所有可能的完成状态（concluded、cancelled 和 failed） | Webhook: <br/> [文档链接](/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade) |PIX0013 |
| PIX0017* | 模拟 Pix 密钥转出可携带性申请 | 模拟接收 Pix 密钥转出可携带性申请 | 第 5 项:<br/> [文档链接](/documentation/pix/simulacao/index.html) | PIX0013 |
| PIX0018* | 批准和拒绝 Pix 密钥转出可携带性申请 | 批准 Pix 密钥转出可携带性申请 | [文档链接](/documentation/pix/portabilidade#request-4) | PIX0017 |
| PIX0019* | 重新发送 Pix 密钥转出可携带性申请的双因素认证 | 重新发送 Pix 密钥转出可携带性申请的双因素认证 | Enum "pending_donator_validation"  <br/> [文档链接](/documentation/pix/portabilidade#request-4) | PIX0018 |
| PIX0020* | 读取 Pix 密钥转出可携带性申请完成 webhook | 正确读取 Pix 密钥转出可携带性申请完成 webhook，测试所有可能的完成状态（concluded、cancelled 和 failed） | [文档链接](D/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade-1) | PIX0018 |

## Pix QR 码管理

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0022* | 创建静态 Pix QR 码 | 生成静态 QR 码 | [文档链接](/documentation/pix/criar_qr_code_estatico) | PIX0008 |
| PIX0023 | 创建动态 Pix QR 码 | 生成带到期日的动态 QR 码及即时动态 QR 码（带过期秒数） | [文档链接](/documentation/pix/criar_qr_code_dinamico) | PIX0008 |
| PIX0024 | 删除动态 Pix QR 码 | 删除 Pix QR 码 | [文档链接](/documentation/pix/baixar_qr_code_dinamico) | PIX0023 |
| PIX0025 | 列出动态 Pix QR 码 | 列出动态 Pix QR 码 | [文档链接](/documentation/pix/pesquisar_por_qr_code_dinamico) | PIX0023 |
| PIX0026 | 读取即时动态 Pix QR 码过期 webhook | 成功接收即时动态 Pix QR 码过期 webhook | [文档链接](/documentation/pix/webhook_por_qr_code_expirado) | PIX0023 |

## Pix QR 码支付

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |

| PIX0029* | 支付静态 Pix QR 码 | 支付静态 Pix QR 码 | [文档链接](/documentation/baas/pix/realizar_transferencia#transfer%C3%AAncia-por-qr-code-pix) | PIX0022 |
| PIX0030* | 支付动态 Pix QR 码 | 支付动态 Pix QR 码 |  [文档链接](/documentation/baas/pix/realizar_transferencia#transfer%C3%AAncia-por-qr-code-pix) | PIX0022 |
| PIX0027* | 解码 Pix QR 码 | 解码静态 Pix QR 码、带到期日动态 QR 码和即时动态 QR 码 | [文档链接](/documentation/pix/decodificar_qr_code) | PIX0022 e PIX0023 |

## Pix 限额管理

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0032* | 申请修改 Pix 限额 | 为 QI 账户发起 Pix 限额修改申请 | [文档链接](/documentation/pix/solicitar_alteracao_de_limite_pix) |  QIC0002 ou QIC0002  |
| PIX0033 | 列出 Pix 限额修改申请 | 列出 QI 账户的 Pix 限额修改申请 | [文档链接](/documentation/pix/busca_por_solicitacao_de_limite_pix) | PIX0032 |
| PIX0034* | 查询已用 Pix 限额 | 查询 QI 账户已用 Pix 限额 | [文档链接](/documentation/pix/busca_por_uso_de_limite_pix) |  QIC0002 ou QIC0002  |

---

# 费率管理
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| GTF0001* | 申请修改费率 | 修改账户费率 | [文档链接](/documentation/contas/gestao_de_tarifas) |  QIC0002 ou QIC0002  |
| GTF0002* | 查询费率 | 查询账户已注册的费率 | [文档链接](/documentation/contas/consulta_de_tarifas) |  QIC0002 ou QIC0002  |

# 卡片管理

## 创建卡片
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| GDC0001* | 创建虚拟卡 | 创建虚拟卡 | [文档链接](/documentation/cards/create/gerar_cartao_virtual) |  QIC0002 ou QIC0002  |
| GDC0002* | 创建实体卡 | 创建实体卡 | [文档链接](/documentation/cards/create/gerar_cartao_fisico) |  QIC0002 ou QIC0002  |

## 卡片查询
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| GDC0003* | 通过密钥查询卡片 | 查询卡片 | [文档链接](/documentation/cards/search/buscar_cartao_by_key) | GDC0001 ou GDC0002 |
| GDC0004* | 列出卡片 | 列出卡片 | [文档链接](/documentation/cards/search/listar_cartoes) | GDC0001 ou GDC0002 |
| GDC0005* | 查询卡片数据 | 查询卡片数据 | [文档链接](/documentation/cards/search/buscar_dados_pci) | GDC0001 ou GDC0002 |
| GDC0006* | 查询 PCI 密码 | 查询 PCI 密码 | [文档链接](/documentation/cards/search/buscar_senha) | GDC0001 ou GDC0002 |
| GDC0007* | 查询配送数据 | 查询配送数据 | [文档链接](/documentation/cards/search/buscar_entrega_by_key) | GDC0001 ou GDC0002 |

## 更新卡片数据
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| GDC0008* | 更新卡片状态 | 更新卡片状态 | [文档链接](/documentation/cards/status/update_status_cartao) | GDC0001 ou GDC0002 |
| GDC0009* | 激活实体卡 | 激活实体卡 | [文档链接](/documentation/cards/status/ativar_cartao) | GDC0001 ou GDC0002 |
| GDC0010* | 修改密码 | 修改卡片密码 | [文档链接](/documentation/cards/update/password_cartao) | GDC0001 ou GDC0002 |
| GDC0011* | 配置卡片非接触功能 | 配置卡片非接触功能 | [文档链接](/documentation/cards/update/contactless_cartao) | GDC0002 |

---

# 测试指南 - BaaS 数字账户（双重认证）

URL: /zh-Hans/documentation/roteiros_de_homologacao/conta_digital_2fa

测试指南描述了集成合作伙伴在进入生产环境之前，需要在 QI Tech 沙盒环境（测试环境）中测试的所有资源和功能。

本指南描述了该产品所涉及的所有资源和功能。

⚠️ **所有测试必须强制在 QI Tech 沙盒环境（测试环境）中进行。在沙盒环境中进行的操作均为虚拟金融操作，仅用于测试 API 功能。**

## BaaS API 注册与认证
| 代码  | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| CAB0001* | 在沙盒环境注册 | 在 QI Tech 平台 Sandbox 环境（sandbox.qitech.app）完成注册 | cs@qitech.com.br |
| CAB0002* | 在沙盒验证 token | 在 Sandbox 环境验证 QI Token | [文档链接](https://docs.qitech.com.br/assets/pdfs/QI%20Tech%20Manual%20Inclus%C3%A3o%20de%20Token.pdf) | CAB0001 |
| CAB0003* | 交换公钥 | 在 QI Tech 平台 Sandbox 环境（sandbox.qitech.app）完成公钥交换 | [文档链接](/documentation/primeiros_passos/troca_de_chaves) | CAB0001 e CAB0002 |
| CAB0004* | 完成 API 调用认证测试 | 完成 API 调用认证测试 | [文档链接](/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2) <br/><br/> [文档链接](/documentation/primeiros_passos/teste_de_autenticacao/endpoints_de_teste) | CAB0003 |
| CAB0005* | 配置 webhook | 通过 QI Tech 平台 Sandbox 环境（sandbox.qitech.app）配置 QI 发送 webhook 的 URL | [文档链接](/documentation/primeiros_passos/configurando_webhooks) | CAB0001 e CAB0002 |

## 反欺诈

## 注册与认证

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| ATF0002* | 获取 onboarding API 密钥 | 向 QI Tech 集成团队获取用于 /onboarding API 的 API 密钥 | suporte.caas@qitech.com.br |  
| ATF0003* | 获取 OCR 移动令牌 | 向 QI Tech 集成团队获取用于 OCR SDK 的移动令牌 | suporte.caas@qitech.com.br |  
| ATF0004* | 获取人脸识别移动令牌 | 向 QI Tech 集成团队获取用于人脸识别 SDK 的移动令牌 | suporte.caas@qitech.com.br |  
| ATF0005* | 获取设备扫描移动令牌 | 向 QI Tech 集成团队获取用于设备扫描 SDK 的移动令牌 | suporte.caas@qitech.com.br |  

## SDK OCR

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| ATF0007* | 构建 SDK | 定义文件采集的模板和自定义选项，并在您的应用中（QI Tech 客户应用）成功构建 SDK | Android: [文档链接](/documentation/caas/ocr/android/introduction) <br/> iOS:[ 文档链接](/documentation/caas/ocr/ios/introduction) |  |
| ATF0008* | 发送文件 | 在您的应用中（QI Tech 客户应用）使用 SDK 完成文件采集 |  | ATF0003 e ATF0007 |
| ATF0009* | 存储 ocr_key | 存储 SDK 返回的密钥，识别采集文件的类型（例如：cnh_front、cnh_back 等） | Android: [文档链接](/documentation/caas/ocr/android/collecting_response) <br/>iOS:[ 文档链接](/documentation/caas/ocr/ios/collecting_response)| ATF0008 |

## SDK 人脸识别

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| ATF0011* | 构建 SDK | 定义自定义选项并在您的应用中（QI Tech 客户应用）成功构建 SDK | Android: [文档链接](/documentation/caas/face_recognition/android/introduction) <br/>iOS:[ 文档链接](/documentation/caas/face_recognition/ios/introduction)  |  |
| ATF0012* | 活体检测流程 | 在您的应用中（QI Tech 客户应用）使用 SDK 完成活体检测流程 | | ATF0004 e ATF0011* |
| ATF0013* | 存储图像密钥 | 完成活体检测流程后，存储 SDK 返回的 image_key | Android: [文档链接](/documentation/caas/face_recognition/android/collecting_response) iOS:[ 文档链接](/documentation/caas/face_recognition/ios/collecting_response) | ATF0012 |

## SDK 设备扫描

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| ATF0015* | 构建 SDK | 定义您的应用（QI Tech 客户应用）向用户请求的权限，并在您的应用中成功构建 SDK | Android: [文档链接](/documentation/caas/device_scan/android/introduction)<br/>iOS:[ 文档链接](/documentation/caas/device_scan/ios/introduction)|  
| ATF0016* | 存储用户会话 | 存储待扫描设备的用户会话（sessionId） | Android: [文档链接](/documentation/caas/device_scan/android/example)<br/>iOS:[ 文档链接](/documentation/caas/device_scan/ios/example) | ATF0015 e ATF0017 |
| ATF0017* | 采集信息 | 使用已存储的 sessionId 实例化 SDK，并在您的应用中（QI Tech 客户应用）调用信息采集方法 | Android: [文档链接](/documentation/caas/face_recognition/android/collecting_response)<br/>iOS:[ 文档链接](/documentation/caas/face_recognition/ios/collecting_response) | ATF0005 e ATF0015 |

## 反欺诈

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| ATF0019* | 个人客户反欺诈 | 成功完成个人客户的反欺诈流程 | [文档链接](/documentation/caas/onboarding/natural_person) | ATF0002 |
| ATF0020* | 企业客户反欺诈 | 成功完成企业客户的反欺诈流程 | [文档链接](/documentation/caas/onboarding/legal_person) | ATF0002 |
| ATF0021* | 读取异步流程中的分析派生 webhook | 成功接收异步响应流程中的分析派生 webhook | [文档链接](/documentation/caas/onboarding/webhook) | ATF0019 ou ATF0020 |

## 平台注册

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| ATF0022* | 注册主用户 | 在 CaaS 平台注册主用户，用于处理转到"人工分析"的派生请求 | suporte.caas@qitech.com.br | ATF0019 ou ATF0020 |

---

# **QI Conta**

## 开户

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| QIC0002* | 预留个人账户 | 申请预留持有人为自然人的账户 | [文档链接](/documentation/baas/account/reservar_conta_pf) | CAB0005 e CAB0006 |
| QIC0003* | 开设个人账户 | 完成持有人为自然人的账户开户 | [文档链接](/documentation/baas/account/abrir_conta_pf) | QIC0002 |
| QIC0004* | 预留企业账户 | 申请预留持有人为法人的账户 | [文档链接](/documentation/baas/account/reservar_conta_pj) | CAB0005 e CAB0006 |
| QIC0005* | 开设企业账户 | 完成持有人为法人的账户开户 | [文档链接](/documentation/baas/account/abrir_conta_pj) | QIC0004 |
| QIC0006* | 读取开户 webhook | 正确读取开户 webhook | 第 1.2 或 1.3 项:<br/>[文档链接](/documentation/baas/account/webhooks) |  QIC0004 ou QIC0005  |
| QIC0007* | 列出账户 | 列出已开设账户 | [文档链接](/documentation/contas/consultar_conta) |  QIC0004 ou QIC0005  |
| QIC0008* | 查询账户数据 | 查询账户余额、持有人数据、开户日期等信息 | [文档链接](/documentation/contas/consultar_conta) |  QIC0004 ou QIC0005  |

## 交易

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| QIC0008* | 查询对账单 | 查询账户对账单 | [文档链接](/documentation/movimentacao_de_contas/consulta_de_transacoes) |  QIC0004 ou QIC0005  |
| QIC0009* | 申请转账凭证 | 申请转账凭证 | [文档链接](/documentation/movimentacao_de_contas/comprovante_de_transferencia)|  |
| QIC0010* | 读取交易 webhook | 成功接收所有交易 webhook |  [文档链接](/documentation/movimentacao_de_contas/webhook_movimentacoes/index.html) |  QIC0004 ou QIC0005  |
| QIC0011* | 查询金融机构列表 | 查询可接收 TED 和 Pix 的金融机构列表 |  [文档链接](/documentation/lista_de_instituicoes_financeiras/consulta_de_instituicoes_financeiras) |  QIC0004 ou QIC0005  |

---

# 文件上传

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| UDD0001* | 上传文件 | 通过文件 API 上传文件 |  [文档链接](/documentation/upload_de_documentos/) |  |

---

# TED

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- |-------------------------------------------------------------------------------------------------------------| --- |
| TED0001* | TED 转出 | 进行 TED 转账 | 1 . 创建转账申请: [文档链接](/documentation/baas/ted/realizar_transferencia_2fa) <br/>   2 . 审批转账: [文档链接](/documentation/baas/ted/realizar_transferencia_2fa) <br/>           | QIC0004 ou QIC0005 |
| TED0006* | 申请重新发送令牌 | 重新发送 TED 转账审批令牌 | [文档链接](/documentation/baas/ted/2fa/solicitacao_de_reenvio_de_token) | TED0001 |
| TED0002* | 模拟 TED 转出退回 | 模拟从 QI 账户发出的 TED 转出退款 | 第 3 项: <br/>[文档链接](/documentation/movimentacao_de_contas/transacao) |  |
| TED0003* | 模拟 TED 转入 | 模拟 TED 转入到 QI 账户 | 第 2 项: <br/>[文档链接](/documentation/movimentacao_de_contas/transacao) | QIC0004 ou QIC0005 |
| TED0004* | 列出 TED 交易 | 列出 TED 入账/出账交易 | [文档链接](/documentation/baas/ted/listar_teds)  | QIC0004 ou QIC0005 |
| TED0004* | 查询 TED 交易 | 查询一笔 TED 交易 | [文档链接](/documentation/baas/ted/consultar_ted)           | QIC0004 ou QIC0005 |
| TED0006* | 读取 TED webhook | 成功接收 TED webhook | [文档链接](/documentation/baas/ted/webhooks/index.html)| QIC0004 ou QIC0005 |
---

# 内部转账

| 编号 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| TFI0001 | 账户借记内部转账 | 从 QI 账户发起转账，目标为另一个 QI 账户 |  1 . 创建转账申请: [文档链接](/documentation/baas/ted/realizar_transferencia_2fa) <br/>   2 . 审批转账: [文档链接](/documentation/baas/ted/realizar_transferencia_2fa) <br/> |  QIC0004 ou QIC0005  |
| TFI0002 | 模拟账户贷记内部转账 | 模拟目标 QI 账户从另一个 QI 账户收款 | 第 1 项: <br/> [文档链接](/documentation/movimentacao_de_contas/transacao) |  QIC0004 ou QIC0005  |

---

# 票据

## 票据管理

| 编号 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| 编号      | 步骤 | 描述 | 链接  | 前置条件 |
|---|---|---|---|---|
| BOL0001 | 登记单张标准收款票据 | 登记一张收款票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao/index.html) |QIC0004 ou QIC0005   |
| BOL0002 | 登记单张即时收款票据 | 登记一张收款票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) |QIC0004 ou QIC0005   |
| BOL0003 | 批量登记收款票据 | 批量登记收款票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_em_lote) |QIC0004 ou QIC0005   |
| BOL0004 | 开具标准单张票据 | 开具标准单张票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao)  |QIC0004 ou QIC0005   |
| BOL0005 | 开具即时单张票据 | 开具即时单张票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) |QIC0004 ou QIC0005   |
| BOL0006 | 批量开具票据 | 批量开具票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_em_lote)|QIC0004 ou QIC0005   |
| BOL0007 | 对票据进行折扣减额 | 对票据进行折扣减额 | [文档链接](/documentation/boletos/v2/instrucoes/abatimento/criar_abatimento) | BOL0001, BOL0002 ou BOL0003 |
| BOL0008 | 取消票据折扣减额 | 取消票据折扣减额 | [文档链接](/documentation/boletos/v2/instrucoes/abatimento/cancelar_abatimento) | BOL0001, BOL0002 ou BOL0003  |
| BOL0009 | 延长票据到期日 | 延长票据到期日 | [文档链接](/documentation/boletos/v2/instrucoes/extensao)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0010 | 添加票据折扣 | 添加票据折扣 | [文档链接](/documentation/boletos/v2/instrucoes/desconto)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0011 | 添加票据利息 | 添加票据利息 | [文档链接](/documentation/boletos/v2/instrucoes/juros)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0012 | 添加票据罚金 | 添加票据罚金 | [文档链接](/documentation/boletos/v2/instrucoes/multa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0013 | 核销票据 | 核销票据 | [文档链接](/documentation/boletos/v2/instrucoes/baixa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0014 | 通过密钥查询票据 | 通过密钥查询票据 | [文档链接](/documentation/boletos/v2/consulta/consulta_por_chave) | BOL0001, BOL0002 ou BOL0003   |
| BOL0015 | 列出票据 | 列出票据 | [文档链接](/documentation/boletos/v2/consulta/listar_boletos) | BOL0001, BOL0002 ou BOL0003   |
| BOL0016 | 查询收款钱包 | 查询收款钱包 | [文档链接](/documentation/boletos/v2/carteira/listar_carteiras/index.html) | BOL0001, BOL0002 ou BOL0003   |
| BOL0017 | 票据 webhook | 读取票据 webhook | [文档链接](/documentation/boletos/v2/webhooks/boleto) | BOL0001, BOL0002 ou BOL0003   |

## 票据支付

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| BOL0009* | 查询可打印条形码 | 查询银行票据的可打印条形码 | [文档链接](/documentation/baas/cobranca/consultar_boleto_bancario) |  |
| BOL0010* | 申请票据支付令牌 | 申请银行票据支付令牌 | [文档链接](/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_boleto_bancario) |  QIC0004 ou QIC0005  |
| BOL0011* | 审批票据支付 | 申请银行票据支付令牌 | [文档链接](/documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_boleto_bancario) |  QIC0004 ou QIC0005  |
| BOL0012* | 查询协议票据条形码 | 查询协议票据的可打印条形码 | [文档链接](/documentation/baas/cobranca/consultar_fatura_de_recolhimento) |  |
| BOL0013* | 申请协议票据支付令牌 | 申请协议票据支付令牌 | [文档链接](/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_fatura_de_recolhimento) |  QIC0004 ou QIC0005  |
| BOL0014* | 审批协议票据支付 | 申请协议票据支付令牌 | [文档链接](/documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_fatura_de_recolhimento) |  QIC0004 ou QIC0005  |

---

## Pix

## Pix 转账
| 代码  | 步骤 | 描述 | 文档链接 | 前置条件 |
|---------|--|---|---|---|
| PIX0002* | Pix 转出 | 从 QI 账户使用银行数据（手动 Pix）或 Pix 密钥进行 Pix 转账 | [1. 申请转账](/documentation/baas/pix/2fa_v2/solicitacao_de_transacao_pix_2fa) <br></br> [2. 审批转账](/documentation/baas/pix/2fa_v2/aprovar_transacao_pix_2fa) | CAB0001 |
| PIX0035 | 查询 Pix 转账 | 获取一笔转账的数据 | [文档链接](/documentation/baas/pix/consultar_transferencias) | PIX0002 |
| PIX0003* | 模拟 Pix 转出退款 | 模拟 Pix 转出退款 | [文档链接 - 第 2 项](/documentation/pix/simulacao)| PIX0002 |
| PIX0004* | 模拟 Pix 转入 | 模拟 Pix 转入到 QI 账户 | [文档链接 -> 第 1 项](/documentation/pix/simulacao)||
| PIX0037* | 读取待处理交易 webhook | 成功接收待处理交易 webhook | [文档链接][(/documentation/baas/pix/webhooks) | PIX0002 |
| PIX0038* | 读取 Pix 转入 webhook | 成功接收 Pix 转入 webhook | [文档链接](/documentation/baas/pix/webhooks#webhook-para-pix-de-entrada)| PIX0004 |
| PIX0039 | 读取 Pix 退款 webhook | 成功接收 Pix 退款 webhook | [文档链接](/documentation/baas/pix/webhooks#webhook-para-devolu%C3%A7%C3%B5es-de-pix) | PIX0003 |
| PIX0040 | 申请退还已收 Pix | 申请退还已收 Pix | [1. 申请退款](/documentation/baas/pix/2fa_v2/solicitacao_de_devolucao_pix) <br></br> [2. 审批退款](/documentation/baas/pix/2fa_v2/aprovar_transacao_pix_2fa) | PIX0003 |
| PIX0041 | 列出账户的 Pix 转账 | 列出账户的 Pix 转账 | [文档链接](/documentation/baas/pix/listar_transferencias) | PIX0003 |

## Pix 密钥管理

### Pix 密钥的创建与删除

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0008* | 创建 Pix 密钥 | 创建 CPF、CNPJ、随机、邮件和电话类型的 Pix 密钥 | [文档链接](/documentation/pix/criar_chave) | 
|QIC0004 ou QIC0005  |](/documentation/baas/pix/consultar_chave_pix)
| PIX0009 | 删除 Pix 密钥 | 删除一个 Pix 密钥 | [文档链接](/documentation/pix/excluir_chave) | PIX0008 |
| PIX0010* | 列出 QI 账户的 Pix 密钥 | 列出绑定到 QI 账户的 Pix 密钥 | [文档链接](/documentation/pix/listar_chaves_pix) | PIX0008 |

### Pix 密钥可携带性

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0013* | 创建 Pix 密钥转入可携带性申请 | 创建 CPF、CNPJ、邮件、电话和随机类型 Pix 密钥的转入可携带性申请 | [文档链接](/documentation/pix/portabilidade#criando-um-pedido-de-portabilidade) |  QIC0004 ou QIC0005  |
| PIX0014* | 重新发送电话/邮箱类型 Pix 密钥转入可携带性申请的双因素认证 | 重新发送待处理 Pix 密钥转入可携带性申请（pending_claimer_validation）的短信（电话类型）或邮件（邮箱类型） | [文档链接](/documentation/pix/portabilidade#reenviando-a-valida%C3%A7%C3%A3o-de-dois-fatores) | PIX0013 |
| PIX0015* | 删除 Pix 密钥转入可携带性申请 | 删除待处理的 Pix 密钥转入可携带性申请 | [文档链接](/documentation/pix/portabilidade#deletando-um-pedido-de-portabilidade) | PIX0013 |
| PIX0016* | 读取 Pix 密钥转入可携带性申请完成 webhook | 正确读取 Pix 密钥转入可携带性申请完成 webhook，测试所有可能的完成状态（concluded、cancelled 和 failed） | Webhook: <br/> [文档链接](/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade) |PIX0013 |
| PIX0017* | 模拟 Pix 密钥转出可携带性申请 | 模拟接收 Pix 密钥转出可携带性申请 | 第 5 项:<br/> [文档链接](/documentation/pix/simulacao/index.html) | PIX0013 |
| PIX0018* | 批准和拒绝 Pix 密钥转出可携带性申请 | 批准 Pix 密钥转出可携带性申请 | [文档链接](/documentation/pix/portabilidade#request-4) | PIX0017 |
| PIX0019* | 重新发送 Pix 密钥转出可携带性申请的双因素认证 | 重新发送 Pix 密钥转出可携带性申请的双因素认证 | Enum "pending_donator_validation"  <br/> [文档链接](/documentation/pix/portabilidade#request-4) | PIX0018 |
| PIX0020* | 读取 Pix 密钥转出可携带性申请完成 webhook | 正确读取 Pix 密钥转出可携带性申请完成 webhook，测试所有可能的完成状态（concluded、cancelled 和 failed） | [文档链接](D/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade-1) | PIX0018 |

## Pix QR 码管理

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0022* | 创建静态 Pix QR 码 | 生成静态 QR 码 | [文档链接](/documentation/pix/criar_qr_code_estatico) | PIX0008 |
| PIX0023 | 创建动态 Pix QR 码 | 生成带到期日的动态 QR 码及即时动态 QR 码（带过期秒数） | [文档链接](/documentation/pix/criar_qr_code_dinamico) | PIX0008 |
| PIX0024 | 删除动态 Pix QR 码 | 删除 Pix QR 码 | [文档链接](/documentation/pix/baixar_qr_code_dinamico) | PIX0023 |
| PIX0025 | 列出动态 Pix QR 码 | 列出动态 Pix QR 码 | [文档链接](/documentation/pix/pesquisar_por_qr_code_dinamico) | PIX0023 |
| PIX0026 | 读取即时动态 Pix QR 码过期 webhook | 成功接收即时动态 Pix QR 码过期 webhook | [文档链接](/documentation/pix/webhook_por_qr_code_expirado) | PIX0023 |

## Pix QR 码支付

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0029* | 支付静态 Pix QR 码 | 支付静态 Pix QR 码 | [1. 申请转账](/documentation/baas/pix/2fa_v2/solicitacao_de_transacao_pix_2fa) <br></br> [2. 审批转账](/documentation/baas/pix/2fa_v2/aprovar_transacao_pix_2fa) | PIX0022 |
| PIX0030* | 支付动态 Pix QR 码 | 支付动态 Pix QR 码 |  [1. 申请转账](/documentation/baas/pix/2fa_v2/solicitacao_de_transacao_pix_2fa) <br></br> [2. 审批转账](/documentation/baas/pix/2fa_v2/aprovar_transacao_pix_2fa) | PIX0022 |
| PIX0027* | 解码 Pix QR 码 | 解码静态 Pix QR 码、带到期日动态 QR 码和即时动态 QR 码 | [文档链接](/documentation/pix/decodificar_qr_code) | PIX0022 e PIX0023 |

## Pix 限额管理

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0032* | 申请修改 Pix 限额 | 为 QI 账户发起 Pix 限额修改申请 | [文档链接](/documentation/pix/solicitar_alteracao_de_limite_pix) |  QIC0004 ou QIC0005  |
| PIX0033 | 列出 Pix 限额修改申请 | 列出 QI 账户的 Pix 限额修改申请 | [文档链接](/documentation/pix/busca_por_solicitacao_de_limite_pix) | PIX0032 |
| PIX0034* | 查询已用 Pix 限额 | 查询 QI 账户已用 Pix 限额 | [文档链接](/documentation/pix/busca_por_uso_de_limite_pix) |  QIC0004 ou QIC0005  |

---

# 费率管理
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| GTF0001* | 申请修改费率 | 修改账户费率 | [文档链接](/documentation/contas/gestao_de_tarifas) |  QIC0004 ou QIC0005  |
| GTF0002* | 查询费率 | 查询账户已注册的费率 | [文档链接](/documentation/contas/consulta_de_tarifas) |  QIC0004 ou QIC0005  |

## 管理员用户管理
| GUA0001* | 添加管理员用户 | 创建管理员用户并绑定到 QI 账户 | 简介: [文档](/documentation/gestao_de_usuarios/tfa_introducao)<br/>1. 创建: [文档](/documentation/gestao_de_usuarios/criacao_de_pessoa)<br/>2. 添加: [文档](/documentation/gestao_de_usuarios/inclusao_de_vinculo) |QIC0004 ou QIC0005 |
| GUA0002* | 修改管理员联系信息 | 修改管理员用户的联系信息（邮件和电话） | [文档链接](/documentation/gestao_de_usuarios/alteracao_de_contato_de_vinculo) |  |
| GUA0003* | 删除管理员用户 | 解除管理员用户与 QI 账户的绑定关系 | [文档链接](/documentation/gestao_de_usuarios/exclusao_de_vinculo) |  |

# 卡片管理

## 创建卡片
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| GDC0001* | 创建虚拟卡 | 创建虚拟卡 | [文档链接](/documentation/cards/create/gerar_cartao_virtual) |  QIC0004 ou QIC0005  |
| GDC0002* | 创建实体卡 | 创建实体卡 | [文档链接](/documentation/cards/create/gerar_cartao_fisico) |  QIC0004 ou QIC0005  |

## 卡片查询
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| GDC0003* | 通过密钥查询卡片 | 查询卡片 | [文档链接](/documentation/cards/search/buscar_cartao_by_key) | GDC0001 ou GDC0002 |
| GDC0004* | 列出卡片 | 列出卡片 | [文档链接](/documentation/cards/search/listar_cartoes) | GDC0001 ou GDC0002 |
| GDC0005* | 查询卡片数据 | 查询卡片数据 | [文档链接](/documentation/cards/search/buscar_dados_pci) | GDC0001 ou GDC0002 |
| GDC0006* | 查询 PCI 密码 | 查询 PCI 密码 | [文档链接](/documentation/cards/search/buscar_senha) | GDC0001 ou GDC0002 |
| GDC0007* | 查询配送数据 | 查询配送数据 | [文档链接](/documentation/cards/search/buscar_entrega_by_key) | GDC0001 ou GDC0002 |

## 更新卡片数据
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| GDC0008* | 更新卡片状态 | 更新卡片状态 | [文档链接](/documentation/cards/status/update_status_cartao) | GDC0001 ou GDC0002 |
| GDC0009* | 激活实体卡 | 激活实体卡 | [文档链接](/documentation/cards/status/ativar_cartao) | GDC0001 ou GDC0002 |
| GDC0010* | 修改密码 | 修改卡片密码 | [文档链接](/documentation/cards/update/password_cartao) | GDC0001 ou GDC0002 |
| GDC0011* | 配置卡片非接触功能 | 配置卡片非接触功能 | [文档链接](/documentation/cards/update/contactless_cartao) | GDC0002 |

---

# 测试指南 - BaaS 数字账户（双重认证）

URL: /zh-Hans/documentation/roteiros_de_homologacao/conta_digital_2fa_baas

测试指南描述了集成合作伙伴在进入生产环境之前，需要在 QI Tech 沙盒环境（测试环境）中测试的所有资源和功能。

本指南描述了该产品所涉及的所有资源和功能。

⚠️ **所有测试必须强制在 QI Tech 沙盒环境（测试环境）中进行。在沙盒环境中进行的操作均为虚拟金融操作，仅用于测试 API 功能。**

## BaaS API 注册与认证
| 代码  | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| CAB0001* | 在沙盒环境注册 | 在 QI Tech 平台 Sandbox 环境（sandbox.qitech.app）完成注册 | cs@qitech.com.br |
| CAB0002* | 在沙盒验证 token | 在 Sandbox 环境验证 QI Token | [文档链接](https://docs.qitech.com.br/assets/pdfs/QI%20Tech%20Manual%20Inclus%C3%A3o%20de%20Token.pdf) | CAB0001 |
| CAB0003* | 交换公钥 | 在 QI Tech 平台 Sandbox 环境（sandbox.qitech.app）完成公钥交换 | [文档链接](/documentation/primeiros_passos/troca_de_chaves) | CAB0001 e CAB0002 |
| CAB0004* | 完成 API 调用认证测试 | 完成 API 调用认证测试 |[文档链接](/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2) <br/><br/> [文档链接](/documentation/primeiros_passos/teste_de_autenticacao/endpoints_de_teste) | CAB0003 |
| CAB0005* | 配置 webhook | 通过 QI Tech 平台 Sandbox 环境（sandbox.qitech.app）配置 QI 发送 webhook 的 URL | [文档链接](/documentation/primeiros_passos/configurando_webhooks) | CAB0001 e CAB0002 |

# **QI Conta**

## 开户

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| QIC0002* | 预留个人账户 | 申请预留持有人为自然人的账户 | [文档链接](/documentation/baas/account/reservar_conta_pf) | CAB0005 e CAB0006 |
| QIC0003* | 开设个人账户 | 完成持有人为自然人的账户开户 | [文档链接](/documentation/baas/account/abrir_conta_pf) | QIC0002 |
| QIC0004* | 预留企业账户 | 申请预留持有人为法人的账户 | [文档链接](/documentation/baas/account/reservar_conta_pj) | CAB0005 e CAB0006 |
| QIC0005* | 开设企业账户 | 完成持有人为法人的账户开户 | [文档链接](/documentation/baas/account/abrir_conta_pj) | QIC0004 |
| QIC0006* | 读取开户 webhook | 正确读取开户 webhook | 第 1.2. 或 1.3 项：<br/>[文档链接](/documentation/baas/account/webhooks) |  QIC0004 ou QIC0005  |
| QIC0007* | 列出账户 | 列出已开设账户 | [文档链接](/documentation/contas/consultar_conta) |  QIC0004 ou QIC0005  |
| QIC0008* | 查询账户数据 | 查询账户余额、持有人数据、开户日期等信息 | [文档链接](/documentation/contas/consultar_conta) |  QIC0004 ou QIC0005  |

## 交易

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| QIC0008* | 查询对账单 | 查询账户对账单 | [文档链接](/documentation/movimentacao_de_contas/consulta_de_transacoes) |  QIC0004 ou QIC0005  |
| QIC0009* | 申请转账凭证 | 申请转账凭证 | [文档链接](/documentation/movimentacao_de_contas/comprovante_de_transferencia)|  |
| QIC0010* | 读取交易 webhook | 成功接收所有交易 webhook |  [文档链接](/documentation/movimentacao_de_contas/webhook_movimentacoes/index.html) |  QIC0004 ou QIC0005  |
| QIC0011* | 查询金融机构列表 | 查询可接收 TED 和 Pix 的金融机构列表 |  [文档链接](/documentation/lista_de_instituicoes_financeiras/consulta_de_instituicoes_financeiras) |  QIC0004 ou QIC0005  |

---

# 文件上传

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| UDD0001* | 上传文件 | 通过文件 API 上传文件 |  [文档链接](/documentation/upload_de_documentos/) |  |

---

# TED

| 代码 | 步骤 | 描述 | 链接                                                                                                        | 前置条件 |
| --- | --- | --- |-------------------------------------------------------------------------------------------------------------| --- |
| TED0001* | TED 转出 | 进行 TED 转账  | 1 . 创建转账申请：[文档链接](/documentation/baas/ted/realizar_transferencia_2fa) <br/>   2 . 审批转账：[文档链接](/documentation/baas/ted/realizar_transferencia_2fa) <br/>           | QIC0004 ou QIC0005 |
| TED0006* | 申请重新发送令牌 | 重新发送 TED 转账审批令牌 | [文档链接](/documentation/baas/ted/2fa/solicitacao_de_reenvio_de_token) | TED0001 |
| TED0002* | 模拟 TED 转出退回 | 模拟从 QI 账户发出的 TED 转出退款 | 第 3 项：<br/>[文档链接](/documentation/movimentacao_de_contas/transacao) |  |
| TED0003* | 模拟 TED 转入 | 模拟 TED 转入到 QI 账户 | 第 2 项：<br/>[文档链接](/documentation/movimentacao_de_contas/transacao) | QIC0004 ou QIC0005 |
| TED0004* | 列出 TED 交易 | 列出 TED 入账/出账交易  | [文档链接](/documentation/baas/ted/listar_teds)  | QIC0004 ou QIC0005 |
| TED0004* | 查询 TED 交易 | 查询一笔 TED 交易  | [文档链接](/documentation/baas/ted/consultar_ted)           | QIC0004 ou QIC0005 |
| TED0006* | 读取 TED webhook | 成功接收 TED webhook | [文档链接](/documentation/baas/ted/webhooks/index.html)| QIC0004 ou QIC0005 |
---

# 内部转账

| 编号 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| TFI0001 | 账户借记内部转账 | 从 QI 账户发起转账，目标为另一个 QI 账户 |  1 . 创建转账申请：[文档链接](/documentation/baas/ted/realizar_transferencia_2fa) <br/>   2 . 审批转账：[文档链接](/documentation/baas/ted/realizar_transferencia_2fa) <br/> |  QIC0004 ou QIC0005  |
| TFI0002 | 模拟账户贷记内部转账 | 模拟目标 QI 账户从另一个 QI 账户收款 | 第 1 项：<br/> [文档链接](/documentation/movimentacao_de_contas/transacao) |  QIC0004 ou QIC0005  |

---

# 票据

## 票据管理

| 编号 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| 编号      | 步骤 | 描述 | 链接  | 前置条件 |
|---|---|---|---|---|
| BOL0001 | 登记单张标准收款票据    | 登记一张收款票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao/index.html) |QIC0004 ou QIC0005   |
| BOL0002 | 登记单张即时收款票据 | 登记一张收款票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) |QIC0004 ou QIC0005   |
| BOL0003 | 批量登记收款票据  | 批量登记收款票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_em_lote) |QIC0004 ou QIC0005   |
| BOL0004 | 开具标准单张票据        | 开具标准单张票据    | [文档链接](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao)  |QIC0004 ou QIC0005   |
| BOL0005 | 开具即时单张票据   | 开具即时单张票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) |QIC0004 ou QIC0005   |
| BOL0006 | 批量开具票据   | 批量开具票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_em_lote)|QIC0004 ou QIC0005   |
| BOL0007 | 对票据进行折扣减额 | 对票据进行折扣减额 | [文档链接](/documentation/boletos/v2/instrucoes/abatimento/criar_abatimento) | BOL0001, BOL0002 ou BOL0003 |
| BOL0008 | 取消票据折扣减额     | 取消票据折扣减额 | [文档链接](/documentation/boletos/v2/instrucoes/abatimento/cancelar_abatimento) | BOL0001, BOL0002 ou BOL0003  |
| BOL0009 | 延长票据到期日               | 延长票据到期日 | [文档链接](/documentation/boletos/v2/instrucoes/extensao)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0010 | 添加票据折扣               | 添加票据折扣    | [文档链接](/documentation/boletos/v2/instrucoes/desconto)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0011 | 添加票据利息                   | 添加票据利息       | [文档链接](/documentation/boletos/v2/instrucoes/juros)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0012 | 添加票据罚金                   | 添加票据罚金       | [文档链接](/documentation/boletos/v2/instrucoes/multa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0013 | 核销票据                   | 核销票据                 | [文档链接](/documentation/boletos/v2/instrucoes/baixa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0014 | 通过密钥查询票据      | 通过密钥查询票据      | [文档链接](/documentation/boletos/v2/consulta/consulta_por_chave) | BOL0001, BOL0002 ou BOL0003   |
| BOL0015 | 列出票据          | 列出票据     | [文档链接](/documentation/boletos/v2/consulta/listar_boletos) | BOL0001, BOL0002 ou BOL0003   |
| BOL0016 | 查询收款钱包      | 查询收款钱包 | [文档链接](/documentation/boletos/v2/carteira/listar_carteiras/index.html) | BOL0001, BOL0002 ou BOL0003   |
| BOL0017 | 票据 webhook      | 读取票据 webhook | [文档链接](/documentation/boletos/v2/webhooks/boleto) | BOL0001, BOL0002 ou BOL0003   |

## 票据支付

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| BOL0009* | 查询可打印条形码 | 查询银行票据的可打印条形码 | [文档链接](/documentation/baas/cobranca/consultar_boleto_bancario) |  |
| BOL0010* | 申请票据支付令牌 | 申请银行票据支付令牌 | [文档链接](/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_boleto_bancario) |  QIC0004 ou QIC0005  |
| BOL0011* | 审批票据支付 | 申请银行票据支付令牌  | [文档链接](/documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_boleto_bancario) |  QIC0004 ou QIC0005  |
| BOL0012* | 查询协议票据条形码 | 查询协议票据的可打印条形码 | [文档链接](/documentation/baas/cobranca/consultar_fatura_de_recolhimento) |  |
| BOL0013* | 申请协议票据支付令牌 | 申请协议票据支付令牌 | [文档链接](/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_fatura_de_recolhimento) |  QIC0004 ou QIC0005  |
| BOL0014* | 审批协议票据支付 | 申请协议票据支付令牌  | [文档链接](/documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_fatura_de_recolhimento) |  QIC0004 ou QIC0005  |

---

## Pix

## Pix 转账
| 代码  | 步骤 | 描述 | 文档链接 | 前置条件 |
|---------|--|---|---|---|
| PIX0002* | Pix 转出 | 从 QI 账户使用银行数据（手动 Pix）或 Pix 密钥进行 Pix 转账 | [1. 申请转账](/documentation/baas/pix/2fa_v2/solicitacao_de_transacao_pix_2fa) <br></br> [2. 审批转账](/documentation/baas/pix/2fa_v2/aprovar_transacao_pix_2fa) | CAB0001 |
| PIX0035 | 查询 Pix 转账 | 获取一笔转账的数据 | [文档链接](/documentation/baas/pix/consultar_transferencias) | PIX0002 |
| PIX0003* | 模拟 Pix 转出退款 | 模拟 Pix 转出退款 | [文档链接 - 第 2 项](/documentation/pix/simulacao)| PIX0002 |
| PIX0004* | 模拟 Pix 转入 | 模拟 Pix 转入到 QI 账户 | [文档链接 -> 第 1 项](/documentation/pix/simulacao)||
| PIX0037* | 读取待处理交易 webhook | 成功接收待处理交易 webhook | [文档链接][(/documentation/baas/pix/webhooks) | PIX0002 |
| PIX0038* | 读取 Pix 转入 webhook | 成功接收 Pix 转入 webhook | [文档链接](/documentation/baas/pix/webhooks#webhook-para-pix-de-entrada)| PIX0004 |
| PIX0039 | 读取 Pix 退款 webhook | 成功接收 Pix 退款 webhook | [文档链接](/documentation/baas/pix/webhooks#webhook-para-devolu%C3%A7%C3%B5es-de-pix) | PIX0003 |
| PIX0040 | 申请退还已收 Pix | 申请退还已收 Pix | [1. 申请退款](/documentation/baas/pix/2fa_v2/solicitacao_de_devolucao_pix) <br></br> [2. 审批退款](/documentation/baas/pix/2fa_v2/aprovar_transacao_pix_2fa) | PIX0003 |
| PIX0041 | 列出账户的 Pix 转账 | 列出账户的 Pix 转账 | [文档链接](/documentation/baas/pix/listar_transferencias) | PIX0003 |

## Pix 密钥管理

### Pix 密钥的创建与删除

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0008* | 创建 Pix 密钥 | 创建 CPF、CNPJ、随机、邮件和电话类型的 Pix 密钥 | [文档链接](/documentation/pix/criar_chave) | 
|QIC0004 ou QIC0005  |](/documentation/baas/pix/consultar_chave_pix)
| PIX0009 | 删除 Pix 密钥 | 删除一个 Pix 密钥 | [文档链接](/documentation/pix/excluir_chave) | PIX0008 |
| PIX0010* | 列出 QI 账户的 Pix 密钥 | 列出绑定到 QI 账户的 Pix 密钥 | [文档链接](/documentation/pix/listar_chaves_pix) | PIX0008 |

### Pix 密钥可携带性

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0013* | 创建 Pix 密钥转入可携带性申请 | 创建 CPF、CNPJ、邮件、电话和随机类型 Pix 密钥的转入可携带性申请 | [文档链接](/documentation/pix/portabilidade#criando-um-pedido-de-portabilidade) |  QIC0004 ou QIC0005  |
| PIX0014* | 重新发送电话/邮箱类型 Pix 密钥转入可携带性申请的双因素认证 | 重新发送待处理 Pix 密钥转入可携带性申请的短信（电话类型）或邮件（邮箱类型） | [文档链接](/documentation/pix/portabilidade#reenviando-a-valida%C3%A7%C3%A3o-de-dois-fatores) | PIX0013 |
| PIX0015* | 删除 Pix 密钥转入可携带性申请 | 删除待处理的 Pix 密钥转入可携带性申请 | [文档链接](/documentation/pix/portabilidade#deletando-um-pedido-de-portabilidade) | PIX0013 |
| PIX0016* | 读取 Pix 密钥转入可携带性申请完成 webhook | 正确读取 Pix 密钥转入可携带性申请完成 webhook，测试所有可能的完成状态 | Webhook：<br/> [文档链接](/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade) |PIX0013 |
| PIX0017* | 模拟 Pix 密钥转出可携带性申请 | 模拟接收 Pix 密钥转出可携带性申请 | 第 5 项：<br/> [文档链接](/documentation/pix/simulacao/index.html) | PIX0013 |
| PIX0018* | 批准和拒绝 Pix 密钥转出可携带性申请 | 批准 Pix 密钥转出可携带性申请 | [文档链接](/documentation/pix/portabilidade#request-4) | PIX0017 |
| PIX0019* | 重新发送 Pix 密钥转出可携带性申请的双因素认证 | 重新发送 Pix 密钥转出可携带性申请的双因素认证 | Enum "pending_donator_validation"  <br/> [文档链接](/documentation/pix/portabilidade#request-4) | PIX0018 |
| PIX0020* | 读取 Pix 密钥转出可携带性申请完成 webhook | 正确读取 Pix 密钥转出可携带性申请完成 webhook，测试所有可能的完成状态 | [文档链接](D/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade-1) | PIX0018 |

## Pix QR 码管理

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0022* | 创建静态 Pix QR 码 | 生成静态 QR 码 | [文档链接](/documentation/pix/criar_qr_code_estatico) | PIX0008 |
| PIX0023 | 创建动态 Pix QR 码 | 生成带到期日的动态 QR 码及即时动态 QR 码（带过期秒数） | [文档链接](/documentation/pix/criar_qr_code_dinamico) | PIX0008 |
| PIX0024 | 删除动态 Pix QR 码 | 删除 Pix QR 码 | [文档链接](/documentation/pix/baixar_qr_code_dinamico) | PIX0023 |
| PIX0025 | 列出动态 Pix QR 码 | 列出动态 Pix QR 码 | [文档链接](/documentation/pix/pesquisar_por_qr_code_dinamico) | PIX0023 |
| PIX0026 | 读取即时动态 Pix QR 码过期 webhook | 成功接收即时动态 Pix QR 码过期 webhook | [文档链接](/documentation/pix/webhook_por_qr_code_expirado) | PIX0023 |

## Pix QR 码支付

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0029* | 支付静态 Pix QR 码 | 支付静态 Pix QR 码 | [1. 申请转账](/documentation/baas/pix/2fa_v2/solicitacao_de_transacao_pix_2fa) <br></br> [2. 审批转账](/documentation/baas/pix/2fa_v2/aprovar_transacao_pix_2fa) | PIX0022 |
| PIX0030* | 支付动态 Pix QR 码 | 支付动态 Pix QR 码 |  [1. 申请转账](/documentation/baas/pix/2fa_v2/solicitacao_de_transacao_pix_2fa) <br></br> [2. 审批转账](/documentation/baas/pix/2fa_v2/aprovar_transacao_pix_2fa) | PIX0022 |
| PIX0027* | 解码 Pix QR 码 | 解码静态 Pix QR 码、带到期日动态 QR 码和即时动态 QR 码 | [文档链接](/documentation/pix/decodificar_qr_code) | PIX0022 e PIX0023 |

## Pix 限额管理

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0032* | 申请修改 Pix 限额 | 为 QI 账户发起 Pix 限额修改申请 | [文档链接](/documentation/pix/solicitar_alteracao_de_limite_pix) |  QIC0004 ou QIC0005  |
| PIX0033 | 列出 Pix 限额修改申请 | 列出 QI 账户的 Pix 限额修改申请 | [文档链接](/documentation/pix/busca_por_solicitacao_de_limite_pix) | PIX0032 |
| PIX0034* | 查询已用 Pix 限额 | 查询 QI 账户已用 Pix 限额 | [文档链接](/documentation/pix/busca_por_uso_de_limite_pix) |  QIC0004 ou QIC0005  |

---

# 费率管理
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| GTF0001* | 申请修改费率 | 修改账户费率 | [文档链接](/documentation/contas/gestao_de_tarifas) |  QIC0004 ou QIC0005  |
| GTF0002* | 查询费率  | 查询账户已注册的费率 | [文档链接](/documentation/contas/consulta_de_tarifas) |  QIC0004 ou QIC0005  |

## 管理员用户管理
| GUA0001* | 添加管理员用户 | 创建管理员用户并绑定到 QI 账户 | 简介：[文档](/documentation/gestao_de_usuarios/tfa_introducao)<br/>1. 创建：[文档](/documentation/gestao_de_usuarios/criacao_de_pessoa)<br/>2. 绑定：[文档](/documentation/gestao_de_usuarios/inclusao_de_vinculo) |QIC0004 ou QIC0005 |
| GUA0002* | 修改管理员联系信息 | 修改管理员用户的联系信息（邮件和电话） | [文档链接](/documentation/gestao_de_usuarios/alteracao_de_contato_de_vinculo) |  |
| GUA0003* | 删除管理员用户 | 解除管理员用户与 QI 账户的绑定关系 | [文档链接](/documentation/gestao_de_usuarios/exclusao_de_vinculo) |  |

# 卡片管理

## 创建卡片
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| GDC0001* | 创建虚拟卡  | 创建虚拟卡 | [文档链接](/documentation/cards/create/gerar_cartao_virtual) |  QIC0004 ou QIC0005  |
| GDC0002* | 创建实体卡  | 创建实体卡 | [文档链接](/documentation/cards/create/gerar_cartao_fisico) |  QIC0004 ou QIC0005  |

## 卡片查询
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| GDC0003* | 通过密钥查询卡片  | 查询卡片 | [文档链接](/documentation/cards/search/buscar_cartao_by_key) | GDC0001 ou GDC0002 |
| GDC0004* | 列出卡片  | 列出卡片 | [文档链接](/documentation/cards/search/listar_cartoes) | GDC0001 ou GDC0002 |
| GDC0005* | 查询卡片数据 | 查询卡片数据 | [文档链接](/documentation/cards/search/buscar_dados_pci) | GDC0001 ou GDC0002 |
| GDC0006* | 查询 PCI 密码 | 查询 PCI 密码 | [文档链接](/documentation/cards/search/buscar_senha) | GDC0001 ou GDC0002 |
| GDC0007* | 查询配送数据 | 查询配送数据 | [文档链接](/documentation/cards/search/buscar_entrega_by_key) | GDC0001 ou GDC0002 |

## 更新卡片数据
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| GDC0008* | 更新卡片状态  | 更新卡片状态 | [文档链接](/documentation/cards/status/update_status_cartao) | GDC0001 ou GDC0002 |
| GDC0009* | 激活实体卡  | 激活实体卡 | [文档链接](/documentation/cards/status/ativar_cartao) | GDC0001 ou GDC0002 |
| GDC0010* | 修改密码   | 修改卡片密码 | [文档链接](/documentation/cards/update/password_cartao) | GDC0001 ou GDC0002 |
| GDC0011* | 配置卡片非接触功能  | 配置卡片非接触功能  | [文档链接](/documentation/cards/update/contactless_cartao) | GDC0002 |

---

# 测试指南 - BaaS 数字账户

URL: /zh-Hans/documentation/roteiros_de_homologacao/conta_digital_baas

测试指南描述了集成合作伙伴在进入生产环境之前，需要在 QI Tech 沙盒环境（测试环境）中测试的所有资源和功能。

本指南描述了该产品所涉及的所有资源和功能。

⚠️ **所有测试必须强制在 QI Tech 沙盒环境（测试环境）中进行。在沙盒环境中进行的操作均为虚拟金融操作，仅用于测试 API 功能。**

## BaaS API 注册与认证
| 代码  | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| CAB0001* | 在沙盒环境注册 | 在 QI Tech 平台 Sandbox 环境（sandbox.qitech.app）完成注册 | cs@qitech.com.br |
| CAB0002* | 在沙盒验证 token | 在 Sandbox 环境验证 QI Token | [文档链接](https://docs.qitech.com.br/assets/pdfs/QI%20Tech%20Manual%20Inclus%C3%A3o%20de%20Token.pdf) | CAB0001 |
| CAB0003* | 交换公钥 | 在 QI Tech 平台 Sandbox 环境（sandbox.qitech.app）完成公钥交换 | [文档链接](/documentation/primeiros_passos/troca_de_chaves) | CAB0001 e CAB0002 |
| CAB0004* | 完成 API 调用认证测试 | 完成 API 调用认证测试 |[文档链接](/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2) <br/><br/> [文档链接](/documentation/primeiros_passos/teste_de_autenticacao/endpoints_de_teste) | CAB0003 |
| CAB0005* | 配置 webhook | 通过 QI Tech 平台 Sandbox 环境（sandbox.qitech.app）配置 QI 发送 webhook 的 URL | [文档链接](/documentation/primeiros_passos/configurando_webhooks) | CAB0001 e CAB0002 |

# **QI Conta**

## 开户

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| QIC0002* | 预留个人账户 | 申请预留持有人为自然人的账户 | [文档链接](/documentation/baas/account/reservar_conta_pf) | CAB0005 e CAB0006 |
| QIC0003* | 开设个人账户 | 完成持有人为自然人的账户开户 | [文档链接](/documentation/baas/account/abrir_conta_pf) | CAB0005 e CAB0006 |
| QIC0004* | 预留企业账户 | 申请预留持有人为法人的账户 | [文档链接](/documentation/baas/account/reservar_conta_pj) | CAB0005 e CAB0006 |
| QIC0005* | 开设企业账户 | 完成持有人为法人的账户开户 | [文档链接](/documentation/baas/account/abrir_conta_pj) | CAB0005 e CAB0006 |
| QIC0006* | 读取开户 webhook | 正确读取开户 webhook | 第 1.2. 或 1.3 项：<br/>[文档链接](/documentation/baas/account/webhooks) |  QIC0003 ou QIC0005  |
| QIC0007* | 列出账户 | 列出已开设账户 | [文档链接](/documentation/contas/consultar_conta) |  QIC0003 ou QIC0005  |
| QIC0008* | 查询账户数据 | 查询账户余额、持有人数据、开户日期等信息 | [文档链接](/documentation/contas/consultar_conta) |  QIC0003 ou QIC0005  |

## 交易

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| QIC0008* | 查询对账单 | 查询账户对账单 | [文档链接](/documentation/movimentacao_de_contas/consulta_de_transacoes) |  QIC0003 ou QIC0005  |
| QIC0009* | 申请转账凭证 | 申请转账凭证 | [文档链接](/documentation/movimentacao_de_contas/comprovante_de_transferencia)|  |
| QIC0010* | 读取交易 webhook | 成功接收所有交易 webhook |  [文档链接](/documentation/movimentacao_de_contas/webhook_movimentacoes/index.html) |  QIC0003 ou QIC0005  |
| QIC0011* | 查询金融机构列表 | 查询可接收 TED 和 Pix 的金融机构列表 |  [文档链接](/documentation/lista_de_instituicoes_financeiras/consulta_de_instituicoes_financeiras) |  QIC0003 ou QIC0005  |

---

# 文件上传

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| UDD0001* | 上传文件 | 通过文件 API 上传文件 |  [文档链接](/documentation/upload_de_documentos/) |  |

---

# TED

| 代码 | 步骤 | 描述 | 链接                                                                                                        | 前置条件 |
| --- | --- | --- |-------------------------------------------------------------------------------------------------------------| --- |
| TED0001* | TED 转出 | 进行 TED 转账  | [文档链接](/documentation/baas/ted/realizar_transferencia) | QIC0003 ou QIC0005 |
| TED0002* | 模拟 TED 转出退回 | 模拟从 QI 账户发出的 TED 转出退款 | 第 3 项：<br/>[文档链接](/documentation/movimentacao_de_contas/transacao) | TED0003 |
| TED0003* | 模拟 TED 转入 | 模拟 TED 转入到 QI 账户 | 第 2 项：<br/>[文档链接](/documentation/movimentacao_de_contas/transacao) | QIC0003 ou QIC0005 |
| TED0004* | 列出 TED 交易 | 列出 TED 入账/出账交易  | [文档链接](/documentation/baas/ted/listar_teds)  | QIC0003 ou QIC0005 |
| TED0004* | 查询 TED 交易 | 查询一笔 TED 交易  | [文档链接](/documentation/baas/ted/consultar_ted)           | QIC0003 ou QIC0005 |
| TED0006* | 读取 TED webhook | 成功接收 TED webhook | [文档链接](/documentation/baas/ted/webhooks/index.html)| QIC0003 ou QIC0005 |
---

# 内部转账

| 编号 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| TFI0001 | 账户借记内部转账 | 从 QI 账户发起转账，目标为另一个 QI 账户 | [文档链接](/documentation/baas/ted/realizar_transferencia) |  QIC0003 ou QIC0005  |
| TFI0002 | 模拟账户贷记内部转账 | 模拟目标 QI 账户从另一个 QI 账户收款 | 第 1 项：<br/> [文档链接](/documentation/movimentacao_de_contas/transacao) |  QIC0003 ou QIC0005  |

---

# 票据

## 票据管理

| 编号 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| 编号      | 步骤 | 描述 | 链接  | 前置条件 |
|---|---|---|---|---|
| BOL0001 | 登记单张标准收款票据    | 登记一张收款票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao/index.html) | CAB0002 ou CAB0003   |
| BOL0002 | 登记单张即时收款票据 | 登记一张收款票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) | CAB0002 ou CAB0003   |
| BOL0003 | 批量登记收款票据  | 批量登记收款票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_em_lote) | CAB0002 ou CAB0003   |
| BOL0004 | 开具标准单张票据        | 开具标准单张票据    | [文档链接](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao)  | CAB0002 ou CAB0003   |
| BOL0005 | 开具即时单张票据   | 开具即时单张票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) | CAB0002 ou CAB0003   |
| BOL0006 | 批量开具票据   | 批量开具票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_em_lote)| CAB0002 ou CAB0003   |
| BOL0007 | 对票据进行折扣减额 | 对票据进行折扣减额 | [文档链接](/documentation/boletos/v2/instrucoes/abatimento/criar_abatimento) | BOL0001, BOL0002 ou BOL0003 |
| BOL0008 | 取消票据折扣减额     | 取消票据折扣减额 | [文档链接](/documentation/boletos/v2/instrucoes/abatimento/cancelar_abatimento) | BOL0001, BOL0002 ou BOL0003  |
| BOL0009 | 延长票据到期日               | 延长票据到期日 | [文档链接](/documentation/boletos/v2/instrucoes/extensao)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0010 | 添加票据折扣               | 添加票据折扣    | [文档链接](/documentation/boletos/v2/instrucoes/desconto)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0011 | 添加票据利息                   | 添加票据利息       | [文档链接](/documentation/boletos/v2/instrucoes/juros)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0012 | 添加票据罚金                   | 添加票据罚金       | [文档链接](/documentation/boletos/v2/instrucoes/multa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0013 | 核销票据                   | 核销票据                 | [文档链接](/documentation/boletos/v2/instrucoes/baixa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0014 | 通过密钥查询票据      | 通过密钥查询票据      | [文档链接](/documentation/boletos/v2/consulta/consulta_por_chave) | BOL0001, BOL0002 ou BOL0003   |
| BOL0015 | 列出票据          | 列出票据     | [文档链接](/documentation/boletos/v2/consulta/listar_boletos) | BOL0001, BOL0002 ou BOL0003   |
| BOL0016 | 查询收款钱包      | 查询收款钱包 | [文档链接](/documentation/boletos/v2/carteira/listar_carteiras/index.html) | BOL0001, BOL0002 ou BOL0003   |
| BOL0017 | 票据 webhook      | 读取票据 webhook | [文档链接](/documentation/boletos/v2/webhooks/boleto) | BOL0001, BOL0002 ou BOL0003   |

## 票据支付

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| BOL0009* | 查询可打印条形码 | 查询银行票据的可打印条形码 | [文档链接](/documentation/baas/cobranca/consultar_boleto_bancario) |  |
| BOL0010* | 支付票据 | 支付银行票据 | [文档链接](/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_boleto_bancario) |  QIC0003 ou QIC0005  |
| BOL0012* | 查询协议票据条形码 | 查询协议票据的可打印条形码 | [文档链接](/documentation/baas/cobranca/consultar_fatura_de_recolhimento) |  |
| BOL0013* | 支付协议票据 | 支付协议票据 | [文档链接](/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_fatura_de_recolhimento) |  QIC0003 ou QIC0005  |

---

## Pix

## Pix 转账
| 代码  | 步骤 | 描述 | 文档链接 | 前置条件 |
|---------|--|---|---|---|
| PIX0002* | Pix 转出 | 从 QI 账户使用银行数据（手动 Pix）或 Pix 密钥进行 Pix 转账 | [文档链接](/documentation/baas/pix/realizar_transferencia) | CAB0001 |
| PIX0035 | 查询 Pix 转账 | 获取一笔转账的数据 | [文档链接](/documentation/baas/pix/consultar_transferencias) | PIX0002 |
| PIX0003* | 模拟 Pix 转出退款 | 模拟 Pix 转出退款 | [文档链接 - 第 2 项](/documentation/pix/simulacao)| PIX0002 |
| PIX0004* | 模拟 Pix 转入 | 模拟 Pix 转入到 QI 账户 | [文档链接 -> 第 1 项](/documentation/pix/simulacao)||
| PIX0037* | 读取待处理交易 webhook | 成功接收待处理交易 webhook | [文档链接][(/documentation/baas/pix/webhooks) | PIX0002 |
| PIX0038* | 读取 Pix 转入 webhook | 成功接收 Pix 转入 webhook | [文档链接](/documentation/baas/pix/webhooks#webhook-para-pix-de-entrada)| PIX0004 |
| PIX0039 | 读取 Pix 退款 webhook | 成功接收 Pix 退款 webhook | [文档链接](/documentation/baas/pix/webhooks#webhook-para-devolu%C3%A7%C3%B5es-de-pix) | PIX0003 |
| PIX0040 | 申请退还已收 Pix | 申请退还已收 Pix | [文档链接](/documentation/baas/pix/solicitar_devolucao) | PIX0003 |
| PIX0041 | 列出账户的 Pix 转账 | 列出账户的 Pix 转账 | [文档链接](/documentation/baas/pix/listar_transferencias) | PIX0003 |

## Pix 密钥管理

### Pix 密钥的创建与删除

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0008* | 创建 Pix 密钥 | 创建 CPF、CNPJ、随机、邮件和电话类型的 Pix 密钥 | [文档链接](/documentation/pix/criar_chave) | 
|QIC0003 ou QIC0005  |](/documentation/baas/pix/consultar_chave_pix)
| PIX0009 | 删除 Pix 密钥 | 删除一个 Pix 密钥 | [文档链接](/documentation/pix/excluir_chave) | PIX0008 |
| PIX0010* | 列出 QI 账户的 Pix 密钥 | 列出绑定到 QI 账户的 Pix 密钥 | [文档链接](/documentation/pix/listar_chaves_pix) | PIX0008 |

### Pix 密钥可携带性

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0013* | 创建 Pix 密钥转入可携带性申请 | 创建 CPF、CNPJ、邮件、电话和随机类型 Pix 密钥的转入可携带性申请 | [文档链接](/documentation/pix/portabilidade#criando-um-pedido-de-portabilidade) |  QIC0003 ou QIC0005  |
| PIX0014* | 重新发送电话/邮箱类型 Pix 密钥转入可携带性申请的双因素认证 | 重新发送待处理 Pix 密钥转入可携带性申请的短信（电话类型）或邮件（邮箱类型） | [文档链接](/documentation/pix/portabilidade#reenviando-a-valida%C3%A7%C3%A3o-de-dois-fatores) | PIX0013 |
| PIX0015* | 删除 Pix 密钥转入可携带性申请 | 删除待处理的 Pix 密钥转入可携带性申请 | [文档链接](/documentation/pix/portabilidade#deletando-um-pedido-de-portabilidade) | PIX0013 |
| PIX0016* | 读取 Pix 密钥转入可携带性申请完成 webhook | 正确读取 Pix 密钥转入可携带性申请完成 webhook，测试所有可能的完成状态 | Webhook：<br/> [文档链接](/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade) |PIX0013 |
| PIX0017* | 模拟 Pix 密钥转出可携带性申请 | 模拟接收 Pix 密钥转出可携带性申请 | 第 5 项：<br/> [文档链接](/documentation/pix/simulacao/index.html) | PIX0013 |
| PIX0018* | 批准和拒绝 Pix 密钥转出可携带性申请 | 批准 Pix 密钥转出可携带性申请 | [文档链接](/documentation/pix/portabilidade#request-4) | PIX0017 |
| PIX0019* | 重新发送 Pix 密钥转出可携带性申请的双因素认证 | 重新发送 Pix 密钥转出可携带性申请的双因素认证 | Enum "pending_donator_validation"  <br/> [文档链接](/documentation/pix/portabilidade#request-4) | PIX0018 |
| PIX0020* | 读取 Pix 密钥转出可携带性申请完成 webhook | 正确读取 Pix 密钥转出可携带性申请完成 webhook，测试所有可能的完成状态 | [文档链接](D/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade-1) | PIX0018 |

## Pix QR 码管理

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0022* | 创建静态 Pix QR 码 | 生成静态 QR 码 | [文档链接](/documentation/pix/criar_qr_code_estatico) | PIX0008 |
| PIX0023 | 创建动态 Pix QR 码 | 生成带到期日的动态 QR 码及即时动态 QR 码（带过期秒数） | [文档链接](/documentation/pix/criar_qr_code_dinamico) | PIX0008 |
| PIX0024 | 删除动态 Pix QR 码 | 删除 Pix QR 码 | [文档链接](/documentation/pix/baixar_qr_code_dinamico) | PIX0023 |
| PIX0025 | 列出动态 Pix QR 码 | 列出动态 Pix QR 码 | [文档链接](/documentation/pix/pesquisar_por_qr_code_dinamico) | PIX0023 |
| PIX0026 | 读取即时动态 Pix QR 码过期 webhook | 成功接收即时动态 Pix QR 码过期 webhook | [文档链接](/documentation/pix/webhook_por_qr_code_expirado) | PIX0023 |

## Pix QR 码支付

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |

| PIX0029* | 支付静态 Pix QR 码 | 支付静态 Pix QR 码 | [文档链接](/documentation/baas/pix/realizar_transferencia#transfer%C3%AAncia-por-qr-code-pix) | PIX0022 |
| PIX0030* | 支付动态 Pix QR 码 | 支付动态 Pix QR 码 |  [文档链接](/documentation/baas/pix/realizar_transferencia#transfer%C3%AAncia-por-qr-code-pix) | PIX0022 |
| PIX0027* | 解码 Pix QR 码 | 解码静态 Pix QR 码、带到期日动态 QR 码和即时动态 QR 码 | [文档链接](/documentation/pix/decodificar_qr_code) | PIX0022 e PIX0023 |

## Pix 限额管理

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0032* | 申请修改 Pix 限额 | 为 QI 账户发起 Pix 限额修改申请 | [文档链接](/documentation/pix/solicitar_alteracao_de_limite_pix) |  QIC0003 ou QIC0005  |
| PIX0033 | 列出 Pix 限额修改申请 | 列出 QI 账户的 Pix 限额修改申请 | [文档链接](/documentation/pix/busca_por_solicitacao_de_limite_pix) | PIX0032 |
| PIX0034* | 查询已用 Pix 限额 | 查询 QI 账户已用 Pix 限额 | [文档链接](/documentation/pix/busca_por_uso_de_limite_pix) |  QIC0003 ou QIC0005  |

---

# 费率管理
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| GTF0001* | 申请修改费率 | 修改账户费率 | [文档链接](/documentation/contas/gestao_de_tarifas) |  QIC0003 ou QIC0005  |
| GTF0002* | 查询费率  | 查询账户已注册的费率 | [文档链接](/documentation/contas/consulta_de_tarifas) |  QIC0003 ou QIC0005  |

# 卡片管理

## 创建卡片
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| GDC0001* | 创建虚拟卡  | 创建虚拟卡 | [文档链接](/documentation/cards/create/gerar_cartao_virtual) |  QIC0003 ou QIC0005  |
| GDC0002* | 创建实体卡  | 创建实体卡 | [文档链接](/documentation/cards/create/gerar_cartao_fisico) |  QIC0003 ou QIC0005  |

## 卡片查询
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| GDC0003* | 通过密钥查询卡片  | 查询卡片 | [文档链接](/documentation/cards/search/buscar_cartao_by_key) | GDC0001 ou GDC0002 |
| GDC0004* | 列出卡片  | 列出卡片 | [文档链接](/documentation/cards/search/listar_cartoes) | GDC0001 ou GDC0002 |
| GDC0005* | 查询卡片数据 | 查询卡片数据 | [文档链接](/documentation/cards/search/buscar_dados_pci) | GDC0001 ou GDC0002 |
| GDC0006* | 查询 PCI 密码 | 查询 PCI 密码 | [文档链接](/documentation/cards/search/buscar_senha) | GDC0001 ou GDC0002 |
| GDC0007* | 查询配送数据 | 查询配送数据 | [文档链接](/documentation/cards/search/buscar_entrega_by_key) | GDC0001 ou GDC0002 |

## 更新卡片数据
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| GDC0008* | 更新卡片状态  | 更新卡片状态 | [文档链接](/documentation/cards/status/update_status_cartao) | GDC0001 ou GDC0002 |
| GDC0009* | 激活实体卡  | 激活实体卡 | [文档链接](/documentation/cards/status/ativar_cartao) | GDC0001 ou GDC0002 |
| GDC0010* | 修改密码   | 修改卡片密码 | [文档链接](/documentation/cards/update/password_cartao) | GDC0001 ou GDC0002 |
| GDC0011* | 配置卡片非接触功能  | 配置卡片非接触功能  | [文档链接](/documentation/cards/update/contactless_cartao) | GDC0002 |

---

# 测试指南 - BaaS 数字账户 Escrow

URL: /zh-Hans/documentation/roteiros_de_homologacao/conta_digital_escrow

测试指南描述了集成合作伙伴在进入生产环境之前，需要在 QI Tech 沙盒环境（测试环境）中测试的所有资源和功能。

本指南描述了该产品所涉及的所有资源和功能。

⚠️ **所有测试必须强制在 QI Tech 沙盒环境（测试环境）中进行。在沙盒环境中进行的操作均为虚拟金融操作，仅用于测试 API 功能。**

## BaaS API 注册与认证
| 代码  | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| CAB0001* | 在沙盒环境注册 | 在 QI Tech 平台 Sandbox 环境（sandbox.qitech.app）完成注册 | cs@qitech.com.br |
| CAB0002* | 在沙盒验证 token | 在 Sandbox 环境验证 QI Token | [文档链接](https://docs.qitech.com.br/assets/pdfs/QI%20Tech%20Manual%20Inclus%C3%A3o%20de%20Token.pdf) | CAB0001 |
| CAB0003* | 交换公钥 | 在 QI Tech 平台 Sandbox 环境（sandbox.qitech.app）完成公钥交换 | [文档链接](/documentation/primeiros_passos/troca_de_chaves) | CAB0001 e CAB0002 |
| CAB0004* | 完成 API 调用认证测试 | 完成 API 调用认证测试 |[文档链接](/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2) <br/><br/> [文档链接](/documentation/primeiros_passos/teste_de_autenticacao/endpoints_de_teste) | CAB0003 |
| CAB0005* | 配置 webhook | 通过 QI Tech 平台 Sandbox 环境（sandbox.qitech.app）配置 QI 发送 webhook 的 URL | [文档链接](/documentation/primeiros_passos/configurando_webhooks) | CAB0001 e CAB0002 |

# **QI Conta**

## 开户

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| QIC0002* | 预留个人账户 | 申请预留持有人为自然人的账户 | [文档链接](/documentation/baas/account/reservar_conta_pf) | CAB0005 e CAB0006 |
| QIC0003* | 开设个人账户 | 完成持有人为自然人的账户开户 | [文档链接](/documentation/baas/account/abrir_conta_pf) | QIC0002 |
| QIC0004* | 预留企业账户 | 申请预留持有人为法人的账户 | [文档链接](/documentation/baas/account/reservar_conta_pj) | CAB0005 e CAB0006 |
| QIC0005* | 开设企业账户 | 完成持有人为法人的账户开户 | [文档链接](/documentation/baas/account/abrir_conta_pj) | QIC0004 |
| QIC0009* | 预留个人托管账户 | 申请预留持有人为自然人的托管账户 | [文档链接](/documentation/baas/escrow/reservar_conta_pf) | CAB0005 e CAB0006 |
| QIC0010* | 开设个人托管账户 | 完成持有人为自然人的托管账户开户 | [文档链接](/documentation/baas/escrow/abrir_conta_pf) | CAB0005 e CAB0006 |
| QIC0011* | 预留企业托管账户 | 申请预留持有人为法人的托管账户 | [文档链接](/documentation/baas/escrow/reservar_conta_pj) | CAB0005 e CAB0006 |
| QIC0012* | 开设企业托管账户 | 完成持有人为法人的托管账户开户 | [文档链接](/documentation/baas/escrow/abrir_conta_pj) | CAB0005 e CAB0006 |
| QIC0006* | 读取开户 webhook | 正确读取开户 webhook | 第 1.2. 或 1.3 项：<br/>[文档链接](/documentation/baas/account/webhooks) |  QIC0003 ou QIC0005  |
| QIC0007* | 列出账户 | 列出已开设账户 | [文档链接](/documentation/contas/consultar_conta) |  QIC0003 ou QIC0005  |
| QIC0008* | 查询账户数据 | 查询账户余额、持有人数据、开户日期等信息 | [文档链接](/documentation/contas/consultar_conta) |  QIC0003 ou QIC0005  |

## 交易

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| QIC0008* | 查询对账单 | 查询账户对账单 | [文档链接](/documentation/movimentacao_de_contas/consulta_de_transacoes) |  QIC0003 ou QIC0005  |
| QIC0009* | 申请转账凭证 | 申请转账凭证 | [文档链接](/documentation/movimentacao_de_contas/comprovante_de_transferencia)|  |
| QIC0010* | 读取交易 webhook | 成功接收所有交易 webhook |  [文档链接](/documentation/movimentacao_de_contas/webhook_movimentacoes/index.html) |  QIC0003 ou QIC0005  |
| QIC0011* | 查询金融机构列表 | 查询可接收 TED 和 Pix 的金融机构列表 |  [文档链接](/documentation/lista_de_instituicoes_financeiras/consulta_de_instituicoes_financeiras) |  QIC0003 ou QIC0005  |

---

# 文件上传

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| UDD0001* | 上传文件 | 通过文件 API 上传文件 |  [文档链接](/documentation/upload_de_documentos/) |  |

---

# TED

| 代码 | 步骤 | 描述 | 链接                                                                                                        | 前置条件 |
| --- | --- | --- |-------------------------------------------------------------------------------------------------------------| --- |
| TED0001* | TED 转出 | 进行 TED 转账  | [文档链接](/documentation/baas/ted/realizar_transferencia) | QIC0003 ou QIC0005 |
| TED0002* | 模拟 TED 转出退回 | 模拟从 QI 账户发出的 TED 转出退款 | 第 3 项：<br/>[文档链接](/documentation/movimentacao_de_contas/transacao) | TED0003 |
| TED0003* | 模拟 TED 转入 | 模拟 TED 转入到 QI 账户 | 第 2 项：<br/>[文档链接](/documentation/movimentacao_de_contas/transacao) | QIC0003 ou QIC0005 |
| TED0004* | 列出 TED 交易 | 列出 TED 入账/出账交易  | [文档链接](/documentation/baas/ted/listar_teds)  | QIC0003 ou QIC0005 |
| TED0004* | 查询 TED 交易 | 查询一笔 TED 交易  | [文档链接](/documentation/baas/ted/consultar_ted)           | QIC0003 ou QIC0005 |
| TED0006* | 读取 TED webhook | 成功接收 TED webhook | [文档链接](/documentation/baas/ted/webhooks/index.html)| QIC0003 ou QIC0005 |
---

# 内部转账

| 编号 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| TFI0001 | 账户借记内部转账 | 从 QI 账户发起转账，目标为另一个 QI 账户 | [文档链接](/documentation/baas/ted/realizar_transferencia) |  QIC0003 ou QIC0005  |
| TFI0002 | 模拟账户贷记内部转账 | 模拟目标 QI 账户从另一个 QI 账户收款 | 第 1 项：<br/> [文档链接](/documentation/movimentacao_de_contas/transacao) |  QIC0003 ou QIC0005  |

---

# 票据

## 票据管理

| 编号 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| 编号      | 步骤 | 描述 | 链接  | 前置条件 |
|---|---|---|---|---|
| BOL0001 | 登记单张标准收款票据    | 登记一张收款票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao/index.html) | CAB0002 ou CAB0003   |
| BOL0002 | 登记单张即时收款票据 | 登记一张收款票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) | CAB0002 ou CAB0003   |
| BOL0003 | 批量登记收款票据  | 批量登记收款票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_em_lote) | CAB0002 ou CAB0003   |
| BOL0004 | 开具标准单张票据        | 开具标准单张票据    | [文档链接](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao)  | CAB0002 ou CAB0003   |
| BOL0005 | 开具即时单张票据   | 开具即时单张票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) | CAB0002 ou CAB0003   |
| BOL0006 | 批量开具票据   | 批量开具票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_em_lote)| CAB0002 ou CAB0003   |
| BOL0007 | 对票据进行折扣减额 | 对票据进行折扣减额 | [文档链接](/documentation/boletos/v2/instrucoes/abatimento/criar_abatimento) | BOL0001, BOL0002 ou BOL0003 |
| BOL0008 | 取消票据折扣减额     | 取消票据折扣减额 | [文档链接](/documentation/boletos/v2/instrucoes/abatimento/cancelar_abatimento) | BOL0001, BOL0002 ou BOL0003  |
| BOL0009 | 延长票据到期日               | 延长票据到期日 | [文档链接](/documentation/boletos/v2/instrucoes/extensao)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0010 | 添加票据折扣               | 添加票据折扣    | [文档链接](/documentation/boletos/v2/instrucoes/desconto)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0011 | 添加票据利息                   | 添加票据利息       | [文档链接](/documentation/boletos/v2/instrucoes/juros)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0012 | 添加票据罚金                   | 添加票据罚金       | [文档链接](/documentation/boletos/v2/instrucoes/multa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0013 | 核销票据                   | 核销票据                 | [文档链接](/documentation/boletos/v2/instrucoes/baixa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0014 | 通过密钥查询票据      | 通过密钥查询票据      | [文档链接](/documentation/boletos/v2/consulta/consulta_por_chave) | BOL0001, BOL0002 ou BOL0003   |
| BOL0015 | 列出票据          | 列出票据     | [文档链接](/documentation/boletos/v2/consulta/listar_boletos) | BOL0001, BOL0002 ou BOL0003   |
| BOL0016 | 查询收款钱包      | 查询收款钱包 | [文档链接](/documentation/boletos/v2/carteira/listar_carteiras/index.html) | BOL0001, BOL0002 ou BOL0003   |
| BOL0017 | 票据 webhook      | 读取票据 webhook | [文档链接](/documentation/boletos/v2/webhooks/boleto) | BOL0001, BOL0002 ou BOL0003   |

## 票据支付

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| BOL0009* | 查询可打印条形码 | 查询银行票据的可打印条形码 | [文档链接](/documentation/baas/cobranca/consultar_boleto_bancario) |  |
| BOL0010* | 支付票据 | 支付银行票据 | [文档链接](/documentation/baas/cobranca/pagar_boleto_bancario) |  QIC0003 ou QIC0005  |
| BOL0012* | 查询协议票据条形码 | 查询协议票据的可打印条形码 | [文档链接](/documentation/baas/cobranca/consultar_fatura_de_recolhimento) |  |
| BOL0013* | 支付协议票据 | 支付协议票据 | [文档链接](/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_fatura_de_recolhimento) |  QIC0003 ou QIC0005  |

---

## Pix

## Pix 转账
| 代码  | 步骤 | 描述 | 文档链接 | 前置条件 |
|---------|--|---|---|---|
| PIX0002* | Pix 转出 | 从 QI 账户使用银行数据（手动 Pix）或 Pix 密钥进行 Pix 转账 | [文档链接](/documentation/baas/pix/realizar_transferencia) | CAB0001 |
| PIX0035 | 查询 Pix 转账 | 获取一笔转账的数据 | [文档链接](/documentation/baas/pix/consultar_transferencias) | PIX0002 |
| PIX0003* | 模拟 Pix 转出退款 | 模拟 Pix 转出退款 | [文档链接 - 第 2 项](/documentation/pix/simulacao)| PIX0002 |
| PIX0004* | 模拟 Pix 转入 | 模拟 Pix 转入到 QI 账户 | [文档链接 -> 第 1 项](/documentation/pix/simulacao)||
| PIX0037* | 读取待处理交易 webhook | 成功接收待处理交易 webhook | [文档链接][(/documentation/baas/pix/webhooks) | PIX0002 |
| PIX0038* | 读取 Pix 转入 webhook | 成功接收 Pix 转入 webhook | [文档链接](/documentation/baas/pix/webhooks#webhook-para-pix-de-entrada)| PIX0004 |
| PIX0039 | 读取 Pix 退款 webhook | 成功接收 Pix 退款 webhook | [文档链接](/documentation/baas/pix/webhooks#webhook-para-devolu%C3%A7%C3%B5es-de-pix) | PIX0003 |
| PIX0040 | 申请退还已收 Pix | 申请退还已收 Pix | [文档链接](/documentation/baas/pix/solicitar_devolucao) | PIX0003 |
| PIX0041 | 列出账户的 Pix 转账 | 列出账户的 Pix 转账 | [文档链接](/documentation/baas/pix/listar_transferencias) | PIX0003 |

## Pix 密钥管理

### Pix 密钥的创建与删除

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0008* | 创建 Pix 密钥 | 创建 CPF、CNPJ、随机、邮件和电话类型的 Pix 密钥 | [文档链接](/documentation/pix/criar_chave) | 
|QIC0003 ou QIC0005  |](/documentation/baas/pix/consultar_chave_pix)
| PIX0009 | 删除 Pix 密钥 | 删除一个 Pix 密钥 | [文档链接](/documentation/pix/excluir_chave) | PIX0008 |
| PIX0010* | 列出 QI 账户的 Pix 密钥 | 列出绑定到 QI 账户的 Pix 密钥 | [文档链接](/documentation/pix/listar_chaves_pix) | PIX0008 |

### Pix 密钥可携带性

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0013* | 创建 Pix 密钥转入可携带性申请 | 创建 CPF、CNPJ、邮件、电话和随机类型 Pix 密钥的转入可携带性申请 | [文档链接](/documentation/pix/portabilidade#criando-um-pedido-de-portabilidade) |  QIC0003 ou QIC0005  |
| PIX0014* | 重新发送电话/邮箱类型 Pix 密钥转入可携带性申请的双因素认证 | 重新发送待处理 Pix 密钥转入可携带性申请的短信（电话类型）或邮件（邮箱类型） | [文档链接](/documentation/pix/portabilidade#reenviando-a-valida%C3%A7%C3%A3o-de-dois-fatores) | PIX0013 |
| PIX0015* | 删除 Pix 密钥转入可携带性申请 | 删除待处理的 Pix 密钥转入可携带性申请 | [文档链接](/documentation/pix/portabilidade#deletando-um-pedido-de-portabilidade) | PIX0013 |
| PIX0016* | 读取 Pix 密钥转入可携带性申请完成 webhook | 正确读取 Pix 密钥转入可携带性申请完成 webhook，测试所有可能的完成状态 | Webhook：<br/> [文档链接](/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade) |PIX0013 |
| PIX0017* | 模拟 Pix 密钥转出可携带性申请 | 模拟接收 Pix 密钥转出可携带性申请 | 第 5 项：<br/> [文档链接](/documentation/pix/simulacao/index.html) | PIX0013 |
| PIX0018* | 批准和拒绝 Pix 密钥转出可携带性申请 | 批准 Pix 密钥转出可携带性申请 | [文档链接](/documentation/pix/portabilidade#request-4) | PIX0017 |
| PIX0019* | 重新发送 Pix 密钥转出可携带性申请的双因素认证 | 重新发送 Pix 密钥转出可携带性申请的双因素认证 | Enum "pending_donator_validation"  <br/> [文档链接](/documentation/pix/portabilidade#request-4) | PIX0018 |
| PIX0020* | 读取 Pix 密钥转出可携带性申请完成 webhook | 正确读取 Pix 密钥转出可携带性申请完成 webhook，测试所有可能的完成状态 | [文档链接](D/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade-1) | PIX0018 |

## Pix QR 码管理

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0022* | 创建静态 Pix QR 码 | 生成静态 QR 码 | [文档链接](/documentation/pix/criar_qr_code_estatico) | PIX0008 |
| PIX0023 | 创建动态 Pix QR 码 | 生成带到期日的动态 QR 码及即时动态 QR 码（带过期秒数） | [文档链接](/documentation/pix/criar_qr_code_dinamico) | PIX0008 |
| PIX0024 | 删除动态 Pix QR 码 | 删除 Pix QR 码 | [文档链接](/documentation/pix/baixar_qr_code_dinamico) | PIX0023 |
| PIX0025 | 列出动态 Pix QR 码 | 列出动态 Pix QR 码 | [文档链接](/documentation/pix/pesquisar_por_qr_code_dinamico) | PIX0023 |
| PIX0026 | 读取即时动态 Pix QR 码过期 webhook | 成功接收即时动态 Pix QR 码过期 webhook | [文档链接](/documentation/pix/webhook_por_qr_code_expirado) | PIX0023 |

## Pix QR 码支付

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |

| PIX0029* | 支付静态 Pix QR 码 | 支付静态 Pix QR 码 | [文档链接](/documentation/baas/pix/realizar_transferencia#transfer%C3%AAncia-por-qr-code-pix) | PIX0022 |
| PIX0030* | 支付动态 Pix QR 码 | 支付动态 Pix QR 码 |  [文档链接](/documentation/baas/pix/realizar_transferencia#transfer%C3%AAncia-por-qr-code-pix) | PIX0022 |
| PIX0027* | 解码 Pix QR 码 | 解码静态 Pix QR 码、带到期日动态 QR 码和即时动态 QR 码 | [文档链接](/documentation/pix/decodificar_qr_code) | PIX0022 e PIX0023 |

## Pix 限额管理

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0032* | 申请修改 Pix 限额 | 为 QI 账户发起 Pix 限额修改申请 | [文档链接](/documentation/pix/solicitar_alteracao_de_limite_pix) |  QIC0003 ou QIC0005  |
| PIX0033 | 列出 Pix 限额修改申请 | 列出 QI 账户的 Pix 限额修改申请 | [文档链接](/documentation/pix/busca_por_solicitacao_de_limite_pix) | PIX0032 |
| PIX0034* | 查询已用 Pix 限额 | 查询 QI 账户已用 Pix 限额 | [文档链接](/documentation/pix/busca_por_uso_de_limite_pix) |  QIC0003 ou QIC0005  |

---

# 费率管理
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| GTF0001* | 申请修改费率 | 修改账户费率 | [文档链接](/documentation/contas/gestao_de_tarifas) |  QIC0003 ou QIC0005  |
| GTF0002* | 查询费率  | 查询账户已注册的费率 | [文档链接](/documentation/contas/consulta_de_tarifas) |  QIC0003 ou QIC0005  |

# 卡片管理

## 创建卡片
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| GDC0001* | 创建虚拟卡  | 创建虚拟卡 | [文档链接](/documentation/cards/create/gerar_cartao_virtual) |  QIC0003 ou QIC0005  |
| GDC0002* | 创建实体卡  | 创建实体卡 | [文档链接](/documentation/cards/create/gerar_cartao_fisico) |  QIC0003 ou QIC0005  |

## 卡片查询
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| GDC0003* | 通过密钥查询卡片  | 查询卡片 | [文档链接](/documentation/cards/search/buscar_cartao_by_key) | GDC0001 ou GDC0002 |
| GDC0004* | 列出卡片  | 列出卡片 | [文档链接](/documentation/cards/search/listar_cartoes) | GDC0001 ou GDC0002 |
| GDC0005* | 查询卡片数据 | 查询卡片数据 | [文档链接](/documentation/cards/search/buscar_dados_pci) | GDC0001 ou GDC0002 |
| GDC0006* | 查询 PCI 密码 | 查询 PCI 密码 | [文档链接](/documentation/cards/search/buscar_senha) | GDC0001 ou GDC0002 |
| GDC0007* | 查询配送数据 | 查询配送数据 | [文档链接](/documentation/cards/search/buscar_entrega_by_key) | GDC0001 ou GDC0002 |

## 更新卡片数据
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| GDC0008* | 更新卡片状态  | 更新卡片状态 | [文档链接](/documentation/cards/status/update_status_cartao) | GDC0001 ou GDC0002 |
| GDC0009* | 激活实体卡  | 激活实体卡 | [文档链接](/documentation/cards/status/ativar_cartao) | GDC0001 ou GDC0002 |
| GDC0010* | 修改密码   | 修改卡片密码 | [文档链接](/documentation/cards/update/password_cartao) | GDC0001 ou GDC0002 |
| GDC0011* | 配置卡片非接触功能  | 配置卡片非接触功能  | [文档链接](/documentation/cards/update/contactless_cartao) | GDC0002 |

---

# 测试指南 - BaaS 数字账户 Escrow

URL: /zh-Hans/documentation/roteiros_de_homologacao/conta_digital_escrow_caas

测试指南描述了集成合作伙伴在进入生产环境之前，需要在 QI Tech 沙盒环境（测试环境）中测试的所有资源和功能。

本指南描述了该产品所涉及的所有资源和功能。

⚠️ **所有测试必须强制在 QI Tech 沙盒环境（测试环境）中进行。在沙盒环境中进行的操作均为虚拟金融操作，仅用于测试 API 功能。**

## BaaS API 注册与认证
| 代码  | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| CAB0001* | 在沙盒环境注册 | 在 QI Tech 平台 Sandbox 环境（sandbox.qitech.app）完成注册 | cs@qitech.com.br |
| CAB0002* | 在沙盒验证 token | 在 Sandbox 环境验证 QI Token | [文档链接](https://docs.qitech.com.br/assets/pdfs/QI%20Tech%20Manual%20Inclus%C3%A3o%20de%20Token.pdf) | CAB0001 |
| CAB0003* | 交换公钥 | 在 QI Tech 平台 Sandbox 环境（sandbox.qitech.app）完成公钥交换 | [文档链接](/documentation/primeiros_passos/troca_de_chaves) | CAB0001 e CAB0002 |
| CAB0004* | 完成 API 调用认证测试 | 完成 API 调用认证测试 |[文档链接](/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2) <br/><br/> [文档链接](/documentation/primeiros_passos/teste_de_autenticacao/endpoints_de_teste) | CAB0003 |
| CAB0005* | 配置 webhook | 通过 QI Tech 平台 Sandbox 环境（sandbox.qitech.app）配置 QI 发送 webhook 的 URL | [文档链接](/documentation/primeiros_passos/configurando_webhooks) | CAB0001 e CAB0002 |

## 反欺诈

## 注册与认证

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| ATF0002* | 获取 onboarding API 密钥 | 向 QI Tech 集成团队获取用于 /onboarding API 的 API 密钥 | suporte.caas@qitech.com.br |  
| ATF0003* | 获取 OCR 移动令牌 | 向 QI Tech 集成团队获取用于 OCR SDK 的移动令牌 | suporte.caas@qitech.com.br |  
| ATF0004* | 获取人脸识别移动令牌 | 向 QI Tech 集成团队获取用于人脸识别 SDK 的移动令牌 | suporte.caas@qitech.com.br |  
| ATF0005* | 获取设备扫描移动令牌 | 向 QI Tech 集成团队获取用于设备扫描 SDK 的移动令牌 | suporte.caas@qitech.com.br |  

## SDK OCR

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| ATF0007* | 构建 SDK | 定义文件采集的模板和自定义选项，并在您的应用中（QI Tech 客户应用）成功构建 SDK | Android: [文档链接](/documentation/caas/ocr/android/introduction) <br/> iOS:[ 文档链接](/documentation/caas/ocr/ios/introduction) |  |
| ATF0008* | 发送文件 | 在您的应用中（QI Tech 客户应用）使用 SDK 完成文件采集 |  | ATF0003 e ATF0007 |
| ATF0009* | 存储 ocr_key | 存储 SDK 返回的密钥，识别采集文件的类型（例如：cnh_front、cnh_back 等） | Android: [文档链接](/documentation/caas/ocr/android/collecting_response) <br/>iOS:[ 文档链接](/documentation/caas/ocr/ios/collecting_response)| ATF0008 |

## SDK 人脸识别

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| ATF0011* | 构建 SDK | 定义自定义选项并在您的应用中（QI Tech 客户应用）成功构建 SDK |Android: [文档链接](/documentation/caas/face_recognition/android/introduction) <br/>iOS:[ 文档链接](/documentation/caas/face_recognition/ios/introduction)  |  |
| ATF0012* | 活体检测流程 | 在您的应用中（QI Tech 客户应用）使用 SDK 完成活体检测流程 | | ATF0004 e ATF0011* |
| ATF0013* | 存储图像密钥 | 完成活体检测流程后，存储 SDK 返回的 image_key | Android: [文档链接](/documentation/caas/face_recognition/android/collecting_response) iOS:[ 文档链接](/documentation/caas/face_recognition/ios/collecting_response) | ATF0012 |

## SDK 设备扫描

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| ATF0015* | 构建 SDK | 定义您的应用（QI Tech 客户应用）向用户请求的权限，并在您的应用中成功构建 SDK | Android: [文档链接](/documentation/caas/device_scan/android/introduction)<br/>iOS:[ 文档链接](/documentation/caas/device_scan/ios/introduction)|  
| ATF0016* | 存储用户会话 | 存储待扫描设备的用户会话（sessionId） | Android: [文档链接](/documentation/caas/device_scan/android/example)<br/>iOS:[ 文档链接](/documentation/caas/device_scan/ios/example) | ATF0015 e ATF0017 |
| ATF0017* | 采集信息 | 使用已存储的 sessionId 实例化 SDK，并在您的应用中（QI Tech 客户应用）调用信息采集方法 | Android: [文档链接](/documentation/caas/face_recognition/android/collecting_response)<br/>iOS:[ 文档链接](/documentation/caas/face_recognition/ios/collecting_response) | ATF0005 e ATF0015 |

## 反欺诈

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| ATF0019* | 个人客户反欺诈 | 成功完成个人客户的反欺诈流程 | [文档链接](/documentation/caas/onboarding/natural_person) | ATF0002 |
| ATF0020* | 企业客户反欺诈 | 成功完成企业客户的反欺诈流程 | [文档链接](/documentation/caas/onboarding/legal_person) | ATF0002 |
| ATF0021* | 读取异步流程中的分析派生 webhook | 成功接收异步响应流程中的分析派生 webhook |[文档链接](/documentation/caas/onboarding/webhook) | ATF0019 ou ATF0020 |

## 平台注册

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| ATF0022* | 注册主用户 | 在 CaaS 平台注册主用户，用于处理转到"人工分析"的派生请求  | suporte.caas@qitech.com.br | ATF0019 ou ATF0020 |

---

# **QI Conta**

## 开户

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| QIC0002* | 预留个人账户 | 申请预留持有人为自然人的账户 | [文档链接](/documentation/baas/account/reservar_conta_pf) | CAB0005 e CAB0006 |
| QIC0003* | 开设个人账户 | 完成持有人为自然人的账户开户 | [文档链接](/documentation/baas/account/abrir_conta_pf) | QIC0002 |
| QIC0004* | 预留企业账户 | 申请预留持有人为法人的账户 | [文档链接](/documentation/baas/account/reservar_conta_pj) | CAB0005 e CAB0006 |
| QIC0005* | 开设企业账户 | 完成持有人为法人的账户开户 | [文档链接](/documentation/baas/account/abrir_conta_pj) | QIC0004 |
| QIC0009* | 预留个人 escrow 账户 | 申请预留持有人为自然人的 escrow 账户 | [文档链接](/documentation/baas/escrow/reservar_conta_pf) | CAB0005 e CAB0006 |
| QIC0010* | 开设个人 escrow 账户 | 完成持有人为自然人的 escrow 账户开户 | [文档链接](/documentation/baas/escrow/abrir_conta_pf) | CAB0005 e CAB0006 |
| QIC0011* | 预留企业 escrow 账户 | 申请预留持有人为法人的 escrow 账户 | [文档链接](/documentation/baas/escrow/reservar_conta_pj) | CAB0005 e CAB0006 |
| QIC0012* | 开设企业 escrow 账户 | 完成持有人为法人的 escrow 账户开户 | [文档链接](/documentation/baas/escrow/abrir_conta_pj) | CAB0005 e CAB0006 |
| QIC0006* | 读取开户 webhook | 正确读取开户 webhook | 第 1.2. 或 1.3 条：<br/>[文档链接](/documentation/baas/account/webhooks) |  QIC0003 ou QIC0005  |
| QIC0007* | 列出账户 | 列出已开设账户 | [文档链接](/documentation/contas/consultar_conta) |  QIC0003 ou QIC0005  |
| QIC0008* | 查询账户数据 | 查询账户余额、持有人数据、开户日期等信息 | [文档链接](/documentation/contas/consultar_conta) |  QIC0003 ou QIC0005  |

## 交易

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| QIC0008* | 查询对账单 | 查询账户对账单 | [文档链接](/documentation/movimentacao_de_contas/consulta_de_transacoes) |  QIC0003 ou QIC0005  |
| QIC0009* | 申请转账凭证 | 申请转账凭证 | [文档链接](/documentation/movimentacao_de_contas/comprovante_de_transferencia)|  |
| QIC0010* | 读取交易 webhook | 成功接收所有交易 webhook |  [文档链接](/documentation/movimentacao_de_contas/webhook_movimentacoes/index.html) |  QIC0003 ou QIC0005  |
| QIC0011* | 查询金融机构列表 | 查询可接收 TED 和 Pix 的金融机构列表 |  [文档链接](/documentation/lista_de_instituicoes_financeiras/consulta_de_instituicoes_financeiras) |  QIC0003 ou QIC0005  |

---

# 文件上传

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| UDD0001* | 上传文件 | 通过文件 API 上传文件 |  [文档链接](/documentation/upload_de_documentos/) |  |

---

# TED

| 代码 | 步骤 | 描述 | 链接                                                                                                        | 前置条件 |
| --- | --- | --- |-------------------------------------------------------------------------------------------------------------| --- |
| TED0001* | TED 转出 | 进行 TED 转账  | [文档链接](/documentation/baas/ted/realizar_transferencia) | QIC0003 ou QIC0005 |
| TED0002* | 模拟 TED 转出退回 | 模拟从 QI 账户发出的 TED 转出退款 | 第 3 条：<br/>[文档链接](/documentation/movimentacao_de_contas/transacao) | TED0003 |
| TED0003* | 模拟 TED 转入 | 模拟 TED 转入到 QI 账户 | 第 2 条：<br/>[文档链接](/documentation/movimentacao_de_contas/transacao) | QIC0003 ou QIC0005 |
| TED0004* | 列出 TED 交易 | 列出 TED 入账/出账交易  | [文档链接](/documentation/baas/ted/listar_teds)  | QIC0003 ou QIC0005 |
| TED0004* | 查询 TED 交易 | 查询一笔 TED 交易  | [文档链接](/documentation/baas/ted/consultar_ted)           | QIC0003 ou QIC0005 |
| TED0006* | 读取 TED webhook | 成功接收 TED webhook | [文档链接](/documentation/baas/ted/webhooks/index.html)| QIC0003 ou QIC0005 |
---

# 内部转账

| 编号 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| TFI0001 | 账户借记内部转账 | 从 QI 账户发起转账，目标为另一个 QI 账户 | [文档链接](/documentation/baas/ted/realizar_transferencia) |  QIC0003 ou QIC0005  |
| TFI0002 | 模拟账户贷记内部转账 | 模拟目标 QI 账户从另一个 QI 账户收款 | 第 1 条：<br/> [文档链接](/documentation/movimentacao_de_contas/transacao) |  QIC0003 ou QIC0005  |

---

# 票据

## 票据管理

| 编号 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| 编号      | 步骤 | 描述 | 链接  | 前置条件 |
|---|---|---|---|---|
| BOL0001 | 登记单张标准收款票据    | 登记一张收款票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao/index.html) | CAB0002 ou CAB0003   |
| BOL0002 | 登记单张即时收款票据 | 登记一张收款票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) | CAB0002 ou CAB0003   |
| BOL0003 | 批量登记收款票据  | 批量登记收款票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_em_lote) | CAB0002 ou CAB0003   |
| BOL0004 | 开具标准单张票据        | 开具标准单张票据    | [文档链接](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao)  | CAB0002 ou CAB0003   |
| BOL0005 | 开具即时单张票据   | 开具即时单张票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) | CAB0002 ou CAB0003   |
| BOL0006 | 批量开具票据   | 批量开具票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_em_lote)| CAB0002 ou CAB0003   |
| BOL0007 | 对票据进行折扣减额 | 对票据进行折扣减额 | [文档链接](/documentation/boletos/v2/instrucoes/abatimento/criar_abatimento) | BOL0001, BOL0002 ou BOL0003 |
| BOL0008 | 取消票据折扣减额     | 取消票据折扣减额 | [文档链接](/documentation/boletos/v2/instrucoes/abatimento/cancelar_abatimento) | BOL0001, BOL0002 ou BOL0003  |
| BOL0009 | 延长票据到期日               | 延长票据到期日 | [文档链接](/documentation/boletos/v2/instrucoes/extensao)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0010 | 添加票据折扣               | 添加票据折扣    | [文档链接](/documentation/boletos/v2/instrucoes/desconto)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0011 | 添加票据利息                   | 添加票据利息       | [文档链接](/documentation/boletos/v2/instrucoes/juros)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0012 | 添加票据罚金                   | 添加票据罚金       | [文档链接](/documentation/boletos/v2/instrucoes/multa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0013 | 核销票据                   | 核销票据                 | [文档链接](/documentation/boletos/v2/instrucoes/baixa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0014 | 通过密钥查询票据      | 通过密钥查询票据      | [文档链接](/documentation/boletos/v2/consulta/consulta_por_chave) | BOL0001, BOL0002 ou BOL0003   |
| BOL0015 | 列出票据          | 列出票据     | [文档链接](/documentation/boletos/v2/consulta/listar_boletos) | BOL0001, BOL0002 ou BOL0003   |
| BOL0016 | 查询收款钱包      | 查询收款钱包 | [文档链接](/documentation/boletos/v2/carteira/listar_carteiras/index.html) | BOL0001, BOL0002 ou BOL0003   |
| BOL0017 | 票据 webhook      | 读取票据 webhook | [文档链接](/documentation/boletos/v2/webhooks/boleto) | BOL0001, BOL0002 ou BOL0003   |

## 票据支付

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| BOL0009* | 查询可打印条形码 | 查询银行票据的可打印条形码 | [文档链接](/documentation/baas/cobranca/consultar_boleto_bancario) |  |
| BOL0010* | 支付票据 | 支付银行票据 | [文档链接](/documentation/baas/cobranca/pagar_boleto_bancario) |  QIC0003 ou QIC0005  |
| BOL0012* | 查询协议票据条形码 | 查询协议票据的可打印条形码 | [文档链接](/documentation/baas/cobranca/consultar_fatura_de_recolhimento) |  |
| BOL0013* | 支付协议票据 | 支付协议票据 | [文档链接](/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_fatura_de_recolhimento) |  QIC0003 ou QIC0005  |

---

## Pix

## Pix 转账
| 代码  | 步骤 | 描述 | 文档链接 | 前置条件 |
|---------|--|---|---|---|
| PIX0002* | Pix 转出 | 从 QI 账户使用银行信息（手动 Pix）或 Pix 密钥发起 Pix 转账 | [文档链接](/documentation/baas/pix/realizar_transferencia) | CAB0001 |
| PIX0035 | 查询 Pix 转账 | 获取一笔转账的数据 | [文档链接](/documentation/baas/pix/consultar_transferencias) | PIX0002 |
| PIX0003* | 模拟 Pix 转出退款 | 模拟 Pix 转出退款 | [文档链接 - 第 2 条](/documentation/pix/simulacao)| PIX0002 |
| PIX0004* | 模拟 Pix 转入 | 模拟 Pix 转入到 QI 账户 | [文档链接 -> 第 1 条](/documentation/pix/simulacao)||
| PIX0037* | 读取待处理交易 webhook | 成功接收待处理交易 webhook | [文档链接][(/documentation/baas/pix/webhooks) | PIX0002 |
| PIX0038* | 读取 Pix 转入 webhook | 成功接收 Pix 转入 webhook | [文档链接](/documentation/baas/pix/webhooks#webhook-para-pix-de-entrada)| PIX0004 |
| PIX0039 | 读取 Pix 退款 webhook | 成功接收 Pix 退款 webhook | [文档链接](/documentation/baas/pix/webhooks#webhook-para-devolu%C3%A7%C3%B5es-de-pix) | PIX0003 |
| PIX0040 | 申请退还已收 Pix | 申请退还已收 Pix | [文档链接](/documentation/baas/pix/solicitar_devolucao) | PIX0003 |
| PIX0041 | 列出账户的 Pix 转账 | 列出账户的 Pix 转账 | [文档链接](/documentation/baas/pix/listar_transferencias) | PIX0003 |

## Pix 密钥管理

### Pix 密钥的创建与删除

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0008* | 创建 Pix 密钥 | 创建 CPF、CNPJ、随机、邮件和电话类型的 Pix 密钥 | [文档链接](/documentation/pix/criar_chave) | 
|QIC0003 ou QIC0005  |](/documentation/baas/pix/consultar_chave_pix)
| PIX0009 | 删除 Pix 密钥 | 删除一个 Pix 密钥 | [文档链接](/documentation/pix/excluir_chave) | PIX0008 |
| PIX0010* | 列出 QI 账户的 Pix 密钥 | 列出绑定到 QI 账户的 Pix 密钥 | [文档链接](/documentation/pix/listar_chaves_pix) | PIX0008 |

### Pix 密钥可携带性

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0013* | 创建 Pix 密钥转入可携带性申请 | 创建 CPF、CNPJ、邮件、电话和随机类型 Pix 密钥的转入可携带性申请 | [文档链接](/documentation/pix/portabilidade#criando-um-pedido-de-portabilidade) |  QIC0003 ou QIC0005  |
| PIX0014* | 重新发送电话/邮箱类型 Pix 密钥转入可携带性申请的双因素认证 | 为处于待处理状态（pending_claimer_validation）的 Pix 密钥转入可携带性申请重新发送短信（电话类型 Pix 密钥）或邮件（邮件类型 Pix 密钥） | [文档链接](/documentation/pix/portabilidade#reenviando-a-valida%C3%A7%C3%A3o-de-dois-fatores) | PIX0013 |
| PIX0015* | 删除 Pix 密钥转入可携带性申请 | 删除待处理的 Pix 密钥转入可携带性申请 | [文档链接](/documentation/pix/portabilidade#deletando-um-pedido-de-portabilidade) | PIX0013 |
| PIX0016* | 读取 Pix 密钥转入可携带性申请完成 webhook | 正确读取 Pix 密钥转入可携带性申请完成 webhook，测试所有可能的完成状态（concluded、cancelled 和 failed） | Webhook：<br/> [文档链接](/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade) |PIX0013 |
| PIX0017* | 模拟 Pix 密钥转出可携带性申请 | 模拟 Pix 密钥转出可携带性申请的到达 | 第 5 条：<br/> [文档链接](/documentation/pix/simulacao/index.html) | PIX0013 |
| PIX0018* | 批准和拒绝 Pix 密钥转出可携带性申请 | 批准 Pix 密钥转出可携带性申请 | [文档链接](/documentation/pix/portabilidade#request-4) | PIX0017 |
| PIX0019* | 重新发送 Pix 密钥转出可携带性申请的双因素认证 | 重新发送 Pix 密钥转出可携带性申请的双因素认证 | Enum "pending_donator_validation"  <br/> [文档链接](/documentation/pix/portabilidade#request-4) | PIX0018 |
| PIX0020* | 读取 Pix 密钥转出可携带性申请完成 webhook | 正确读取 Pix 密钥转出可携带性申请完成 webhook，测试所有可能的完成状态（concluded、cancelled 和 failed） | [文档链接](D/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade-1) | PIX0018 |

## Pix QR 码管理

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0022* | 创建静态 Pix QR 码 | 生成静态 QR 码 | [文档链接](/documentation/pix/criar_qr_code_estatico) | PIX0008 |
| PIX0023 | 创建动态 Pix QR 码 | 生成带到期日的动态 QR 码及即时动态 QR 码（带过期秒数） | [文档链接](/documentation/pix/criar_qr_code_dinamico) | PIX0008 |
| PIX0024 | 删除动态 Pix QR 码 | 删除 Pix QR 码 | [文档链接](/documentation/pix/baixar_qr_code_dinamico) | PIX0023 |
| PIX0025 | 列出动态 Pix QR 码 | 列出动态 Pix QR 码 | [文档链接](/documentation/pix/pesquisar_por_qr_code_dinamico) | PIX0023 |
| PIX0026 | 读取即时动态 Pix QR 码过期 webhook | 成功接收即时动态 Pix QR 码过期 webhook | [文档链接](/documentation/pix/webhook_por_qr_code_expirado) | PIX0023 |

## Pix QR 码支付

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |

| PIX0029* | 支付静态 Pix QR 码 | 支付静态 Pix QR 码 | [文档链接](/documentation/baas/pix/realizar_transferencia#transfer%C3%AAncia-por-qr-code-pix) | PIX0022 |
| PIX0030* | 支付动态 Pix QR 码 | 支付动态 Pix QR 码 |  [文档链接](/documentation/baas/pix/realizar_transferencia#transfer%C3%AAncia-por-qr-code-pix) | PIX0022 |
| PIX0027* | 解码 Pix QR 码 | 解码静态 Pix QR 码、带到期日动态 QR 码和即时动态 QR 码 | [文档链接](/documentation/pix/decodificar_qr_code) | PIX0022 e PIX0023 |

## Pix 限额管理

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0032* | 申请修改 Pix 限额 | 为 QI 账户发起 Pix 限额修改申请 | [文档链接](/documentation/pix/solicitar_alteracao_de_limite_pix) |  QIC0003 ou QIC0005  |
| PIX0033 | 列出 Pix 限额修改申请 | 列出 QI 账户的 Pix 限额修改申请 | [文档链接](/documentation/pix/busca_por_solicitacao_de_limite_pix) | PIX0032 |
| PIX0034* | 查询已用 Pix 限额 | 查询 QI 账户已用 Pix 限额 | [文档链接](/documentation/pix/busca_por_uso_de_limite_pix) |  QIC0003 ou QIC0005  |

---

# 费率管理
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| GTF0001* | 申请修改费率 | 修改账户费率| [文档链接](/documentation/contas/gestao_de_tarifas) |  QIC0003 ou QIC0005  |
| GTF0002* | 查询费率  | 查询账户已注册的费率 | [文档链接](/documentation/contas/consulta_de_tarifas) |  QIC0003 ou QIC0005  |

# 卡片管理

## 创建卡片
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| GDC0001* | 创建虚拟卡  | 创建虚拟卡| [文档链接](/documentation/cards/create/gerar_cartao_virtual) |  QIC0003 ou QIC0005  |
| GDC0002* | 创建实体卡  | 创建实体卡| [文档链接](/documentation/cards/create/gerar_cartao_fisico) |  QIC0003 ou QIC0005  |

## 卡片查询
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| GDC0003* | 通过密钥查询卡片  | 查询卡片 | [文档链接](/documentation/cards/search/buscar_cartao_by_key) | GDC0001 ou GDC0002 |
| GDC0004* | 列出卡片  | 列出卡片| [文档链接](/documentation/cards/search/listar_cartoes) | GDC0001 ou GDC0002 |
| GDC0005* | 查询卡片数据 | 查询卡片数据| [文档链接](/documentation/cards/search/buscar_dados_pci) | GDC0001 ou GDC0002 |
| GDC0006* | 查询 PCI 密码 | 查询 PCI 密码| [文档链接](/documentation/cards/search/buscar_senha) | GDC0001 ou GDC0002 |
| GDC0007* | 查询配送数据 | 查询配送数据| [文档链接](/documentation/cards/search/buscar_entrega_by_key) | GDC0001 ou GDC0002 |

## 更新卡片数据
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| GDC0008* | 更新卡片状态  | 更新卡片状态| [文档链接](/documentation/cards/status/update_status_cartao) | GDC0001 ou GDC0002 |
| GDC0009* | 激活实体卡  | 激活实体卡| [文档链接](/documentation/cards/status/ativar_cartao) | GDC0001 ou GDC0002 |
| GDC0010* | 修改密码   | 修改卡片密码 | [文档链接](/documentation/cards/update/password_cartao) | GDC0001 ou GDC0002 |
| GDC0011* | 配置卡片非接触功能  | 配置卡片非接触功能  | [文档链接](/documentation/cards/update/contactless_cartao) | GDC0002 |

---

# 测试指南 - BaaS 收款

URL: /zh-Hans/documentation/roteiros_de_homologacao/roteiro_cobranca

测试指南描述了集成合作伙伴在进入生产环境之前，需要在 QI Tech 沙盒环境（测试环境）中测试的所有资源和功能。

本指南描述了该产品所涉及的所有资源和功能。

:::info 注意
标有 * 的步骤是进入生产环境的必须步骤
:::

:::info 注意
⚠️ **所有测试必须强制在 QI Tech 沙盒环境（测试环境）中进行。在沙盒环境中进行的操作均为虚拟金融操作，仅用于测试 API 功能。**
:::

## BaaS API 注册与认证
| 代码  | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| CAB0001* | 在沙盒环境注册 | 在 QI Tech 平台 Sandbox 环境（sandbox.qitech.app）完成注册 | cs@qitech.com.br |
| CAB0002* | 在沙盒验证 token | 在 Sandbox 环境验证 QI Token | [下载 Token 接入手册](https://docs.qitech.com.br/assets/pdfs/QI%20Tech%20Manual%20Inclus%C3%A3o%20de%20Token.pdf) | CAB0001 |
| CAB0003* | 交换公钥 | 在 QI Tech 平台 Sandbox 环境（sandbox.qitech.app）完成公钥交换 | [文档链接](/documentation/primeiros_passos/troca_de_chaves) | CAB0001 e CAB0002 |
| CAB0004* | 完成 API 调用认证测试 | 完成 API 调用认证测试 | [分步说明](/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2) <br/><br/> [文档链接](/documentation/primeiros_passos/teste_de_autenticacao/endpoints_de_teste) | CAB0003 |
| CAB0005* | 配置 webhook | 通过 QI Tech 平台 Sandbox 环境（sandbox.qitech.app）配置 QI 发送 webhook 的 URL | [文档链接](/documentation/primeiros_passos/configurando_webhooks) | CAB0001 e CAB0002 |

---

## QI Conta

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| QIC0001* | 查询账户数据 | 查询账户余额、持有人数据、开户日期等信息 | [文档链接](/documentation/contas/consultar_contas) | CAB0003  |

---

## 交易

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| QIC0008* | 查询对账单 | 查询账户对账单 | [文档链接](/documentation/movimentacao_de_contas/consulta_de_transacoes) |  CAB0003  |
| QIC0009* | 申请转账凭证 | 申请转账凭证 | [文档链接](/documentation/movimentacao_de_contas/consulta_de_transacoes)| CAB0003 |
| QIC0010* | 读取交易 webhook | 成功接收所有交易 webhook |  [文档链接](/documentation/movimentacao_de_contas/comprovante_de_transferencia) |  CAB0003  |
| QIC0011* | 查询金融机构列表 | 查询可接收 TED 和 Pix 的金融机构列表 |  [文档链接](/documentation/lista_de_instituicoes_financeiras/consulta_de_instituicoes_financeiras) |  CAB0003  |

---

## 票据

### Pix 密钥管理
#### Pix 密钥的创建与删除
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0001* | 创建 Pix 密钥 | 创建 CPF、CNPJ、随机、邮件和电话类型的 Pix 密钥 | [文档链接](/documentation/pix/criar_chave) | 
| PIX0010* | 列出 QI 账户的 Pix 密钥 | 列出绑定到 QI 账户的 Pix 密钥 | [文档链接](/documentation/pix/listar_chaves_pix) | PIX0001 |

### 钱包管理
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| CRT0001* | 创建钱包 | 为特定付款、核销、催收等配置创建钱包  | [文档链接](/documentation/boletos/carteira/criar_carteira) | 
| CRT0002* | 编辑钱包 | 编辑默认配置  | [文档链接](/documentation/boletos/carteira/editar_carteira) |  CRT0002  |

### 票据管理
| 编号      | 步骤 | 描述 | 链接  | 前置条件 |
|---|---|---|---|---|
| BOL0001 | 登记标准单张收款票据    | 登记一张收款票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao/index.html) | CAB0002 ou CAB0003   |
| BOL0002 | 登记即时单张收款票据 | 登记一张收款票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) | CAB0002 ou CAB0003   |
| BOL0003 | 批量登记收款票据  | 批量登记收款票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_em_lote) | CAB0002 ou CAB0003   |
| BOL0004 | 对票据进行折扣减额 | 对票据进行折扣减额 | [文档链接](/documentation/boletos/v2/instrucoes/abatimento/criar_abatimento) | BOL0001, BOL0002 ou BOL0003 |
| BOL0005 | 取消票据折扣减额     | 取消票据折扣减额 | [文档链接](/documentation/boletos/v2/instrucoes/abatimento/cancelar_abatimento) | BOL0001, BOL0002 ou BOL0003  |
| BOL0006 | 延长票据到期日               | 延长票据到期日 | [文档链接](/documentation/boletos/v2/instrucoes/extensao)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0007 | 添加票据折扣               | 添加票据折扣    | [文档链接](/documentation/boletos/v2/instrucoes/desconto)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0008 | 添加票据利息                   | 添加票据利息       | [文档链接](/documentation/boletos/v2/instrucoes/juros)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0009 | 添加票据罚金                   | 添加票据罚金       | [文档链接](/documentation/boletos/v2/instrucoes/multa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0010 | 核销票据                   | 核销票据                 | [文档链接](/documentation/boletos/v2/instrucoes/baixa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0011 | 通过密钥查询票据      | 通过密钥查询票据      | [文档链接](/documentation/boletos/v2/consulta/consulta_por_chave) | BOL0001, BOL0002 ou BOL0003   |
| BOL0012 | 列出票据          | 列出票据     | [文档链接](/documentation/boletos/v2/consulta/listar_boletos) | BOL0001, BOL0002 ou BOL0003   |
| BOL0013 | 查询收款钱包      | 查询收款钱包 | [文档链接](/documentation/boletos/v2/carteira/listar_carteiras/index.html) | BOL0001, BOL0002 ou BOL0003   |
| BOL0014 | 票据 webhook      | 读取票据 webhook | [文档链接](/documentation/boletos/v2/webhooks/boleto) | BOL0001, BOL0002 ou BOL0003   |

### 票据对账
| 编号      | 步骤 | 描述 | 链接  | 前置条件 |
|---|---|---|---|---|
| CON0001 | 列出清算组  | 列出已清算票据的清算组 | [文档链接](/documentation/boletos/liquidacao/listar_grupos_de_liquidacao) | BOL0001 ou BOL0002 ou BOL0003   |
| CON0002 | 列出清算记录 | 列出清算组中的票据 | [文档链接](/documentation/boletos/liquidacao/listar_liquidacoes) | BOL0001 ou BOL0002 ou BOL0003   |

## 费率管理
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| GTF0001* | 申请修改费率 | 修改账户费率| [文档链接](/documentation/contas/gestao_de_tarifas) |  
| GTF0002* | 查询费率  | 查询账户已注册的费率 | [文档链接](/documentation/contas/consulta_de_tarifas) |

---

# 测试指南 - BaaS 数字账户（双重认证）

URL: /zh-Hans/documentation/roteiros_de_homologacao/roteiro_conta_digital

测试指南描述了集成合作伙伴在进入生产环境之前，需要在 QI Tech 沙盒环境（测试环境）中测试的所有资源和功能。

本指南描述了该产品所涉及的所有资源和功能。

⚠️ **所有测试必须强制在 QI Tech 沙盒环境（测试环境）中进行。在沙盒环境中进行的操作均为虚拟金融操作，仅用于测试 API 功能。**

## BaaS API 注册与认证
| 代码  | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| CAB0001* | 在沙盒环境注册 | 在 QI Tech 平台 Sandbox 环境（sandbox.qitech.app）完成注册 | cs@qitech.com.br |
| CAB0002* | 在沙盒验证 token | 在 Sandbox 环境验证 QI Token | [文档链接](https://docs.qitech.com.br/assets/pdfs/QI%20Tech%20Manual%20Inclus%C3%A3o%20de%20Token.pdf) | CAB0001 |
| CAB0003* | 交换公钥 | 在 QI Tech 平台 Sandbox 环境（sandbox.qitech.app）完成公钥交换 | [文档链接](/documentation/primeiros_passos/troca_de_chaves) | CAB0001 e CAB0002 |
| CAB0004* | 完成 API 调用认证测试 | 完成 API 调用认证测试 |[文档链接](/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2) <br/><br/> [文档链接](/documentation/primeiros_passos/teste_de_autenticacao/endpoints_de_teste) | CAB0003 |
| CAB0005* | 配置 webhook | 通过 QI Tech 平台 Sandbox 环境（sandbox.qitech.app）配置 QI 发送 webhook 的 URL | [文档链接](/documentation/primeiros_passos/configurando_webhooks) | CAB0001 e CAB0002 |

## 反欺诈

## 注册与认证

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| ATF0002* | 获取 onboarding API 密钥 | 向 QI Tech 集成团队获取用于 /onboarding API 的 API 密钥 | suporte.caas@qitech.com.br |  
| ATF0003* | 获取 OCR 移动令牌 | 向 QI Tech 集成团队获取用于 OCR SDK 的移动令牌 | suporte.caas@qitech.com.br |  
| ATF0004* | 获取人脸识别移动令牌 | 向 QI Tech 集成团队获取用于人脸识别 SDK 的移动令牌 | suporte.caas@qitech.com.br |  
| ATF0005* | 获取设备扫描移动令牌 | 向 QI Tech 集成团队获取用于设备扫描 SDK 的移动令牌 | suporte.caas@qitech.com.br |  

## SDK OCR

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| ATF0007* | 构建 SDK | 定义文件采集的模板和自定义选项，并在您的应用中（QI Tech 客户应用）成功构建 SDK | Android: [文档链接](/documentation/caas/ocr/android/introduction) <br/> iOS:[ 文档链接](/documentation/caas/ocr/ios/introduction) |  |
| ATF0008* | 发送文件 | 在您的应用中（QI Tech 客户应用）使用 SDK 完成文件采集 |  | ATF0003 e ATF0007 |
| ATF0009* | 存储 ocr_key | 存储 SDK 返回的密钥，识别采集文件的类型（例如：cnh_front、cnh_back 等） | Android: [文档链接](/documentation/caas/ocr/android/collecting_response) <br/>iOS:[ 文档链接](/documentation/caas/ocr/ios/collecting_response)| ATF0008 |

## SDK 人脸识别

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| ATF0011* | 构建 SDK | 定义自定义选项并在您的应用中（QI Tech 客户应用）成功构建 SDK |Android: [文档链接](/documentation/caas/face_recognition/android/introduction) <br/>iOS:[ 文档链接](/documentation/caas/face_recognition/ios/introduction)  |  |
| ATF0012* | 活体检测流程 | 在您的应用中（QI Tech 客户应用）使用 SDK 完成活体检测流程 | | ATF0004 e ATF0011* |
| ATF0013* | 存储图像密钥 | 完成活体检测流程后，存储 SDK 返回的 image_key | Android: [文档链接](/documentation/caas/face_recognition/android/collecting_response) iOS:[ 文档链接](/documentation/caas/face_recognition/ios/collecting_response) | ATF0012 |

## SDK 设备扫描

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| ATF0015* | 构建 SDK | 定义您的应用（QI Tech 客户应用）向用户请求的权限，并在您的应用中成功构建 SDK | Android: [文档链接](/documentation/caas/device_scan/android/introduction)<br/>iOS:[ 文档链接](/documentation/caas/device_scan/ios/introduction)|  
| ATF0016* | 存储用户会话 | 存储待扫描设备的用户会话（sessionId） | Android: [文档链接](/documentation/caas/device_scan/android/example)<br/>iOS:[ 文档链接](/documentation/caas/device_scan/ios/example) | ATF0015 e ATF0017 |
| ATF0017* | 采集信息 | 使用已存储的 sessionId 实例化 SDK，并在您的应用中（QI Tech 客户应用）调用信息采集方法 | Android: [文档链接](/documentation/caas/face_recognition/android/collecting_response)<br/>iOS:[ 文档链接](/documentation/caas/face_recognition/ios/collecting_response) | ATF0005 e ATF0015 |

## 反欺诈

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| ATF0019* | 个人客户反欺诈 | 成功完成个人客户的反欺诈流程 | [文档链接](/documentation/caas/onboarding/natural_person) | ATF0002 |
| ATF0020* | 企业客户反欺诈 | 成功完成企业客户的反欺诈流程 | [文档链接](/documentation/caas/onboarding/legal_person) | ATF0002 |
| ATF0021* | 读取异步流程中的分析派生 webhook | 成功接收异步响应流程中的分析派生 webhook |[文档链接](/documentation/caas/onboarding/webhook) | ATF0019 ou ATF0020 |

## 平台注册

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| ATF0022* | 注册主用户 | 在 CaaS 平台注册主用户，用于处理转到"人工分析"的派生请求  | suporte.caas@qitech.com.br | ATF0019 ou ATF0020 |

---

# **QI Conta**

## 开户

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| QIC0002* | 预留个人账户 | 申请预留持有人为自然人的账户 | [文档链接](/documentation/baas/account/reservar_conta_pf) | CAB0005 e CAB0006 |
| QIC0003* | 开设个人账户 | 完成持有人为自然人的账户开户 | [文档链接](/documentation/baas/account/abrir_conta_pf) | QIC0002 |
| QIC0004* | 预留企业账户 | 申请预留持有人为法人的账户 | [文档链接](/documentation/baas/account/reservar_conta_pj) | CAB0005 e CAB0006 |
| QIC0005* | 开设企业账户 | 完成持有人为法人的账户开户 | [文档链接](/documentation/baas/account/abrir_conta_pj) | QIC0004 |
| QIC0006* | 读取开户 webhook | 正确读取开户 webhook | 第 1.2. 或 1.3 条：<br/>[文档链接](/documentation/baas/account/webhooks) |  QIC0003 ou QIC0005  |
| QIC0007* | 列出账户 | 列出已开设账户 | [文档链接](/documentation/contas/consultar_conta) |  QIC0003 ou QIC0005  |
| QIC0008* | 查询账户数据 | 查询账户余额、持有人数据、开户日期等信息 | [文档链接](/documentation/contas/consultar_conta) | QIC0003 ou QIC0005  |

## 交易

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| QIC0008* | 查询对账单 | 查询账户对账单 | [文档链接](/documentation/movimentacao_de_contas/consulta_de_transacoes) |  QIC0003 ou QIC0005  |
| QIC0009* | 申请转账凭证 | 申请转账凭证 | [文档链接](/documentation/movimentacao_de_contas/comprovante_de_transferencia)|  |
| QIC0010* | 读取交易 webhook | 成功接收所有交易 webhook |  [文档链接](/documentation/movimentacao_de_contas/webhook_movimentacoes/index.html) |  QIC0003 ou QIC0005  |
| QIC0011* | 查询金融机构列表 | 查询可接收 TED 和 Pix 的金融机构列表 |  [文档链接](/documentation/lista_de_instituicoes_financeiras/consulta_de_instituicoes_financeiras) |  QIC0003 ou QIC0005  |

---

# 文件上传

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| UDD0001* | 上传文件 | 通过文件 API 上传文件 |  [文档链接](/documentation/upload_de_documentos/) |  |

---

# TED

| 代码 | 步骤 | 描述 | 链接                                                                                                        | 前置条件 |
| --- | --- | --- |-------------------------------------------------------------------------------------------------------------| --- |
| TED0001* | TED 转出 | 进行 TED 转账  | 1. 创建转账申请：[文档链接](/documentation/baas/ted/realizar_transferencia_2fa) <br/>   2. 审批转账：[文档链接](/documentation/baas/ted/realizar_transferencia_2fa) <br/>           | QIC0003 ou QIC0005 |
| TED0002* | 申请重新发送令牌 | 重新发送 TED 转账审批令牌 | [文档链接](/documentation/baas/ted/2fa/solicitacao_de_reenvio_de_token) | TED0001 |
| TED0003* | 模拟 TED 转出退回 | 模拟从 QI 账户发出的 TED 转出退款 | 第 3 条：<br/>[文档链接](/documentation/movimentacao_de_contas/transacao) | TED0004 |
| TED0004* | 模拟 TED 转入 | 模拟 TED 转入到 QI 账户 | 第 2 条：<br/>[文档链接](/documentation/movimentacao_de_contas/transacao) | QIC0003 ou QIC0005 |
| TED0005* | 列出 TED 交易 | 列出 TED 入账/出账交易  | [文档链接](/documentation/baas/ted/listar_teds)  | QIC0003 ou QIC0005 |
| TED0006* | 查询 TED 交易 | 查询一笔 TED 交易  | [文档链接](/documentation/baas/ted/consultar_ted)           | TED0001 ou TED0004  |
| TED0007* | 读取 TED webhook | 成功接收 TED webhook | [文档链接](/documentation/baas/ted/webhooks/index.html)| TED0001 ou TED0004 |
---

# 内部转账

| 编号 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| TFI0001 | 账户借记内部转账 | 从 QI 账户发起转账，目标为另一个 QI 账户 |  1. 创建转账申请：[文档链接](/documentation/baas/ted/realizar_transferencia_2fa) <br/>   2. 审批转账：[文档链接](/documentation/baas/ted/realizar_transferencia_2fa) <br/> |  QIC0003 ou QIC0005  |
| TFI0002 | 模拟账户贷记内部转账 | 模拟目标 QI 账户从另一个 QI 账户收款 | 第 1 条：<br/> [文档链接](/documentation/movimentacao_de_contas/transacao) |  QIC0003 ou QIC0005  |

---

# 票据

## 票据管理

| 编号 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| 编号      | 步骤 | 描述 | 链接  | 前置条件 |
|---|---|---|---|---|
| BOL0001 | 登记单张标准收款票据    | 登记一张收款票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao/index.html) | QIC0003 ou QIC0005   |
| BOL0002 | 登记单张即时收款票据 | 登记一张收款票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) | QIC0003 ou QIC0005   |
| BOL0003 | 批量登记收款票据  | 批量登记收款票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_em_lote) | QIC0003 ou QIC0005   |
| BOL0004 | 开具标准单张票据        | 开具标准单张票据    | [文档链接](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao)  | QIC0003 ou QIC0005   |
| BOL0005 | 开具即时单张票据   | 开具即时单张票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) | QIC0003 ou QIC0005   |
| BOL0006 | 批量开具票据   | 批量开具票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_em_lote)| QIC0003 ou QIC0005   |
| BOL0007 | 对票据进行折扣减额 | 对票据进行折扣减额 | [文档链接](/documentation/boletos/v2/instrucoes/abatimento/criar_abatimento) | BOL0001, BOL0002 ou BOL0003 |
| BOL0008 | 取消票据折扣减额     | 取消票据折扣减额 | [文档链接](/documentation/boletos/v2/instrucoes/abatimento/cancelar_abatimento) | BOL0001, BOL0002 ou BOL0003  |
| BOL0009 | 延长票据到期日               | 延长票据到期日 | [文档链接](/documentation/boletos/v2/instrucoes/extensao)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0010 | 添加票据折扣               | 添加票据折扣    | [文档链接](/documentation/boletos/v2/instrucoes/desconto)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0011 | 添加票据利息                   | 添加票据利息       | [文档链接](/documentation/boletos/v2/instrucoes/juros)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0012 | 添加票据罚金                   | 添加票据罚金       | [文档链接](/documentation/boletos/v2/instrucoes/multa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0013 | 核销票据                   | 核销票据                 | [文档链接](/documentation/boletos/v2/instrucoes/baixa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0014 | 通过密钥查询票据      | 通过密钥查询票据      | [文档链接](/documentation/boletos/v2/consulta/consulta_por_chave) | BOL0001, BOL0002 ou BOL0003   |
| BOL0015 | 列出票据          | 列出票据     | [文档链接](/documentation/boletos/v2/consulta/listar_boletos) | BOL0001, BOL0002 ou BOL0003   |
| BOL0016 | 查询收款钱包      | 查询收款钱包 | [文档链接](/documentation/boletos/v2/carteira/listar_carteiras/index.html) | BOL0001, BOL0002 ou BOL0003   |
| BOL0017 | 票据 webhook      | 读取票据 webhook | [文档链接](/documentation/boletos/v2/webhooks/boleto) | BOL0001, BOL0002 ou BOL0003   |

## 票据支付

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| BOL0009* | 查询可打印条形码 | 查询银行票据的可打印条形码 | [文档链接](/documentation/baas/cobranca/consultar_boleto_bancario) |  |
| BOL0010* | 申请票据支付令牌 | 申请银行票据支付令牌 | [文档链接](/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_boleto_bancario) |  QIC0003 ou QIC0005  |
| BOL0011* | 审批票据支付 | 申请银行票据支付令牌  | [文档链接](/documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_boleto_bancario) |  QIC0003 ou QIC0005  |
| BOL0012* | 查询协议票据条形码 | 查询协议票据的可打印条形码 | [文档链接](/documentation/baas/cobranca/consultar_fatura_de_recolhimento) |  |
| BOL0013* | 申请协议票据支付令牌 | 申请协议票据支付令牌 | [文档链接](/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_fatura_de_recolhimento) |  QIC0003 ou QIC0005  |
| BOL0014* | 审批协议票据支付 | 申请协议票据支付令牌  | [文档链接](/documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_fatura_de_recolhimento) |  QIC0003 ou QIC0005  |

---

## Pix

## Pix 转账
| 代码  | 步骤 | 描述 | 文档链接 | 前置条件 |
|---------|--|---|---|---|
| PIX0002* | Pix 转出 | 从 QI 账户使用银行信息（手动 Pix）或 Pix 密钥发起 Pix 转账 | [1. 申请转账](/documentation/baas/pix/2fa_v2/solicitacao_de_transacao_pix_2fa) <br></br> [2. 审批转账](/documentation/baas/pix/2fa_v2/aprovar_transacao_pix_2fa) | CAB0001 |
| PIX0035 | 查询 Pix 转账 | 获取一笔转账的数据 | [文档链接](/documentation/baas/pix/consultar_transferencias) | PIX0002 |
| PIX0003* | 模拟 Pix 转出退款 | 模拟 Pix 转出退款 | [文档链接 - 第 2 条](/documentation/pix/simulacao)| PIX0002 |
| PIX0004* | 模拟 Pix 转入 | 模拟 Pix 转入到 QI 账户 | [文档链接 -> 第 1 条](/documentation/pix/simulacao)||
| PIX0037* | 读取待处理交易 webhook | 成功接收待处理交易 webhook | [文档链接][(/documentation/baas/pix/webhooks) | PIX0002 |
| PIX0038* | 读取 Pix 转入 webhook | 成功接收 Pix 转入 webhook | [文档链接](/documentation/baas/pix/webhooks#webhook-para-pix-de-entrada)| PIX0004 |
| PIX0039 | 读取 Pix 退款 webhook | 成功接收 Pix 退款 webhook | [文档链接](/documentation/baas/pix/webhooks#webhook-para-devolu%C3%A7%C3%B5es-de-pix) | PIX0003 |
| PIX0040 | 申请退还已收 Pix | 申请退还已收 Pix | [1. 申请退款](/documentation/baas/pix/2fa_v2/solicitacao_de_devolucao_pix) <br></br> [2. 审批退款](/documentation/baas/pix/2fa_v2/aprovar_transacao_pix_2fa) | PIX0003 |
| PIX0041 | 列出账户的 Pix 转账 | 列出账户的 Pix 转账 | [文档链接](/documentation/baas/pix/listar_transferencias) | PIX0003 |

## Pix 密钥管理

### Pix 密钥的创建与删除

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0008* | 创建 Pix 密钥 | 创建 CPF、CNPJ、随机、邮件和电话类型的 Pix 密钥 | [文档链接](/documentation/pix/criar_chave) | 
|QIC0003 ou QIC0005  |](/documentation/baas/pix/consultar_chave_pix)
| PIX0009 | 删除 Pix 密钥 | 删除一个 Pix 密钥 | [文档链接](/documentation/pix/excluir_chave) | PIX0008 |
| PIX0010* | 列出 QI 账户的 Pix 密钥 | 列出绑定到 QI 账户的 Pix 密钥 | [文档链接](/documentation/pix/listar_chaves_pix) | PIX0008 |

### Pix 密钥可携带性

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0013* | 创建 Pix 密钥转入可携带性申请 | 创建 CPF、CNPJ、邮件、电话和随机类型 Pix 密钥的转入可携带性申请 | [文档链接](/documentation/pix/portabilidade#criando-um-pedido-de-portabilidade) |  QIC0003 ou QIC0005  |
| PIX0014* | 重新发送电话/邮箱类型 Pix 密钥转入可携带性申请的双因素认证 | 为处于待处理状态（pending_claimer_validation）的 Pix 密钥转入可携带性申请重新发送短信（电话类型 Pix 密钥）或邮件（邮件类型 Pix 密钥） | [文档链接](/documentation/pix/portabilidade#reenviando-a-valida%C3%A7%C3%A3o-de-dois-fatores) | PIX0013 |
| PIX0015* | 删除 Pix 密钥转入可携带性申请 | 删除待处理的 Pix 密钥转入可携带性申请 | [文档链接](/documentation/pix/portabilidade#deletando-um-pedido-de-portabilidade) | PIX0013 |
| PIX0016* | 读取 Pix 密钥转入可携带性申请完成 webhook | 正确读取 Pix 密钥转入可携带性申请完成 webhook，测试所有可能的完成状态（concluded、cancelled 和 failed） | Webhook：<br/> [文档链接](/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade) |PIX0013 |
| PIX0017* | 模拟 Pix 密钥转出可携带性申请 | 模拟 Pix 密钥转出可携带性申请的到达 | 第 5 条：<br/> [文档链接](/documentation/pix/simulacao/index.html) | PIX0013 |
| PIX0018* | 批准和拒绝 Pix 密钥转出可携带性申请 | 批准 Pix 密钥转出可携带性申请 | [文档链接](/documentation/pix/portabilidade#request-4) | PIX0017 |
| PIX0019* | 重新发送 Pix 密钥转出可携带性申请的双因素认证 | 重新发送 Pix 密钥转出可携带性申请的双因素认证 | Enum "pending_donator_validation"  <br/> [文档链接](/documentation/pix/portabilidade#request-4) | PIX0018 |
| PIX0020* | 读取 Pix 密钥转出可携带性申请完成 webhook | 正确读取 Pix 密钥转出可携带性申请完成 webhook，测试所有可能的完成状态（concluded、cancelled 和 failed） | [文档链接](D/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade-1) | PIX0018 |

## Pix QR 码管理

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0022* | 创建静态 Pix QR 码 | 生成静态 QR 码 | [文档链接](/documentation/pix/criar_qr_code_estatico) | PIX0008 |
| PIX0023 | 创建动态 Pix QR 码 | 生成带到期日的动态 QR 码及即时动态 QR 码（带过期秒数） | [文档链接](/documentation/pix/criar_qr_code_dinamico) | PIX0008 |
| PIX0024 | 删除动态 Pix QR 码 | 删除 Pix QR 码 | [文档链接](/documentation/pix/baixar_qr_code_dinamico) | PIX0023 |
| PIX0025 | 列出动态 Pix QR 码 | 列出动态 Pix QR 码 | [文档链接](/documentation/pix/pesquisar_por_qr_code_dinamico) | PIX0023 |
| PIX0026 | 读取即时动态 Pix QR 码过期 webhook | 成功接收即时动态 Pix QR 码过期 webhook | [文档链接](/documentation/pix/webhook_por_qr_code_expirado) | PIX0023 |

## Pix QR 码支付

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0029* | 支付静态 Pix QR 码 | 支付静态 Pix QR 码 | [1. 申请转账](/documentation/baas/pix/2fa_v2/solicitacao_de_transacao_pix_2fa) <br></br> [2. 审批转账](/documentation/baas/pix/2fa_v2/aprovar_transacao_pix_2fa) | PIX0022 |
| PIX0030* | 支付动态 Pix QR 码 | 支付动态 Pix QR 码 |  [1. 申请转账](/documentation/baas/pix/2fa_v2/solicitacao_de_transacao_pix_2fa) <br></br> [2. 审批转账](/documentation/baas/pix/2fa_v2/aprovar_transacao_pix_2fa) | PIX0022 |
| PIX0027* | 解码 Pix QR 码 | 解码静态 Pix QR 码、带到期日动态 QR 码和即时动态 QR 码 | [文档链接](/documentation/pix/decodificar_qr_code) | PIX0022 e PIX0023 |

## Pix 限额管理

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0032* | 申请修改 Pix 限额 | 为 QI 账户发起 Pix 限额修改申请 | [文档链接](/documentation/pix/solicitar_alteracao_de_limite_pix) |  QIC0003 ou QIC0005  |
| PIX0033 | 列出 Pix 限额修改申请 | 列出 QI 账户的 Pix 限额修改申请 | [文档链接](/documentation/pix/busca_por_solicitacao_de_limite_pix) | PIX0032 |
| PIX0034* | 查询已用 Pix 限额 | 查询 QI 账户已用 Pix 限额 | [文档链接](/documentation/pix/busca_por_uso_de_limite_pix) |  QIC0003 ou QIC0005  |

---

# 费率管理
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| GTF0001* | 申请修改费率 | 修改账户费率| [文档链接](/documentation/contas/gestao_de_tarifas) |  QIC0003 ou QIC0005  |
| GTF0002* | 查询费率  | 查询账户已注册的费率 | [文档链接](/documentation/contas/consulta_de_tarifas) |  QIC0003 ou QIC0005  |

## 管理员用户管理
| GUA0001* | 添加管理员用户 | 创建管理员用户并绑定到 QI 账户 | 简介：[文档](/documentation/gestao_de_usuarios/tfa_introducao)<br/>1. 创建：[文档](/documentation/gestao_de_usuarios/criacao_de_pessoa)<br/>2. 绑定：[文档](/documentation/gestao_de_usuarios/inclusao_de_vinculo) | QIC0003 ou QIC0005 |
| GUA0002* | 修改管理员联系信息 | 修改管理员用户的联系信息（邮件和电话） | [文档链接](/documentation/gestao_de_usuarios/alteracao_de_contato_de_vinculo) | QIC0003 ou QIC0005 |
| GUA0003* | 删除管理员用户 | 解除管理员用户与 QI 账户的绑定关系 | [文档链接](/documentation/gestao_de_usuarios/exclusao_de_vinculo) |  QIC0003 ou QIC0005 |

# 卡片管理

## 创建卡片
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| GDC0001* | 创建虚拟卡  | 创建虚拟卡| [文档链接](/documentation/cards/create/gerar_cartao_virtual) |  QIC0003 ou QIC0005  |
| GDC0002* | 创建实体卡  | 创建实体卡| [文档链接](/documentation/cards/create/gerar_cartao_fisico) |  QIC0003 ou QIC0005  |

## 卡片查询
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| GDC0003* | 通过密钥查询卡片  | 查询卡片 | [文档链接](/documentation/cards/search/buscar_cartao_by_key) | GDC0001 ou GDC0002 |
| GDC0004* | 列出卡片  | 列出卡片| [文档链接](/documentation/cards/search/listar_cartoes) | GDC0001 ou GDC0002 |
| GDC0005* | 查询卡片数据 | 查询卡片数据| [文档链接](/documentation/cards/search/buscar_dados_pci) | GDC0001 ou GDC0002 |
| GDC0006* | 查询 PCI 密码 | 查询 PCI 密码| [文档链接](/documentation/cards/search/buscar_senha) | GDC0001 ou GDC0002 |
| GDC0007* | 查询配送数据 | 查询配送数据| [文档链接](/documentation/cards/search/buscar_entrega_by_key) | GDC0001 ou GDC0002 |

## 更新卡片数据
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| GDC0008* | 更新卡片状态  | 更新卡片状态| [文档链接](/documentation/cards/status/update_status_cartao) | GDC0001 ou GDC0002 |
| GDC0009* | 激活实体卡  | 激活实体卡| [文档链接](/documentation/cards/status/ativar_cartao) | GDC0001 ou GDC0002 |
| GDC0010* | 修改密码   | 修改卡片密码 | [文档链接](/documentation/cards/update/password_cartao) | GDC0001 ou GDC0002 |
| GDC0011* | 配置卡片非接触功能  | 配置卡片非接触功能  | [文档链接](/documentation/cards/update/contactless_cartao) | GDC0002 |

---

# 测试指南 - BaaS 数字账户

URL: /zh-Hans/documentation/roteiros_de_homologacao/roteiro_conta_digital_d795dc71-05b2-4476-bfbc-07ef247abd90

测试指南描述了集成合作伙伴在进入生产环境之前，需要在 QI Tech 沙盒环境（测试环境）中测试的所有资源和功能。

本指南描述了该产品所涉及的所有资源和功能。
:::info 注意
标有 * 的步骤是进入生产环境的必须步骤
:::

⚠️ **所有测试必须强制在 QI Tech 沙盒环境（测试环境）中进行。在沙盒环境中进行的操作均为虚拟金融操作，仅用于测试 API 功能。**

## BaaS API 注册与认证
| 代码  | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| CAB0001* | 在沙盒环境注册 | 在 QI Tech 平台的沙盒环境（sandbox.qitech.app）中完成注册 | cs@qitech.com.br |
| CAB0002* | 在沙盒验证 token | 在沙盒环境中完成 QI Token 验证 | [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* | 交换公钥 | 在 QI Tech 平台沙盒环境（sandbox.qitech.app）中完成公钥交换 | [Link Documentação](/documentation/primeiros_passos/troca_de_chaves) | CAB0001 和 CAB0002 |
| CAB0004* | 完成 API 调用认证测试 | 完成 API 调用认证测试 | [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* | 配置 webhook | 通过 QI Tech 平台沙盒环境（sandbox.qitech.app）完成 QI 发送 webhook 的 URL 配置 | [Link Documentação](/documentation/primeiros_passos/configurando_webhooks) | CAB0001 和 CAB0002 |

## 反欺诈

## 注册与认证

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| ATF0002* | 获取入驻 API 密钥 | 向 QI Tech 集成团队获取用于 /onboarding API 的 API 密钥 | suporte.caas@qitech.com.br |  
| ATF0003* | 获取 OCR 移动令牌 | 向 QI Tech 集成团队获取用于 OCR SDK 的移动令牌 | suporte.caas@qitech.com.br |  
| ATF0004* | 获取人脸识别移动令牌 | 向 QI Tech 集成团队获取用于人脸识别 SDK 的移动令牌 | suporte.caas@qitech.com.br |  
| ATF0005* | 获取设备扫描移动令牌 | 向 QI Tech 集成团队获取用于设备扫描 SDK 的移动令牌 | suporte.caas@qitech.com.br |  

## SDK OCR

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| ATF0007* | 构建 SDK | 定义文档采集的模板和自定义配置，并在您的应用（QI Tech 客户端应用）中成功构建 SDK | Android: [Link Documentação](/documentation/caas/ocr/android/introduction) <br/> iOS:[ Link Documentação](/documentation/caas/ocr/ios/introduction) |  |
| ATF0008* | 提交文档 | 在您的应用（QI Tech 客户端应用）中使用 SDK 完成文档采集 |  | ATF0003 和 ATF0007 |
| ATF0009* | 存储 ocr_key | 存储 SDK 返回的密钥，并识别所采集文档的类型（例如：cnh_front、cnh_back 等） | Android: [Link Documentação](/documentation/caas/ocr/android/collecting_response) <br/>iOS:[ Link Documentação](/documentation/caas/ocr/ios/collecting_response)| ATF0008 |

## SDK 人脸识别

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| ATF0011* | 构建 SDK | 定义自定义配置并在您的应用（QI Tech 客户端应用）中成功构建 SDK |Android: [Link Documentação](/documentation/caas/face_recognition/android/introduction) <br/>iOS:[ Link Documentação](/documentation/caas/face_recognition/ios/introduction)  |  |
| ATF0012* | 活体检测流程 | 在您的应用（QI Tech 客户端应用）中使用 SDK 完成活体检测流程 | | ATF0004 和 ATF0011* |
| ATF0013* | 存储图像密钥 | 在完成活体检测流程后存储 SDK 返回的 image_key | Android: [Link Documentação](/documentation/caas/face_recognition/android/collecting_response) iOS:[ Link Documentação](/documentation/caas/face_recognition/ios/collecting_response) | ATF0012 |

## SDK 设备扫描

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| ATF0015* | 构建 SDK | 定义您的应用（QI Tech 客户端应用）向用户请求的权限，并在您的应用（QI Tech 客户端应用）中成功构建 SDK | Android: [Link Documentação](/documentation/caas/device_scan/android/introduction)<br/>iOS:[ Link Documentação](/documentation/caas/device_scan/ios/introduction)|  
| ATF0016* | 存储用户会话 | 存储将要被扫描设备的用户会话（sessionId） | Android: [Link Documentação](/documentation/caas/device_scan/android/example)<br/>iOS:[ Link Documentação](/documentation/caas/device_scan/ios/example) | ATF0015 和 ATF0017 |
| ATF0017* | 采集信息 | 使用存储的 sessionId 实例化 SDK，并在您的应用（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 和 ATF0015 |

## 反欺诈

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| ATF0019* | 自然人反欺诈 | 成功完成自然人客户的反欺诈 | [Link Documentação](/documentation/caas/onboarding/natural_person) | ATF0002 |
| ATF0020* | 法人反欺诈 | 成功完成法人客户的反欺诈 | [Link Documentação](/documentation/caas/onboarding/legal_person) | ATF0002 |
| ATF0021* | 读取异步流程派生分析 webhook | 成功接收异步响应流程的派生分析 webhook |[Link Documentação](/documentation/caas/onboarding/webhook) | ATF0019 或 ATF0020 |

## 平台注册

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| ATF0022* | 注册主用户 | 在 CaaS 平台注册主用户，用于处理派生至"人工审核"的请求  | suporte.caas@qitech.com.br | ATF0019 或 ATF0020 |

---

# **QI Conta**

## 开户

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| QIC0002* | 开设自然人账户 | 开设一个持有人为自然人的账户 | [Link Documentação](/documentation/baas/manual_baas#13-cria%C3%A7%C3%A3o-da-conta-pf) |  |
| QIC0002* | 开设法人账户 | 开设一个持有人为法人的账户 | [Link Documentação](/documentation/baas/manual_baas#12-cria%C3%A7%C3%A3o-da-conta-pj) | CAB0005 和 CAB0006 |
| QIC0004* | 读取开户 webhook | 正确读取开户 webhook | Item 1.2. 或 1.3:<br/>[Link Documentação](/documentation/baas/manual_baas#12-cria%C3%A7%C3%A3o-da-conta-pj) |  QIC0002 或 QIC0002  |
| QIC0005* | 查询账户数据 | 查询余额、持有人数据、开户日期等账户数据 | [Link Documentação](/documentation/contas/consultar_contas) |  QIC0002 或 QIC0002  |

## 交易

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| QIC0008* | 查询对账单 | 查询账户对账单 | [Link Documentação](/documentation/movimentacao_de_contas/consulta_de_transacoes) |  QIC0002 或 QIC0002  |
| QIC0009* | 申请转账凭证 | 申请一张转账凭证 | [Link Documentação](/documentation/movimentacao_de_contas/consulta_de_transacoes)|  |
| QIC0010* | 读取交易 webhook | 成功接收所有交易 webhook |  [Link Documentação](/documentation/movimentacao_de_contas/comprovante_de_transferencia) |  QIC0002 或 QIC0002  |
| QIC0011* | 查询金融机构列表 | 查询可接收 TED 和 Pix 的金融机构列表 |  [Link Documentação](/documentation/lista_de_instituicoes_financeiras/consulta_de_instituicoes_financeiras) |  QIC0002 或 QIC0002  |

---

# 文件上传

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| UDD0001* | 上传文件 | 通过文档 API 上传文件 |  [Link Documentação](/documentation/upload_de_documentos/) |  |

---

# TED

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| TED0001* | TED 转出 | 向其他金融机构进行 TED 转账 | [Link Documentação](/documentation/baas/ted/realizar_transferencia) | QIC0002 或 QIC0002 |
| TED0002* | 模拟 TED 转出退回 | 模拟从 QI 账户发出的 TED 转出退回 | Item 3: <br/>[Link Documentação](/documentation/movimentacao_de_contas/transacao) | TED0001 |
| TED0003* | 模拟 TED 转入 | 模拟 TED 转入到 QI 账户 | Item 2: <br/>[Link Documentação](/documentation/movimentacao_de_contas/transacao) | QIC0002 或 QIC0002 |
| TED0004* | 查询 TED 交易 | 列出 TED 交易  | [Link Documentação](/documentation/baas/ted/listar_transferencias) | QIC0002 或 QIC0002 |
| TED0004* | 查询 TED 交易 | 查询一笔 TED 交易  | [Link Documentação](/documentation/baas/ted/consultar_transferencia) | QIC0002 或 QIC0002 |
| TED0006* | 读取 TED webhook | 成功接收 TED webhook | [Link Documentação](/documentation/baas/ted/webhooks) | QIC0002 或 QIC0002 |
---

# 内部转账

| 编号 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| TFI0001 | 账户借记内部转账 | 从一个 QI 账户发起转账，目标账户为另一个 QI 账户 | [Link Documentação](/documentation/baas/ted/realizar_transferencia) |  QIC0002 或 QIC0002  |
| TFI0002 | 模拟账户贷记内部转账 | 模拟目标 QI 账户接收来自另一个 QI 账户的资金 | Item 1: <br/> [Link Documentação](/documentation/movimentacao_de_contas/transacao) |  QIC0002 或 QIC0002  |

---

# 票据

## 票据管理

| 编号 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| BOL0002* | 登记收款票据 | 通过发送登记事件完成收款票据登记 | [Link Documentação](/documentation/boletos/emissao/emissao_via_json) |  QIC0002 或 QIC0002 , |
| BOL0003 | 查询票据收款钱包 | 查询可供票据登记的收款钱包 | [Link Documentação](/documentation/boletos/consultar/consulta_de_carteira) |  QIC0002 或 QIC0002  |
| BOL0004* | 发送收款票据指令 | 向已登记票据发送指令 | [Link Documentação](/documentation/boletos/enviar_instrucao_de_boleto) | BOL0002 |
| BOL0005 | 模拟票据清算 | 模拟票据清算 | [Link Documentação](/documentation/boletos/pagamento/liquidacao) | BOL0002 |
| BOL0006* | 读取票据 webhook | 成功接收所有与票据状态变更相关的 webhook | [Link Documentação](/documentation/webhooks/boletos) | BOL0004 |
| BOL0007 | 登记 bolepix | 完成 bolepix 登记 | [Link Documentação](/documentation/boletos/emissao/emissao_de_um_bolepix) |  |

## 票据支付

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| BOL0009* | 查询可打印条形码 | 查询银行票据或协议票据的可打印条形码 | [Link Documentação](/documentation/boletos/pagamento/consulta_linha_digitavel) |  |
| BOL0010* | 支付票据 | 支付银行票据或协议票据 | [Link Documentação](/documentation/boletos/pagamento/realizar_pagamento) |  QIC0002 或 QIC0002  |
| BOL0011* | 查询可打印条形码 | 查询协议票据的可打印条形码 | [Link Documentação](/documentation/boletos/pagamento/consulta_linha_digitavel) |  |
| BOL0013* | 支付票据 | 支付协议票据 | [Link Documentação](/documentation/boletos/pagamento/realizar_pagamento) |  QIC0002 或 QIC0002  |

---

## Pix

## Pix 转账
| 代码  | 步骤 | 描述 | 文档链接 | 前置条件 |
|---------|--|---|---|---|
| PIX0002* | Pix 转出 | 从 QI 账户使用银行数据（手动 Pix）或 Pix 密钥进行 Pix 转账 | [Link Documentação](/documentation/baas/pix/realizar_transferencia)| CAB0001 |
| PIX0035 | 查询 Pix 转账 | 获取一笔转账的数据 | [Link Documentação](/documentation/baas/pix/consultar_transferencias) | PIX0002 |
| PIX0003* | 模拟 Pix 转出退款 | 模拟 Pix 转出退款 | [Link Documentação - Item 2](/documentation/pix/simulacao)| PIX0002 |
| PIX0004* | 模拟 Pix 转入 | 模拟 Pix 转入到 QI 账户 | [Link Documentação -> Item 1](/documentation/pix/simulacao)||
| PIX0037* | 读取待处理交易 webhook | 成功接收待处理交易 webhook | [Link Documentação][(/documentation/baas/pix/webhooks) | PIX0002 |
| PIX0038* | 读取 Pix 转入 webhook | 成功接收 Pix 转入 webhook | [Link Documentação](/documentation/baas/pix/webhooks)| PIX0004 |
| PIX0039 | 读取 Pix 退款 webhook | 成功接收 Pix 退款 webhook | [Link Documentação](/documentation/baas/pix/webhooks#webhook-para-devolu%C3%A7%C3%B5es-de-pix) | PIX0003 |

## Pix 密钥管理

### Pix 密钥的创建与删除

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0008* | 创建 Pix 密钥 | 创建 CPF、CNPJ、随机、邮件和电话类型的 Pix 密钥 | Item 5.1. e 5.2:<br/>[Link Documentação](/documentation/baas/manual_baas#5---gerenciar-chaves-pix) |  QIC0002 或 QIC0002  |](/documentation/pix_v2/index.html#consulta-de-chave-pix-no-banco-central)
| PIX0009 | 删除 Pix 密钥 | 删除一个 Pix 密钥 | [Link Documentação](/documentation/pix/excluir_chave) | PIX0008 |
| PIX0010* | 列出 QI 账户的 Pix 密钥 | 列出绑定到 QI 账户的 Pix 密钥 | [Link Documentação](/documentation/pix/listar_chaves_pix) | PIX0008 |
| PIX0011* | 读取随机 Pix 密钥激活 webhook | 成功接收随机密钥创建 webhook | Item 5.1:  <br/> [Link Documentação](/documentation/baas/manual_baas#51-criar-chave-pix-cpf-cnpj-ou-aleat%C3%B3ria) | PIX0008 |

### Pix 密钥可携性

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0013* | 创建 Pix 密钥转入可携性申请 | 创建 CPF、CNPJ、电子邮件、电话和随机类型的 Pix 密钥转入可携性申请 | [Link Documentação](/documentation/pix/portabilidade#criando-um-pedido-de-portabilidade) |  QIC0002 或 QIC0002  |
| PIX0014* | 重发电话或邮件类型 Pix 密钥转入可携性申请的双重验证 | 申请重发待处理（pending_claimer_validation）的 Pix 密钥转入可携性申请的 SMS（电话类型密钥）或电子邮件（邮件类型密钥） | [Link Documentação](/documentation/pix/portabilidade#reenviando-a-valida%C3%A7%C3%A3o-de-dois-fatores) | PIX0013 |
| PIX0015* | 删除 Pix 密钥转入可携性申请 | 删除待处理的 Pix 密钥转入可携性申请 | [Link Documentação](/documentation/pix/portabilidade#deletando-um-pedido-de-portabilidade) | PIX0013 |
| PIX0016* | 读取 Pix 密钥转入可携性申请完成的 webhook | 正确读取 Pix 密钥转入可携性申请完成的 webhook，测试所有可能的完成状态（concluded、cancelled 和 failed） | Webhook: <br/> [Link Documentação](/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade) |PIX0013 |
| PIX0017* | 模拟 Pix 密钥转出可携性申请 | 模拟收到 Pix 密钥转出可携性申请 | Item 5:<br/> [Link Documentação](/documentation/pix/simulacao/index.html) | PIX0013 |
| PIX0018* | 批准和拒绝 Pix 密钥转出可携性申请 | 批准 Pix 密钥转出可携性申请 | [Link Documentação](/documentation/pix/portabilidade#request-4) | PIX0017 |
| PIX0019* | 重发 Pix 密钥转出可携性申请的双重验证 | 申请重发 Pix 密钥转出可携性申请的双重验证 | Enum "pending_donator_validation"  <br/> [Link Documentação](/documentation/pix/portabilidade#request-4) | PIX0018 |
| PIX0020* | 读取 Pix 密钥转出可携性申请完成的 webhook | 正确读取 Pix 密钥转出可携性申请完成的 webhook，测试所有可能的完成状态（concluded、cancelled 和 failed） | [Link Documentação](D/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade-1) | PIX0018 |

## Pix QR 码管理

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0022* | 创建静态 Pix QR 码 | 生成静态 QR 码 | [Link Documentação](/documentation/pix/criar_qr_code_estatico) | PIX0008 |
| PIX0023 | 创建动态 Pix QR 码 | 生成带到期日的动态 QR 码及即时动态 QR 码（带过期秒数） | [Link Documentação](/documentation/pix/criar_qr_code_dinamico) | PIX0008 |
| PIX0024 | 删除动态 Pix QR 码 | 删除 Pix QR 码 | [Link Documentação](/documentation/pix/baixar_qr_code_dinamico) | PIX0023 |
| PIX0025 | 列出动态 Pix QR 码 | 列出动态 Pix QR 码 | [Link Documentação](/documentation/pix/pesquisar_por_qr_code_dinamico) | PIX0023 |
| PIX0026 | 读取即时动态 Pix QR 码过期 webhook | 成功接收即时动态 Pix QR 码过期 webhook | [Link Documentação](/documentation/pix/webhook_por_qr_code_expirado) | PIX0023 |
| PIX0027* | 解码 Pix QR 码 | 解码静态 Pix QR 码、带到期日动态 QR 码和即时动态 QR 码 | [Link Documentação](/documentation/pix/decodificar_qr_code) | PIX0022 和 PIX0023 |

## Pix QR 码支付

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0029* | 支付静态 Pix QR 码 | 支付静态 Pix QR 码 | Item 4.1: [Link Documentação](/documentation/baas/manual_baas#41-pagando-um-qr-code-pix-est%C3%A1tico) | PIX0022 |
| PIX0030* | 支付动态 Pix QR 码 | 支付动态 Pix QR 码 | Item 4.2: [Link Documentação](/documentation/baas/manual_baas#42-pagando-um-qr-code-pix-din%C3%A2mico) | PIX0022 |

## Pix 限额管理

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0032* | 申请修改 Pix 限额 | 申请修改 QI 账户的 Pix 限额 | [Link Documentação](/documentation/pix/solicitar_alteracao_de_limite_pix) |  QIC0002 或 QIC0002  |
| PIX0033 | 列出 Pix 限额修改申请 | 列出 QI 账户的 Pix 限额修改申请 | [Link Documentação](/documentation/pix/busca_por_solicitacao_de_limite_pix) | PIX0032 |
| PIX0034* | 查询 Pix 已用限额 | 查询 QI 账户的 Pix 已用限额 | [Link Documentação](/documentation/pix/busca_por_uso_de_limite_pix) |  QIC0002 或 QIC0002  |

---

# 费率管理
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| GTF0001* | 申请修改费率 | 修改账户费率 | [Link Documentação](/documentation/contas/gestao_de_tarifas) |  QIC0002 或 QIC0002  |
| GTF0002* | 查询费率  | 查询账户已注册的费率 | [Link Documentação](/documentation/contas/consulta_de_tarifas) |  QIC0002 或 QIC0002  |

# 卡片管理

## 创建卡片
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| GDC0001* | 创建虚拟卡  | 创建一张虚拟卡 | [Link Documentação](/documentation/cards/create/gerar_cartao_virtual) |  QIC0002 或 QIC0002  |
| GDC0002* | 创建实体卡  | 创建一张实体卡 | [Link Documentação](/documentation/cards/create/gerar_cartao_fisico) |  QIC0002 或 QIC0002  |

## 查询卡片
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| GDC0003* | 通过密钥查询卡片  | 查询一张卡片 | [Link Documentação](/documentation/cards/search/buscar_cartao_by_key) | GDC0001 或 GDC0002 |
| GDC0004* | 列出卡片  | 列出卡片 | [Link Documentação](/documentation/cards/search/listar_cartoes) | GDC0001 或 GDC0002 |
| GDC0005* | 获取卡片数据 | 获取卡片数据 | [Link Documentação](/documentation/cards/search/buscar_dados_pci) | GDC0001 或 GDC0002 |
| GDC0006* | 获取 PCI 密码 | 获取 PCI 密码 | [Link Documentação](/documentation/cards/search/buscar_senha) | GDC0001 或 GDC0002 |
| GDC0007* | 查询配送数据 | 查询配送数据 | [Link Documentação](/documentation/cards/search/buscar_entrega_by_key) | GDC0001 或 GDC0002 |

## 更新卡片数据
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| GDC0008* | 更新卡片状态  | 更新卡片状态 | [Link Documentação](/documentation/cards/status/update_status_cartao) | GDC0001 或 GDC0002 |
| GDC0009* | 激活实体卡  | 激活一张实体卡 | [Link Documentação](/documentation/cards/status/ativar_cartao) | GDC0001 或 GDC0002 |
| GDC0010* | 修改密码   | 修改卡片密码 | [Link Documentação](/documentation/cards/update/password_cartao) | GDC0001 或 GDC0002 |
| GDC0011* | 配置卡片的非接触式支付  | 配置卡片的非接触式支付  | [Link Documentação](/documentation/cards/update/contactless_cartao) | GDC0002 |

---

# 同质化测试路线图 - 集成账户

URL: /zh-Hans/documentation/roteiros_de_homologacao/roteiro_conta_integrada

同质化测试路线图描述了集成合作方在将产品上线到 QI Tech 生产环境之前，需要在 QI Tech 沙盒环境（测试环境）中测试的所有资源和功能。

本路线图描述了产品中涉及的所有资源和功能。

`*: 上线生产环境的必需步骤`

## BaaS API 注册与认证
| 代码     | 步骤 | 描述 | 文档链接 | 前提条件 |
|---------|--|---|---|---|
| CAB0001* | 沙盒环境注册 | 在沙盒环境（sandbox.qitech.app）中完成 QI Tech 平台注册 | [文档链接](/documentation/primeiros_passos/inicio) 
| CAB0002* | 沙盒环境 Token 验证 | 在沙盒环境中验证 QI Token | [Token 接入手册](https://docs.qitech.com.br/assets/pdfs/QI%20Tech%20Manual%20Inclus%C3%A3o%20de%20Token.pdf) | CAB0001 |
| CAB0003* | 公钥交换 | 在 QI Tech 沙盒平台（sandbox.qitech.app）中完成公钥交换 | [密钥交换](/documentation/primeiros_passos/troca_de_chaves) | CAB0001 和 CAB0002 |
| CAB0004* | 调用认证测试 | 完成调用认证测试 | [认证测试](/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2) <br/><br/> [认证测试端点](/documentation/primeiros_passos/teste_de_autenticacao/endpoints_de_teste) | CAB0003 |
| CAB0005* | Webhook 配置 | 通过 QI Tech 沙盒平台（sandbox.qitech.app）配置 QI 发送 Webhook 的 URL | [Webhook 配置](/documentation/primeiros_passos/configurando_webhooks) | CAB0001 和 CAB0002 |

## QI 账户
| 代码     | 步骤 | 描述 | 文档链接 | 前提条件 |
|---------|--|---|---|---|
| QIC0005 | 查询账户数据 | 成功获取一个 QI 账户的数据 | [查询账户](/documentation/contas/consultar_conta) ||

## PIX 转账
| 代码     | 步骤 | 描述 | 文档链接 | 前提条件 |
|---------|--|---|---|---|
| PIX0002* | PIX 转出 | 通过银行数据（手动 PIX）或 PIX 密钥从 QI 账户发起 PIX 转账 | [发起 PIX 交易](/documentation/baas/pix/realizar_transferencia)||
| PIX0035 | 查询 PIX 转账 | 获取转账数据 | [查询 PIX 转账](/documentation/baas/pix/consultar_transferencias) | PIX0002 |
| PIX0003* | 模拟 PIX 转出退款 | 模拟 PIX 转出的退款。 | [模拟 PIX 转出退款 -> 第2项](/documentation/pix/simulacao)| PIX0002 |
| PIX0004* | 模拟 PIX 转入 | 模拟 QI 账户接收 PIX 转入。 | [模拟 PIX 转入 -> 第1项](/documentation/pix/simulacao)||
| PIX0005* | PIX 转入退款 | 从 QI 账户对 PIX 转入进行退款。 | [PIX 转入退款](/documentation/baas/pix/solicitar_devolucao)| PIX0004 |
| PIX0037* | 读取待处理交易 Webhook | 成功接收待处理交易 Webhook | [待处理交易 Webhook](/documentation/baas/pix/webhooks#webhook-para-transa%C3%A7%C3%B5es-pendentes) | PIX0002 |
| PIX0038* | 读取 PIX 转入 Webhook | 成功接收 PIX 转入 Webhook | [PIX 转入 Webhook](/documentation/baas/pix/webhooks#webhook-para-pix-de-entrada) | PIX0004 |
| PIX0039 | 读取 PIX 退款 Webhook | 成功接收 PIX 退款 Webhook | [PIX 退款 Webhook](/documentation/baas/pix/webhooks#webhook-para-devolu%C3%A7%C3%B5es-de-pix) | PIX0003 |

## 账户流水
| 代码     | 步骤 | 描述 | 文档链接 | 前提条件 |
|---------|--|---|---|---|
| QIC0008* | 交易查询 | 查询账户交易记录 | [交易查询](/documentation/movimentacao_de_contas/consulta_de_transacoes) ||
| QIC0009 | 申请转账凭证 | 申请转账凭证 | [申请转账凭证](/documentation/movimentacao_de_contas/comprovante_de_transferencia) | PIX0002 |
| QIC0010* | 读取交易 Webhook | 成功接收所有交易 Webhook | [account_transaction Webhook](/documentation/movimentacao_de_contas/webhook_movimentacoes) | CAB0005 和 PIX0002 |
| QIC0011 | 查询金融机构列表 | 查询启用接收 TED 和 PIX 的金融机构列表 | [查询金融机构](/documentation/lista_de_instituicoes_financeiras/consulta_de_instituicoes_financeiras) ||

## PIX 密钥查询
| 代码     | 步骤 | 描述 | 文档链接 | 前提条件 |
|---------|--|---|---|---|
| PIX0008* | 创建随机 PIX 密钥 | 创建一个随机 PIX 密钥 | [文档链接](/documentation/pix/criar_chave#criar-chave-pix-cpf-cnpj-ou-aleat%C3%B3ria) | PIX008 |
| PIX0036* | 查询 PIX 密钥数据 | 成功在央行查询 PIX 密钥。 | [PIX 密钥查询](/documentation/baas/pix/consultar_chave_pix) ||

## PIX QR Code 管理

| 代码 | 步骤 | 描述 | 链接 | 前提条件 |
| --- | --- | --- | --- | --- |
| PIX0022* | 创建静态 PIX QR Code | 生成静态 QR Code | [文档链接](/documentation/pix/criar_qr_code_estatico) | PIX0008 |
| PIX0023 | 创建动态 PIX QR Code | 生成带到期日的动态 QR Code 和即时动态 QR Code（带过期秒数）。 | [文档链接](/documentation/pix/criar_qr_code_dinamico) | PIX0008 |
| PIX0024 | 删除动态 PIX QR Code | 删除 PIX QR Code | [文档链接](/documentation/pix/baixar_qr_code_dinamico) | PIX0023 |
| PIX0025 | 列出动态 PIX QR Code | 列出动态 PIX QR Code | [文档链接](/documentation/pix/pesquisar_por_qr_code_dinamico) | PIX0023 |
| PIX0026* | 读取即时动态 PIX QR Code 过期 Webhook | 成功接收即时动态 PIX QR Code 过期 Webhook | [文档链接](/documentation/pix/webhook_por_qr_code_expirado) | PIX0023 |
| PIX0027* | PIX QR Code 解码 | 解码静态、带到期日动态和即时动态 PIX QR Code | [文档链接](/documentation/pix/decodificar_qr_code) | PIX0022 和 PIX0023 |

## PIX QR Code 解码
| 代码     | 步骤 | 描述 | 文档链接 | 前提条件 |
|---------|--|---|---|---|
| PIX0027* | PIX QR Code 解码 | 使用 PIX 复制粘贴 URL 查询并解码 PIX QR Code 数据 | [PIX QR Code 解码](/documentation/pix/decodificar_qr_code)||

## 票据（Boletos）

## 票据管理
| 编号 | 步骤 | 描述 | 链接 | 前提条件 |
|---|---|---|---|---|
| BOL0001 | 注册单张收款票据 | 注册一张收款票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao/index.html) | CAB0002 或 CAB0003 |
| BOL0002 | 注册即时单张收款票据 | 注册一张收款票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) | CAB0002 或 CAB0003 |
| BOL0003 | 批量注册票据 | 批量注册收款票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_em_lote) | CAB0002 或 CAB0003 |
| BOL0004 | 发行标准单张票据 | 发行一张标准单张票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao) | CAB0002 或 CAB0003 |
| BOL0005 | 发行即时单张票据 | 发行一张即时单张票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) | CAB0002 或 CAB0003 |
| BOL0006 | 批量发行票据 | 批量发行票据 | [文档链接](/documentation/boletos/v2/emissao/emissao_em_lote) | CAB0002 或 CAB0003 |
| BOL0007 | 对票据金额进行折扣 | 对票据金额进行折扣 | [文档链接](/documentation/boletos/v2/instrucoes/abatimento/criar_abatimento) | BOL0001、BOL0002 或 BOL0003 |
| BOL0008 | 取消折扣 | 取消票据折扣 | [文档链接](/documentation/boletos/v2/instrucoes/abatimento/cancelar_abatimento) | BOL0001、BOL0002 或 BOL0003 |
| BOL0009 | 延长票据到期日 | 提交票据延期申请 | [文档链接](/documentation/boletos/v2/instrucoes/extensao) | BOL0001、BOL0002 或 BOL0003 |
| BOL0010 | 在票据中添加折扣 | 在票据中添加折扣 | [文档链接](/documentation/boletos/v2/instrucoes/desconto) | BOL0001、BOL0002 或 BOL0003 |
| BOL0011 | 在票据中添加利息 | 在票据中添加利息 | [文档链接](/documentation/boletos/v2/instrucoes/juros) | BOL0001、BOL0002 或 BOL0003 |
| BOL0012 | 在票据中添加罚款 | 在票据中添加罚款 | [文档链接](/documentation/boletos/v2/instrucoes/multa) | BOL0001、BOL0002 或 BOL0003 |
| BOL0013 | 注销票据 | 注销一张票据 | [文档链接](/documentation/boletos/v2/instrucoes/baixa) | BOL0001、BOL0002 或 BOL0003 |
| BOL0014 | 按密钥查询票据 | 按密钥查询票据 | [文档链接](/documentation/boletos/v2/consulta/consulta_por_chave) | BOL0001、BOL0002 或 BOL0003 |
| BOL0015 | 列出票据 | 列出票据 | [文档链接](/documentation/boletos/v2/consulta/listar_boletos) | BOL0001、BOL0002 或 BOL0003 |
| BOL0016 | 票据 Webhook | 读取票据 Webhook | [文档链接](/documentation/boletos/v2/webhooks/boleto) | BOL0001、BOL0002 或 BOL0003 |

---

# 后台构建指南

URL: /zh-Hans/documentation/roteiros_de_homologacao/roteiro_criacao_backoffice_cliente

# **QI Conta**

### 账户

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| QIC0001 | 列出账户 | 列出已开设账户| [文档链接](/documentation/contas/consultar_conta) |  QIC0003 ou QIC0005  |
| QIC0002 | 查询账户数据 | 查询账户余额、持有人数据、开户日期等信息 | [文档链接](/documentation/contas/consultar_conta) |  QIC0003 ou QIC0005  |
| QIC0003 | Pix 限额 | 查询 Pix 限额申请 | [文档链接](/documentation/pix/busca_por_solicitacao_de_limite_pix)
| QIC0004 | 账户注销 | 注销特定账户 | [文档链接](/documentation/contas/encerramento_de_conta)

### 交易

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| QIC0005 | 查询对账单 | 查询账户对账单 | [文档链接](/documentation/movimentacao_de_contas/consulta_de_transacoes) |  QIC0003 ou QIC0005  |
| QIC0006 | 申请转账凭证 | 申请转账凭证 | [文档链接](/documentation/movimentacao_de_contas/comprovante_de_transferencia)|  |
| QIC0007 | 收益报告 | 特定账户的收益报告 | [文档链接](/documentation/contas/informe_rendimentos)
| QIC0008 | 列出 TED 转账 | 查看特定账户的 TED 交易 | [文档链接](/documentation/baas/ted/listar_teds) | 
| QIC0009 | 列出 Pix 转账 | 查看特定账户的 PIX 交易 | [文档链接](/documentation/baas/pix/listar_transferencias)

## 费率管理
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| GTF0001* | 申请修改费率 | 修改账户费率| [文档链接](/documentation/contas/gestao_de_tarifas) |  QIC0003 ou QIC0005  |
| GTF0002* | 查询费率  | 查询账户已注册的费率 | [文档链接](/documentation/contas/consulta_de_tarifas) |  QIC0003 ou QIC0005  |

## 票据

| 编号      | 步骤 | 描述 | 链接  | 前置条件 |
|---|---|---|---|---|
| BOL0004 | 开具标准单张票据        | 开具标准单张票据    | [文档链接](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao)  | CAB0002 ou CAB0003   |
| BOL0007 | 对票据进行折扣减额 | 对票据进行折扣减额 | [文档链接](/documentation/boletos/v2/instrucoes/abatimento/criar_abatimento) | BOL0001, BOL0002 ou BOL0003 |
| BOL0008 | 取消票据折扣减额     | 取消票据折扣减额 | [文档链接](/documentation/boletos/v2/instrucoes/abatimento/cancelar_abatimento) | BOL0001, BOL0002 ou BOL0003  |
| BOL0009 | 延长票据到期日               | 延长票据到期日 | [文档链接](/documentation/boletos/v2/instrucoes/extensao)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0010 | 添加票据折扣               | 添加票据折扣    | [文档链接](/documentation/boletos/v2/instrucoes/desconto)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0011 | 添加票据利息                   | 添加票据利息       | [文档链接](/documentation/boletos/v2/instrucoes/juros)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0012 | 添加票据罚金                   | 添加票据罚金       | [文档链接](/documentation/boletos/v2/instrucoes/multa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0013 | 核销票据                   | 核销票据                 | [文档链接](/documentation/boletos/v2/instrucoes/baixa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0014 | 通过密钥查询票据      | 通过密钥查询票据      | [文档链接](/documentation/boletos/v2/consulta/consulta_por_chave) | BOL0001, BOL0002 ou BOL0003   |
| BOL0015 | 列出票据          | 列出票据     | [文档链接](/documentation/boletos/v2/consulta/listar_boletos) | BOL0001, BOL0002 ou BOL0003   |
| BOL0016 | 查询收款钱包      | 查询收款钱包 | [文档链接](/documentation/boletos/v2/carteira/listar_carteiras/index.html) | BOL0001, BOL0002 ou BOL0003   |
| BOL0017 | 申请票据补打 | 生成票据补打 PDF | [文档链接](/documentation/boletos/consultar_v1/segunda_via_de_boleto)
| BOL0018 | 列出清算记录 | 清算记录列表将返回请求中所传清算组的所有清算记录 | [文档链接](/documentation/boletos/liquidacao/listar_liquidacoes)

---

# 测试指南 - BaaS Conta Payments

URL: /zh-Hans/documentation/roteiros_de_homologacao/roteiro_payments

测试指南描述了集成合作伙伴在进入生产环境之前，需要在 QI Tech 沙盒环境（测试环境）中测试的所有资源和功能。

本指南描述了该产品所涉及的所有资源和功能。 

⚠️ **所有测试必须强制在 QI Tech 沙盒环境（测试环境）中进行。在沙盒环境中进行的操作均为虚拟金融操作，仅用于测试 API 功能。**

## BaaS API 注册与认证
| 代码  | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| CAB0001* | 在沙盒环境注册 | 在 QI Tech 平台的沙盒环境（sandbox.qitech.app）中完成注册 | cs@qitech.com.br |
| CAB0002* | 在沙盒验证 token | 在沙盒环境中完成 QI Token 验证 | [Link Documentação](https://docs.qitech.com.br/assets/pdfs/QI%20Tech%20Manual%20Inclus%C3%A3o%20de%20Token.pdf) | CAB0001 |
| CAB0003* | 交换公钥 | 在 QI Tech 平台沙盒环境（sandbox.qitech.app）中完成公钥交换 | [Link Documentação](/documentation/primeiros_passos/troca_de_chaves) | CAB0001 和 CAB0002 |
| CAB0004* | 完成 API 调用认证测试 | 完成 API 调用认证测试 |[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* | 配置 webhook | 通过 QI Tech 平台沙盒环境（sandbox.qitech.app）完成 QI 发送 webhook 的 URL 配置 | [Link Documentação](/documentation/primeiros_passos/configurando_webhooks) | CAB0001 和 CAB0002 |

# **QI Conta**

## 开户

| 代码 | 步骤 | 描述 | 文档链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| QIC0002* | 预留自然人账户 | 申请一个持有人为自然人的账户预留 | [Link Documentação](/documentation/baas/account/reservar_conta_pf) | CAB0005 和 CAB0006 |
| QIC0003* | 开设自然人账户 | 开设一个持有人为自然人的账户 | [Link Documentação](/documentation/baas/account/abrir_conta_pf) | CAB0005 和 CAB0006 |
| QIC0004* | 预留法人账户 | 申请一个持有人为法人的账户预留 | [Link Documentação](/documentation/baas/account/reservar_conta_pj) | CAB0005 和 CAB0006 |
| QIC0005* | 开设法人账户 | 开设一个持有人为法人的账户 | [Link Documentação](/documentation/baas/account/abrir_conta_pj) | CAB0005 和 CAB0006 |
| QIC0006* | 读取开户 webhook | 正确读取开户 webhook | Item 1.2. 或 1.3:<br/>[Link Documentação](/documentation/baas/account/webhooks) |  QIC0003 或 QIC0005  |
| QIC0007* | 列出账户 | 列出已开设的账户 | [Link Documentação](/documentation/contas/consultar_conta) |  QIC0003 或 QIC0005  |
| QIC0008* | 查询账户数据 | 查询余额、持有人数据、开户日期等账户数据 | [Link Documentação](/documentation/contas/consultar_conta) |  QIC0003 或 QIC0005  |

## 交易

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| QIC0008* | 查询对账单 | 查询账户对账单 | [Link Documentação](/documentation/movimentacao_de_contas/consulta_de_transacoes) |  QIC0003 或 QIC0005  |
| QIC0009* | 申请转账凭证 | 申请一张转账凭证 | [Link Documentação](/documentation/movimentacao_de_contas/comprovante_de_transferencia)|  |
| QIC0010* | 读取交易 webhook | 成功接收所有交易 webhook |  [Link Documentação](/documentation/movimentacao_de_contas/webhook_movimentacoes/index.html) |  QIC0003 或 QIC0005  |
| QIC0011* | 查询金融机构列表 | 查询可接收 TED 和 Pix 的金融机构列表 |  [Link Documentação](/documentation/lista_de_instituicoes_financeiras/consulta_de_instituicoes_financeiras) |  QIC0003 或 QIC0005  |

---

# 文件上传

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| UDD0001* | 上传文件 | 通过文档 API 上传文件 |  [Link Documentação](/documentation/upload_de_documentos/) |  |

---

# TED

| 代码 | 步骤 | 描述 | 链接                                                                                                        | 前置条件 |
| --- | --- | --- |-------------------------------------------------------------------------------------------------------------| --- |
| TED0001* | TED 转出 | 进行 TED 转账  | [Link Documentação](/documentation/baas/ted/realizar_transferencia) | QIC0003 或 QIC0005 |
| TED0002* | 模拟 TED 转出退回 | 模拟从 QI 账户发出的 TED 转出退回 | Item 3: <br/>[Link Documentação](/documentation/movimentacao_de_contas/transacao) | TED0003 |
| TED0003* | 模拟 TED 转入 | 模拟 TED 转入到 QI 账户 | Item 2: <br/>[Link Documentação](/documentation/movimentacao_de_contas/transacao) | QIC0003 或 QIC0005 |
| TED0004* | 列出 TED 交易 | 列出进出 TED 交易  | [Link Documentação](/documentation/baas/ted/listar_teds)  | QIC0003 或 QIC0005 |
| TED0004* | 查询 TED 交易 | 查询一笔 TED 交易  | [Link Documentação](/documentation/baas/ted/consultar_ted)           | QIC0003 或 QIC0005 |
| TED0006* | 读取 TED webhook | 成功接收 TED webhook | [Link Documentação](/documentation/baas/ted/webhooks/index.html)| QIC0003 或 QIC0005 |
---

# 内部转账

| 编号 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| TFI0001 | 账户借记内部转账 | 从一个 QI 账户发起转账，目标账户为另一个 QI 账户 | [Link Documentação](/documentation/baas/ted/realizar_transferencia) |  QIC0003 或 QIC0005  |
| TFI0002 | 模拟账户贷记内部转账 | 模拟目标 QI 账户接收来自另一个 QI 账户的资金 | Item 1: <br/> [Link Documentação](/documentation/movimentacao_de_contas/transacao) |  QIC0003 或 QIC0005  |

---

# 票据

## 票据管理

| 编号 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| 编号      | 步骤 | 描述 | 链接  | 前置条件 |
|---|---|---|---|---|
| BOL0001 | 登记单张标准收款票据    | 完成收款票据登记 | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao/index.html) | CAB0002 或 CAB0003   |
| BOL0002 | 登记单张即时收款票据 | 完成收款票据登记 | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) | CAB0002 或 CAB0003   |
| BOL0003 | 批量登记收款票据  | 完成批量收款票据登记 | [Link Documentação](/documentation/boletos/v2/emissao/emissao_em_lote) | CAB0002 或 CAB0003   |
| BOL0004 | 开具标准单张票据        | 开具一张标准票据    | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao)  | CAB0002 或 CAB0003   |
| BOL0005 | 开具即时单张票据   | 开具一张即时票据 | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) | CAB0002 或 CAB0003   |
| BOL0006 | 批量开具票据   | 批量开具票据 | [Link Documentação](/documentation/boletos/v2/emissao/emissao_em_lote)| CAB0002 或 CAB0003   |
| BOL0007 | 对票据进行折扣减额 | 对票据进行折扣减额 | [Link Documentação](/documentation/boletos/v2/instrucoes/abatimento/criar_abatimento) | BOL0001、BOL0002 或 BOL0003 |
| BOL0008 | 取消票据折扣减额     | 取消票据折扣减额 | [Link Documentação](/documentation/boletos/v2/instrucoes/abatimento/cancelar_abatimento) | BOL0001、BOL0002 或 BOL0003  |
| BOL0009 | 延长票据到期日               | 发送票据期限延长 | [Link Documentação](/documentation/boletos/v2/instrucoes/extensao)     | BOL0001、BOL0002 或 BOL0003   |
| BOL0010 | 添加票据折扣               | 添加票据折扣    | [Link Documentação](/documentation/boletos/v2/instrucoes/desconto)     | BOL0001、BOL0002 或 BOL0003   |
| BOL0011 | 添加票据利息                   | 添加票据利息       | [Link Documentação](/documentation/boletos/v2/instrucoes/juros)        | BOL0001、BOL0002 或 BOL0003   |
| BOL0012 | 添加票据罚金                   | 添加票据罚金       | [Link Documentação](/documentation/boletos/v2/instrucoes/multa)        | BOL0001、BOL0002 或 BOL0003   |
| BOL0013 | 核销票据                   | 核销一张票据                 | [Link Documentação](/documentation/boletos/v2/instrucoes/baixa)        | BOL0001、BOL0002 或 BOL0003   |
| BOL0014 | 通过密钥查询票据      | 通过密钥查询票据      | [Link Documentação](/documentation/boletos/v2/consulta/consulta_por_chave) | BOL0001、BOL0002 或 BOL0003   |
| BOL0015 | 列出票据          | 列出票据     | [Link Documentação](/documentation/boletos/v2/consulta/listar_boletos) | BOL0001、BOL0002 或 BOL0003   |
| BOL0016 | 查询收款钱包      | 查询一个收款钱包 | [Link Documentação](/documentation/boletos/v2/carteira/listar_carteiras/index.html) | BOL0001、BOL0002 或 BOL0003   |
| BOL0017 | 票据 webhook      | 读取票据 webhook | [Link Documentação](/documentation/boletos/v2/webhooks/boleto) | BOL0001、BOL0002 或 BOL0003   |

## 票据支付

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| BOL0009* | 查询可打印条形码或条码 | 查询银行票据的可打印条形码 | [Link Documentação](/documentation/baas/cobranca/consultar_boleto_bancario) |  |
| BOL0010* | 支付票据 | 支付银行票据 | [Link Documentação](/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_boleto_bancario) |  QIC0003 或 QIC0005  |
| BOL0012* | 查询协议票据的可打印条形码或条码 | 查询协议票据的可打印条形码 | [Link Documentação](/documentation/baas/cobranca/consultar_fatura_de_recolhimento) |  |
| BOL0013* | 支付协议票据 | 支付协议票据 | [Link Documentação](/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_fatura_de_recolhimento) |  QIC0003 或 QIC0005  |

---

## Pix

## Pix 转账
| 代码  | 步骤 | 描述 | 文档链接 | 前置条件 |
|---------|--|---|---|---|
| PIX0002* | Pix 转出 | 从 QI 账户使用银行数据（手动 Pix）或 Pix 密钥进行 Pix 转账 | [Link Documentação](/documentation/baas/pix/realizar_transferencia) | CAB0001 |
| PIX0035 | 查询 Pix 转账 | 获取一笔转账的数据 | [Link Documentação](/documentation/baas/pix/consultar_transferencias) | PIX0002 |
| PIX0003* | 模拟 Pix 转出退款 | 模拟 Pix 转出退款 | [Link Documentação - Item 2](/documentation/pix/simulacao)| PIX0002 |
| PIX0004* | 模拟 Pix 转入 | 模拟 Pix 转入到 QI 账户 | [Link Documentação -> Item 1](/documentation/pix/simulacao)||
| PIX0037* | 读取待处理交易 webhook | 成功接收待处理交易 webhook | [Link Documentação](/documentation/baas/pix/webhooks) | PIX0002 |
| PIX0038* | 读取 Pix 转入 webhook | 成功接收 Pix 转入 webhook | [Link Documentação](/documentation/baas/pix/webhooks#webhook-para-pix-de-entrada)| PIX0004 |
| PIX0039 | 读取 Pix 退款 webhook | 成功接收 Pix 退款 webhook | [Link Documentação](/documentation/baas/pix/webhooks#webhook-para-devolu%C3%A7%C3%B5es-de-pix) | PIX0003 |
| PIX0040 | 申请退还已收到的 Pix | 申请退还已收到的 Pix | [Link Documentação](/documentation/baas/pix/solicitar_devolucao) | PIX0003 |
| PIX0041 | 列出账户的 Pix 转账 | 列出账户的 Pix 转账 | [Link Documentação](/documentation/baas/pix/listar_transferencias) | PIX0003 |

## Pix 密钥管理

### Pix 密钥的创建与删除

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0008* | 创建 Pix 密钥 | 创建 CPF、CNPJ、随机、邮件和电话类型的 Pix 密钥 | [Link Documentação](/documentation/pix/criar_chave) | 
| PIX0010* | 列出 QI 账户的 Pix 密钥 | 列出绑定到 QI 账户的 Pix 密钥 | [Link Documentação](/documentation/pix/listar_chaves_pix) | PIX0008 |

## Pix QR 码管理

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0022* | 创建静态 Pix QR 码 | 生成静态 QR 码 | [Link Documentação](/documentation/pix/criar_qr_code_estatico) | PIX0008 |
| PIX0023 | 创建动态 Pix QR 码 | 生成带到期日的动态 QR 码及即时动态 QR 码（带过期秒数） | [Link Documentação](/documentation/pix/criar_qr_code_dinamico) | PIX0008 |
| PIX0024 | 删除动态 Pix QR 码 | 删除 Pix QR 码 | [Link Documentação](/documentation/pix/baixar_qr_code_dinamico) | PIX0023 |
| PIX0025 | 列出动态 Pix QR 码 | 列出动态 Pix QR 码 | [Link Documentação](/documentation/pix/pesquisar_por_qr_code_dinamico) | PIX0023 |
| PIX0026 | 读取即时动态 Pix QR 码过期 webhook | 成功接收即时动态 Pix QR 码过期 webhook | [Link Documentação](/documentation/pix/webhook_por_qr_code_expirado) | PIX0023 |

## Pix QR 码支付

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0029* | 支付静态 Pix QR 码 | 支付静态 Pix QR 码 | [Link Documentação](/documentation/baas/pix/realizar_transferencia#transfer%C3%AAncia-por-qr-code-pix) | PIX0022 |
| PIX0030* | 支付动态 Pix QR 码 | 支付动态 Pix QR 码 |  [Link Documentação](/documentation/baas/pix/realizar_transferencia#transfer%C3%AAncia-por-qr-code-pix) | PIX0022 |
| PIX0027* | 解码 Pix QR 码 | 解码静态 Pix QR 码、带到期日动态 QR 码和即时动态 QR 码 | [Link Documentação](/documentation/pix/decodificar_qr_code) | PIX0022 和 PIX0023 |

## Pix 限额管理

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0032* | 申请修改 Pix 限额 | 申请修改 QI 账户的 Pix 限额 | [Link Documentação](/documentation/pix/solicitar_alteracao_de_limite_pix) |  QIC0003 或 QIC0005  |
| PIX0033 | 列出 Pix 限额修改申请 | 列出 QI 账户的 Pix 限额修改申请 | [Link Documentação](/documentation/pix/busca_por_solicitacao_de_limite_pix) | PIX0032 |
| PIX0034* | 查询 Pix 已用限额 | 查询 QI 账户的 Pix 已用限额 | [Link Documentação](/documentation/pix/busca_por_uso_de_limite_pix) |  QIC0003 或 QIC0005  |

---

# 费率管理
| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| GTF0001* | 申请修改费率 | 修改账户费率 | [Link Documentação](/documentation/contas/gestao_de_tarifas) |  QIC0003 或 QIC0005  |
| GTF0002* | 查询费率  | 查询账户已注册的费率 | [Link Documentação](/documentation/contas/consulta_de_tarifas) |  QIC0003 或 QIC0005  |

---

# 测试指南 - Pix 综合账户

URL: /zh-Hans/documentation/roteiros_de_homologacao/roteiro_pix_conta_integrada

测试指南描述了集成合作伙伴在进入生产环境之前，需要在 QI Tech 沙盒环境（测试环境）中测试的所有资源和功能。

本指南描述了该产品所涉及的所有资源和功能。 

`*：进入生产环境的必须步骤`

## BaaS API 注册与认证
| 代码  | 步骤 | 描述 | 文档链接 | 前置条件 |
|---------|--|---|---|---|
| CAB0001* | 在沙盒环境注册 | 在 QI Tech 平台的沙盒环境（sandbox.qitech.app）中完成注册 | [Link documentação](/documentation/primeiros_passos/inicio) 
| CAB0002* | 在沙盒验证 token | 在沙盒环境中完成 QI Token 验证 | [Manual de Inclusão do Token](https://docs.qitech.com.br/assets/pdfs/QI%20Tech%20Manual%20Inclus%C3%A3o%20de%20Token.pdf) | CAB0001 |
| CAB0003* | 交换公钥 | 在 QI Tech 平台沙盒环境（sandbox.qitech.app）中完成公钥交换 | [Troca de chaves](/documentation/primeiros_passos/troca_de_chaves) | CAB0001 和 CAB0002 |
| CAB0004* | 完成 API 调用认证测试 | 完成 API 调用认证测试 | [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* | 配置 webhook | 通过 QI Tech 平台沙盒环境（sandbox.qitech.app）完成 QI 发送 webhook 的 URL 配置 | [Configuração de webhooks](/documentation/primeiros_passos/configurando_webhooks) | CAB0001 和 CAB0002 |

## QI Conta
| 代码  | 步骤 | 描述 | 文档链接 | 前置条件 |
|---------|--|---|---|---|
| QIC0005* | 查询账户数据 | 成功获取 QI 账户数据 | [Consultar Conta](/documentation/contas/consultar_conta) | - |
| QIC0006* | 列出账户 | 列出已开设的账户 | [Link Documentação](/documentation/contas/consultar_contas) |  -  |

## Pix QR 码管理

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0023 | 创建动态 Pix QR 码 | 生成带到期日的动态 QR 码及即时动态 QR 码（带过期秒数） | [Link Documentação](/documentation/pix/criar_qr_code_dinamico) | PIX0008 |
| PIX0024 | 删除动态 Pix QR 码 | 删除 Pix QR 码 | [Link Documentação](/documentation/pix/baixar_qr_code_dinamico) | PIX0023 |
| PIX0025 | 列出动态 Pix QR 码 | 列出动态 Pix QR 码 | [Link Documentação](/documentation/pix/pesquisar_por_qr_code_dinamico) | PIX0023 |
| PIX0026 | 读取即时动态 Pix QR 码过期 webhook | 成功接收即时动态 Pix QR 码过期 webhook | [Link Documentação](/documentation/pix/webhook_por_qr_code_expirado) | PIX0023 |
| PIX0038 | 读取 Pix 转入 webhook  | 成功接收 Pix 转入 webhook  | [Link Documentação](/documentation/baas/pix/webhooks#webhook-para-pix-de-entrada) | - |

## Pix 密钥查询
| 代码  | 步骤 | 描述 | 文档链接 | 前置条件 |
|---------|--|---|---|---|
| PIX0036* | 查询 Pix 密钥数据 | 成功查询 Bacen 中的 Pix 密钥 | [Consulta de chave Pix](/documentation/baas/pix/consultar_chave_pix) ||

## Pix 转账
| 代码  | 步骤 | 描述 | 文档链接 | 前置条件 |
|---------|--|---|---|---|
| PIX0002* | Pix 转出 | 从 QI 账户使用银行数据（手动 Pix）或 Pix 密钥进行 Pix 转账 | [Realização de Transação Pix](/documentation/baas/pix/realizar_transferencia)||
| PIX0035 | 列出 Pix 转账 | 列出账户的所有 Pix 转账 | [Listagem de transferências Pix](/documentation/baas/pix/listar_transferencias) | PIX0002 |
| PIX0036 | 查询 Pix 转账 | 获取一笔转账的数据 | [Consulta de transferência Pix](/documentation/baas/pix/consultar_transferencias) | PIX0002 |
| PIX0003* | 模拟 Pix 转出退款 | 模拟 Pix 转出退款 | [Simulação reembolso Pix Out -> Item 3](/documentation/pix/simulacao)| PIX0002 |
| PIX0004* | 模拟 Pix 转入 | 模拟 Pix 转入到 QI 账户 | [Simulação Pix In -> Item 1](/documentation/pix/simulacao)||
| PIX0005* | Pix 转入退款 | 从 QI 账户退还 Pix 转入 | [Reembolso Pix In](/documentation/baas/pix/solicitar_devolucao)| PIX0004 |
| PIX0040* | 模拟待处理 Pix 转账状态 | 模拟 Pix 转账状态 | [Simulação Pix In -> Item 5](/documentation/pix/simulacao)||
| PIX0037* | 读取待处理交易 webhook | 成功接收待处理交易 webhook | [Webhook de transação pendente](/documentation/baas/pix/webhooks#webhook-para-transa%C3%A7%C3%B5es-pendentes) | PIX0040 |
| PIX0038* | 读取 Pix 转入 webhook | 成功接收 Pix 转入 webhook | [Webhook Pix In](/documentation/baas/pix/webhooks#webhook-para-pix-de-entrada) | PIX0004 |
| PIX0039 | 读取 Pix 退款 webhook | 成功接收 Pix 退款 webhook | [Webhook Devolução Pix](/documentation/baas/pix/webhooks#webhook-para-devolu%C3%A7%C3%B5es-de-pix) | PIX0003 |

## 交易
| 代码  | 步骤 | 描述 | 文档链接 | 前置条件 |
|---------|--|---|---|---|
| QIC0008* | 查询交易记录 | 查询账户交易记录 | [Consulta de Transações](/documentation/movimentacao_de_contas/consulta_de_transacoes) ||
| QIC0009 | 申请转账凭证 | 申请转账凭证 | [Solicitar comprovante de transferência](/documentation/movimentacao_de_contas/comprovante_de_transferencia) | PIX0002 |
| QIC0010* | 读取交易 webhook | 成功接收所有交易 webhook | [Webhook account_transaction](/documentation/movimentacao_de_contas/webhook_movimentacoes) | CAB0005 和 PIX0002 |
| QIC0011 | 查询金融机构列表 | 查询可接收 TED 和 Pix 的金融机构列表 | [Consulta de Instituições Financeiras](/documentation/lista_de_instituicoes_financeiras/consulta_de_instituicoes_financeiras) ||

## Pix 密钥管理

### Pix 密钥的创建与删除

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0008* | 创建 Pix 密钥 | 创建 CPF、CNPJ、随机、邮件和电话类型的 Pix 密钥 | [Link Documentação](/documentation/pix/criar_chave) | -  | 
| PIX0009 | 删除 Pix 密钥 | 删除一个 Pix 密钥 | [Link Documentação](/documentation/pix/excluir_chave) | PIX0008 |
| PIX0010* | 列出 QI 账户的 Pix 密钥 | 列出绑定到 QI 账户的 Pix 密钥 | [Link Documentação](/documentation/pix/listar_chaves_pix) | PIX0008 |

## 解码 Pix QR 码
| 代码  | 步骤 | 描述 | 文档链接 | 前置条件 |
|---------|--|---|---|---|
| PIX0027* | 解码 Pix QR 码 | 使用 Pix 复制粘贴 URL 查询（解码）Pix QR 码数据 | [Decodificação de QR Code Pix](/documentation/pix/decodificar_qr_code)||

## Pix 密钥管理

### Pix 密钥的创建与删除

| 代码 | 步骤 | 描述 | 链接 | 前置条件 |
| --- | --- | --- | --- | --- |
| PIX0008* | 创建 Pix 密钥 | 创建 CPF、CNPJ、随机、邮件和电话类型的 Pix 密钥 | [Link Documentação](/documentation/pix/criar_chave) | -  | 
| PIX0009 | 删除 Pix 密钥 | 删除一个 Pix 密钥 | [Link Documentação](/documentation/pix/excluir_chave) | PIX0008 |
| PIX0010* | 列出 QI 账户的 Pix 密钥 | 列出绑定到 QI 账户的 Pix 密钥 | [Link Documentação](/documentation/pix/listar_chaves_pix) | PIX0008 |

## 解码 Pix QR 码
| 代码  | 步骤 | 描述 | 文档链接 | 前置条件 |
|---------|--|---|---|---|
| PIX0027* | 解码 Pix QR 码 | 使用 Pix 复制粘贴 URL 查询（解码）Pix QR 码数据 | [Decodificação de QR Code Pix](/documentation/pix/decodificar_qr_code)||

---

# 测试指南 - 间接 Pix

URL: /zh-Hans/documentation/roteiros_de_homologacao/roteiro_pix_indireto

测试指南描述了集成合作伙伴在进入生产环境之前，需要在 QI Tech 沙盒环境（测试环境）中测试的所有资源和功能。

本指南描述了该产品所涉及的所有资源和功能。 

## BaaS API 注册与认证
| 代码  | 步骤 | 描述 | 文档链接 | 前置条件 |
|---------|--|---|---|---|
| CAB0001 | 在沙盒环境注册 | 在 QI Tech 平台的沙盒环境（sandbox.qitech.app）中完成注册 | [Link documentação](/documentation/primeiros_passos/inicio) 
| CAB0002 | 在沙盒验证 token | 在沙盒环境中完成 QI Token 验证 | [Link documentação](https://docs.qitech.com.br/assets/pdfs/QI%20Tech%20Manual%20Inclus%C3%A3o%20de%20Token.pdf) | CAB0001 |
| CAB0003 | 交换公钥 | 在 QI Tech 平台沙盒环境（sandbox.qitech.app）中完成公钥交换 | [Link documentação](/documentation/primeiros_passos/troca_de_chaves) | CAB0001 和 CAB0002 |
| CAB0004 | 完成 API 调用认证测试 | 完成 API 调用认证测试 | [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 | 配置 webhook | 通过 QI Tech 平台沙盒环境（sandbox.qitech.app）完成 QI 发送 webhook 的 URL 配置 | [Link documentação](/documentation/primeiros_passos/configurando_webhooks) | CAB0001 和 CAB0002 |

## QI Conta
### 账户
| 代码  | 步骤 | 描述 | 文档链接                                                                                                        | 前置条件 |
|---------|--|---|-------------------------------------------------------------------------------------------------------------|---------------|
| QCI0012 | 开设间接参与者名下账户 | 完成 4 个间接参与者名下账户的开户 | [Link documentação](/documentation/contas/abertura_de_conta/abertura_de_conta_pj) | CAB0004 和 CAB0005 |
| QIC0005 | 查询账户数据 | 获取参与者此前开设的账户数据 | [Link documentação](/documentation/contas/consultar_contas)                          |        QCI0012       |
| QIC0006 | 注销账户 | 注销间接参与者名下的账户 | [Link documentação](/documentation/contas/encerramento_de_conta)                          |        QCI0012       |

## Alias
| 代码  | 步骤 | 描述 | 文档链接 | 前置条件 |
|---------|--|---|---|---|
| QCA0014 | 为间接参与者名下账户创建法人 alias | 为间接参与者名下账户创建 2 个法人 alias | [Link documentação](/documentation/pix_indireto/gerenciamento_de_alias/criacao_de_alias)|QCI0012|
| QCA0015 | 为间接参与者名下账户创建自然人 alias | 为间接参与者名下账户创建 2 个自然人 alias | [Link documentação](/documentation/pix_indireto/gerenciamento_de_alias/criacao_de_alias) | QCI0012 |
| QCA0016 | 查询 alias 数据 | 查询绑定到间接参与者名下账户的 alias 数据 | [Link documentação](/documentation/pix_indireto/gerenciamento_de_alias/consultar_alias)| QCA0014 或 QCA0015 |
| QCA0017 | 删除 alias | 删除绑定到间接参与者名下账户的 alias | [Link documentação](/documentation/pix_indireto/gerenciamento_de_alias/deletar_alias)|QCA0014 或 QCA0015|
| QCA0018 | 列出绑定到 QI 账户的 alias | 删除绑定到间接参与者名下账户的 alias | [Link documentação](/documentation/pix_indireto/gerenciamento_de_alias/listagem_de_alias)| QCA0014 或 QCA0015 |

## 交易
| 代码  | 步骤 | 描述 | 文档链接 | 前置条件                                                       |
|---------|--|---|---|---------------------------------------------------------------------|
| QIC0008 | 查询对账单 | 查询账户对账单 | [Link documentação](/documentation/movimentacao_de_contas/consulta_de_transacoes) | QCI0012 |
| QIC0009 | 申请转账凭证 | 申请转账凭证 | [Link documentação](/documentation/movimentacao_de_contas/comprovante_de_transferencia) | PXI0002、或 PXI0003、或 PXI0009、或 PXI0010、或 PXI0004、或 PXI0005 |
| QIC0010 | 读取交易 webhook | 成功接收所有交易 webhook | [Link documentação](/documentation/movimentacao_de_contas/webhook_movimentacoes/index.html) | PXI0002、或 PXI0003、或 PXI0009、或 PXI0010、或 PXI0004、或 PXI0005 |
| QIC0011 | 查询金融机构列表 | 查询可接收 TED 和 Pix 的金融机构列表 | [Link documentação](/documentation/lista_de_instituicoes_financeiras/consulta_de_instituicoes_financeiras) |                                                                     |

## 间接 Pix
### Pix 转出
| 代码   | 步骤                                            | 描述 | 文档链接 | 前置条件                               |
|----------|--------------------------------------------------|---|---|---------------------------------------------|
| PXI0002  | 通过 Pix 密钥进行 Pix 转出 - 同步	  | 使用 Pix 密钥从 QI 账户进行 Pix 转账，API 以同步方式响应 | [Link documentação](/documentation/pix_indireto/movimentacoes/transacao/transacao_pix_chave_sync) | QCA0014 或 QCA0015                          |
| PXI0003  | 手动 Pix 转出 - 同步	         | 使用手动 Pix（银行数据）从 QI 账户进行 Pix 转账，API 以同步方式响应 | [Link documentação](/documentation/pix_indireto/movimentacoes/transacao/transacao_pix_manual_sync) | QCA0014 或 QCA0015                          |
| PXI0009  | 通过 Pix 密钥进行 Pix 转出 - 异步	 | 使用 Pix 密钥从 QI 账户进行 Pix 转账，API 以异步方式响应 | [Link documentação](/documentation/pix_indireto/movimentacoes/transacao_async/transacao_pix_normal) | QCA0014 或 QCA0015                          |
| PXI0010  | 手动 Pix 转出 - 异步        | 使用手动 Pix（银行数据）从 QI 账户进行 Pix 转账，API 以异步方式响应 | [Link documentação](/documentation/pix_indireto/movimentacoes/transacao_async/transacao_pix_manual) | QCA0014 或 QCA0015                          |
| PXI0004  | 模拟 Pix 转出退款                | 模拟 Pix 转出退款 | [Link documentação](/documentation/pix_indireto/movimentacoes/simulacao#3---simulação-de-devolução-de-pix) | PXI0002、或 PXI0003、或 PXI0009、或 PXI0010 |
| PXI0005  | 模拟 Pix 转入                              | 模拟 Pix 转入到 QI 账户 | [Link documentação](/documentation/pix_indireto/movimentacoes/simulacao#3---simulação-de-devolução-de-pix) | QCA0014 或 QCA0015                          |
| PXI0006  | Pix 转入退款                              | 从 QI 账户退还 Pix 转入 | [Link documentação](/documentation/pix_indireto/movimentacoes/devolucao_pix) | PXI0005                                     |
| PXI0007  | 模拟被拒绝的 Pix 转出                   | 使用 QI Tech 文档中提供的模拟密钥进行 Pix 转出，以模拟 Pix 被拒绝的场景 | [Link documentação](/documentation/pix_indireto/movimentacoes/simulacao/index.html#5---simulação-de-transação-rejeitada) |                                             |
| PXI0008  | 模拟待处理 Pix 转出                    | 使用 QI Tech 文档中提供的模拟密钥进行 Pix 转出，以模拟 Pix 待处理的场景 | [Link documentação](/documentation/pix_indireto/movimentacoes/simulacao#4---simulação-de-transação-em-estado-pendente-de-confirmação) | PXI0003、或 PXI0010                         |

### 内部 Pix 转账
| 代码   | 步骤                              | 描述 | 文档链接 | 前置条件                               |
|----------|------------------------------------|---|---|---------------------------------------------|
| PXI0012  | 通过 Pix 密钥在两个 alias 间进行内部 Pix 转账 - 同步	 | 使用 Pix 密钥从 QI 账户进行 Pix 转账，API 以同步方式响应 | [Link documentação](/documentation/pix_indireto/movimentacoes/transacao/transacao_pix_chave_sync) | QCA0014 或 QCA0015                          |
| PXI0013  | 手动在两个 alias 间进行内部 Pix 转账 - 同步 | 使用手动 Pix（银行数据）从 QI 账户进行 Pix 转账，API 以同步方式响应 | [Link documentação](/documentation/pix_indireto/movimentacoes/transacao/transacao_pix_manual_sync) | QCA0014 或 QCA0015                          |
| PXI0015  | 通过 Pix 密钥在两个 alias 间进行内部 Pix 转账 - 异步	 | 使用 Pix 密钥从 QI 账户进行 Pix 转账，API 以异步方式响应 | [Link documentação](/documentation/pix_indireto/movimentacoes/transacao_async/transacao_pix_normal) | QCA0014 或 QCA0015                          |
| PXI0016  | 手动在两个 alias 间进行内部 Pix 转账 - 异步 | 使用手动 Pix（银行数据）从 QI 账户进行 Pix 转账，API 以异步方式响应 | [Link documentação](/documentation/pix_indireto/movimentacoes/transacao_async/transacao_pix_manual) | QCA0014 或 QCA0015                          |
| PXI0014  | 内部 Pix 退款  | 从 QI 账户退还内部 Pix | [Link documentação](/documentation/pix_indireto/movimentacoes/simulacao#3---simulação-de-devolução-de-pix) | PXI0012、或 PXI0013、或 PXI0015、或 PXI0016 |

### 查询 Pix 转账
| 代码  | 步骤 | 描述 | 文档链接 | 前置条件                                                                                           |
|---------|--|---|---|---------------------------------------------------------------------------------------------------------|
| PXI0017 | 查询 Pix 转账 | 获取一笔 Pix 转账的数据 | [Link documentação](/documentation/pix_indireto/movimentacoes/consultar_pix)| PXI0002、或 PXI0003、或 PXI0009、或 PXI0010、或 PXI0005、或 PXI0012、或 PXI0013、或 PXI0015、或 PXI0016 |

### Pix 交易
| 代码   | 步骤                              | 描述 | 文档链接 | 前置条件                               |
|----------|------------------------------------|---|---|---------------------------------------------|
| PXI0018  | 读取 Pix 转入 webhook	 | 成功读取 Pix 转入 webhook，该 webhook 由模拟 Pix 转入生成 | [Link documentação](/documentation/pix_indireto/movimentacoes/webhook/webhook_incoming_pix) | PXI0005                         |
| PXI0019  | 读取内部 Pix webhook | 成功读取内部 Pix webhook，该 webhook 在完成内部 Pix 后生成 | [Link documentação](/documentation/pix_indireto/movimentacoes/webhook/webhook_incoming_pix) | PXI0012、或 PXI0013、或 PXI0015、或 PXI0016                          |
| PXI0020  | 读取待处理 Pix 交易 webhook	 | 成功读取待处理 Pix 交易 webhook，该 webhook 由模拟待处理 Pix 交易生成 | [Link documentação](/documentation/pix_indireto/movimentacoes/webhook/webhook_transacao) | PXI0008                         |
| PXI0021  | 读取 Pix 转出退款 webhook | 成功读取 Pix 转出退款 webhook，该 webhook 由模拟 Pix 转出退款生成 | [Link documentação](/documentation/pix_indireto/movimentacoes/webhook/webhook_devolucao_outgoing_pix) | PXI0004                          |

## Pix 密钥管理

### Pix 密钥的创建与删除
| 代码   | 步骤                                          | 描述 | 文档链接 | 前置条件 |
|----------|------------------------------------------------|---|---|--------|
| PXI0022  | 创建自然人随机 Pix 密钥	  | 在自然人 alias 中创建 **5** 个随机密钥 | [Link documentação](/documentation/pix_indireto/chaves_pix/criacao_de_chaves) | QCA0014 或 QCA0015 |
| PXI0023  | 创建法人随机 Pix 密钥 | 在法人 alias 中创建 **20** 个随机密钥 | [Link documentação](/documentation/pix_indireto/chaves_pix/criacao_de_chaves) | QCA0014 或 QCA0015 |
| PXI0024  | 删除自然人 Pix 密钥        | 删除自然人的 Pix 密钥 | [Link documentação](/documentation/pix_indireto/chaves_pix/deletar_chaves) | PXI0022 |
| PXI0025  | 删除法人 Pix 密钥          | 删除法人的 Pix 密钥 | [Link documentação](/documentation/pix_indireto/chaves_pix/deletar_chaves) | PXI0025|
| PXI0026  | 列出 alias 的 Pix 密钥 | 列出绑定到 alias 的 Pix 密钥 | [Link documentação](/documentation/pix_indireto/chaves_pix/listar_chaves) | PXI0022、或 PXI0023 |

## Pix QR 码管理
| 代码   | 步骤                                                 | 描述                                                                         | 文档链接                                                                                                     | 前置条件       |
|----------|-------------------------------------------------------|-----------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|---------------------|
| PXI0027  | Pix QR 码简介	                               | Pix QR 码简介                                                            | [Link documentação](/documentation/pix_indireto/qr_code/introducao_qr_code) | PXI0022、或 PXI0023 |
| PXI0027  | 创建静态 Pix QR 码	                      | 生成静态 QR 码                                                            | [Link documentação](/documentation/pix_indireto/qr_code/Criar%20QR%20Code/criar_qr_code_estatico) | PXI0022、或 PXI0023 |
| PXI0028  | 创建带到期日的动态 Pix QR 码        | 生成带到期日的动态 QR 码                                             | [Link documentação](/documentation/pix_indireto/qr_code/Criar%20QR%20Code/criar_qr_code_dinamico_com_vencimento) | PXI0022、或 PXI0023 |
| PXI0029  | 创建即时支付动态 Pix QR 码 | 创建即时支付动态 Pix QR 码                                     | [Link documentação](/documentation/pix_indireto/qr_code/Criar%20QR%20Code/criar_qr_code_dinamico_imediato) | PXI0028  |
| PXI0029  | 停用动态 Pix QR 码                     | 停用动态 Pix QR 码                                                            | [Link documentação](/documentation/pix_indireto/qr_code/desativar_qr_code) | PXI0028  |
| PXI0030  | 列出 alias 的 QR 码                           | 列出 alias 的 QR 码                                                      | [Link documentação](/documentation/pix_indireto/qr_code/listar_alias_qr_codes) | PXI0029  |
| PXI0030  | 查询 Pix QR 码                              | 查询 Pix QR 码                                                       | [Link documentação](/documentation/pix_indireto/qr_code/consultar_qr_code) |   |
| PXI0031  | QR 码支付 Pix 转入 webhook   | QR 码支付 Pix 转入 webhook | [Link documentação](/documentation/pix_indireto/qr_code/webhook_incoming_pix) | PXI0028 |
| PXI0032  | 解码 Pix QR 码                          | 解码静态 Pix QR 码、带到期日动态 QR 码和即时动态 QR 码 | [Link documentação](/documentation/pix_indireto/qr_code/decodificar_qr_code)                                 |   |

## Pix QR 码支付
| 代码   | 步骤                                          | 描述                                                                            | 文档链接                                                                                                     | 前置条件       |
|----------|------------------------------------------------|--------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|---------------------|
| PXI0033  | 支付静态 Pix QR 码 - 同步	  | 支付静态 Pix QR 码，API 以同步方式响应   | [Link documentação](/documentation/pix_indireto/movimentacoes/transacao/transacao_pix_qr_code_sync) | PXI0032 |
| PXI0028  | 支付动态 Pix QR 码 - 同步	  | 支付动态 Pix QR 码，API 以同步方式响应     | [Link documentação](/documentation/pix_indireto/movimentacoes/transacao/transacao_pix_qr_code_sync) | PXI0032 |
| PXI0035  | 支付静态 Pix QR 码 - 异步  | 支付静态 Pix QR 码，API 以异步方式响应    | [Link documentação](/documentation/pix_indireto/movimentacoes/transacao_async/transacao_pix_qr_code) | PXI0032  |
| PXI0036  | 支付动态 Pix QR 码 - 异步  | 支付动态 Pix QR 码，API 以异步方式响应     | [Link documentação](/documentation/pix_indireto/movimentacoes/transacao_async/transacao_pix_qr_code) | PXI0032  |

## 违规报告
| 代码   | 步骤                                          | 描述                                                                            | 文档链接                                                                                                    | 前置条件                               |
|----------|------------------------------------------------|--------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|---------------------------------------------|
| PXI0037  | Pix 转出违规报告（发出）	  | 为 Pix 转出开立违规报告  | [Link documentação](/documentation/pix_indireto/relato_de_infracao/criar_relato_infracao) | PXI0002、或 PXI0003、或 PXI0009、或 PXI0010 |
| PXI0038  | Pix 转入违规报告（发出）  | 为 Pix 转入开立违规报告     | [Link documentação](/documentation/pix_indireto/relato_de_infracao/criar_relato_infracao) | PXI0005                                     |
| PXI0039  | 读取违规报告状态更新 webhook（收入和发出）  | 成功接收参与者此前开立的违规报告状态更新 webhook  | [Link documentação](/documentation/pix_indireto/relato_de_infracao/webhooks_relato_infracao) | PXI0037、或 PXI0038                        |
| PXI0040  | 查询违规报告（收入和发出）  | 获取参与者开立的 Pix 转出/转入违规报告数据     | [Link documentação](/documentation/pix_indireto/relato_de_infracao/consultar_relato_infracao) | PXI0037、或 PXI0038                        |
| PXI0041  | 取消违规报告（发出）	  | 取消参与者此前开立的违规报告   | [Link documentação](/documentation/pix_indireto/relato_de_infracao/cancelar_relato_infracao) | PXI0037、或 PXI0038                        |
| PXI0042  | 模拟违规报告接受响应（发出）	  | 模拟交易对手接受参与者创建的违规报告（analysis_result=agreed）     | 请联系 QI 技术团队进行此场景的模拟 | PXI0037、或 PXI0038                        |
| PXI0043  | 模拟违规报告拒绝响应（发出）  | 模拟交易对手拒绝参与者创建的违规报告（analysis_result=disagreed）  | [Link documentação](/documentation/pix_indireto/relato_de_infracao/webhooks_relato_infracao) | PXI0037、或 PXI0038                        |
| PXI0044  | 模拟接收违规报告（收入） | 模拟接收另一 PSP 为参与者已收 Pix 转入创建的违规报告    | 请联系 QI 技术团队进行此场景的模拟 | PXI0005                                     |
| PXI0045  | 接受违规报告（收入）  | 关闭收入违规报告，表示接受已收到的报告  | [Link documentação](/documentation/pix_indireto/relato_de_infracao/fechar_relato_infracao) | PXI0044                                     |
| PXI0046  | 拒绝违规报告（收入）	  | 关闭收入违规报告，表示拒绝已收到的违规报告    | [Link documentação](/documentation/pix_indireto/relato_de_infracao/fechar_relato_infracao) | PXI0044                                     |
| PXI0047  | 列出违规报告（收入和发出） | 列出参与者收到或创建的违规报告（收入和发出） | [Link documentação](/documentation/pix_indireto/devolucao/listar_solicitacoes) | PXI0037、或 PXI0038、或 PXI0044             |

## 退款申请
| 代码   | 步骤                                                                   | 描述                                                                                                                                           | 文档链接                                                                               | 前置条件                               |
|----------|-------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------|---------------------------------------------|
| PXI0048  | 因违规报告申请退款                         | 为交易对手（收款方 PSP）接受的发出违规报告开立退款申请                                   | [Link documentação](/documentation/pix_indireto/devolucao/criar_devolucao) | PXI0042                                     |
| PXI0049  | 因操作错误申请退款                            | 为交易对手（收款方 PSP）接受的发出违规报告开立退款申请                                    | [Link documentação](/documentation/pix_indireto/devolucao/criar_devolucao) | PXI0002、或 PXI0003、或 PXI0009、或 PXI0010 |
| PXI0050  | 查询退款申请（收入和发出）               | 获取参与者开立的退款申请数据                          | [Link documentação](/documentation/pix_indireto/devolucao/consultar_devolucao) | PXI0048、或 PXI0049                         |
| PXI0051  | 取消退款申请                                | 取消参与者此前开立的退款申请                                                           | [Link documentação](/documentation/pix_indireto/devolucao/cancelar_devolucao) | PXI0048、或 PXI0049                         |
| PXI0052  | 模拟因违规报告接受退款申请	 | 模拟接受参与者开立的因违规报告退款申请                                                                            | 请联系 QI 技术团队进行此场景的模拟                                        | PXI0048                                     |
| PXI0053  | 模拟因操作错误接受退款申请 | 模拟接受参与者开立的因操作错误退款申请                         | 请联系 QI 技术团队进行此场景的模拟                                        | PXI0049                                     |
| PXI0054  | 模拟因违规报告拒绝退款申请 | 模拟拒绝参与者开立的因违规报告退款申请                    | 请联系 QI 技术团队进行此场景的模拟                                        | PXI0048                                     |
| PXI0055  | 模拟因操作错误拒绝退款申请 | 模拟拒绝参与者开立的因操作错误退款申请                                      | 请联系 QI 技术团队进行此场景的模拟                                        | PXI0049                                     |
| PXI0056  | 读取退款申请状态更新 webhook | 成功接收退款申请状态更新 webhook                                                                     | [Link documentação](/documentation/pix_indireto/devolucao/webhooks_devolucao) | PXI0048、或 PXI0049                         |
| PXI0057  | 列出退款申请	                                  | 列出参与者收到或创建的退款申请                                                       | [Link documentação](/documentation/pix_indireto/devolucao/listar_solicitacoes) | PXI0048、或 PXI0049、或 PXI0058             |
| PXI0058  | 模拟接收因违规报告的退款申请 | 模拟接收因违规报告的退款申请                                                                        | 请联系 QI 技术团队进行此场景的模拟                      | PXI0038、或 PXI0044                         |
| PXI0059  | 模拟接收因操作错误的退款申请 | 模拟接收因操作错误的退款申请                                                                          | 请联系 QI 技术团队进行此场景的模拟                     | PXI0005                                     |
| PXI0060  | 对已接收退款申请进行 Pix 转入退款            | 对参与者收到的退款申请中所述 Pix 转入进行退款                                                 | [Link documentação](/documentation/pix_indireto/movimentacoes/devolucao_pix) | PXI0058、或 PXI0059                         |
| PXI0061  | 关闭退款申请	                                        | 关闭退款申请，填写为响应此退款申请而进行的 Pix 退款的 pix_transfer_key | [Link documentação](/documentation/pix_indireto/devolucao/fechar_devolucao) | PXI0060                                     |

## 费率管理
| 代码   | 步骤                                          | 描述                                                                            | 文档链接                                                                                                     | 前置条件       |
|----------|------------------------------------------------|--------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|---------------------|
| GDT0001  | 修改 QI 账户费率配置  | 修改 QI 账户费率配置   | [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: /zh-Hans/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 |

---

# 同质化路线 - 个人债务发行 - 预付法院判决款（Precatório）

URL: /zh-Hans/documentation/roteiros_laas/roteiro_5d068423-6094-49e4-b15b-7740038295a8

`*: 进入生产环境的必要步骤`

## 1 - LaaS API 注册与认证
| 代码  | 步骤 | 描述 | 文档链接 | 前提条件 |
|---------|--|---|---|---|
| CAB0001* | 在沙盒环境注册 | 在 QI Tech 沙盒环境（sandbox.qitech.app）完成平台注册 | https://sandbox.qitech.com.br/register| |
| CAB0002* | 在沙盒中验证 Token | 在沙盒中验证 QI Token | [下载 Token 接入手册](https://docs.qitech.com.br/assets/pdfs/QI%20Tech%20Manual%20Inclus%C3%A3o%20de%20Token.pdf) | CAB0001 |
| CAB0003* | 交换公钥 | 在 QI Tech 沙盒平台（sandbox.qitech.app）内完成公钥交换 | [文档链接](/documentation/primeiros_passos/troca_de_chaves) | CAB0001 和 CAB0002 |
| CAB0004* | 调用认证测试 | 完成调用认证测试 | [步骤说明](/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2) <br/><br/> [文档链接](/documentation/primeiros_passos/teste_de_autenticacao/endpoints_de_teste) | CAB0003 |
| CAB0005* | 配置 Webhooks | 通过 QI Tech 沙盒平台（sandbox.qitech.app）配置 QI 发送 webhooks 的 URL | [文档链接](/documentation/primeiros_passos/configurando_webhooks) | CAB0001 和 CAB0002 |

## 2 - 债务模拟

| 代码 | 步骤 | 描述 | 链接 | 前提条件 |
| --- | --- | --- | --- | --- |
| SID0001* | 债务模拟 | 使用预先确定的变量模拟债务条件 | [文档链接](/documentation/emissao_de_divida/simulacao_de_divida_novo) | **步骤 1** |

## 3 - 债务发行（个人）

| 代码 | 步骤 | 描述 | 链接 | 前提条件 |
| --- | --- | --- | --- | --- |
| EMD0001* | 个人债务发行 | 发行个人 CCB。由四个主要对象组成：债务人注册数据（borrower 对象）、操作财务数据（financial 对象）、付款银行账户数据（disbursement_bank_account）以及受让人指定（purchaser_document_number） | [文档链接](/documentation/emissao_de_divida/emissao/emissao_de_divida_pf) | **步骤 1 和 2**  |
| EMD0002* | 实施附加数据 | 用于填充生成的 CCB 的数据 | 并行协商的 Payload | 如已定义使用，则为必填。  |

## 4 - 债务正式化

| 代码 | 步骤 | 描述 | 链接 | 前提条件 |
| --- | --- | --- | --- | --- |
| FOR0001 | 债务正式化  | CCB 签署将在债务发行后由 QI SCD 通过 QI Sign 自动触发 | -- |  **步骤 3** |
| FOR0002* | 读取签署完成 webhook | 读取操作正式化的异步响应。Webhook 状态：signature_finished | [文档链接](/documentation/webhooks/dividas) | FOR0001 |

## 5 - 债务放款

| 代码 | 步骤 | 描述 | 链接 | 前提条件 |
| --- | --- | --- | --- | --- |
| DES0001* | 选择放款日期 | 完成操作付款的所有要求（文件提交、签署和批注）后，必须在放款范围内选择放款日期，以便支付该操作。 | [文档链接](/documentation/emissao_de_divida/reprocessar_multiplas_datas/trocar_data) |  **步骤 4** |
| DES0002* | 授权放款 | 付款释放标志，防止操作在未经预先授权的情况下放款 | [文档链接](/documentation/emissao_de_divida/autorizar_desembolso) |  DES0001 |
| DES0003* | 读取操作放款 webhook | 读取表示操作付款成功的异步响应。Webhook 状态：disbursed。此处将包含 PDF 格式付款凭证，以及各期付款及相应银行单据标识密钥的返回 | [文档链接](/documentation/webhooks/dividas) |  DES0001 和 DES0002 |

## 6 - 债务分期

| 代码 | 步骤 | 描述 | 链接 | 前提条件 |
| --- | --- | --- | --- | --- |
| INS0001* | 读取分期 webhook | 读取表示债务分期状态更新的异步响应。此处 webhook_type 为：installment.status_change。Webhook 状态：opened、paid、waiting_payment、paid_early、paid_partial、overdue、paid_partial_overdue 和 paid_overdue。 | [文档链接](/documentation/webhooks/parcelas) |  DES0002 |

## 7 - 债务重新提交

| 代码 | 步骤 | 描述 | 链接 | 前提条件 |
| --- | --- | --- | --- | --- |
| PAG0001* | 更改/更新放款日期 | 当操作已取消时，更新放款日期可使操作恢复到取消前的状态。 | [文档链接](/documentation/emissao_de_divida/reprocessar_multiplas_datas/trocar_data) | **步骤 5**   |
| PAG0002 | 更改银行数据 | 更改操作付款数据，必须是与债务人同名的账户 | [文档链接](/documentation/emissao_de_divida/reprocessar_multiplas_datas/trocar_conta) |  PAG0001。如存在重试则为必填  |

## 8 - 取消操作

| 代码 | 步骤 | 描述 | 链接 | 前提条件 |
| --- | --- | --- | --- | --- |
| CAN0002* | 放款前永久取消债务  | 允许在付款前对债务进行最终取消（最终状态） | [文档链接](/documentation/emissao_de_divida/cancelamento/cancelar_permanentemente) |  EMD0001 |
| CAN0003* | 读取取消 webhook  | 读取操作取消的异步响应。Webhook 状态：canceled | [文档链接](/documentation/webhooks/dividas) |  CAN0002 |
| CAN0004 | 放款后七天内取消债务  | 考虑到借款人可在放款后 7 天内取消债务，他可以对收到的 PIX 进行退款或支付退款二维码 | [文档链接](/documentation/emissao_de_divida/cancelamento/desistencia/introducao) |  DES0002 |

## 9 - 债务银行单据

| 代码 | 步骤 | 描述 | 链接 | 前提条件 |
| --- | --- | --- | --- | --- |
| BKS0001 | 申请银行单据补发 | 通过放款 webhook 返回的银行单据标识密钥（*bank_slip_key*）补发银行单据 | [文档链接](/documentation/boletos/consultar/segunda_via_de_boleto) |  DES0002 |

## 10 - 债务重新协商

| 代码 | 步骤 | 描述 | 链接 | 前提条件 |
| --- | --- | --- | --- | --- |
| REN0001 | 模拟重新协商  | 允许进行部分或全部重新协商的模拟  | [文档链接](/documentation/renegociacao/simulacao_de_uma_renegociacao) | DES0002 |
| REN0002 | 创建重新协商  | 允许创建部分或全部重新协商（生成用于提前支付分期的预付银行单据） | [文档链接](/documentation/renegociacao/criacao_de_uma_renegociacao) |  DES0002 |
| REN0003 | 查询重新协商  | 验证重新协商的条件、受影响的分期、财务数据、到期日和支付类型 | [文档链接](/documentation/renegociacao/consultar_uma_renegociacao) | REN0002 |
| REN0004 | 列出重新协商 | 查看多个重新协商条件的列表 | [文档链接](/documentation/renegociacao/consultar_uma_renegociacao) | REN0002 |
| REN0005 | 取消重新协商 | 取消一次重新协商 | [文档链接](/documentation/renegociacao/cancelar_uma_renegociacao) | REN0002 |
| REN0006 | 重新协商付款 | 重新协商状态更新的 webhooks。Webhook_type：renegotiation.proposal | [文档链接](/documentation/renegociacao/consultar_uma_renegociacao) | REN0002 |

## 11 - 付款与转账

| 代码 | 步骤 | 描述 | 链接 | 前提条件 |
| --- | --- | --- | --- | --- |
| PGT0001 | 解码二维码 | 通过 Pix 复制粘贴 URI 获取退款二维码的支付数据  | [文档链接](/documentation/pix/decodificar_qr_code/index.html) |  CAN0004 |
| PGT0002 | 通过 Pix 二维码转账 | 使用二维码解码获取的信息支付二维码，以取消债务 | [文档链接](/documentation/baas/pix/realizar_transferencia/index.html#transfer%C3%AAncia-por-qr-code-pix) |  PGT0001 |
| PGT0003 | 通过 PIX 转账 | 从托管账户向借款人进行 PIX 转账  | [文档链接](/documentation/baas/pix/realizar_transferencia/index.html#transfer%C3%AAncia-por-qr-code-pix) |  DES0003 |
| PGT0004 | 提高账户限额 | 申请提高托管账户的 PIX 限额 | [文档链接](/documentation/pix/solicitar_alteracao_de_limite_pix/index.html) |  DES0003 |
| PGT0005 | 通过 TED 转账 | 从托管账户向借款人进行 TED 转账  | [文档链接](/documentation/baas/ted/realizar_transferencia/index.html) |  DES0003 |

---

# Homologation Roadmap - Credit Pay

URL: /zh-Hans/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: /zh-Hans/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

---

# INSS Webhooks

URL: /zh-Hans/documentation/roteiros_laas/webhooks_inss

## 查询（福利列表与福利数据）

### 1. 查询福利列表

- 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. 查询福利数据

- 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"
}
```

## 可携性 IN + 再融资

### 1. 发行可携性 + 再融资债务

- 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. 可携性状态

- 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. 批注状态（尝试与成功）

        **可携性**

- 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"
}
```

        **再融资**

- 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. 再融资放款（找零）

- 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. 查询来源可携性合同

- 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"
    }
}

```

## 新信贷

### 1. 债务状态

- 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. 批注状态

- 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"
}
```

## 可携性 Out

### 1. 接收可携性攻击通知

- 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. 状态

- 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"
   }
  }
}
```

---

# 查询可用余额

URL: /zh-Hans/documentation/saque_aniversario_fgts/consultar_saldo_disponivel

## 请求

ENDPOINT /baas/v2/fgts/available_balance
方法 POST

此服务用于查询工作者在 FGTS 中的可用余额。查询结果将显示未来可用于生日提款的各期余额。

V2 版本的余额查询为异步操作。提交请求后，响应将通过 Webhook 返回。

Request Body

```json
{
   "document_number": "639.092.770-39"
}

```

### Body Params

| 字段 | 描述 |
|---|---|
| `document_number` | 账户持有人的 CPF（仅数字）|

---

# 创建信贷操作

URL: /zh-Hans/documentation/saque_aniversario_fgts/criacao_da_operacao

## 请求

ENDPOINT /baas/debt_fgts
方法 POST

模拟操作将返回一系列信息，其中最重要的是 `disbursed_issue_amount`，它代表可以发放的净现值。基于此值，可以进行计算并按所需格式构建操作请求。

**FGTS 生日提款发行属性**

操作创建包含 4 个对象：

- borrower：债务借款人（自然人对象）
- collaterals：付款分期信息（FGTS Collateral 对象）
- financial：操作的财务流程数据（FGTS 财务对象）
- disbursement_bank_accounts：发放信息的银行账户列表（银行账户对象）

### Body Params

| 字段 | 描述 |
|---|---|
| `borrower` *（必填）| 标识发送对象为自然人。对于自然人对象，必须始终包含 "natural" 值 |
| `collaterals` *（必填）| 付款分期信息 |
| `financial` *（必填）| 包含财务对象的所有信息，还需加入 desired installments，表示客户模拟的每期金额 |
| `disbursement_bank_accounts` *（必填）| 债务发行必须包含发放银行信息，默认为借款人账户。此对象必须为包含一个或多个账户的列表 |

### BORROWER 对象

| 字段 | 描述 |
|---|---|
| `person_type` *（必填）| 标识发送对象为自然人。必须始终包含 "natural" 值 |
| `name` *（必填）| 人员姓名 |
| `mother_name` *（必填）| 母亲姓名 |
| `birth_date` *（必填）| 出生日期（格式 "YYYY-MM-DD"）|
| `profession` *（必填）| 职业 |
| `nationality` *（必填）| 国籍 |
| `marital_status` *（必填）| 婚姻状况："single"、"married"、"widower" 或 "divorced" |
| `property_system` | 财产分配制度（仅对 marital_status 为 "married" 的人员必填）："total_communion_of_goods"、"partial_communion_of_goods"、"total_separation_of_goods"、"final_participation_of_acquisitions" 或 "compulsory_separation_of_goods" |
| `wedding_certificate` *（必填）| 结婚证 PDF 的 DOCUMENT_KEY（提前上传）。若 marital_status 为 "single"，此字段值应为 null |
| `spouse` *（必填）| 配偶的自然人对象（仅在财产制度为 "total_communion_of_goods"、"partial_communion_of_goods"、"final_participation_of_acquisitions" 或 "compulsory_separation_of_goods" 时必填）。若 marital_status 为 "single"，此字段值应为 null |
| `is_pep` *（必填）| 是否为政治公众人物（PEP）的声明，布尔值 |
| `individual_document_number` *（必填）| 人员 CPF（仅数字）|
| `document_identification` *（必填）| 带照片身份证件 PDF 的 DOCUMENT_KEY（RG 或 CNH，提前上传）|
| `document_identification_back` | 带照片身份证件背面 PDF 的 DOCUMENT_KEY（提前上传）|
| `document_identification_type` | 身份证件类型，接受 "rg" 或 "cnh" 的枚举值 |
| `document_identification_number` *（必填）| document_identification 中发送的身份证件号码 |
| `email` | 电子邮件地址 |
| `phone` | 电话号码 |
| `address` | 地址 |
| `proof_of_residence` *（必填）| 地址证明 PDF 的 DOCUMENT_KEY（提前上传）|
| `ocr` | 用于传递 OCR SDK 生成 key 的对象 |

### PHONE 对象

| 字段 | 描述 |
|---|---|
| `country_code` *（必填）| 电话 DDI 代码（需恰好为 3 位数字）|
| `area_code` *（必填）| 电话 DDD 代码 |
| `number` *（必填）| 电话号码（仅数字）|
| `document_number` *（必填）| 签署人证件号码 |

### ADDRESS 对象

| 字段 | 描述 |
|---|---|
| `street` *（必填）| 街道名称 |
| `state` *（必填）| 州（两位大写字母）|
| `city` *（必填）| 城市 |
| `neighborhood` *（必填）| 社区/街区 |
| `number` *（必填）| 门牌号 |
| `postal_code` *（必填）| 邮政编码（仅数字）|
| `complement` *（必填）| 地址补充信息（自由文本）|

### COLLATERALS 对象

| 字段 | 描述 |
|---|---|
| `percentage` | 担保比例（0 到 1 之间）|
| `collateral_type` *（必填）| 担保类型。对于 FGTS，必须为 "fgts_balance" |
| `collateral_data` | 担保数据 |

### COLLATERAL DATA 对象

| 字段 | 描述 |
|---|---|
| `total_amount` *（必填）| 特定日期的摊销金额 |
| `due_date` | 到期日期（格式 "YYYY-MM-DD"）|

### FINANCIAL 对象

| 字段 | 描述 |
|---|---|
| `desired_installments` | 客户的发放金额 |
| `interest_type` *（必填）| 债务适用的利息类型 |
| `credit_operation_type` *（必填）| 信贷操作类型："ccb"、"cce"、"cci"、"nce" |
| `annual_interest_rate` *（必填）| 固定利息的百分比值（注意：1 = 100%）|
| `disbursement_date` | 发放日期（格式 "YYYY-MM-DD"，与 disbursement_date 互斥）|
| `disbursement_start_date` | 发放期间起始日期（格式 "YYYY-MM-DD"，与 disbursement_date 互斥）|
| `disbursement_end_date` | 发放期间结束日期（格式 "YYYY-MM-DD"，与 disbursement_date 互斥）|
| `issue_date` | CCB 发行日期（格式 "YYYY-MM-DD"）|
| `interest_grace_period` | 利息宽限期（月）|
| `principal_grace_period` | 本金宽限期（月）|
| `number_of_installments` | 分期数量（年）|
| `fine_configuration` | 罚款配置 |
| `rebates` | 返利对象列表 |

### DISBURSEMENT BANK ACCOUNT 对象

| 字段 | 描述 |
|---|---|
| `bank_code` *（必填）| 巴西支付系统中的机构标识符（仅在未发送 COMPE 时必填）|
| `branch_number` *（必填）| 支行号 |
| `account_number` *（必填）| 账号 |
| `account_digit` | 账户验证位（如有则必填）|
| `document_number` | 发放账户持有人的 CPF 或 CNPJ（如有多个发放账户则必填）|
| `name` | 发放账户持有人姓名（如有多个发放账户则必填）|
| `percentage_receivable` | 账户发放金额的百分比（用于多账户分配）|
| `ispb_number` | 巴西支付系统标识符 |
| `pix_key` | Pix 密钥 |
| `qr_code_key` | 创建 QR Code 时提供的密钥 |
| `digitable_line` | 银行划款条码的数字表示 |

---

# FGTS 生日提款简介

URL: /zh-Hans/documentation/saque_aniversario_fgts/introducao

根据第 8.036 号法律的规定，并经 2019 年第 13.932 号法律的规范，持有 FGTS 关联账户的工作者可以选择生日提款模式，作为合同解除提款模式的替代方案。选择生日提款模式允许每年在其生日当月提取 FGTS 关联账户余额的一部分。

### 实施前提条件

要发行 FGTS 信贷操作，首先需要在 sandbox 环境中完成 API 同质化验证。
请执行同质化验证流程。

---

# roteiro_de_homologacao

URL: /zh-Hans/documentation/saque_aniversario_fgts/roteiro_de_homologacao

## 同质化验证流程

在同质化验证环境中使用 FGTS 生日提款预支服务的分步指南

根据第 8.036 号法律的规定，并经 2019 年第 13.932 号法律的规范，持有 FGTS 关联账户的工作者可以选择生日提款模式，作为合同解除提款模式的替代方案。选择生日提款模式允许每年在其生日当月提取 FGTS 关联账户余额的一部分。

通过此方式，任何自然人均有权在接下来的若干天内（在创建操作时确定）收到一笔款项，该贷款以其在生日当月原本有权提取的最多 7 年分期作为担保。

## FGTS

服务时间保证基金（FGTS）是一项旨在保护被无故解雇员工的基金。通过在与劳动合同关联的账户中存款，雇主每月初在工人名下在巴西联邦储蓄银行开立的账户中存入相当于每位员工税前工资 8% 的金额。

在后续章节中，我们将使用以下术语：

- **登记（Averbação）**：将 FGTS 生日提款分期登记为信贷操作担保；
- **注销（Desaverbação）**：因操作取消或债务清偿而释放分期担保。

## 信贷操作

QI Tech 是一家直接信贷公司（SCD），有权通过发行银行信贷凭证（CCBs）来发行以 FGTS 生日提款分期为担保的信贷操作，贷款金额应发放至签约人的账户。

在后续章节中，我们将使用以下术语：

- **SCD**：根据 2018 年 4 月 26 日第 4.656 号决议第 3 条，SCD 是一种金融机构，其业务对象是专门通过电子平台开展贷款、融资和债权收购业务，仅使用自有资本作为唯一资金来源。
- **借款人（Tomador）**：将收到贷款的自然人（持有 CPF）
- **债权人（Credor）**：有权发行信贷操作的法人（持有 CNPJ），此处由 QI Tech 代表
- **发起人（Originador）**：将使用 QI Tech 服务，发起向借款人账户发放信贷操作的法人（持有 CNPJ）
- **CCB**：根据 2000 年 12 月 14 日第 1.925-15 号临时措施第 1 条，银行信贷凭证是由自然人或法人以金融机构或与之等同的实体为受益人发行的信用票据，代表因任何形式的信贷操作而产生的现金支付承诺。
- **FIDC**：信用权益投资基金是负责将债务转化为可交易证券的基金，可按折扣价出售给投资者

## 通过 API 提供的服务

为了在同质化验证环境的 API 服务消费层面完成一项完整的 FGTS 生日提款预支操作，以下服务必须成功使用：

1. 查询可用余额
2. 最高金额模拟
3. 按期望金额模拟（可选）
4. 文件上传
5. 创建操作
6. 提交借款人签署的操作
7. 操作重新计算
8. 操作取消
9. 担保注销

需要特别指出的是，发起人必须能够通过在平台上注册的 URL 接收 webhook（通过 POST 方式）。由于 CCB 的借款人签署过程是异步的，签署完成后，生成的文件将通过 webhook 发送至发起人注册的 URL。

:::tip **何时开始在生产环境运营？**

在各相关方的商务和法律部门协商达成一致后，即：

- 债权人（QiTech）
- 发起人
- FIDC
- 证券化机构（可选）

当以下事项完成后，QI Tech 将认定集成已通过同质化验证：

1. 合伙协议合同
2. 银行代理协议（CORBAN）
3. 发行的 CCB 在条款和金额上经核对确认（计算说明）
4. QI 服务费和返利的收费方式协议
5. 载体（QI、基金、证券化机构）的正式确立及转让草案
6. 将在生产环境中运营的发起人 CNPJ 和代表人的正式确认

:::

---

# 按期望金额模拟

URL: /zh-Hans/documentation/saque_aniversario_fgts/simulacao_do_valor_desejado

## 请求

ENDPOINT /baas/fgts_simulation_guess
方法 POST

此服务根据提供的分期信息，显示借款人可以预支的最高金额。

作为发起人，可以指定借款人每期可以发放的金额，支持单期或多期设置。

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

| 字段 | 描述 |
|---|---|
| `target_disbursed_amount` *（必填）| 信贷操作的期望发放金额 |
| `borrower` *（必填）| 债务借款人，此处仅需提供人员类型（"person_type"）|
| `financial` | 财务对象（针对 FGTS 生日提款改编）|

### BORROWER 对象

| 字段 | 描述 |
|---|---|
| `person_type` *（必填）| 债务借款人，此处仅需提供人员类型（"person_type"）|

### FINANCIAL 对象

| 字段 | 描述 |
|---|---|
| `desired_installments` | 客户的发放金额 |
| `interest_type` *（必填）| 债务适用的利息类型 |
| `credit_operation_type` *（必填）| 信贷操作类型："ccb"、"cce"、"cci"、"nce" |
| `annual_interest_rate` *（必填）| 固定利息的百分比值（注意：1 = 100%）|
| `disbursement_date` | 发放日期（格式 "YYYY-MM-DD"，与 disbursement_date 互斥）|
| `disbursement_start_date` *（必填）| 发放期间起始日期（格式 "YYYY-MM-DD"，与 disbursement_date 互斥）|
| `disbursement_end_date` *（必填）| 发放期间结束日期（格式 "YYYY-MM-DD"，与 disbursement_date 互斥）|
| `issue_date` *（必填）| CCB 发行日期（格式 "YYYY-MM-DD"）|
| `interest_grace_period` *（必填）| 利息宽限期（月）|
| `principal_grace_period` *（必填）| 本金宽限期（月）|
| `number_of_installments` *（必填）| 分期数量（年）|
| `fine_configuration` *（必填）| 罚款配置 |
| `rebates` *（必填）| 返利对象列表 |

### FINE CONFIGURATION 对象

| 字段 | 描述 |
|---|---|
| `contract_fine_rate` *（必填）| 固定罚款百分比值 |
| `interest_base` | 罚款计时方式（"calendar_days" 表示自然日，"workdays" 表示工作日）|
| `monthly_rate` | 月罚款百分比值 |

### REBATES 对象

| 字段 | 描述 |
|---|---|
| `amount` | 返利金额 |
| `fee_type` | 费用类型 |
| `amount_type` | 插入值的类型（绝对值或百分比）|
| `rebate_bank_account` | 返利银行账户对象 |

### REBATES BANK ACCOUNT 对象

| 字段 | 描述 |
|---|---|
| `name` | 金融机构名称 |
| `bank_code` | 金融机构 COMPE 代码（3 位数字）|
| `ispb_number` | 巴西支付系统中的机构标识符 |
| `account_digit` | 账户验证位 |
| `branch_number` | 支行号 |
| `account_number` | 账号 |
| `document_number` | 返利账户持有人的 CPF 或 CNPJ |

---

# 最高金额模拟

URL: /zh-Hans/documentation/saque_aniversario_fgts/simulacao_do_valor_maximo

## 请求

ENDPOINT /baas/fgts_simulation
方法 POST

此服务根据提供的分期信息，显示借款人可以预支的最高金额。

作为发起人，可以指定借款人每期可以发放的金额，支持单期或多期设置。

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

| 字段 | 描述 |
|---|---|
| `borrower` *（必填）| 债务借款人，此处仅需提供人员类型（"person_type"）|
| `financial` | 财务对象（针对 FGTS 生日提款改编）|

### BORROWER 对象

| 字段 | 描述 |
|---|---|
| `person_type` *（必填）| 债务借款人，此处仅需提供人员类型（"person_type"）|

### FINANCIAL 对象

| 字段 | 描述 |
|---|---|
| `desired_installments` | 客户的发放金额 |
| `interest_type` *（必填）| 债务适用的利息类型 |
| `credit_operation_type` *（必填）| 信贷操作类型："ccb"、"cce"、"cci"、"nce" |
| `annual_interest_rate` *（必填）| 固定利息的百分比值（注意：1 = 100%）|
| `disbursement_date` | 发放日期（格式 "YYYY-MM-DD"，与 disbursement_date 互斥）|
| `disbursement_start_date` *（必填）| 发放期间起始日期（格式 "YYYY-MM-DD"，与 disbursement_date 互斥）|
| `disbursement_end_date` *（必填）| 发放期间结束日期（格式 "YYYY-MM-DD"，与 disbursement_date 互斥）|
| `issue_date` *（必填）| CCB 发行日期（格式 "YYYY-MM-DD"）|
| `interest_grace_period` *（必填）| 利息宽限期（月）|
| `principal_grace_period` *（必填）| 本金宽限期（月）|
| `number_of_installments` *（必填）| 分期数量（年）|
| `fine_configuration` *（必填）| 罚款配置 |
| `rebates` *（必填）| 返利对象列表 |

### FINE CONFIGURATION 对象

| 字段 | 描述 |
|---|---|
| `contract_fine_rate` *（必填）| 固定罚款百分比值 |
| `interest_base` | 罚款计时方式（"calendar_days" 表示自然日，"workdays" 表示工作日）|
| `monthly_rate` | 月罚款百分比值 |

### REBATES 对象

| 字段 | 描述 |
|---|---|
| `amount` | 返利金额 |
| `fee_type` | 费用类型 |
| `amount_type` | 插入值的类型（绝对值或百分比）|
| `rebate_bank_account` | 返利银行账户对象 |

### REBATES BANK ACCOUNT 对象

| 字段 | 描述 |
|---|---|
| `name` | 金融机构名称 |
| `bank_code` | 金融机构 COMPE 代码（3 位数字）|
| `ispb_number` | 巴西支付系统中的机构标识符 |
| `account_digit` | 账户验证位 |
| `branch_number` | 支行号 |
| `account_number` | 账号 |
| `document_number` | 返利账户持有人的 CPF 或 CNPJ |

---

# 余额查询 Webhook

URL: /zh-Hans/documentation/saque_aniversario_fgts/webhooks_de_consulta_de_saldo

返回的 webhook 有两种情况：成功或失败。

成功时：

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"
            }
        ]
    }
}

```

失败时：

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"
    }
}

```

**查询中的错误类型：**

| CPF 末两位 | 枚举值 | 描述 |
|---|---|---|
| 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 和 99 | caixa_error | Request wasn't able to process due to an error on CEF |

---

# Assinatura em Lote

URL: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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: /zh-Hans/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)

2.  POST /account  (conta interna QI p/ debt_purchase)

3.  POST /document/document_batch

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.
:::

---

## 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 |

**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` |

:::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: /zh-Hans/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).

---

# 审批转账

URL: /zh-Hans/documentation/ted/2fa/aprovar_transferencia

要通过 TED 进行转账，需要执行以下步骤：

1. [申请转账验证 Token](/documentation/ted/2fa/solicitar_transferencia)：/baas/token_request

2. 审批转账 /baas/movement_validation

:::info
TED 转账仅可在工作日 **7:00** 至 **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
| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---| ---|
| `token` * | string | 认证 Token | 6 |
| `agent_document_number` * | string | 将接收 Token 的用户 CPF（仅数字） | 11 | 
| `movement_payload` | Object | 包含转账信息的 Payload | **[movement_payload 对象](#objeto-movement_payload)** | 

### movement_payload 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---| ---|
| `source_account` * | Object | 包含来源账户数据的对象 | **[source_account 对象](#objeto-source_account)** |
| `target_account` * | Object | 包含目标账户数据的对象 | **[target_account 对象](#objeto-target_account)** |
| `transaction_amount` * | float | 转账金额 | - |
| `approver_document_number` * | string | 将接收 Token 的用户 CPF（仅数字） | - |

### source_account 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---| ---|
| `account_branch` * | string | 支行号码。 | 0 |
| `branch_digit` |string | 支行数字。| 0 |
| `account_digit` * | string | 账户数字。| 0 |
| `account_number` * | string | 账户号码。| 0 | 
| `owner_document_number` * | string | 账户持有人的 CPF 或 CNPJ（仅数字）。| 0 |

### target_account 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---| ---|
| `account_branch` * | string | 支行。 | 10 |
| `account_digit` * | string | 账户数字 | 10 |
| `account_number` * | string | 账户号码。 | 10 |
| `owner_document_number` * | string | 账户持有人的 CPF 或 CNPJ（仅数字）。 | 10 |
| `owner_name` * | string | 账户持有人姓名。 | 10 |
| `account_type` * |string | 账户持有人的 CPF 或 CNPJ（仅数字）。| 10 |
| `ispb` | string | 用于在巴西中央银行储备转账系统中标识银行的八位代码。| 10 |

## Response

:::info
`transacted_at` 字段格式为 UTC。
:::

:::info
`transaction_key` 将在后续用于申请转账凭证。
:::

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\"}"
}
```

---

# 申请转账

URL: /zh-Hans/documentation/ted/2fa/solicitar_transferencia

要通过 TED 进行转账，需要执行以下步骤：

1. 申请转账验证 Token：/baas/token_request

2. [审批转账](/documentation/ted/2fa/aprovar_transferencia) /baas/movement_validation

:::info
TED 转账仅可在工作日 **7:00** 至 **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
| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---| ---|
| `contact_type` * | string | 认证 Token 的发送方式，可通过邮件（"email"）或短信（"sms"）发送 | 10 |
| `agent_document_number` * | string | 将接收 Token 的用户 CPF（仅数字） | 11 | 
| `movement_payload` | Object | 包含转账信息的 Payload | **[movement_payload 对象](#objeto-movement_payload)** | 

### movement_payload 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---| ---|
| `source_account` * | Object | 包含来源账户数据的对象 | **[source_account 对象](#objeto-source_account)** |
| `target_account` * | Object | 包含目标账户数据的对象 | **[target_account 对象](#objeto-target_account)** |
| `transaction_amount` * | float | 转账金额 | - |
| `approver_document_number` * | string | 将接收 Token 的用户 CPF（仅数字） | - |

### source_account 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---| ---|
| `account_branch` * | string | 支行号码。 | 0 |
| `branch_digit` |string | 支行数字。| 0 |
| `account_digit` * | string | 账户数字。| 0 |
| `account_number` * | string | 账户号码。| 0 | 
| `owner_document_number` * | string | 账户持有人的 CPF 或 CNPJ（仅数字）。| 0 |

### target_account 对象

| 字段 | 类型 | 描述 | 字符数 |
|---|---| ---| ---|
| `account_branch` * | string | 支行。 | 10 |
| `account_digit` * | string | 账户数字 | 10 |
| `account_number` * | string | 账户号码。 | 10 |
| `owner_document_number` * | string | 账户持有人的 CPF 或 CNPJ（仅数字）。 | 10 |
| `owner_name` * | string | 账户持有人姓名。 | 10 |
| `account_type` * |string | 账户持有人的 CPF 或 CNPJ（仅数字）。| 10 |
| `ispb` | string | 用于在巴西中央银行储备转账系统中标识银行的八位代码。| 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: /zh-Hans/documentation/ted/ted_v2

## 执行 TED 转账

在巴西国家金融系统中，TED 交易的接收并非即时完成。在 QI 系统中执行 TED 交易时，系统将立即返回响应，说明转账的错误、拒绝或接受情况。即使转账已被置于 `sent` 状态， 接收金融机构 也可能拒绝资金转入并将金额退回。在此情况下，将发送一个新的状态为 `rejected` 的 webhook，拒绝原因将在 `refusal_reason` 字段中返回。

对来源账户的扣款将立即执行。这并不意味着金额已被贷记至目标账户，因为上述 TED 交易原则仍然适用。若发出的交易被拒绝，交易金额将重新贷记至来源账户。

### 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

| 字段                   | 类型   | 描述                                                                         | 字符数                                          |
|-------------------------|--------|------------------------------------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | string | 客户使用的请求唯一标识密钥，格式为 uuid v4。 | 36                                                  |
| `target_account` *      | object | 目标账户                                                                     | **[target_account 对象](#objeto-target_account)** | 
| `transaction_amount` *  | float  | 转账金额                                                                     | 10                                                  |

### target_account 对象

| 字段                     | 类型   | 描述                                           | 字符数                                                |
|---------------------------|--------|-----------------------------------------------------|-----------------------------------------------------------|
| `account_branch` *        | string | 支行。                                            | 4                                                         |
| `account_digit` *         | string | 账户数字                                     | 1                                                         |
| `account_number` *        | string | 账户号码。                                    | 20                                                        |
| `owner_document_number` * | string | 账户持有人的 CPF 或 CNPJ（仅数字）。   | 14                                                        |
| `owner_name` *            | string | 账户持有人姓名。                           | 50                                                        |
| `account_type`*           | string | 账户类型。                                      | **[account_type 枚举](#enumerador-account_type)** |
| `ispb` *                  | string | 以金融机构 CNPJ 为基础（8位数字）。 | 8                                                         |

### account_type 枚举

| 枚举值         | 描述              |
|--------------------|-----------------------|
| checking_account   | 活期账户        |
| deposit_account    | 存款账户        |
| guaranteed_account | 担保账户     |
| investment_account | 投资账户 |
| payment_account    | 支付账户    |
| saving_account     | 储蓄账户        |

### 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: 错误

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

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`                                 | 描述（英文）<br/>`description`                                                                                       | 描述（葡文）<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 -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------)

## 查询 TED 交易

### Request

ENDPOINT /account/ ACCOUNT_KEY /ted/ TED_KEY / TED_DIRECTION
MÉTODO GET

### Request Path Params

| 字段             | 类型   | 描述                                                   | 字符数                                                  |
|-------------------|--------|-------------------------------------------------------------|-------------------------------------------------------------|
| `ted_direction` * | string | 用于指示交易是入账还是出账的过滤器。 | **[ted_direction 枚举](#enumeradores-ted_direction)** |
| `account_key` *   | uuidv4 | QI 账户的唯一标识密钥                    | 36                                                          |
| `ted_key` *       | uuidv4 | TED 转账的唯一标识密钥           | 36                                                          |

### ted_direction 枚举

| 枚举值 | 描述 |
|------------|----------|
| incoming   | 入账  |
| outgoing   | 出账    |

:::caution 注意
仅在以下情况下允许查看转账：对于 outgoing 类型的 ted_direction，请求方需对交易来源账户有权限；对于 incoming 类型的 ted_direction，请求方需对交易接收账户有权限。否则将返回未找到错误。
:::

### Response

STATUS 200

Response Body: 被拒绝转账（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: 已发送转账（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: 已接收转账（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: 错误

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

| HTTP 状态码<br/>`status` | QI 代码<br/>`code` | 标题<br/>`title`     | 描述（英文）<br/>`description` | 描述（葡文）<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 -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------)

## 查询 TED 交易列表

### Request

ENDPOINT /account/ ACCOUNT_KEY /teds
MÉTODO GET

### Path Params

| 字段           | 类型   | 描述                                | 字符数 |
|-----------------|--------|------------------------------------------|------------|
| `account_key` * | uuidv4 | QI 账户的唯一标识密钥 | 36         |

### Query Params

| 字段                 | 类型       | 描述                                                                                                  | 字符数                                                                  |
|-----------------------|------------|------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| `ted_direction`       | enumerator | 交易方向指示器（入账或出账）。若未发送，默认为 **outgoing** | [ted_transfer_direction 枚举](#enumeradores-ted_transfer_direction) |
| `request_control_key` | uuidv4     | 客户使用的请求唯一标识密钥。                                            | 36                                                                          |
| `date_from`           | string     | 起始日期。格式为 "YYYY-MM-DD"                                                                         |                                                                             |
| `date_to`             | string     | 结束日期。格式为 "YYYY-MM-DD"                                                                           |                                                                             |
| `page`                | integer    | 请求的页码，默认为 1                                                                 |                                                                             |
| `page_size`           | integer    | 查询请求的页面大小，默认值和最大值均为 30                                    | 最大值为 30                                                          |

### ted_transfer_direction 枚举

| 枚举值   | 描述                    |
|--------------|------------------------------|
| **incoming** | 入账 TED 转账 |
| **outgoing** | 出账 TED 转账   |

### 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 -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------)

## TED 发送完成后的 Webhook

Webhook 将通知 TED 交易是否被退回。

### Webhook Request Body

**Webhook Body: TED 被拒绝**

```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

| 字段                 | 类型   | 描述                                                                         | 最大字符数                                     |
|-----------------------|--------|-----------------------------------------------------------------------------------|-----------------------------------------------------|
| `webhook_type`        | string | 定义所报告事件类型的枚举值                         | 23                                                  |
| `webhook_datetime`    | string | Webhook 发送的日期和时间                                                   | 20                                                  |
| `request_control_key` | string | 客户使用的请求唯一标识密钥，格式为 uuid v4 | 36                                                  | 
| `ted_key`             | string | TED 转账的唯一标识密钥                                 | 36                                                  |
| `created_at`          | string | 交易创建的日期和时间                                               | 24                                                  |
| `ted_status`          | string | TED 交易状态                                                           | **[ted_status 枚举](#enumerador-ted_status)** |
| `transaction_amount`  | number | 转账金额                                                            | 10                                                  |
| `fee_amount`          | number | 转账收取的费用                                         | 35                                                  |
| `target_account`      | Object | 目标账户 - 仅在 "manual" 类型交易中发送                | **[target_account 对象](#objeto-target_account)** |
| `refusal_reason`      | Object | 根据巴西中央银行标准的拒绝原因                          | **[refusal_reason 对象](#objeto-refusal_reason)** |

### ted_status 枚举

| 枚举值   | 描述                                |
|--------------|--------------------------------------------|
| **sent**     | TED 转账成功执行。 |
| **pending**  | TED 转账待处理。              |
| **rejected** | TED 转账被拒绝。             |
| **returned** | TED 转账被退回。             |

### target_account 对象

| 字段                     | 类型   | 描述                                           | 字符数                                              |
|---------------------------|--------|-----------------------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string | 支行。                                            | 4                                                       |
| `account_digit` *         | string | 账户数字                                     | 1                                                       |
| `account_number` *        | string | 账户号码。                                    | 20                                                      |
| `owner_document_number` * | string | 账户持有人的 CPF 或 CNPJ（仅数字）。   | 14                                                      |
| `owner_name` *            | string | 账户持有人姓名。                           | 50                                                      |
| `account_type`*           | string | 账户类型。                                      | **[account_type 枚举](#enumerador-account_type)** |
| `ispb` *                  | string | 以金融机构 CNPJ 为基础（8位数字）。 | 8                                                       |

### refusal_reason 对象

| 字段           | 类型   | 描述                  | 字符数 |
|-----------------|--------|----------------------------|------------|
| `bacen_code` *  | string | 巴西中央银行拒绝代码     | 3          |
| `enumerator` *  | string | 巴西中央银行拒绝枚举值 | 100        |
| `description` * | string | 巴西中央银行拒绝描述  | 100        |

### account_type 枚举

| 枚举值         | 描述              |
|--------------------|-----------------------|
| checking_account   | 活期账户        |
| deposit_account    | 存款账户        |
| guaranteed_account | 担保账户     |
| investment_account | 投资账户 |
| payment_account    | 支付账户    |
| saving_account     | 储蓄账户        |

## 接收 TED 后的 Webhook

Webhook 将通知 TED 交易的最终状态。

### Webhook Request Body

**Request Body: TED 已接收**

```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

| 字段                 | 类型   | 描述                                                                         | 最大字符数                                     |
|-----------------------|--------|-----------------------------------------------------------------------------------|-----------------------------------------------------|
| `webhook_type`        | string | 定义所报告事件类型的枚举值                         | 23                                                  |
| `webhook_datetime`    | string | Webhook 发送的日期和时间                                                   | 20                                                  |
| `ted_key`             | string | TED 转账的唯一标识密钥                                 | 36                                                  |
| `created_at`          | string | 交易创建的日期和时间                                               | 100                                                 |
| `ted_status`          | string | TED 交易状态                                                           | **[ted_status 枚举](#enumerador-ted_status)** |
| `transaction_amount`  | number | 转账金额                                                            | 10                                                  |
| `fee_amount`          | number | 转账收取的费用                                         | 35                                                  |
| `target_account`      | Object | 目标账户 - 仅在 "manual" 类型交易中发送                | **[target_account 对象](#objeto-target_account)** |
| `refusal_reason`      | Object | 根据巴西中央银行标准的拒绝原因                          | **[refusal_reason 对象](#objeto-refusal_reason)** |

### ted_status 枚举

| 枚举值   | 描述                                |
|--------------|--------------------------------------------|
| **received** | TED 转账成功执行。 |
| **pending**  | TED 转账待处理。              |
| **rejected** | TED 转账被拒绝。             |

### target_account 对象

| 字段                     | 类型   | 描述                                           | 字符数                                              |
|---------------------------|--------|-----------------------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string | 支行。                                            | 10                                                      |
| `account_digit` *         | string | 账户数字                                     | 10                                                      |
| `account_number` *        | string | 账户号码。                                    | 10                                                      |
| `owner_document_number` * | string | 账户持有人的 CPF 或 CNPJ（仅数字）。   | 14                                                      |
| `owner_name` *            | string | 账户持有人姓名。                           | 50                                                      |
| `account_type`*           | string | 账户类型。                                      | **[account_type 枚举](#enumerador-account_type)** |
| `ispb` *                  | string | 以金融机构 CNPJ 为基础（8位数字）。 | 8                                                       |

### refusal_reason 对象

| 字段           | 类型   | 描述                  | 字符数 |
|-----------------|--------|----------------------------|------------|
| `bacen_code` *  | string | 巴西中央银行拒绝代码     | 3          |
| `enumerator` *  | string | 巴西中央银行拒绝枚举值 | 100        |
| `description` * | string | 巴西中央银行拒绝描述  | 100        |

### account_type 枚举

| 枚举值         | 描述              |
|--------------------|-----------------------|
| checking_account   | 活期账户        |
| deposit_account    | 存款账户        |
| guaranteed_account | 担保账户     |
| investment_account | 投资账户 |
| payment_account    | 支付账户    |
| saving_account     | 储蓄账户        |

---

# consulta_de_agenda_com_opt_in

URL: /zh-Hans/documentation/trava_de_domicilio_bancario/consulta_de_agenda_com_opt_in

## Request

- ENDPOINT /receivables/inquiry
- MÉTODO POST
- BODY （签署前）：

:::caution **注意**

此请求将生成一份待签署的授权文件，签署后将查询日程并通过 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

| 字段 | 描述 |
|---|---|
| `notification_type` *（必填）* |  |
| `owner_person_type` *（必填）* | 日程查询对象的人员类型（自然人或法人）。 |
| `owner_person_name` *（必填）* | 日程查询对象的名称。 |
| `owner_document_number` *（必填）* | 日程查询对象的文件号码。 |
| `reference_code` *（必填）* | opt-in 的唯一标识符。 |
| `signature` *（必填）* | opt-in 信息。 |
| `agenda` *（必填）* | 日程查询参数。 |

### SIGNATURE OBJECT

| 字段 | 描述 |
|---|---|
| `signers` *（必填）* | 签署人列表。 |

### AGENDA OBJECT

| 字段 | 描述 |
|---|---|
| `acquirers` *（必填）* | 收单机构文件号码列表。 |
| `card_schemes` *（必填）* | 支付安排列表。 |
| `end_date` | 查询结束日期。 |
| `start_date` *（必填）* | 查询开始日期。 |

---

# consulta_de_agenda_sem_opt_in

URL: /zh-Hans/documentation/trava_de_domicilio_bancario/consulta_de_agenda_sem_opt_in

## Request

- ENDPOINT /receivables/inquiry
- MÉTODO POST
- BODY （签署前）：

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 **注意**

含预授权的请求应在请求方已获得客户同意时使用。因此，必须在 signatures 中的 authorization 字段中传递与客户同意相关的所有信息。

此请求将生成一次日程查询，该查询将异步进行，结果将通过 webhook 返回。

:::

### Body Params

| 字段 | 描述 |
|---|---|
| `notification_type` *（必填）* |  |
| `owner_person_type` *（必填）* | 日程查询对象的人员类型（自然人或法人）。 |
| `owner_person_name` *（必填）* | 日程查询对象的名称。 |
| `owner_document_number` *（必填）* | 日程查询对象的文件号码。 |
| `reference_code` *（必填）* | opt-in 的唯一标识符。 |
| `signature` *（必填）* | opt-in 信息。 |
| `agenda` *（必填）* | 日程查询参数。 |

### SIGNATURE OBJECT

| 字段 | 描述 |
|---|---|
| `signers` *（必填）* | 签署人列表。 |
| `authorization` *（必填）* | |

### AGENDA OBJECT

| 字段 | 描述 |
|---|---|
| `acquirers` *（必填）* | 收单机构文件号码列表。 |
| `card_schemes` *（必填）* | 支付安排列表。 |
| `end_date` | 查询结束日期。 |
| `start_date` *（必填）* | 查询开始日期。 |

---

# emissao_de_divida_com_trava_de_agenda

URL: /zh-Hans/documentation/trava_de_domicilio_bancario/emissao_de_divida_com_trava_de_agenda

## Request

- ENDPOINT /baas/debt_receivables
- MÉTODO POST
- BODY （签署前）：

YOUR REQUEST HISTORY

:::info

含日程锁定的债务发行与第 3 组 API 中介绍的简单债务发行方式相同，区别在于添加了此处描述的 "contract" 对象。

:::

**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

| 字段 | 描述 |
|---|---|
| `contract` | 担保数据。 |

### CONTRACT OBJECT

| 字段 | 描述 |
|---|---|
| `payment_account` | 应收账款的支付账户 |
| `collaterals` | 担保列表。 |
| `collateral_management` | 担保配置。 |

### PAYMENT ACCOUNT OBJECT

| 字段 | 描述 |
|---|---|
| `account_number` *（必填）* | 卡片应收账款将汇入的账户号码。 |
| `account_branch` *（必填）* | 账户支行。 |
| `account_digit` *（必填）* | 账户数字。 |
| `owner_document_number` *（必填）* | 账户持有人的文件号码（CPF 或 CNPJ）。 |

### COLLATERALS OBJECT

| 字段 | 描述 |
|---|---|
| `acquirer` *（必填）* | 收单机构文件号码列表。 |
| `card_scheme` *（必填）* | 支付安排列表。 |
| `initial_date` *（必填）* | 合同开始日期。 |
| `final_date` *（必填）* | 合同结束日期。 |
| `division_rule` *（必填）* | 根据 QI Tech 提供的表格预定义的负担分配类型。1- 承担固定金额 2- 承担将构成金额的百分比 |
| `encumbered_amount` *（必填）* | 根据分配规则需负担的金额。 |

### COLLATERALS MANAGEMENT OBJECT

| 字段 | 描述 |
|---|---|
| `collateral_management_type` *（必填）* | 用于摊销债务的管理类型。 |
| `amount` *（必填）* | 将使用的金额。 |
| `maximum_value` | 用于支付操作的最大金额。 |
| `maximum_daily_value` | 每日使用的最大金额。 |
| `minimum_date` | 开始使用应收账款的最早日期。 |
| `contract_payment_type` *（必填）* | 合同的支付类型 |

---

# introducao

URL: /zh-Hans/documentation/trava_de_domicilio_bancario/introducao

## 银行收款账户锁定（Trava de Domicílio Bancário）

如果客户希望以应收账款作为担保进行信贷操作，QI Tech 联合 CERC，能够以与普通债务发行流程非常相似的方式创建此类操作。

---

# 开启票据 tombamento 批次

URL: /zh-Hans/documentation/troca_de_titularidade/abrir_lote

此端点将创建一个票据 tombamento 批次。
批次创建时不包含任何票据，票据需通过[票据纳入](/incluir_boletos)端点添加。

## 请求

ENDPOINT /account/ ACCOUNT-KEY /requester_profile/ REQUESTER-PROFILE-KEY /bank_slip_ownership_exchange_batch/stream
MÉTODO POST

### 路径参数

| 字段         | 类型   | 描述                                                                                                              | 字符数 |
|---------------|--------|------------------------------------------------------------------------------------------------------------------------|------------|
| `ACCOUNT-KEY` | uuidv4 | 原始账户的唯一识别键，即票据最初登记的账户。                      | 36         |
| `REQUESTER-PROFILE-KEY` | uuidv4 | 原始托收钱包的唯一识别键，即票据最初登记的托收钱包。 | 36         |

Request Body - 托收钱包 UUID 键

```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 - 托收钱包代码

```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 票据托收钱包代码
托收钱包代码是遵循以下模式的字符串：

[ 银行编号 ] + [ 钱包代码 ] + [ 账户支行号 ] + [ 7位不含校验位的账户号 ]

在 QI Tech，银行编号、钱包代码和支行号始终分别为 `329`、`09` 和 `0001`。

因此，账户号 5308318-3 的托收钱包代码为：`329-09-0001-5308318`。
:::

## Body 参数
| 字段 | 类型 | 描述 | 字符数 |
|---|------|-----------| --|
|`request_control_key`| uuidv4 | 此端点请求的唯一识别键。用于避免 API 调用重复。 |36|
|`new_requester_profile_key`| uuidv4 | 目标托收钱包的唯一识别键，即票据将被转移（tombados）到的托收钱包。可通过[账户托收钱包查询端点](../boletos/carteira/listar_carteiras)获取此键。 |36|
|`new_requester_profile_code`| string | 目标托收钱包代码，即票据将被转移（tombados）到的托收钱包。 |19|
|`new_pix_key` | string | tombamento 目标账户的 Pix 密钥（BolePix 情况下使用）。 | 255 |

## 响应

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
}
```

## 响应参数
| 字段                                         | 类型  | 描述                                                                                                                                                                                                                                                                   | 字符数                                                                                                          |
|-----------------------------------------------|-------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
| `bank_slip_ownership_exchange_batch_key`      | uuidv4 | tombamento 批次的唯一识别键。                                                                                                                                                                                                                        | 36                                                                                                                  |
| `request_control_key`                         | uuidv4 | 此端点请求的唯一识别键。用于避免 API 调用重复。                                                                                                                                                            | 36                                                                                                                  |
| `bank_slip_ownership_exchange_batch_status`   | enum  | tombamento 批次的状态。                                                                                                                                                                                                                                               | [枚举器 `bank_slip_ownership_exchange_batch_status`](#enumeradores-bank_slip_ownership_exchange_batch_status) |
| `new_requester_profile_key`                   | uuidv4 | 目标托收钱包的唯一识别键，即票据将被转移（tombados）到的托收钱包。可通过[账户托收钱包查询端点](../boletos/carteira/listar_carteiras)获取此键。 | 36                                                                                                                  |
| `new_requester_profile_code`                  | string | 目标托收钱包代码，即票据将被转移（tombados）到的托收钱包。                                                                                                                                                                                                                    | 19                                                                                                                  |
| `new_requester_profile_owner_name`            | string | 目标账户持有人及目标托收钱包受益人的姓名。                                                                                                                                                                                                                                   | 255                                                                                                                 |
| `new_requester_profile_owner_document_number` | string | 目标账户持有人及目标托收钱包受益人的证件号（CPF/CNPJ）。                                                                                                                                                         | 255                                                                                                                 |
| `new_requester_profile_account_number`        | string | tombamento 目标账户号。                                                                                                                                                                                                                                                   | 7                                                                                                                   |
| `new_requester_profile_account_digit`         | string | tombamento 目标账户校验位。                                                                                                                                                                                                                                       | 1                                                                                                                   |
| `new_requester_profile_account_branch`        | string | tombamento 目标账户支行号。                                                                                                                                                                                                                                        | 4                                                                                                                   |
| `new_pix_key`                                 | string | tombamento 目标账户的 Pix 密钥（BolePix 情况下使用）。                                                                                                                                                                                                                     | 255                                                                                                                 |
| `total_bank_slip_count`                       | float | tombamento 批次中的票据总数。                                                                                                                                                                                                                                     | -                                                                                                                   |
| `total_amount`                                 | float | tombamento 批次中票据面值总和。                                                                                                                                                                                                                               | -                                                                                                                   |

### 枚举器 bank_slip_ownership_exchange_batch_status
| 枚举器 | 描述                                                                                              |
|------------|--------------------------------------------------------------------------------------------------------|
| open       | 批次已创建，仍开放以纳入/删除票据。                               |
| sent     | 票据选择已完成，tombamento 批次待批准。批准方需完成批准操作。                  |
| processing | 票据选择已完成，批次中票据的 tombamento 正在处理中。 |
| approved | 批次中的票据已完成 tombamento 转移给目标方。 |
| cancelled   | tombamento 批次已取消。 |
| rejected | tombamento 批次已拒绝。 |

---

# 批准票据 tombamento 批次

URL: /zh-Hans/documentation/troca_de_titularidade/aprovar_lote

通过 ```/send``` 发送 tombamento 批次后，需要完成 tombamento 的批准。

批准必须由目标账户和 requester 完成，他们将成为 tombamento 后票据的新负责人。如果 tombamento 在同一 requester 的账户间进行，只需更改 account-key。

## 请求

ENDPOINT /account/ ACCOUNT-KEY /requester_profile/ REQUESTER-PROFILE-KEY /bank_slip_ownership_exchange_batch/ BANK-SLIP-OWNERSHIP-EXCHANGE-BATCH-KEY /approve
MÉTODO PATCH

### 路径参数

| 字段                                    | 类型   | 描述                                                                                                        | 字符数 |
|------------------------------------------|--------|------------------------------------------------------------------------------------------------------------------|------------|
| `ACCOUNT-KEY`                            | uuidv4 | 目标账户的唯一识别键，即票据将被发送到的账户。                | 36         |
| `REQUESTER-PROFILE-KEY`                  | uuidv4 | 目标钱包的唯一识别键，即票据将被转移到的钱包。 | 36         |
| `BANK-SLIP-OWNERSHIP-EXCHANGE-BATCH-KEY` | uuidv4 | tombamento 批次的唯一识别键。                                                             | 36         |

Request Body

```json
{}
```

## 响应

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
}
```

## 响应参数
| 字段 | 类型 | 描述 | 字符数                                                                                                          |
|---|------|-----------|---------------------------------------------------------------------------------------------------------------------|
| `bank_slip_ownership_exchange_batch_key`      | uuidv4 | tombamento 批次的唯一识别键。                                                                                                                                                                                                                        | 36                                                                                                                  |
| `request_control_key`                         | uuidv4 | 此端点请求的唯一识别键。用于避免 API 调用重复。                                                                                                                                                            | 36                                                                                                                  |
| `bank_slip_ownership_exchange_batch_status`   | enum  | tombamento 批次的状态。                                                                                                                                                                                                                                               | [枚举器 `bank_slip_ownership_exchange_batch_status`](#enumeradores-bank_slip_ownership_exchange_batch_status) |
| `new_requester_profile_key`                   | uuidv4 | 目标托收钱包的唯一识别键，即票据将被转移（tombados）到的托收钱包。可通过[账户托收钱包查询端点](../boletos/carteira/listar_carteiras)获取此键。 | 36                                                                                                                  |
| `new_requester_profile_code`                  | string | 目标托收钱包代码，即票据将被转移（tombados）到的托收钱包。                                                                                                                                                                                                                    | 19                                                                                                                  |
| `new_requester_profile_owner_name`            | string | 目标账户持有人及目标托收钱包受益人的姓名。                                                                                                                                                                                                                                   | 255                                                                                                                 |
| `new_requester_profile_owner_document_number` | string | 目标账户持有人及目标托收钱包受益人的证件号（CPF/CNPJ）。                                                                                                                                                         | 255                                                                                                                 |
| `new_requester_profile_account_number`        | string | tombamento 目标账户号。                                                                                                                                                                                                                                                   | 7                                                                                                                   |
| `new_requester_profile_account_digit`         | string | tombamento 目标账户校验位。                                                                                                                                                                                                                                       | 1                                                                                                                   |
| `new_requester_profile_account_branch`        | string | tombamento 目标账户支行号。                                                                                                                                                                                                                                        | 4                                                                                                                   |
| `new_pix_key`                                 | string | tombamento 目标账户的 Pix 密钥（BolePix 情况下使用）。                                                                                                                                                                                                                     | 255                                                                                                                 |
| `total_bank_slip_count`                       | float | tombamento 批次中的票据总数。                                                                                                                                                                                                                                     | -                                                                                                                   |
| `total_amount`                                | float | tombamento 批次中票据面值总和。 | -                                                                                                                   |

### 枚举器 bank_slip_ownership_exchange_batch_status
| 枚举器 | 描述                                                                                              |
|------------|--------------------------------------------------------------------------------------------------------|
| open       | 批次已创建，仍开放以纳入/删除票据。                               |
| closed     | 批次已关闭，批次中票据的 tombamento 已完成。                  |
| processing | 票据选择已完成，批次中票据的 tombamento 正在处理中。 |
| pending_approval | 票据选择已完成，tombamento 批次待批准。批准方可以从批次中删除票据。 |
| canceled   | tombamento 批次已取消。 |
| rejected | tombamento 批次已拒绝。 |

---

# 取消票据 tombamento 批次

URL: /zh-Hans/documentation/troca_de_titularidade/cancelar_lote

## 请求

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

### 路径参数

| 字段                                    | 类型   | 描述                                                                                                              | 字符数 |
|------------------------------------------|--------|------------------------------------------------------------------------------------------------------------------------|------------|
| `ACCOUNT-KEY`                            | uuidv4 | 原始账户的唯一识别键，即票据最初登记的账户。                      | 36         |
| `REQUESTER-PROFILE-KEY`                  | uuidv4 | 原始托收钱包的唯一识别键，即票据最初登记的托收钱包。 | 36         |
| `BANK-SLIP-OWNERSHIP-EXCHANGE-BATCH-KEY` | uuidv4 | tombamento 批次的唯一识别键。| 36         |

Request Body

```json
{}
```

## 响应

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
}
```

## 响应参数
| 字段 | 类型 | 描述 | 字符数                                                                                                          |
|---|------|-----------|---------------------------------------------------------------------------------------------------------------------|
| `bank_slip_ownership_exchange_batch_key`      | uuidv4 | tombamento 批次的唯一识别键。                                                                                                                                                                                                                        | 36                                                                                                                  |
| `request_control_key`                         | uuidv4 | 此端点请求的唯一识别键。用于避免 API 调用重复。                                                                                                                                                            | 36                                                                                                                  |
| `bank_slip_ownership_exchange_batch_status`   | enum  | tombamento 批次的状态。                                                                                                                                                                                                                                               | [枚举器 `bank_slip_ownership_exchange_batch_status`](#enumeradores-bank_slip_ownership_exchange_batch_status) |
| `new_requester_profile_key`                   | uuidv4 | 目标托收钱包的唯一识别键，即票据将被转移（tombados）到的托收钱包。可通过[账户托收钱包查询端点](../boletos/carteira/listar_carteiras)获取此键。 | 36                                                                                                                  |
| `new_requester_profile_code`                  | string | 目标托收钱包代码，即票据将被转移（tombados）到的托收钱包。                                                                                                                                                                                                                    | 19                                                                                                                  |
| `new_requester_profile_owner_name`            | string | 目标账户持有人及目标托收钱包受益人的姓名。                                                                                                                                                                                                                                   | 255                                                                                                                 |
| `new_requester_profile_owner_document_number` | string | 目标账户持有人及目标托收钱包受益人的证件号（CPF/CNPJ）。                                                                                                                                                         | 255                                                                                                                 |
| `new_requester_profile_account_number`        | string | tombamento 目标账户号。                                                                                                                                                                                                                                                   | 7                                                                                                                   |
| `new_requester_profile_account_digit`         | string | tombamento 目标账户校验位。                                                                                                                                                                                                                                       | 1                                                                                                                   |
| `new_requester_profile_account_branch`        | string | tombamento 目标账户支行号。                                                                                                                                                                                                                                        | 4                                                                                                                   |
| `new_pix_key`                                 | string | tombamento 目标账户的 Pix 密钥（BolePix 情况下使用）。                                                                                                                                                                                                                     | 255                                                                                                                 |
| `total_bank_slip_count`                       | float | tombamento 批次中的票据总数。                                                                                                                                                                                                                                     | -                                                                                                                   |
| `total_amount`                                | float | tombamento 批次中票据面值总和。 | -                                                                                                                   |

### 枚举器 bank_slip_ownership_exchange_batch_status
| 枚举器 | 描述                                                                                              |
|------------|--------------------------------------------------------------------------------------------------------|
| open       | 批次已创建，仍开放以纳入/删除票据。                               |
| closed     | 批次已关闭，批次中票据的 tombamento 已完成。                  |
| processing | 票据选择已完成，批次中票据的 tombamento 正在处理中。 |
| pending_approval | 票据选择已完成，tombamento 批次待批准。批准方可以从批次中删除票据。 |
| canceled   | tombamento 批次已取消。 |
| rejected | tombamento 批次已拒绝。 |

---

# 创建票据 tombamento 批次

URL: /zh-Hans/documentation/troca_de_titularidade/criar_lote_batch

## 请求

ENDPOINT /bank_slip/account/ ACCOUNT-KEY /requester_profile/ REQUESTER-PROFILE-KEY /bank_slip_ownership_exchange_batch
MÉTODO POST

### 路径参数

| 字段         | 类型   | 描述                                                                                                              | 字符数 |
|---------------|--------|------------------------------------------------------------------------------------------------------------------------|------------|
| `ACCOUNT-KEY` | uuidv4 | 原始账户的唯一识别键，即票据最初登记的账户。                      | 36         |
| `REQUESTER-PROFILE-KEY` | uuidv4 | 原始托收钱包的唯一识别键，即票据最初登记的托收钱包。 | 36         |

Request Body - 托收钱包键

```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 - 托收钱包代码

```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 参数
| 字段 | 类型 | 描述 | 字符数 |
|---|------|-----------|------------|
|`bank_slips` | list | 将纳入 tombamento 批次的票据列表。         | 36         |
|`request_control_key`| uuidv4 | 此端点请求的唯一识别键。用于避免 API 调用重复。 | 36         |
|`new_requester_profile_key`| uuidv4 | 目标托收钱包的唯一识别键，即票据将被转移（tombados）到的托收钱包。可通过[账户托收钱包查询端点](../boletos/carteira/listar_carteiras)获取此键。 | 36         |
|`new_requester_profile_code`| string | 目标托收钱包代码，即票据将被转移（tombados）到的托收钱包。 | 19         |
|`new_pix_key` | uuidv4 | tombamento 目标账户的 Pix 密钥（BolePix 情况下使用）。 | 36         |

:::caution 注意！
批次创建 payload 中 `bank_slips` 对象的票据列表，每次请求限制为 10,000 个票据。
:::

:::info 票据托收钱包代码
托收钱包代码是遵循以下模式的字符串：

[ 银行编号 ] + [ 钱包代码 ] + [ 账户支行号 ] + [ 7位不含校验位的账户号 ]

在 QI Tech，银行编号、钱包代码和支行号始终分别为 `329`、`09` 和 `0001`。

因此，账户号 5308318-3 的托收钱包代码为：`329-09-0001-5308318`。
:::

## 响应

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
}
```

## 响应参数
| 字段 | 类型 | 描述 | 字符数                                                                                                          |
|---|------|-----------|---------------------------------------------------------------------------------------------------------------------|
| `bank_slip_ownership_exchange_batch_key`      | uuidv4 | tombamento 批次的唯一识别键。                                                                                                                                                                                                                        | 36                                                                                                                  |
| `request_control_key`                         | uuidv4 | 此端点请求的唯一识别键。用于避免 API 调用重复。                                                                                                                                                            | 36                                                                                                                  |
| `bank_slip_ownership_exchange_batch_status`   | enum  | tombamento 批次的状态。                                                                                                                                                                                                                                               | [枚举器 `bank_slip_ownership_exchange_batch_status`](#enumeradores-bank_slip_ownership_exchange_batch_status) |
|`bank_slips` | list | 将纳入 tombamento 批次的票据列表。         | 36                                                                                                                  |
| `new_requester_profile_key`                   | uuidv4 | 目标托收钱包的唯一识别键，即票据将被转移（tombados）到的托收钱包。可通过[账户托收钱包查询端点](../boletos/carteira/listar_carteiras)获取此键。 | 36                                                                                                                  |
| `new_requester_profile_code`                  | string | 目标托收钱包代码，即票据将被转移（tombados）到的托收钱包。                                                                                                                                                                                                                    | 19                                                                                                                  |
| `new_requester_profile_owner_name`            | string | 目标账户持有人及目标托收钱包受益人的姓名。                                                                                                                                                                                                                                   | 255                                                                                                                 |
| `new_requester_profile_owner_document_number` | string | 目标账户持有人及目标托收钱包受益人的证件号（CPF/CNPJ）。                                                                                                                                                         | 255                                                                                                                 |
| `new_requester_profile_account_number`        | string | tombamento 目标账户号。                                                                                                                                                                                                                                                   | 7                                                                                                                   |
| `new_requester_profile_account_digit`         | string | tombamento 目标账户校验位。                                                                                                                                                                                                                                       | 1                                                                                                                   |
| `new_requester_profile_account_branch`        | string | tombamento 目标账户支行号。                                                                                                                                                                                                                                        | 4                                                                                                                   |
| `new_pix_key`                                 | string | tombamento 目标账户的 Pix 密钥（BolePix 情况下使用）。                                                                                                                                                                                                                     | 255                                                                                                                 |
| `total_bank_slip_count`                       | float | tombamento 批次中的票据总数。                                                                                                                                                                                                                                     | -                                                                                                                   |
| `total_amount`                                 | float | tombamento 批次中票据面值总和。 | -                                                                                                                   |

### 枚举器 bank_slip_ownership_exchange_batch_status
| 枚举器 | 描述                                                                                              |
|------------|--------------------------------------------------------------------------------------------------------|
| open       | 批次已创建，仍开放以纳入/删除票据。                               |
| closed     | 批次已关闭，批次中票据的 tombamento 已完成。                  |
| processing | 票据选择已完成，批次中票据的 tombamento 正在处理中。 |
| canceled   | tombamento 批次已取消。 |
| rejected | tombamento 批次已拒绝。 |

---

# 将票据加入 tombamento 批次

URL: /zh-Hans/documentation/troca_de_titularidade/incluir_boletos

此端点用于将票据加入票据 tombamento 批次。

## 请求

ENDPOINT /account/ ACCOUNT-KEY /requester_profile/ REQUESTER-PROFILE-KEY /bank_slip_ownership_exchange_batch/ BANK-SLIP-OWNERSHIP-EXCHANGE-BATCH-KEY /append
MÉTODO PATCH

### 路径参数

| 字段                                    | 类型   | 描述                                                                                                              | 字符数 |
|------------------------------------------|--------|------------------------------------------------------------------------------------------------------------------------|------------|
| `ACCOUNT-KEY`                            | uuidv4 | 原始账户的唯一识别键，即票据最初登记的账户。                      | 36         |
| `REQUESTER-PROFILE-KEY`                  | uuidv4 | 原始托收钱包的唯一识别键，即票据最初登记的托收钱包。 | 36         |
| `BANK-SLIP-OWNERSHIP-EXCHANGE-BATCH-KEY` | uuidv4 | tombamento 批次的唯一识别键。| 36         |

Request Body

```json
{
	"bank_slips": [
		"b21c5b5a-a71f-4672-9254-022401cd15f6",
		"8197e3d0-1500-439f-9f9d-d243115542fa",
		"8293b817-bed9-418a-8c1e-ec8ef5a31468"
	]
}
```

:::caution 注意！
payload 中 `bank_slips` 对象的票据列表，每次请求限制为 10,000 个票据。
:::

## 响应

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
}
```

## 响应参数
| 字段 | 类型 | 描述 | 字符数                                                                                                          |
|---|------|-----------|---------------------------------------------------------------------------------------------------------------------|
| `bank_slip_ownership_exchange_batch_key`      | uuidv4 | tombamento 批次的唯一识别键。                                                                                                                                                                                                                        | 36                                                                                                                  |
| `request_control_key`                         | uuidv4 | 此端点请求的唯一识别键。用于避免 API 调用重复。                                                                                                                                                            | 36                                                                                                                  |
| `bank_slip_ownership_exchange_batch_status`   | enum  | tombamento 批次的状态。                                                                                                                                                                                                                                               | [枚举器 `bank_slip_ownership_exchange_batch_status`](#enumeradores-bank_slip_ownership_exchange_batch_status) |
| `new_requester_profile_key`                   | uuidv4 | 目标托收钱包的唯一识别键，即票据将被转移（tombados）到的托收钱包。可通过[账户托收钱包查询端点](../boletos/carteira/listar_carteiras)获取此键。 | 36                                                                                                                  |
| `new_requester_profile_code`                  | string | 目标托收钱包代码，即票据将被转移（tombados）到的托收钱包。                                                                                                                                                                                                                    | 19                                                                                                                  |
| `new_requester_profile_owner_name`            | string | 目标账户持有人及目标托收钱包受益人的姓名。                                                                                                                                                                                                                                   | 255                                                                                                                 |
| `new_requester_profile_owner_document_number` | string | 目标账户持有人及目标托收钱包受益人的证件号（CPF/CNPJ）。                                                                                                                                                         | 255                                                                                                                 |
| `new_requester_profile_account_number`        | string | tombamento 目标账户号。                                                                                                                                                                                                                                                   | 7                                                                                                                   |
| `new_requester_profile_account_digit`         | string | tombamento 目标账户校验位。                                                                                                                                                                                                                                       | 1                                                                                                                   |
| `new_requester_profile_account_branch`        | string | tombamento 目标账户支行号。                                                                                                                                                                                                                                        | 4                                                                                                                   |
| `new_pix_key`                                 | string | tombamento 目标账户的 Pix 密钥（BolePix 情况下使用）。                                                                                                                                                                                                                     | 255                                                                                                                 |
| `total_bank_slip_count`                       | float | tombamento 批次中的票据总数。                                                                                                                                                                                                                                     | -                                                                                                                   |
| `total_amount`                                | float | tombamento 批次中票据面值总和。 | -                                                                                                                   |

### 枚举器 bank_slip_ownership_exchange_batch_status
| 枚举器 | 描述                                                                                              |
|------------|--------------------------------------------------------------------------------------------------------|
| open       | 批次已创建，仍开放以纳入/删除票据。                               |
| sent     | 票据选择已完成，tombamento 批次待批准。批准方需完成批准操作。                  |
| processing | 票据选择已完成，批次中票据的 tombamento 正在处理中。 |
| approved | 批次中的票据已完成 tombamento 转移给目标方。 |
| cancelled   | tombamento 批次已取消。 |
| rejected | tombamento 批次已拒绝。 |

---

# 简介

URL: /zh-Hans/documentation/troca_de_titularidade/introducao

银行票据的持有人变更**（tombamento）**是指对已登记票据的托收钱包及关联结算账户进行更改的过程。

在持有人变更中，始终存在**一个原始账户和托收钱包，以及一个目标账户和托收钱包。**

- **原始账户和钱包**是票据最初登记的账户和钱包。

- **目标账户和钱包**是票据将被转移（tombado）到的账户和钱包。

**什么会被更改？**
- 托收钱包
- 结算账户

**什么不会被更改？**
- 托收受益人数据
- 付款可输入行
- 付款 Pix QR Code（BolePix 情况下）

## 使用场景

### 担保合成
一个钱包的托收票据可用于合成信贷操作的担保。
在此场景下，目标账户持有人将其简单托收钱包中的票据转移（tombamento）到与操作担保账户关联的托收钱包。

### 信贷权益转让
在票据与预付信贷权益关联的情况下，预付完成后，可将票据转移到预付权益新债权人的钱包。

:::caution 注意！
票据持有人变更 API **不办理**信托转让或信贷权益预付的正式化手续。
它仅反映与已变更托收票据挂钩的资产财务流应发生的情况。
:::

## 流程说明
票据 tombamento 是将已登记票据的持有权从一个钱包转移到另一个钱包的过程。
该流程由四个主要步骤组成，必须按顺序通过 API 调用执行。

以下描述每个步骤的功能。

**1. 开批**

第一步是创建一个 tombamento 批次，该批次将汇总所有将被转移的票据。
批次创建后，以初始状态 `opened` 返回。
此步骤需要填写原始账户、目标钱包和新关联 Pix 密钥的键。

**2. 将票据加入批次**

批次开启后，可以添加将纳入持有人变更的票据。
此阶段批次状态保持为 `opened`，表示批次仍在准备中，可以接收新票据。

**3. 发送票据**

添加所有目标票据后，需要将批次发送进行处理。
发送时，批次状态更新为 `sent`，并触发 webhook 通知状态变更。
此发送标志着 tombamento 操作流程的开始。

**4. 批准 tombamento**

最后，批次的批准由目标账户完成，确认票据持有权的转移。
批准后，批次状态变更为 `processing`，表示 tombamento 正在进行中。
流程成功完成后，系统发送带有 `approved` 状态的最终 webhook，确认持有人变更已完成。

以下链接展示了完整流程的组织图，包括各步骤的关联端点及相应状态变更：

---

# 列出 tombamento 批次中的票据

URL: /zh-Hans/documentation/troca_de_titularidade/listar_boletos_lote

使用此端点列出所查询 tombamento 批次中所有纳入的票据。

## 请求

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

### 路径参数

| 字段         | 类型   | 描述                                                                                                              | 字符数 |
|---------------|--------|------------------------------------------------------------------------------------------------------------------------|------------|
| `account_key` | uuidv4 | 原始账户的唯一识别键，即票据最初登记的账户。                      | 36         |
| `requester_profile_key` | uuidv4 | 原始托收钱包的唯一识别键，即票据最初登记的托收钱包。 | 36         |
| `bank_slip_ownership_exchange_batch_key` | uuidv4 | tombamento 批次的唯一识别键。| 36         |

### 查询参数

| 字段                | 描述                                  |
|----------------------|--------------------------------------------|
| `page_number`        | 当前查询的页码     |
| `page_size`          | 每页结果数量        |

## 响应

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
    }
}
```

## 响应参数

[票据列表对象](../boletos/consulta/listar_boletos#response-body-params)

---

# 列出票据 tombamento 批次 - 目标方

URL: /zh-Hans/documentation/troca_de_titularidade/listar_lotes_destino

使用此端点从目标账户列出票据 tombamento 批次——即票据被转移到的账户。

## 请求

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip_ownership_exchange_batches/incoming
MÉTODO GET

### 路径参数

| 字段         | 类型   | 描述                                                                                             | 字符数 |
|---------------|--------|-------------------------------------------------------------------------------------------------------|------------|
| `account_key` | uuidv4 | 目标账户的唯一识别键，即票据将被转移到的账户。                | 36         |
| `requester_profile_key` | uuidv4 | 目标托收钱包的唯一识别键，即票据将被转移到的托收钱包。 | 36         |

### 查询参数

| 字段                | 描述                                  |
|----------------------|--------------------------------------------|
| `page_number`        | 当前查询的页码     |
| `page_size`          | 每页结果数量        |

## 响应

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
	}
}
```

## 响应参数
| 字段                                         | 类型  | 描述                                                                                                                                                                                                                                          | 字符数                                                                                                          |
|-----------------------------------------------|-------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
| `bank_slip_ownership_exchange_batch_key`      | uuidv4 | tombamento 批次的唯一识别键。                                                                                                                                                                                                               | 36                                                                                                                  |
| `request_control_key`                         | uuidv4 | 此端点请求的唯一识别键。用于避免 API 调用重复。                                                                                                                                                   | 36                                                                                                                  |
| `bank_slip_ownership_exchange_batch_status`   | enum  | tombamento 批次的状态。                                                                                                                                                                                                                      | [枚举器 `bank_slip_ownership_exchange_batch_status`](#enumeradores-bank_slip_ownership_exchange_batch_status) |
| `old_requester_profile_key`                   | uuidv4 | 目标托收钱包的唯一识别键，即票据将被转移到的托收钱包。可通过[账户托收钱包查询端点](../boletos/carteira/listar_carteiras)获取此键。 | 36                                                                                                                  |
| `old_requester_profile_code`                  | string | 目标托收钱包代码，即票据将被转移到的托收钱包。                                                                                                                                                                                                                    | 19                                                                                                                  |
| `old_requester_profile_owner_name`            | string | 目标账户持有人及目标托收钱包受益人的姓名。                                                                                                                                                                                                                          | 255                                                                                                                 |
| `old_requester_profile_owner_document_number` | string | 目标账户持有人及目标托收钱包受益人的证件号（CPF/CNPJ）。                                                                                                                                                | 255                                                                                                                 |
| `old_requester_profile_account_number`        | string | tombamento 目标账户号。                                                                                                                                                                                                                          | 7                                                                                                                   |
| `old_requester_profile_account_digit`         | string | tombamento 目标账户校验位。                                                                                                                                                                                                              | 1                                                                                                                   |
| `old_requester_profile_account_branch`        | string | tombamento 目标账户支行号。                                                                                                                                                                                                               | 4                                                                                                                   |
| `old_pix_key`                                 | string | tombamento 目标账户的 Pix 密钥（BolePix 情况下使用）。                                                                                                                                                                                                            | 255                                                                                                                 |
| `total_bank_slip_count`                       | float | tombamento 批次中的票据总数。                                                                                                                                                                                                            | -                                                                                                                   |
| `total_amount`                                 | float | tombamento 批次中票据面值总和。                                                                                                                                                                                                                      | -                                                                                                                   |

### 枚举器 bank_slip_ownership_exchange_batch_status
| 枚举器 | 描述                                                                                              |
|------------|--------------------------------------------------------------------------------------------------------|
| open       | 批次已创建，仍开放以纳入/删除票据。                               |
| sent     | 票据选择已完成，tombamento 批次待批准。批准方需完成批准操作。                  |
| processing | 票据选择已完成，批次中票据的 tombamento 正在处理中。 |
| approved | 批次中的票据已完成 tombamento 转移给目标方。 |
| cancelled   | tombamento 批次已取消。 |
| rejected | tombamento 批次已拒绝。 |

---

# 列出票据 tombamento 批次 - 来源方

URL: /zh-Hans/documentation/troca_de_titularidade/listar_lotes_origem

使用此端点从 tombamento 来源账户列出票据 tombamento 批次——即票据最初登记的账户。

## 请求

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip_ownership_exchange_batches/outgoing
MÉTODO GET

### 路径参数

| 字段         | 类型   | 描述                                                                                                              | 字符数 |
|---------------|--------|------------------------------------------------------------------------------------------------------------------------|------------|
| `ACCOUNT-KEY` | uuidv4 | 原始账户的唯一识别键，即票据最初登记的账户。                      | 36         |
| `REQUESTER-PROFILE-KEY` | uuidv4 | 原始托收钱包的唯一识别键，即票据最初登记的托收钱包。 | 36         |

### 查询参数

| 字段                | 描述                                  |
|----------------------|--------------------------------------------|
| `page_number`        | 当前查询的页码     |
| `page_size`          | 每页结果数量        |

## 响应

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
	}
}
```

## 响应参数
| 字段                                         | 类型  | 描述                                                                                                                                                                                                                                                                   | 字符数                                                                                                          |
|-----------------------------------------------|-------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
| `bank_slip_ownership_exchange_batch_key`      | uuidv4 | tombamento 批次的唯一识别键。                                                                                                                                                                                                                        | 36                                                                                                                  |
| `request_control_key`                         | uuidv4 | 此端点请求的唯一识别键。用于避免 API 调用重复。                                                                                                                                                            | 36                                                                                                                  |
| `bank_slip_ownership_exchange_batch_status`   | enum  | tombamento 批次的状态。                                                                                                                                                                                                                                               | [枚举器 `bank_slip_ownership_exchange_batch_status`](#enumeradores-bank_slip_ownership_exchange_batch_status) |
| `new_requester_profile_key`                   | uuidv4 | 目标托收钱包的唯一识别键，即票据将被转移（tombados）到的托收钱包。可通过[账户托收钱包查询端点](../boletos/carteira/listar_carteiras)获取此键。 | 36                                                                                                                  |
| `new_requester_profile_code`                  | string | 目标托收钱包代码，即票据将被转移（tombados）到的托收钱包。                                                                                                                                                                                                                    | 19                                                                                                                  |
| `new_requester_profile_owner_name`            | string | 目标账户持有人及目标托收钱包受益人的姓名。                                                                                                                                                                                                                                   | 255                                                                                                                 |
| `new_requester_profile_owner_document_number` | string | 目标账户持有人及目标托收钱包受益人的证件号（CPF/CNPJ）。                                                                                                                                                         | 255                                                                                                                 |
| `new_requester_profile_account_number`        | string | tombamento 目标账户号。                                                                                                                                                                                                                                                   | 7                                                                                                                   |
| `new_requester_profile_account_digit`         | string | tombamento 目标账户校验位。                                                                                                                                                                                                                                       | 1                                                                                                                   |
| `new_requester_profile_account_branch`        | string | tombamento 目标账户支行号。                                                                                                                                                                                                                                        | 4                                                                                                                   |
| `new_pix_key`                                 | string | tombamento 目标账户的 Pix 密钥（BolePix 情况下使用）。                                                                                                                                                                                                                     | 255                                                                                                                 |
| `total_bank_slip_count`                       | float | tombamento 批次中的票据总数。                                                                                                                                                                                                                                     | -                                                                                                                   |
| `total_amount`                                 | float | tombamento 批次中票据面值总和。                                                                                                                                                                                                                               | -                                                                                                                   |

### 枚举器 bank_slip_ownership_exchange_batch_status
| 枚举器 | 描述                                                                                              |
|------------|--------------------------------------------------------------------------------------------------------|
| open       | 批次已创建，仍开放以纳入/删除票据。                               |
| sent     | 票据选择已完成，tombamento 批次待批准。批准方需完成批准操作。                  |
| processing | 票据选择已完成，批次中票据的 tombamento 正在处理中。 |
| approved | 批次中的票据已完成 tombamento 转移给目标方。 |
| cancelled   | tombamento 批次已取消。 |
| rejected | tombamento 批次已拒绝。 |

---

# 票据 Tombamento Webhook

URL: /zh-Hans/documentation/troca_de_titularidade/notificacoes_webhooks

在 tombamento 流程中，webhook 在两个时间点触发：批次发送处理后，以及目标账户批准批次后。

这些通知允许跟踪 tombamento 的进度，确保合作方在批次发送处理及 tombamento 完成时收到通知。

## tombamento 流程状态

### 已发送

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"
}
```

### 已批准

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"
}
```

---

# 从 tombamento 批次中移除票据

URL: /zh-Hans/documentation/troca_de_titularidade/remover_boletos

此端点用于从状态为 `open` 的票据 tombamento 批次中移除票据。

## 请求

ENDPOINT /account/ ACCOUNT-KEY /requester_profile/ REQUESTER-PROFILE-KEY /bank_slip_ownership_exchange_batch/ BANK-SLIP-OWNERSHIP-EXCHANGE-BATCH-KEY /remove
MÉTODO PATCH

### 路径参数

| 字段                                    | 类型   | 描述                                                                                                              | 字符数 |
|------------------------------------------|--------|------------------------------------------------------------------------------------------------------------------------|------------|
| `ACCOUNT-KEY`                            | uuidv4 | 原始账户的唯一识别键，即票据最初登记的账户。                      | 36         |
| `REQUESTER-PROFILE-KEY`                  | uuidv4 | 原始托收钱包的唯一识别键，即票据最初登记的托收钱包。 | 36         |
| `BANK-SLIP-OWNERSHIP-EXCHANGE-BATCH-KEY` | uuidv4 | tombamento 批次的唯一识别键。| 36         |

Request Body

```json
{
	"bank_slips": [
		"b21c5b5a-a71f-4672-9254-022401cd15f6",
		"8197e3d0-1500-439f-9f9d-d243115542fa",
		"8293b817-bed9-418a-8c1e-ec8ef5a31468"
	]
}
```

:::caution 注意！
payload 中 `bank_slips` 对象的票据列表，每次请求限制为 10,000 个票据。
:::

## 响应

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
}
```

## 响应参数
| 字段 | 类型 | 描述 | 字符数                                                                                                          |
|---|------|-----------|---------------------------------------------------------------------------------------------------------------------|
| `bank_slip_ownership_exchange_batch_key`      | uuidv4 | tombamento 批次的唯一识别键。                                                                                                                                                                                                                        | 36                                                                                                                  |
| `request_control_key`                         | uuidv4 | 此端点请求的唯一识别键。用于避免 API 调用重复。                                                                                                                                                            | 36                                                                                                                  |
| `bank_slip_ownership_exchange_batch_status`   | enum  | tombamento 批次的状态。                                                                                                                                                                                                                                               | [枚举器 `bank_slip_ownership_exchange_batch_status`](#enumeradores-bank_slip_ownership_exchange_batch_status) |
| `new_requester_profile_key`                   | uuidv4 | 目标托收钱包的唯一识别键，即票据将被转移（tombados）到的托收钱包。可通过[账户托收钱包查询端点](../boletos/carteira/listar_carteiras)获取此键。 | 36                                                                                                                  |
| `new_requester_profile_code`                  | string | 目标托收钱包代码，即票据将被转移（tombados）到的托收钱包。                                                                                                                                                                                                                    | 19                                                                                                                  |
| `new_requester_profile_owner_name`            | string | 目标账户持有人及目标托收钱包受益人的姓名。                                                                                                                                                                                                                                   | 255                                                                                                                 |
| `new_requester_profile_owner_document_number` | string | 目标账户持有人及目标托收钱包受益人的证件号（CPF/CNPJ）。                                                                                                                                                         | 255                                                                                                                 |
| `new_requester_profile_account_number`        | string | tombamento 目标账户号。                                                                                                                                                                                                                                                   | 7                                                                                                                   |
| `new_requester_profile_account_digit`         | string | tombamento 目标账户校验位。                                                                                                                                                                                                                                       | 1                                                                                                                   |
| `new_requester_profile_account_branch`        | string | tombamento 目标账户支行号。                                                                                                                                                                                                                                        | 4                                                                                                                   |
| `new_pix_key`                                 | string | tombamento 目标账户的 Pix 密钥（BolePix 情况下使用）。                                                                                                                                                                                                                     | 255                                                                                                                 |
| `total_bank_slip_count`                       | float | tombamento 批次中的票据总数。                                                                                                                                                                                                                                     | -                                                                                                                   |
| `total_amount`                                | float | tombamento 批次中票据面值总和。 | -                                                                                                                   |

### 枚举器 bank_slip_ownership_exchange_batch_status
| 枚举器 | 描述                                                                                              |
|------------|--------------------------------------------------------------------------------------------------------|
| open       | 批次已创建，仍开放以纳入/删除票据。                               |
| sent     | 票据选择已完成，tombamento 批次待批准。批准方需完成批准操作。                  |
| processing | 票据选择已完成，批次中票据的 tombamento 正在处理中。 |
| approved | 批次中的票据已完成 tombamento 转移给目标方。 |
| cancelled   | tombamento 批次已取消。 |
| rejected | tombamento 批次已拒绝。 |

---

# 发送票据 tombamento 批次

URL: /zh-Hans/documentation/troca_de_titularidade/validar_lote_e_enviar

此端点用于关闭批次并启动持有权变更的处理。发起请求时，批次将被验证，状态更改为 sent，双方将收到与 tombamento 相关的 webhook。

:::danger 注意！
只有在票据插入完成且来源和目标各方之间的正式化手续已完成时，才应调用此端点。
:::

## 请求

ENDPOINT /account/ ACCOUNT-KEY /requester_profile/ REQUESTER-PROFILE-KEY /bank_slip_ownership_exchange_batch/ BANK-SLIP-OWNERSHIP-EXCHANGE-BATCH-KEY /send
MÉTODO PATCH

### 路径参数

| 字段                                    | 类型   | 描述                                                                                                        | 字符数 |
|------------------------------------------|--------|------------------------------------------------------------------------------------------------------------------|------------|
| `ACCOUNT-KEY`                            | uuidv4 | 原始账户的唯一识别键，即票据最初登记的账户。                | 36         |
| `REQUESTER-PROFILE-KEY`                  | uuidv4 | 原始托收钱包的唯一识别键，即票据最初登记的托收钱包。 | 36         |
| `BANK-SLIP-OWNERSHIP-EXCHANGE-BATCH-KEY` | uuidv4 | tombamento 批次的唯一识别键。                                                             | 36         |

Request Body

```json
{}
```

## 响应

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
}
```

## 响应参数
| 字段 | 类型 | 描述 | 字符数                                                                                                          |
|---|------|-----------|---------------------------------------------------------------------------------------------------------------------|
| `bank_slip_ownership_exchange_batch_key`      | uuidv4 | tombamento 批次的唯一识别键。                                                                                                                                                                                                                        | 36                                                                                                                  |
| `request_control_key`                         | uuidv4 | 此端点请求的唯一识别键。用于避免 API 调用重复。                                                                                                                                                            | 36                                                                                                                  |
| `bank_slip_ownership_exchange_batch_status`   | enum  | tombamento 批次的状态。                                                                                                                                                                                                                                               | [枚举器 `bank_slip_ownership_exchange_batch_status`](#enumeradores-bank_slip_ownership_exchange_batch_status) |
| `new_requester_profile_key`                   | uuidv4 | 目标托收钱包的唯一识别键，即票据将被转移（tombados）到的托收钱包。可通过[账户托收钱包查询端点](../boletos/carteira/listar_carteiras)获取此键。 | 36                                                                                                                  |
| `new_requester_profile_code`                  | string | 目标托收钱包代码，即票据将被转移（tombados）到的托收钱包。                                                                                                                                                                                                                    | 19                                                                                                                  |
| `new_requester_profile_owner_name`            | string | 目标账户持有人及目标托收钱包受益人的姓名。                                                                                                                                                                                                                                   | 255                                                                                                                 |
| `new_requester_profile_owner_document_number` | string | 目标账户持有人及目标托收钱包受益人的证件号（CPF/CNPJ）。                                                                                                                                                         | 255                                                                                                                 |
| `new_requester_profile_account_number`        | string | tombamento 目标账户号。                                                                                                                                                                                                                                                   | 7                                                                                                                   |
| `new_requester_profile_account_digit`         | string | tombamento 目标账户校验位。                                                                                                                                                                                                                                       | 1                                                                                                                   |
| `new_requester_profile_account_branch`        | string | tombamento 目标账户支行号。                                                                                                                                                                                                                                        | 4                                                                                                                   |
| `new_pix_key`                                 | string | tombamento 目标账户的 Pix 密钥（BolePix 情况下使用）。                                                                                                                                                                                                                     | 255                                                                                                                 |
| `total_bank_slip_count`                       | float | tombamento 批次中的票据总数。                                                                                                                                                                                                                                     | -                                                                                                                   |
| `total_amount`                                | float | tombamento 批次中票据面值总和。 | -                                                                                                                   |

### 枚举器 bank_slip_ownership_exchange_batch_status
| 枚举器 | 描述                                                                                              |
|------------|--------------------------------------------------------------------------------------------------------|
| open       | 批次已创建，仍开放以纳入/删除票据。                               |
| closed     | 批次已关闭，批次中票据的 tombamento 已完成。                  |
| processing | 票据选择已完成，批次中票据的 tombamento 正在处理中。 |
| pending_approval | 票据选择已完成，tombamento 批次待批准。批准方可以从批次中删除票据。 |
| canceled   | tombamento 批次已取消。 |
| rejected | tombamento 批次已拒绝。 |

---

# 文档查询

URL: /zh-Hans/documentation/upload_de_documentos/consulta_documents

文档查询可通过以下请求进行：

### Request

ENDPOINT /document/[document_key]/url
MÉTODO GET

### Path Params

| 字段            | 描述                     |
|----------------|--------------------------|
| `document_key` | 文档的唯一密钥            |

:::caution 注意
文档 URL 将生成带有 10 分钟过期时限的链接。
:::

### 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"
}
```

| 字段                   | 类型   | 描述                                                                                                  | 
|------------------------|--------|-------------------------------------------------------------------------------------------------------|
| `document_url`*        | string | 原始文档的可过期 URL。                                                                                |
| `signed_document_url`  | string | 已签名文档的可过期 URL（如存在）。如不存在，则不返回此字段。                                          |
| `expiration_datetime`* | string | URL 过期的日期和时间。                                                                                |

---

# 文档上传

URL: /zh-Hans/documentation/upload_de_documentos/

---

调用必须按照[1.1.3. 认证测试](../primeiros_passos/teste_de_autenticacao)章节描述的标准进行身份验证。注意以下事项：

- 发送到 header 签名中的变量 **md5_hash**（v1 认证中为 **md5_body**）的值应为所发送文件二进制数据的 MD5 值
- 文件的二进制数据必须作为 FormData 发送在请求体中，键名使用字符串 "file"，值为要发送的文件。（此内容不加密）
- 在此调用的响应体中将返回一个 GUID，即文档标识符（以下称为 DOCUMENT_KEY），需保存以备后续使用。

---

## Request

ENDPOINT /upload
MÉTODO POST

Response Body

```json
{
  "document_key": "cfbc8469-89ea-4a80-9f64-ba7b1566c68b",
  "document_md5": "cd451103fa512frc98ce684d3896698c"
}
```

:::caution 注意
请记住保存 **document_key**，该密钥是查询文档时所必需的。
:::

## 调用示例

以下是从 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" # 此密钥仅为示例，请使用您自己的密钥
CLIENT_PRIVATE_KEY = ''''
-----BEGIN EC PRIVATE KEY-----
MIHbAgEBBEHh1hIeOPE5XNNhn6bxRAmVswsPZ0wZCmzVvP8Tl/LZK9ofVmRVGzll
srU1uezJEyHKYdOHrE2p52xUj+pHzjJvb6AHBgUrgQQAI6GBiQOBhgAEAAofUz1J
hBSOyGHLsnV9Sz0DSWmhl7U+ljqbfa8PKVFWSV3w16I1v2zME5/UzUhHn1gWsjnv
7/ekcLLAQbvqMPNXAfjIhFXLAPzqbB9iCuVua1v0Vgy52rBemOWrJka/Ws2bnKR8
h1N1OxOYeYr6C2jqMygBLktKMAs+282CEiEb4bIv
-----END EC PRIVATE 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):
    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-----`; // 此密钥仅为示例，请使用您自己的密钥
  const api_key = '4c268c0a-53ff-429b-92b6-47ef98a6d89a' // 此密钥仅为示例，请使用您自己的密钥

  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()
```

- 注意：上述示例使用 [node-fetch](https://www.npmjs.com/package/node-fetch) 库进行调用，但您可以使用任何您偏好的库。重要的是调用必须使用 POST 方法，header 的 `Content-Type` 值为 `multipart/form-data`，且 body 为包含键名 `file` 和文件二进制数据的 FormData。

:::warning 警告
'Axios' 库存在一个 bug，会导致 FormData 发送为空。该问题可在 [GitHub 仓库](https://github.com/axios/axios/issues/5986)查看。如果在您集成时该问题尚未解决，建议使用 'node-fetch' 库进行此调用。
:::

---

# acg1

URL: /zh-Hans/documentation/webhooks/acg1

提交查询请求后，其余流程由 QI Tech 负责处理。随后将发送一个 webhook，包含两种不同的模型：

- 若查询成功找到结果，将收到一个 `status` 字段值为 "completed" 的通知；此时，`data` 对象将包含查询的其他详细信息。

- 若在查询的周期内未找到相关文件，将收到一个 `status` 字段值为 "not_found" 的通知，表明查询未返回任何信息。

----

### 成功示例

webhook 的 `data` 对象包含以下字段：

**"valueless_months"**：无活动的月数。
**"card_schemes"**：构成已结算总金额的支付安排。
**"value"**：卡结算总金额。

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"
}

```

### 查询未找到结果时

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: /zh-Hans/documentation/webhooks/agenda_de_recebiveis

查询 webhook 按议程（agenda）划分，每个议程代表一个收单机构和一种支付安排。

每个议程中包含一个应收单位列表，按结算日期划分。

每个应收单位都有一个支付列表，标明这些应收款将存入的账户。

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
            }
         ],
         "card_scheme_code":"MCC"
      }
   ]
}

```

---

# 银行划款 Webhook

URL: /zh-Hans/documentation/webhooks/boletos

:::danger 注意！
QI Tech 的 webhooks 不应以严格方式进行映射。
API 返回的 webhook payload 中可能会添加额外字段。
:::

:::info Webhook 重发
您可以按照文档中的详细说明查询并重发 webhooks：[Webhook 重发](/documentation/notificacoes/reenvio_de_notificacoes)。
:::

## 简介

在我们的系统中创建划款后，将发送包含以下状态的 webhook：

| 枚举值 | 中文 | 描述 |
|---|---|---|
| registered | 已登记 | 划款已登记，可供支付 |
| rejected | 已拒绝 | 划款发行请求被拒绝，当划款登记请求包含阻止登记的语义错误时发生 |
| payment_notice | 付款通知 | 划款付款通知，在划款付款时发送此通知，但尚未完成财务结算 |
| notary_office_payment_notice | 公证处付款通知 | 划款在公证处付款时的通知，但尚未完成财务结算 |
| paid | 已支付 | 划款已支付（已完成财务结算的核销）|
| written_off | 已核销 | 划款已核销但未完成财务结算 |

:::info
我们 webhook 的响应超时时间为 10 秒。
:::

## 示例

----

### 登记

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"
}
```

### 付款通知

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"
}

```

支付来源 ID 说明：

| ID | 描述 |
|---|---|
| 1 | 传统网点 |
| 2 | 自动取款机 |
| 3 | 互联网（个人/企业网银）|
| 5 | 银行代理 |
| 6 | 客服中心（电话）|
| 7 | 电子文件 |
| 8 | DDA |
| 9 | 数字代理 |
| 901 | 通过 Pix QR Code 支付 |

### 支付

Webhook Body：通过 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

```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"
}

```

核销发生原因说明：

| 代码 | 描述 |
|---|---|
| 00 | 事件已接受 |
| 10 | 客户主动核销 |
| 14 | 已进行公证抗议 |
| 16 | 金融机构因逾期核销划款 |
| 20 | 划款已核销并转入贴现 |

---

# 债务 Webhook

URL: /zh-Hans/documentation/webhooks/dividas

:::info 提示
我们 webhook 的响应超时时间为 5 秒。
:::

:::danger 注意！
QI Tech 的 webhooks 不应以严格方式进行映射。
API 返回的 webhook payload 中可能会添加额外字段。
:::

:::info Webhook 重发
您可以按照文档中的详细说明查询并重发 webhooks：[Webhook 重发](/documentation/notificacoes/reenvio_de_notificacoes)。
:::

## 签署完成 Webhook

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

Response Body

```json
{
    "key": "bb81d525s-aa4b-4ddf-81d6-aa4b41fd04nb",
    "data": {
        "installments": [...],
        "ted_receipt_list": [...],
        "requester_identifier_key": null
    },
    "status": "disbursed",
    "webhook_type": "debt",
    "event_datetime": "2025-10-26 17:00:52"
}
```

:::info 重要
当债务的银行划款生成后，会发送另一个 webhook：[分期 Webhook](/documentation/webhooks/parcelas)
:::

## 取消 Webhook

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

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"
}
```

----

### 取消原因

| cancel_reason_enumerator | 描述 |
|---|---|
| disbursing_error | 发放时发生错误，操作被取消 |
| waiting_signature | 因缺少签名，操作被取消 |
| is_portability | 操作被取消，因为这是一个未完成的可携性操作 |
| not_collateral_constituted | 操作被取消，因为担保未构成 |
| entry_not_paid | 操作被取消，因为首付款未支付 |
| not_assigned | 操作被取消，因为转让流程未完成 |
| pix_max_retry | 操作被取消，因为接收银行无法收到发放款项 |
| lack_of_resource | 操作因资源不足被取消 |
| manual | 操作被手动取消 |
| kyc_not_accepted | 操作被取消，因为未通过合规审查 |
| not_collateral_fgts | 操作因 FGTS 错误被取消 |
| agencia_conta_invalida | 收款银行支行或账户无效 |
| invalid_account | 目标账号不存在或无效 |
| invalid_document_number | 目标账户的 CPF/CNPJ 不正确 |
| unsupported_transaction | 目标账户不支持此类交易 |
| bank_slip_payment | 因划款支付错误，操作被取消 |
| bank_slip_paid | 操作被取消，因为划款已支付 |
| bank_slip_written_off | 操作被取消，因为划款已核销 |
| invalid_ispb | ISPB 号码无效或不存在 |
| rejected_payment | 支付指令被接收银行拒绝 |
| disbursed_amount_refunded | 操作因发放金额退回而被取消 |

---

# Webhooks de gestão de risco

URL: /zh-Hans/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 |

---

# 不当款项 Webhook

URL: /zh-Hans/documentation/webhooks/indevidos

:::info 提示
我们 webhook 的响应超时时间为 5 秒。
:::

:::danger 注意！
QI Tech 的 webhooks 不应以严格方式进行映射。
API 返回的 webhook payload 中可能会添加额外字段。
:::

:::info Webhook 重发
您可以按照文档中的详细说明查询并重发 webhooks：[Webhook 重发](/documentation/notificacoes/reenvio_de_notificacoes)。
:::

## 简介

当 QI Tech 识别并处理不当款项退款时，此 webhook 会自动触发。验证完成后，系统将使用系统中注册的发放账户，通过 PIX 向借款人进行转账。此事件仅在退款成功完成时发送。

## 不当款项退款 Webhook

Response Body

```json
{
    "callback": {
        "event_datetime": "2024-01-15T14:30:00.000Z",
        "key": "fb34e0ac-2c98-47e7-9040-406b8c3d80e7",
        "status": "refunded",
        "webhook_type": "laas.devolution.refund_receipt",
        "data": {
            "devolution_key": "fb34e0ac-2c98-47e7-9040-406b8c3d80e7",
            "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"
        }
    }
}
```

## 字段定义

### callback 对象

| 字段 | 类型 | 描述 | 必填 |
|-------|------|-----------|-------------|
| **event_datetime** | string | ISO 8601 UTC 格式的事件日期和时间 | 是 |
| **key** | string | 退款的唯一 key | 是 |
| **status** | string | 退款状态 | 是 |
| **webhook_type** | string | webhook 类型 | 是 |
| **data** | object | 退款的具体数据 | 是 |

### data 对象

| 字段 | 类型 | 描述 | 必填 |
|-------|------|-----------|-------------|
| **devolution_key** | string | 退款的唯一 key | 是 |
| **devolution_amount** | number | 退款金额（巴西雷亚尔）| 是 |
| **devolution_status** | string | 退款当前状态 | 是 |
| **devolution_reason_description** | string | 退款原因描述 | 是 |
| **receipt_url** | string | 退款凭证 URL | 是 |
| **document_key** | string | 相关文件的 key | 是 |
| **transacted_at** | string | ISO 8601 UTC 格式的交易日期和时间 | 是 |

## 可能的状态

| 状态 | 描述 |
|--------|-----------|
| **refunded** | 退款已成功处理 |

## 使用示例

当您收到此 webhook 时，表示已成功处理了一笔 PIX 退款。您可以：

1. 通过 `devolution_status` 字段验证退款状态
2. 通过 `receipt_url` 提供的 URL 访问凭证
3. 通过 `devolution_amount` 字段确认退款金额
4. 通过 `devolution_reason_description` 字段了解退款原因

---

# notificacoes_baas_e_laas

URL: /zh-Hans/documentation/webhooks/notificacoes_baas_e_laas

---- 

QI Tech 拥有一套 webhook 系统，用于通知以异步或离线方式发生的流程状态，这些 webhook 按其所服务的类别进行分类。

:::caution 注意！

我们的 webhook 可能会被发送多次（例如在超时情况下），也可能不按顺序发送。
:::

---- 

### 信贷操作：
#### 合同：
- 合同等待签署；
- 合同已签署；

#### 发放：
- 操作已发放；
- 操作已取消；
- 合同已结清（根据请求配置）；
#### 分期（根据请求配置）：
- 分期待处理
- 分期已支付
- 分期等待支付；
- 分期已提前支付；
- 分期已逾期；
- 逾期后部分支付；
- 逾期后已支付
#### 银行划款：
- 登记请求已创建；
- 划款已登记；
- 付款通知；
- 划款已支付；
- 划款已核销；
- 划款已拒绝；
- 划款在公证处支付；
#### SCR：
- 查询结果；

---- 

### 如何确认通知已收到？

要确认接收成功，响应状态码必须为 200，并且必须存在与发送请求类似的签名响应。

即，响应体需符合 **\{"encoded_body": "payloadEmJWT"\}** 格式，并包含 `Authorization` 响应头。此响应头的唯一区别是在路径中需填写接收通知的端点。

如果没有收到接收确认，webhook 冗余机制将被激活。

---- 

### 冗余机制
我们的通知拥有冗余机制，每隔 5 分钟重试一次，共重试 3 次。

---

# 分期支付 Webhook

URL: /zh-Hans/documentation/webhooks/pagamento_de_parcela

:::info 提示
我们 webhook 的响应超时时间为 10 秒。
:::

:::danger 注意！
QI Tech 的 webhooks 不应以严格方式进行映射。
API 返回的 webhook payload 中可能会添加额外字段。
:::

:::info Webhook 重发
您可以按照文档中的详细说明查询并重发 webhooks：[Webhook 重发](/documentation/notificacoes/reenvio_de_notificacoes)。
:::

----
### 分期支付 Webhook 示例

```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
            }
    },
}
```

## 附录

### 字段说明 {#paid_method}

| 字段 | 类型 | 描述 |
|-------------------------------------- |------ |-----          |
| key | UUID | 债务标识 key（credit_operation_key 或 DEBT_KEY）|
| installment_key | UUID | 分期标识 key |
| reference_date | Date | 计算分期未偿余额的参考日期 |
| paid_at | DateTime | 支付日期 |
| paid_method_type | string | 支付方式，请参阅[paid_method_type 枚举值](#paid_method)表 |
| installment_status | string | 分期状态，请参阅[installment_status 枚举值](#installment_status)表 |
| installment_payment_key | UUID | 支付的唯一 key |
| paid_amount | decimal | 已支付金额 |
| total_amount | decimal | 分期总金额，部分支付时更新为未付余额 |
| present_total_amount | decimal | 参考日期（reference_date）的现值 |
| prefixed_interest_payment_amount | decimal | 利息摊销的支付金额 |
| principal_amortization_payment_amount | decimal | 本金摊销的支付金额 |
| resource_account_key | UUID | 用于结算的余额来源账户 |
| batch_renegotiation_proposal_key | UUID | 批量重组 key（如适用）|
| renegotiation_proposal_key | UUID | 重组方案 key（如适用）|
| refinancing_credit_operation_key | UUID | 再融资操作 key（如适用）|
| received_portability_key | UUID | 收到的可携性 key（如适用）|
| bank_slip_key | UUID | 与分期关联的已登记划款 key（如适用）|
| pix_qrcode_key | UUID | 与分期关联的 Pix QR Code key（如适用）|
| paid_in | 对象 | 付款银行信息，适用于通过 Pix 或划款支付的情况 |

:::warning 罚款和滞纳金
支付的罚款+滞纳金（fine_amount）可通过以下公式计算：

fine_amount = paid_amount - prefixed_interest_payment_amount - principal_amortization_payment_amount.
:::

### paid_method_type 枚举值 {#paid_method}

| 枚举值 | 描述 |
|-----------------------|--------|
| bankslip | 银行划款 |
| ted | TED |
| pix | Pix |
| refinancing | 再融资 |
| portability | 可携性 |
| unmonitored | 手动核销 |
| collateral | 担保 |

### installment_status 枚举值 {#installment_status}

| 枚举值 | 描述 |
|-----------------------|---------|
| created | 待处理 |
| opened | 待处理 |
| waiting_payment | 待处理，等待到期日支付 |
| paid_partial | 部分支付 |
| paid | 已支付 |
| paid_early | 已提前支付 |
| overdue | 已逾期 |
| paid_partial_overdue | 逾期后部分支付 |
| paid_overdue | 逾期后已支付 |
| canceled | 已取消 |
| unmonitored | 待处理 |
| waiting_payment_confirmation | 等待再融资结算 |

:::warning 部分提前支付
请注意，不存在"部分提前支付"状态。如果在分期到期日前发生部分核销，之前的状态（unmonitored 或 opened）将保持不变。
:::

---

# 分期 Webhook

URL: /zh-Hans/documentation/webhooks/parcelas

:::info 提示
我们 webhook 的响应超时时间为 10 秒。
:::

:::danger 注意！
QI Tech 的 webhooks 不应以严格方式进行映射。
API 返回的 webhook payload 中可能会添加额外字段。
:::

:::info Webhook 重发
您可以按照文档中的详细说明查询并重发 webhooks：[Webhook 重发](/documentation/notificacoes/reenvio_de_notificacoes)。
:::

当 QI Tech 为操作的收款代理时，可启用此配置，启用后您将收到操作分期的状态变更通知。

可配置的状态有：

- **opened**（待处理）
- **paid**（已支付）
- **waiting_payment**（等待支付）
- **paid_early**（已提前支付）
- **paid_partial**（部分支付）
- **overdue**（已逾期）
- **paid_partial_overdue**（逾期后部分支付）
- **paid_overdue**（逾期后已支付）

----
### 分期支付 Webhook 示例

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",
            "installment_key": "92a05d9c-e457-4f28-9fa8-86be638ee2d0",
            "installment_status": {
                "enumerator": "paid",
                "translation_path": "co.InstallmentStatus.paid"
            },
            "installment_payment": [{
                "installment_payment_key": "f03e1fbc-6d7a-456b-bd6a-db0faac1b481",
                "paid_at": "2026-02-10T11:39:07",
                "paid_amount": 1009.68,
                "paid_method_type": {
                    "enumerator": "pix",
                    "translation_path": "co.PaymentType.pix"
                }
            }]
        },
        "is_finished": true
    },
    "webhook_type": "installment.status_change"
}

```

### 为分期支付创建银行划款的 Webhook 示例

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
            }
        ]
    }
}

```

## 字段定义

### Request Body 对象

| 字段 | 类型 | 描述 | 最大字符 |
|---------------------------------|--------|---------|--------------|
| **key** * | object | 信贷操作的 DEBT-KEY | - |
| **data** * | object | webhook 数据 | - |
| **webhook_type** * | object | 发送的 webhook 类型 | - |

### data 对象

| 字段 | 类型 | 描述 | 最大字符 |
|---------------------------------|--------|---------|--------------|
| **status** * | object | 分期状态 | - |
| **installment** * | object | 分期数据 | - |
| **is_finished** * | boolean | 布尔字段，表示分期是否还有新状态或已完成 | - |