# QI Tech — Outros Documentação da QI Tech em texto corrido, para colar em um LLM. Fonte: https://docs.qitech.com.br 206 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) - 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/account_draft_checking) - 申请账户预留 (/zh-Hans/documentation/baas/account/d4bf7f96-69b0-424b-a9d6-0a1bc79629cd) - 开户 Webhooks (/zh-Hans/documentation/baas/escrow/webhooks) - 上传汇款文件（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/movimentacoes/criar_recorrencia) - Tabela de Erros para Pix Schedule (/zh-Hans/documentation/baas/pix/agendamento/erros_de_agendamento) - Pix Transfer 错误表 (/zh-Hans/documentation/baas/pix/erros_de_pix) - TED 批量交易简介 (/zh-Hans/documentation/baas/ted/batch/introducao_a_transacao_em_lote_ted) - Tabela de Erros para Ted (/zh-Hans/documentation/baas/ted/erros_ted) - 批准票据支付 (/zh-Hans/documentation/boletos/2fa/realizar_pagamento_de_um_boleto) - 请求票据支付 token (/zh-Hans/documentation/boletos/2fa/solicitar_token_para_pagamento) - 查询催收钱包 (/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) - 回执文件对账例程 (/zh-Hans/documentation/boletos/consultar_v1/rotina_de_conciliacao_de_arquivo_retorno) - 批准票据付款 (/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) - 发行 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) - authentication (/zh-Hans/documentation/caas/banking/authentication) - authentication (/zh-Hans/documentation/caas/card_issuance/authentication) - authentication (/zh-Hans/documentation/caas/card_order/authentication) - authentication (/zh-Hans/documentation/caas/credit_analysis/authentication) - 图像 (/zh-Hans/documentation/caas/credit_analysis/image) - 库兼容性 (/zh-Hans/documentation/caas/device_scan/android/compatibility) - 库兼容性 (/zh-Hans/documentation/caas/device_scan/flutter/compatibility) - builder (/zh-Hans/documentation/caas/face_recognition/android/builder) - 1:1 验证 - Face Match (/zh-Hans/documentation/caas/face_recognition/android/face_match) - using_sdk (/zh-Hans/documentation/caas/face_recognition/android/using_sdk) - Registration (/zh-Hans/documentation/caas/face_recognition/api/registration) - Validation (/zh-Hans/documentation/caas/face_recognition/api/validation) - necessary_permissions (/zh-Hans/documentation/caas/face_recognition/ios/necessary_permissions) - using_sdk (/zh-Hans/documentation/caas/face_recognition/ios/using_sdk) - authentication (/zh-Hans/documentation/caas/limits/authentication) - builder (/zh-Hans/documentation/caas/ocr/android/builder) - DocumentDetectorStep (/zh-Hans/documentation/caas/ocr/android/implementation_demo) - using_sdk (/zh-Hans/documentation/caas/ocr/android/using_sdk) - authentication (/zh-Hans/documentation/caas/ocr/api/authentication) - quality (/zh-Hans/documentation/caas/ocr/api/quality) - necessary_permissions (/zh-Hans/documentation/caas/ocr/ios/necessary_permissions) - 导入 SDK (/zh-Hans/documentation/caas/ocr/ios/using_sdk) - QI Conta 交易 (/zh-Hans/documentation/cards/autorizacao/balance_transaction) - Manual BaaS - 数字账户 (/zh-Hans/documentation/casos_de_uso/manual_baas) - Manual BaaS - 服务 (/zh-Hans/documentation/casos_de_uso/manual_baas_servico) - 创建债权转让 (/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) - 为 Escrow 账户创建目标账户 (/zh-Hans/documentation/d88ff174-100d-4b55-80b7-86e11f508400) - 获取 DDA 注册的接受和取消条款 (/zh-Hans/documentation/dda/recuperacao_termo) - 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/reprocessar_contrato) - 错误目录 (/zh-Hans/documentation/erros/catalogo_de_erros) - 更新操作中的投资人数据 (/zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-investidores) - 提交操作的已签署合同 (/zh-Hans/documentation/escrituracao/emissao-de-notas/envio-contratos-assinados) - 查询可用模板 (/zh-Hans/documentation/escrituracao/emissao-de-notas/geracao-minutas/consulta-minutas-disponiveis) - 商业票据书写集成路线图 (/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) - INSS 工资贷款 (/zh-Hans/documentation/guides/INSS/intro) - Assinatura em lote (INSS) (/zh-Hans/documentation/guides/INSS/signatures/batch-signature) - 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) - Atualizar Status da Conta Bancária (/zh-Hans/documentation/iaas/investidor/compartilhado/contas_bancarias/atualizar_status_conta_bancaria) - 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) - 简介 (/zh-Hans/documentation/iaas/investidor/inicio) - 经理审批 (/zh-Hans/documentation/iaas/venda_ativos/assignment/aprovacao_recompra) - 获取账户交易记录 (/zh-Hans/documentation/iaas/visibildade_de_caixa/get_transaction_reversals) - 文档介绍 (/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/manual_aeronautica/manual_consignado) - Homologation Roadmap - BNPL (/zh-Hans/documentation/manual_bnpl_ecommerce/manual_bnpl) - 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_contratos_legados) - 保险 (/zh-Hans/documentation/manual_consignado_privado/manual_seguro) - 私人薪资抵押贷款手册 - 遗留合同归档 (/zh-Hans/documentation/manual_consignado_privado/manual_tombamento_legado) - Emissão Crédito Clean (/zh-Hans/documentation/manual_credito_clean/emissao/) - Emissão de Dívida PJ com Assinatura Imediata (/zh-Hans/documentation/manual_emissao_pj_signed_debt/emissao_signed_debt_pj) - 我的 INSS 提案拍卖手册 (/zh-Hans/documentation/manual_leilao_meu_inss/) - 审批转账 (/zh-Hans/documentation/movimentacao_de_contas/aprovar_transferencia) - 查询待处理交易 (/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) - 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) - 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) - 定期转账收据 (/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/pesquisar_por_transferencia_pix_de_saida) - 申请 Pix 退款 (/zh-Hans/documentation/pix/solicitar_chargeback_pix) - solicitar_transferencia (/zh-Hans/documentation/pix/solicitar_transferencia) - Renegociação internal e external (/zh-Hans/documentation/renegociacao/criacao_renegociacao_internal) - 按分期金额模拟 (/zh-Hans/documentation/renegociacao/simulacao_com_valor_por_parcela) - 更新手动支付记录 (/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) - 审批转账 (/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/criar_lote_batch) - 票据 Tombamento Webhook (/zh-Hans/documentation/troca_de_titularidade/notificacoes_webhooks) - acg1 (/zh-Hans/documentation/webhooks/acg1) - agenda_de_recebiveis (/zh-Hans/documentation/webhooks/agenda_de_recebiveis) - 银行划款 Webhook (/zh-Hans/documentation/webhooks/boletos) - notificacoes_baas_e_laas (/zh-Hans/documentation/webhooks/notificacoes_baas_e_laas) --- # 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": "\", "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": "\", "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": "\", "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": "\", "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": "\", "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": "\", "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 ( 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 ( 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)

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

**[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": "\", "amendment_date": "\", "financial": { "calculate_delay": "\", "monthly_rate": "\", "desired_installments" : [ { "due_date": "\", } ] }, "additional_data": "\", } ``` **Response** Response Body ```json { "amendment_debt_key": "\", "amendment_date": "\", "financial":{ "calculate_delay": "\", "monthly_rate": "\", "desired_installments" : [ { "due_date": "\", "total_amount": "\", } ] }, "additional_data": "\", "final_debt": { "annual_cet": "\", "cet": "\", "installments":{ "bank_slip_key": "\", "business_due_date": "\", "calendar_days": "\", "digitable_line": "\", "due_date": "\", "due_interest": "\", "due_principal":"\", "installment_key": "\", "installment_number": "\", "post_fixed_amount": "\", "pre_fixed_amount": "\", "principal_amortization_amount": "\", "qr_code_key": "\", "qr_code_url": "\", "total_amount": "\", "workdays": "\", }, "prefixed_interest_rate": { "annual_rate": "\", "daily_rate": "\", "interest_base": "\", "monthly_rate": "\", }, "issue_amount": "\", "number_of_installments": "\", "total_iof": "\" } } ``` **1.2.** 创建： **Request** ENDPOINT /amendment MÉTODO POST Request Body ```json { "amendment_debt_key": "\", "amendment_date": "\", "financial": { "calculate_delay": "\", "monthly_rate": "\", "desired_installments" : [ { "due_date": "\", } ] }, "additional_data": "\", } ``` **Response** Response Body ```json { "amendment_key": "\", "amendment_debt_key": "\", "amendment_date": "\", "financial":{ "calculate_delay": "\", "monthly_rate": "\", "desired_installments" : [ { "due_date": "\", "total_amount": "\", } ] }, "additional_data": "\", "amendment_status": "waiting_signature", "document_key": "\", "document_url": "\", "final_debt": { "annual_cet": "\", "cet": "\", "installments":{ "bank_slip_key": "\", "business_due_date": "\", "calendar_days": "\", "digitable_line": "\", "due_date": "\", "due_interest": "\", "due_principal":"\", "installment_key": "\", "installment_number": "\", "post_fixed_amount": "\", "pre_fixed_amount": "\", "principal_amortization_amount": "\", "qr_code_key": "\", "qr_code_url": "\", "total_amount": "\", "workdays": "\", }, "prefixed_interest_rate": { "annual_rate": "\", "daily_rate": "\", "interest_base": "\", "monthly_rate": "\", }, "issue_amount": "\", "number_of_installments": "\", "total_iof": "\" } } ``` 与模拟相比，创建操作的 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": "\", "amendment_debt_key": "\", "amendment_date": "\", "financial":{ "calculate_delay": "\", "monthly_rate": "\", "desired_installments" : [ { "due_date": "\", "total_amount": "\", } ] }, "additional_data": "\", "amendment_status": "\", "document_key": "\", "document_url": "\", "final_debt": { "annual_cet": "\", "cet": "\", "installments":{ "bank_slip_key": "\", "business_due_date": "\", "calendar_days": "\", "digitable_line": "\", "due_date": "\", "due_interest": "\", "due_principal":"\", "installment_key": "\", "installment_number": "\", "post_fixed_amount": "\", "pre_fixed_amount": "\", "principal_amortization_amount": "\", "qr_code_key": "\", "qr_code_url": "\", "total_amount": "\", "workdays": "\", }, "prefixed_interest_rate": { "annual_rate": "\", "daily_rate": "\", "interest_base": "\", "monthly_rate": "\", }, "issue_amount": "\", "number_of_installments": "\", "total_iof": "\" } } ``` **Response Canceled** Response Body ```json { "amendment_key": "\", "amendment_debt_key": "\", "amendment_date": "\", "financial":{ "calculate_delay": "\", "monthly_rate": "\", "desired_installments" : [ { "due_date": "\", "total_amount": "\", } ] }, "additional_data": "\", "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": "\", "document_url": "\", "final_debt": { "annual_cet": "\", "cet": "\", "installments":{ "bank_slip_key": "\", "business_due_date": "\", "calendar_days": "\", "digitable_line": "\", "due_date": "\", "due_interest": "\", "due_principal":"\", "installment_key": "\", "installment_number": "\", "post_fixed_amount": "\", "pre_fixed_amount": "\", "principal_amortization_amount": "\", "qr_code_key": "\", "qr_code_url": "\", "total_amount": "\", "workdays": "\", }, "prefixed_interest_rate": { "annual_rate": "\", "daily_rate": "\", "interest_base": "\", "monthly_rate": "\", }, "issue_amount": "\", "number_of_installments": "\", "total_iof": "\" } } ``` ## 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": "\", "event_datetime": "\", "data": { "amendment_status": "signed", "document_key": "\", "signed_document_url": "\" } } ``` **4.2.** 放款： Body ```json { "webhook_type": "amendment", "amendment_key": "\", "event_datetime": "\", "data": { "amendment_status": "disbursed", "final_debt_key": "\", "installments": [ { "bank_slip_key": "\", "business_due_date": "\", "calendar_days": "\", "digitable_line": "\", "due_date": "\", "due_interest": "\", "due_principal":"\", "installment_key": "\", "installment_number": "\", "post_fixed_amount": "\", "pre_fixed_amount": "\", "principal_amortization_amount": "\", "qr_code_key": "\", "qr_code_url": "\", "total_amount": "\", "workdays": "\" } ] } } ``` **4.3.** 取消： Body ```json { "webhook_type": "amendment", "amendment_key": "\", "event_datetime": "\", "data": { "amendment_status": "canceled", "cancel_reason": { "enumerator": "\", "description": "\", "translation": "\" } } } ``` 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** | 创建延期修改操作与放款时的未偿期数不同 | --- # 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": "\", "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": "\", "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 代码
`status` | QI 代码
`code` | 标题
`title` | 描述（英文）
`description` | 描述（葡文）
`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 代码
`status` | QI 代码
`code` | 标题
`title` | 描述（英文）
`description` | 描述（葡文）
`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 代码
`status` | QI 代码
`code` | 标题
`title` | 描述（英文）
`description` | 描述（葡文）
`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 代码
`status` | QI 代码
`code` | 标题
`title` | 描述（英文）
`description` | 描述（葡文）
`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" } ``` --- # 上传汇款文件（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 代码
`status` | QI 代码
`code` | 标题
`title` | 描述（英文）
`description` | 描述（葡文）
`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 '``' . Please do not use specials characters like '!', '@', '(', ')', '$'. | Nome de arquivo invalido '``'. 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/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 代码
`code` | 标题
`title` | 描述（英文）
`Description` | 描述（葡文）
`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 | --- # 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
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (ptbr)
`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 | --- # 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 | --- # 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` 对象。 --- # 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
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (ptbr)
`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 | --- # 批准票据支付 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/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 属性将为空。 ::: --- # 回执文件对账例程 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/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 状态码
`status` | QI 代码
`code` | 标题
`title` | 描述（英文）
`description` | 描述（葡文）
`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. | --- # 发行 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：票据已核销，无财务清算。 --- # 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。 ::: --- # 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。 ::: --- # 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。 ::: --- # 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/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/device_scan/android/compatibility | 配置 | 最低版本 | |------------|--------------| |minSdkVersion|21| --- # 库兼容性 URL: /zh-Hans/documentation/caas/device_scan/flutter/compatibility | 配置 | 最低版本 | |------------|--------------| |Dart SDK|2.15| |iOS|12| |minSdkVersion|21| --- # builder URL: /zh-Hans/documentation/caas/face_recognition/android/builder ## FaceRecognition.Builder | 参数 | 功能 | 是否必填 | | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---- | | mobileToken | 客户密钥，用于标识收集的数据来源于您的应用程序。如果尚未收到您的 mobile-token，请联系支持团队。 | 是。 | | .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 引导屏幕上向用户显示的文本 | 否。 | ``` ``` --- # 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` 时，需要有记录才能进行验证。 --- # 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。 ::: --- # 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}` --- # 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}` --- # 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。 ::: --- # 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。 ::: --- # builder URL: /zh-Hans/documentation/caas/ocr/android/builder ## DocumentRecognition.Builder | 参数 | 功能 | 是否必填 | |------------|--------------|--------------| |mobileToken |客户密钥，用于标识收集的数据来源于您的应用程序。如果尚未收到您的 mobile-token，请联系支持团队。|是。| |.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 引导屏幕上向用户显示的文本| 否。| --- # 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 mDocumentRecognitionResponse = data.getParcelableArrayListExtra("DocumentRecognitionResponse"); resultIntent.putParcelableArrayListExtra("DocumentRecognitionResponse", mDocumentRecognitionResponse); finish(); } else { // 用户关闭了 activity } } super.onActivityResult(requestCode, resultCode, data); } } ``` --- # 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。 ::: --- # 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" 的返回才是图片质量验证的结果，因此才应转达给用户。 --- # 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', '~> ' ``` 最后，只需按照旁边的格式添加 `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。 ::: --- # 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) ::: --- # 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": "\", "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_identification_back": "\", "document_identification_type": "cnh", ``` 如果文件以 1 个文件提交，同一文件中包含证件正面和背面（**证件照片或电子驾照**），则应在 ***/account*** 端点（**1.2.2.**）的 account_owner 对象中填写以下字段： Request Body ```json "document_identification": "\", "document_identification_type": "cnh", ``` ##### 1.3.1.2. 提交 RG 类型身份证件 对于 RG 类型证件，必须始终提交 2 个文件，一个包含证件正面，另一个包含证件背面。在此情况下，应在 /account 端点（1.2.2.）的 account_owner 对象中填写以下字段： Request Body ```json "document_identification": "\", "document_identification_back": "\", "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": "\", "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": "\", "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": "\", "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 () could not be completed and is pending confirmation.\", \"translation\": \"Não foi possível concluir a transação () 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": "\", "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": "\" } ``` **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": "\", "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": [{ "\": "\" }] } ``` :::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": [{ "\": "\" }], "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": "\", "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": [{ "\": "\" }] } ``` **响应（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": [{ "\": "\" }], "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": "\", "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": [{ "\": "\" }] } ``` **请求（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": [{ "\": "\" }], "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": "\", "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": "\", "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": "\", "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": "\", "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": "\", "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": "\", "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"格式发送。  **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",  **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": "\", "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": "\", "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": "\", "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 () could not be completed and is pending confirmation.\", \"translation\": \"Não foi possível concluir a transação () 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": "\", "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": "\", "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": "\", "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": "\", "payload": "\", "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": [{ "\": "\" }] } ``` :::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": [{ "\": "\" }], "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": "\", "image": "\", "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": [{ "\": "\" }] } ``` **响应** 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": [{ "\": "\" }], "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": "\", "image": "\", "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": [{ "\": "\" }] } ``` **响应** 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": [{ "\": "\" }], "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": "\", "image": "\", "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": "\" } ``` :::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": "\" } ``` **响应** 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/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 代码
`status` | QI 代码
`code` | 标题
`title` | 描述（英文）
`description` | 描述（葡文）
`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" } ``` --- # 为 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/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 | 付款方签署的授权数据 | - | --- # 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/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/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 | 支付类型无效。 | --- # 更新操作中的投资人数据 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/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/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/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)

[文档链接](/documentation/escrituracao/introducao/teste-autenticacao/endpoints_de_teste) | CAB0001 | | CAB0003* | Webhooks 配置 | 配置 QI 发送 webhooks 的 URL。 | [文档链接](/documentation/escrituracao/introducao/autenticacao_webhooks)

[文档链接](/documentation/escrituracao/configuracao-webhooks)

[文档链接](/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)

[文档链接](/documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor-remocao) | CED0001 | | CED0003* | 发行人代表的登记和删除 | 上传和删除与已登记发行人关联的代表 | [文档链接](/documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor)

[文档链接](/documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor-remocao) | CED0001 | | CED0004* | 发行人代表文件的上传和删除 | 上传和删除与已登记发行人代表关联的文件 | [文档链接](/documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor)

[文档链接](/documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor-remocao) | CED0001, CED0003 | | CED0005* | 发行人银行账户的登记和删除 | 登记和删除与已登记发行人关联的银行账户 | [文档链接](/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor)

[文档链接](/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor-remocao) | CED0001 | | CED0006* | 发行人签署人组的登记和删除 | 登记和删除与已登记发行人关联的签署人组 | [文档链接](/documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor)

[文档链接](/documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor-remocao) | CED0001 | | CED0007* | 发行人联系信息的登记和删除 | 登记和删除与已登记发行人关联的联系信息 | [文档链接](/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor)

[文档链接](/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)

[文档链接](/documentation/escrituracao/homologacao-investidor/cadastro/documentos-investidor-remocao) | INV0001 | | INV0003* | 投资人代表的登记和删除 | 上传和删除与已登记投资人关联的代表 | [文档链接](/documentation/escrituracao/homologacao-investidor/cadastro/representantes-investidor)

[文档链接](/documentation/escrituracao/homologacao-investidor/cadastro/representantes-investidor-remocao) | INV0001 | | INV0004* | 投资人代表文件的上传和删除 | 上传和删除与已登记投资人代表关联的文件 | [文档链接](/documentation/escrituracao/homologacao-investidor/cadastro/documentos-representantes-investidor)

[文档链接](/documentation/escrituracao/homologacao-investidor/cadastro/documentos-representantes-investidor-remocao) | INV0001, INV0003 | | INV0005* | 投资人银行账户的登记和删除 | 登记和删除与已登记投资人关联的银行账户 | [文档链接](/documentation/escrituracao/homologacao-investidor/cadastro/conta-bancaria-investidor)

[文档链接](/documentation/escrituracao/homologacao-investidor/cadastro/conta-bancaria-investidor-remocao) | INV0001 | | INV0006* | 投资人签署人组的登记和删除 | 登记和删除与已登记投资人关联的签署人组 | [文档链接](/documentation/escrituracao/homologacao-investidor/cadastro/assinantes-investidor)

[文档链接](/documentation/escrituracao/homologacao-investidor/cadastro/assinantes-investidor-remocao) | INV0001 | | INV0007* | 投资人联系信息的登记和删除 | 登记和删除与已登记投资人关联的联系信息 | [文档链接](/documentation/escrituracao/homologacao-investidor/cadastro/informacao-contato-investidor)

[文档链接](/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)

[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)

[Link Documentação](/documentation/escrituracao/configuracao-webhooks)

[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)

[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)

[Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/configuracao-webhooks)

[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)

[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)

[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)

[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)

[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)

[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)

[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)

[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 | --- # 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 中的单个签名信封。 --- # 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` | ::: --- # 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**. --- # 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. --- # 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. --- # 简介 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/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/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/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/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": "\", "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": "\", "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": "\", "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 ( 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": "\", "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": "\", "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 = '' 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 | --- # 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
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
das Operações] --> E2[2. Registro na B3, Envio
do Lote e Retorno do Cessionário] E2 --> E3[3. Termo de Cessão
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_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": "", "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_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": "\" } ``` ::: ## 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" : "", "inquiry_type" : "legacy" } ``` ### Response STATUS **202** Accepted **Response Body** ```json { "employment_relationships_inquiry_key": "", "employment_relationships_inquiry_status": "pending_inquiry" } ``` ### Webhooks WEBHOOK TYPE laas.private_payroll.employment_relationships_inquiry_status_change 雇佣关系查询返回结果： STATUS completed **Webhook Body** ```json { "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": "", "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": "", "contract_number": "LEG0123456789", "first_due_date": "2025-04-07", "disbursement_end_date": "2024-11-07", "requester_identifier_key": "", "credit_operation_key": "", "operation_type_enumerator": "external_operation", "issue_amount": 700, "requester_key": "", "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 }, ... ] } ``` --- # 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 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=, purchaser_document_number=. The borrower has no active analysis for the given product.", "translation": "Nenhuma analise de credito ativa encontrada para product_name=, purchaser_document_number=. 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`. --- # 我的 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 中，参见认证部分。 | | 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/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 | 账户持有人姓名 | --- # 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 本身执行的）。 #### 征税凭单与税款 征税凭单和税款的结算取决于各发行机构/代理方的规则和操作要素。 --- # 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 状态码
`status` | QI 代码
`code` | 标题
`title` | 英文描述
`description` | 葡语描述
`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 状态码
`status` | QI 代码
`code` | 标题
`title` | 英文描述
`description` | 葡语描述
`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 状态码
`status` | QI 代码
`code` | 标题
`title` | 英文描述
`description` | 葡语描述
`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 代码
`code` | 标题
`title` | 英文描述
`Description` | 葡语描述
`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 代码
`status` | QI 代码
`code` | 标题
`title` | 描述（英文）
`description` | 描述（葡萄牙语）
`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 () could not be completed and is pending confirmation.\", \"translation\": \"Não foi possível concluir a transação () 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 代码
`code` | 标题
`title` | 描述（英文）
`Description` | 描述（葡萄牙语）
`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 | --- # 定期转账收据 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 代码
`code` | 标题
`title` | 描述（英文）
`Description` | 描述（葡萄牙语）
`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/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` | 转账出错 | --- # 申请 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 代码
`status` | QI 代码
`code` | 标题
`title` | 描述（英文）
`description` | 描述（葡萄牙语）
`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\"}" } ``` --- # 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/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/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)

[文档链接](/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 项:
[文档链接](/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 项:
[文档链接](/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 项
[文档链接](/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)

[文档链接](/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)
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)
iOS:[ 文档链接](/documentation/caas/ocr/ios/collecting_response)| ATF0008 | ## SDK 人脸识别 | 代码 | 步骤 | 描述 | 文档链接 | 前置条件 | | --- | --- | --- | --- | --- | | ATF0011* | 构建 SDK | 定义自定义选项并在您的应用中（QI Tech 客户应用）成功构建 SDK | Android: [文档链接](/documentation/caas/face_recognition/android/introduction)
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)
iOS:[ 文档链接](/documentation/caas/device_scan/ios/introduction)| | ATF0016* | 存储用户会话 | 存储待扫描设备的用户会话（sessionId） | Android: [文档链接](/documentation/caas/device_scan/android/example)
iOS:[ 文档链接](/documentation/caas/device_scan/ios/example) | ATF0015 e ATF0017 | | ATF0017* | 采集信息 | 使用已存储的 sessionId 实例化 SDK，并在您的应用中（QI Tech 客户应用）调用信息采集方法 | Android: [文档链接](/documentation/caas/face_recognition/android/collecting_response)
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 项:
[文档链接](/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 项:
[文档链接](/documentation/movimentacao_de_contas/transacao) | | | TED0003* | 模拟 TED 转入 | 模拟 TED 转入到 QI 账户 | 第 2 项:
[文档链接](/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 项:
[文档链接](/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:
[文档链接](/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade) |PIX0013 | | PIX0017* | 模拟 Pix 密钥转出可携带性申请 | 模拟接收 Pix 密钥转出可携带性申请 | 第 5 项:
[文档链接](/documentation/pix/simulacao/index.html) | PIX0013 | | PIX0018* | 批准和拒绝 Pix 密钥转出可携带性申请 | 批准 Pix 密钥转出可携带性申请 | [文档链接](/documentation/pix/portabilidade#request-4) | PIX0017 | | PIX0019* | 重新发送 Pix 密钥转出可携带性申请的双因素认证 | 重新发送 Pix 密钥转出可携带性申请的双因素认证 | Enum "pending_donator_validation"
[文档链接](/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)

[文档链接](/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)
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)
iOS:[ 文档链接](/documentation/caas/ocr/ios/collecting_response)| ATF0008 | ## SDK 人脸识别 | 代码 | 步骤 | 描述 | 文档链接 | 前置条件 | | --- | --- | --- | --- | --- | | ATF0011* | 构建 SDK | 定义自定义选项并在您的应用中（QI Tech 客户应用）成功构建 SDK | Android: [文档链接](/documentation/caas/face_recognition/android/introduction)
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)
iOS:[ 文档链接](/documentation/caas/device_scan/ios/introduction)| | ATF0016* | 存储用户会话 | 存储待扫描设备的用户会话（sessionId） | Android: [文档链接](/documentation/caas/device_scan/android/example)
iOS:[ 文档链接](/documentation/caas/device_scan/ios/example) | ATF0015 e ATF0017 | | ATF0017* | 采集信息 | 使用已存储的 sessionId 实例化 SDK，并在您的应用中（QI Tech 客户应用）调用信息采集方法 | Android: [文档链接](/documentation/caas/face_recognition/android/collecting_response)
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 项:
[文档链接](/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)
2 . 审批转账: [文档链接](/documentation/baas/ted/realizar_transferencia_2fa)
| QIC0004 ou QIC0005 | | TED0006* | 申请重新发送令牌 | 重新发送 TED 转账审批令牌 | [文档链接](/documentation/baas/ted/2fa/solicitacao_de_reenvio_de_token) | TED0001 | | TED0002* | 模拟 TED 转出退回 | 模拟从 QI 账户发出的 TED 转出退款 | 第 3 项:
[文档链接](/documentation/movimentacao_de_contas/transacao) | | | TED0003* | 模拟 TED 转入 | 模拟 TED 转入到 QI 账户 | 第 2 项:
[文档链接](/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)
2 . 审批转账: [文档链接](/documentation/baas/ted/realizar_transferencia_2fa)
| QIC0004 ou QIC0005 | | TFI0002 | 模拟账户贷记内部转账 | 模拟目标 QI 账户从另一个 QI 账户收款 | 第 1 项:
[文档链接](/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)

[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)

[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:
[文档链接](/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade) |PIX0013 | | PIX0017* | 模拟 Pix 密钥转出可携带性申请 | 模拟接收 Pix 密钥转出可携带性申请 | 第 5 项:
[文档链接](/documentation/pix/simulacao/index.html) | PIX0013 | | PIX0018* | 批准和拒绝 Pix 密钥转出可携带性申请 | 批准 Pix 密钥转出可携带性申请 | [文档链接](/documentation/pix/portabilidade#request-4) | PIX0017 | | PIX0019* | 重新发送 Pix 密钥转出可携带性申请的双因素认证 | 重新发送 Pix 密钥转出可携带性申请的双因素认证 | Enum "pending_donator_validation"
[文档链接](/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)

[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)

[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)
1. 创建: [文档](/documentation/gestao_de_usuarios/criacao_de_pessoa)
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)

[文档链接](/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 项：
[文档链接](/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)
2 . 审批转账：[文档链接](/documentation/baas/ted/realizar_transferencia_2fa)
| QIC0004 ou QIC0005 | | TED0006* | 申请重新发送令牌 | 重新发送 TED 转账审批令牌 | [文档链接](/documentation/baas/ted/2fa/solicitacao_de_reenvio_de_token) | TED0001 | | TED0002* | 模拟 TED 转出退回 | 模拟从 QI 账户发出的 TED 转出退款 | 第 3 项：
[文档链接](/documentation/movimentacao_de_contas/transacao) | | | TED0003* | 模拟 TED 转入 | 模拟 TED 转入到 QI 账户 | 第 2 项：
[文档链接](/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)
2 . 审批转账：[文档链接](/documentation/baas/ted/realizar_transferencia_2fa)
| QIC0004 ou QIC0005 | | TFI0002 | 模拟账户贷记内部转账 | 模拟目标 QI 账户从另一个 QI 账户收款 | 第 1 项：
[文档链接](/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)

[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)

[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：
[文档链接](/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade) |PIX0013 | | PIX0017* | 模拟 Pix 密钥转出可携带性申请 | 模拟接收 Pix 密钥转出可携带性申请 | 第 5 项：
[文档链接](/documentation/pix/simulacao/index.html) | PIX0013 | | PIX0018* | 批准和拒绝 Pix 密钥转出可携带性申请 | 批准 Pix 密钥转出可携带性申请 | [文档链接](/documentation/pix/portabilidade#request-4) | PIX0017 | | PIX0019* | 重新发送 Pix 密钥转出可携带性申请的双因素认证 | 重新发送 Pix 密钥转出可携带性申请的双因素认证 | Enum "pending_donator_validation"
[文档链接](/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)

[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)

[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)
1. 创建：[文档](/documentation/gestao_de_usuarios/criacao_de_pessoa)
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)

[文档链接](/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 项：
[文档链接](/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 项：
[文档链接](/documentation/movimentacao_de_contas/transacao) | TED0003 | | TED0003* | 模拟 TED 转入 | 模拟 TED 转入到 QI 账户 | 第 2 项：
[文档链接](/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 项：
[文档链接](/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：
[文档链接](/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade) |PIX0013 | | PIX0017* | 模拟 Pix 密钥转出可携带性申请 | 模拟接收 Pix 密钥转出可携带性申请 | 第 5 项：
[文档链接](/documentation/pix/simulacao/index.html) | PIX0013 | | PIX0018* | 批准和拒绝 Pix 密钥转出可携带性申请 | 批准 Pix 密钥转出可携带性申请 | [文档链接](/documentation/pix/portabilidade#request-4) | PIX0017 | | PIX0019* | 重新发送 Pix 密钥转出可携带性申请的双因素认证 | 重新发送 Pix 密钥转出可携带性申请的双因素认证 | Enum "pending_donator_validation"
[文档链接](/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)

[文档链接](/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 项：
[文档链接](/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 项：
[文档链接](/documentation/movimentacao_de_contas/transacao) | TED0003 | | TED0003* | 模拟 TED 转入 | 模拟 TED 转入到 QI 账户 | 第 2 项：
[文档链接](/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 项：
[文档链接](/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：
[文档链接](/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade) |PIX0013 | | PIX0017* | 模拟 Pix 密钥转出可携带性申请 | 模拟接收 Pix 密钥转出可携带性申请 | 第 5 项：
[文档链接](/documentation/pix/simulacao/index.html) | PIX0013 | | PIX0018* | 批准和拒绝 Pix 密钥转出可携带性申请 | 批准 Pix 密钥转出可携带性申请 | [文档链接](/documentation/pix/portabilidade#request-4) | PIX0017 | | PIX0019* | 重新发送 Pix 密钥转出可携带性申请的双因素认证 | 重新发送 Pix 密钥转出可携带性申请的双因素认证 | Enum "pending_donator_validation"
[文档链接](/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)

[文档链接](/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)
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)
iOS:[ 文档链接](/documentation/caas/ocr/ios/collecting_response)| ATF0008 | ## SDK 人脸识别 | 代码 | 步骤 | 描述 | 文档链接 | 前置条件 | | --- | --- | --- | --- | --- | | ATF0011* | 构建 SDK | 定义自定义选项并在您的应用中（QI Tech 客户应用）成功构建 SDK |Android: [文档链接](/documentation/caas/face_recognition/android/introduction)
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)
iOS:[ 文档链接](/documentation/caas/device_scan/ios/introduction)| | ATF0016* | 存储用户会话 | 存储待扫描设备的用户会话（sessionId） | Android: [文档链接](/documentation/caas/device_scan/android/example)
iOS:[ 文档链接](/documentation/caas/device_scan/ios/example) | ATF0015 e ATF0017 | | ATF0017* | 采集信息 | 使用已存储的 sessionId 实例化 SDK，并在您的应用中（QI Tech 客户应用）调用信息采集方法 | Android: [文档链接](/documentation/caas/face_recognition/android/collecting_response)
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 条：
[文档链接](/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 条：
[文档链接](/documentation/movimentacao_de_contas/transacao) | TED0003 | | TED0003* | 模拟 TED 转入 | 模拟 TED 转入到 QI 账户 | 第 2 条：
[文档链接](/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 条：
[文档链接](/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：
[文档链接](/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade) |PIX0013 | | PIX0017* | 模拟 Pix 密钥转出可携带性申请 | 模拟 Pix 密钥转出可携带性申请的到达 | 第 5 条：
[文档链接](/documentation/pix/simulacao/index.html) | PIX0013 | | PIX0018* | 批准和拒绝 Pix 密钥转出可携带性申请 | 批准 Pix 密钥转出可携带性申请 | [文档链接](/documentation/pix/portabilidade#request-4) | PIX0017 | | PIX0019* | 重新发送 Pix 密钥转出可携带性申请的双因素认证 | 重新发送 Pix 密钥转出可携带性申请的双因素认证 | Enum "pending_donator_validation"
[文档链接](/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)

[文档链接](/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)

[文档链接](/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)
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)
iOS:[ 文档链接](/documentation/caas/ocr/ios/collecting_response)| ATF0008 | ## SDK 人脸识别 | 代码 | 步骤 | 描述 | 文档链接 | 前置条件 | | --- | --- | --- | --- | --- | | ATF0011* | 构建 SDK | 定义自定义选项并在您的应用中（QI Tech 客户应用）成功构建 SDK |Android: [文档链接](/documentation/caas/face_recognition/android/introduction)
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)
iOS:[ 文档链接](/documentation/caas/device_scan/ios/introduction)| | ATF0016* | 存储用户会话 | 存储待扫描设备的用户会话（sessionId） | Android: [文档链接](/documentation/caas/device_scan/android/example)
iOS:[ 文档链接](/documentation/caas/device_scan/ios/example) | ATF0015 e ATF0017 | | ATF0017* | 采集信息 | 使用已存储的 sessionId 实例化 SDK，并在您的应用中（QI Tech 客户应用）调用信息采集方法 | Android: [文档链接](/documentation/caas/face_recognition/android/collecting_response)
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 条：
[文档链接](/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)
2. 审批转账：[文档链接](/documentation/baas/ted/realizar_transferencia_2fa)
| QIC0003 ou QIC0005 | | TED0002* | 申请重新发送令牌 | 重新发送 TED 转账审批令牌 | [文档链接](/documentation/baas/ted/2fa/solicitacao_de_reenvio_de_token) | TED0001 | | TED0003* | 模拟 TED 转出退回 | 模拟从 QI 账户发出的 TED 转出退款 | 第 3 条：
[文档链接](/documentation/movimentacao_de_contas/transacao) | TED0004 | | TED0004* | 模拟 TED 转入 | 模拟 TED 转入到 QI 账户 | 第 2 条：
[文档链接](/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)
2. 审批转账：[文档链接](/documentation/baas/ted/realizar_transferencia_2fa)
| QIC0003 ou QIC0005 | | TFI0002 | 模拟账户贷记内部转账 | 模拟目标 QI 账户从另一个 QI 账户收款 | 第 1 条：
[文档链接](/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)

[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)

[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：
[文档链接](/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade) |PIX0013 | | PIX0017* | 模拟 Pix 密钥转出可携带性申请 | 模拟 Pix 密钥转出可携带性申请的到达 | 第 5 条：
[文档链接](/documentation/pix/simulacao/index.html) | PIX0013 | | PIX0018* | 批准和拒绝 Pix 密钥转出可携带性申请 | 批准 Pix 密钥转出可携带性申请 | [文档链接](/documentation/pix/portabilidade#request-4) | PIX0017 | | PIX0019* | 重新发送 Pix 密钥转出可携带性申请的双因素认证 | 重新发送 Pix 密钥转出可携带性申请的双因素认证 | Enum "pending_donator_validation"
[文档链接](/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)

[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)

[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)
1. 创建：[文档](/documentation/gestao_de_usuarios/criacao_de_pessoa)
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)

[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)
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)
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)
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)
iOS:[ Link Documentação](/documentation/caas/device_scan/ios/introduction)| | ATF0016* | 存储用户会话 | 存储将要被扫描设备的用户会话（sessionId） | Android: [Link Documentação](/documentation/caas/device_scan/android/example)
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)
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:
[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:
[Link Documentação](/documentation/movimentacao_de_contas/transacao) | TED0001 | | TED0003* | 模拟 TED 转入 | 模拟 TED 转入到 QI 账户 | Item 2:
[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:
[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:
[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:
[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:
[Link Documentação](/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade) |PIX0013 | | PIX0017* | 模拟 Pix 密钥转出可携性申请 | 模拟收到 Pix 密钥转出可携性申请 | Item 5:
[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"
[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)

[认证测试端点](/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)

[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:
[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:
[Link Documentação](/documentation/movimentacao_de_contas/transacao) | TED0003 | | TED0003* | 模拟 TED 转入 | 模拟 TED 转入到 QI 账户 | Item 2:
[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:
[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)

[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)

[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)

[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)

[文档链接](/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 | --- # 审批转账 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": "\", "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 状态码
`status` | QI 代码
`code` | 标题
`title` | 描述（英文）
`description` | 描述（葡文）
`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 状态码
`status` | QI 代码
`code` | 标题
`title` | 描述（英文）
`description` | 描述（葡文）
`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/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 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" } ``` --- # 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 | 划款已核销并转入贴现 | --- # 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 次。