# QI Tech — Outros
Documentação da QI Tech em texto corrido, para colar em um LLM.
Fonte: https://docs.qitech.com.br
210 página(s).
Índice:
- Atualização uso de TAC (/documentation/1bb151c7-735f-4449-bd9a-4780be271da8)
- Troca com Troco SIAPE/EXÉRCITO (/documentation/6fabde14-8ce4-42ac-9f93-28246356e45d)
- Abertura de Conta em Duas Etapas (/documentation/account_request)
- Manual de Aditamento (/documentation/aditamento/manual_aditamento)
- arranjos_e_adquirentes (/documentation/arranjos_e_adquirentes/)
- Criar uma renegociação (/documentation/arranjos_e_adquirentes/consulta_de_agenda)
- trava_de_domicilio_bancario (/documentation/arranjos_e_adquirentes/trava_de_domicilio_bancario)
- emissao_de_divida (/documentation/auxilio_brasil/emissao_de_divida)
- webhook_auxilio_brasil (/documentation/auxilio_brasil/webhook_auxilio_brasil)
- Confirmar Abertura de Conta de Pessoa Física (/documentation/baas/account/2fa_v2/abrir_conta_pf)
- Abertura de Conta de Pessoa Jurídica (/documentation/baas/account/2fa_v2/abrir_conta_pj)
- Solicitar reserva de conta (/documentation/baas/account/account_draft_checking)
- Solicitar reserva de conta (/documentation/baas/account/d4bf7f96-69b0-424b-a9d6-0a1bc79629cd)
- Webhooks de abertura de conta (/documentation/baas/escrow/webhooks)
- Upload de arquivo remessa (CNAB) (/documentation/baas/pagamento_em_lote/envio_de_remessa)
- Introdução a Transação em Lote CNAB240 (/documentation/baas/pagamento_em_lote/introducao)
- Criar recorrência de pagamento (/documentation/baas/pix_automatico/movimentacoes/criar_recorrencia)
- Tabela de Erros para Pix Schedule (/documentation/baas/pix/agendamento/erros_de_agendamento)
- Tabela de Erros para Pix Transfer (/documentation/baas/pix/erros_de_pix)
- Introdução a Transação em Lote Ted (/documentation/baas/ted/batch/introducao_a_transacao_em_lote_ted)
- Tabela de Erros para Ted (/documentation/baas/ted/erros_ted)
- Aprovar o pagamento de um Boleto (/documentation/boletos/2fa/realizar_pagamento_de_um_boleto)
- Solicitar token para pagamento de um Boleto (/documentation/boletos/2fa/solicitar_token_para_pagamento)
- Consulta de carteiras de cobrança (/documentation/boletos/consultar_v1/consulta_de_carteira)
- Consultar arquivo retorno (/documentation/boletos/consultar_v1/consultar_arquivo_retorno)
- Consultar boleto (/documentation/boletos/consultar_v1/consultar_boleto)
- Emitir PDF (/documentation/boletos/consultar_v1/emitir_pdf)
- Francesinha (/documentation/boletos/consultar_v1/francesinha)
- Listar boletos (/documentation/boletos/consultar_v1/listar_boletos)
- Rotina de conciliação de arquivo retorno (/documentation/boletos/consultar_v1/rotina_de_conciliacao_de_arquivo_retorno)
- Aprovar pagamento de boleto (/documentation/boletos/pagamento/aprovar_pagamento)
- Consultar linha digitável de boleto (/documentation/boletos/pagamento/consulta_linha_digitavel)
- Realizar pagamento de boleto (/documentation/boletos/pagamento/realizar_pagamento)
- Redirecionamento da Conta de Liquidação de um Boleto (/documentation/boletos/redirecionamento_de_conta_de_liquidacao)
- Emissão de um bolePix (/documentation/boletos/v1/emissao/emissao_de_um_bolepix)
- Emissão de boleto via CNAB (/documentation/boletos/v1/emissao/emissao_via_cnab)
- Emissão de boleto via JSON (/documentation/boletos/v1/emissao/emissao_via_json)
- Enviar instrução de boleto (/documentation/boletos/v1/enviar_instrucao_de_boleto)
- Introdução (/documentation/boletos/v1/introducao)
- authentication (/documentation/caas/banking/authentication)
- authentication (/documentation/caas/card_issuance/authentication)
- authentication (/documentation/caas/card_order/authentication)
- authentication (/documentation/caas/credit_analysis/authentication)
- Imagens (/documentation/caas/credit_analysis/image)
- Compatibilidade da Biblioteca (/documentation/caas/device_scan/android/compatibility)
- builder (/documentation/caas/face_recognition/android/builder)
- Validação 1:1 - Face Match (/documentation/caas/face_recognition/android/face_match)
- using_sdk (/documentation/caas/face_recognition/android/using_sdk)
- Registration (/documentation/caas/face_recognition/api/registration)
- Validation (/documentation/caas/face_recognition/api/validation)
- necessary_permissions (/documentation/caas/face_recognition/ios/necessary_permissions)
- using_sdk (/documentation/caas/face_recognition/ios/using_sdk)
- authentication (/documentation/caas/limits/authentication)
- builder (/documentation/caas/ocr/android/builder)
- DocumentDetectorStep (/documentation/caas/ocr/android/implementation_demo)
- using_sdk (/documentation/caas/ocr/android/using_sdk)
- authentication (/documentation/caas/ocr/api/authentication)
- quality (/documentation/caas/ocr/api/quality)
- necessary_permissions (/documentation/caas/ocr/ios/necessary_permissions)
- Importando o SDK (/documentation/caas/ocr/ios/using_sdk)
- Transações na QI Conta (/documentation/cards/autorizacao/balance_transaction)
- Manual BaaS - Conta Digital (/documentation/casos_de_uso/manual_baas)
- Manual BaaS - Serviço (/documentation/casos_de_uso/manual_baas_servico)
- Criação de Cessões (/documentation/cessoes/criacao_de_cessao_0eaeffec-ee95-4cb1-a266-bcb52f23237d)
- Abertura de conta escrow PF (/documentation/contas/abertura_de_conta_escrow/abertura_de_conta_escrow_pf)
- Abertura de conta escrow PJ (/documentation/contas/abertura_de_conta_escrow/abertura_de_conta_escrow_pj)
- Introdução (/documentation/contas/abertura_de_conta_escrow/introducao)
- Abertura de conta PF (/documentation/contas/abertura_de_conta/abertura_de_conta_pf)
- Abertura de conta PJ (/documentation/contas/abertura_de_conta/abertura_de_conta_pj)
- Rascunho de Conta Livre Movimentação - Pessoa Jurídica (/documentation/contas/abertura_de_conta/draft_checking_legal_person)
- fluxo_de_abertura_de_conta (/documentation/contas/abertura_de_conta/fluxo_de_abertura_de_conta)
- Introdução (/documentation/contas/abertura_de_conta/introducao)
- Webhooks de abertura de conta (/documentation/contas/abertura_de_conta/webhooks_contas)
- Criar conta destino para escrow (/documentation/d88ff174-100d-4b55-80b7-86e11f508400)
- Recuperação de termo de aceite e cancelamento de cadastro no DDA (/documentation/dda/recuperacao_termo)
- acg1 (/documentation/documentacoes ocultas/agc1/acg1)
- introducao (/documentation/documentacoes ocultas/agc1/introducao)
- Permissão (Geral): (/documentation/documentacoes ocultas/perfis_de_acesso)
- cancelamento_de_solicitacao.md (/documentation/documentacoes ocultas/scr/cancelamento_de_solicitacao.md)
- consultar_solicitacao (/documentation/documentacoes ocultas/scr/consultar_solicitacao)
- consultar_solicitacoes (/documentation/documentacoes ocultas/scr/consultar_solicitacoes)
- introducao (/documentation/documentacoes ocultas/scr/introducao)
- refazer_consulta (/documentation/documentacoes ocultas/scr/refazer_consulta)
- solicitacao_de_consulta (/documentation/documentacoes ocultas/scr/solicitacao_de_consulta)
- webhook (/documentation/documentacoes ocultas/scr/webhook)
- Recalcular contrato de crédito (/documentation/emissao_de_divida/reprocessar_contrato)
- Catálogo de Erros (/documentation/erros/catalogo_de_erros)
- Atualização de dados dos investidores na Operação (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-investidores)
- Consulta de templates disponíveis (/documentation/escrituracao/emissao-de-notas/geracao-minutas/consulta-minutas-disponiveis)
- Roteiro de Integração — API de Escrituração de Notas Comerciais (NC) com Auto-Assinatura (/documentation/escrituracao/roteiro-integracao/integration-guide-nc-auto-signature)
- Roteiro de Integração de escrituração de notas comerciais (/documentation/escrituracao/roteiro-integracao/roteiro-integracao-padrao)
- Roteiro de Integração de escrituração de notas comerciais (/documentation/escrituracao/roteiro-integracao/roteiro-integracao-padrao-external)
- Roteiro de Integração de escrituração de notas comerciais + Boletos + Sistema de baixas (/documentation/escrituracao/roteiro-integracao/roteiro-integracao-securities-baas-dtvm)
- Crédito Consignado INSS (/documentation/guides/INSS/intro)
- Assinatura em lote (INSS) (/documentation/guides/INSS/signatures/batch-signature)
- Consignado Público - Visão Geral (/documentation/guides/publico/visao_geral)
- Assinar Documento (/documentation/iaas/investidor/compartilhado/assinar_documento)
- Atualização Cadastral (/documentation/iaas/investidor/compartilhado/atualizacao_cadastral)
- Atualizar Status do Grupo de Assinantes (/documentation/iaas/investidor/compartilhado/atualizar_status_grupo_assinantes)
- Consulta Informações de uma Análise Cadastral do Investidor (/documentation/iaas/investidor/compartilhado/busca_informacoes_de_uma_analise_cadastral_do_investidor)
- Consulta Informações do Investidor (/documentation/iaas/investidor/compartilhado/busca_informacoes_do_investidor)
- Buscar Lotes de Documentos para Assinatura (/documentation/iaas/investidor/compartilhado/buscar_documentos_para_assinatura)
- Ciclo de vida da análise cadastral (/documentation/iaas/investidor/compartilhado/ciclo_de_vida_da_analise)
- Consultar Análise em Andamento (/documentation/iaas/investidor/compartilhado/consultar_analise_em_andamento)
- Atualizar Status da Conta Bancária (/documentation/iaas/investidor/compartilhado/contas_bancarias/atualizar_status_conta_bancaria)
- Definir Conta Bancária Principal (/documentation/iaas/investidor/compartilhado/contas_bancarias/definir_conta_principal)
- Enviar Conta Bancária do Investidor (/documentation/iaas/investidor/compartilhado/contas_bancarias/enviar_contas_bancarias)
- Criar investidor (/documentation/iaas/investidor/compartilhado/criar_investidor)
- Definir Grupo de Assinantes Padrão (/documentation/iaas/investidor/compartilhado/definir_grupo_assinantes_padrao)
- Enviar Cadastro do Investidor para Análise (/documentation/iaas/investidor/compartilhado/enviar_cadastro_para_analise)
- Enviar Dados Cadastrais do Investidor (/documentation/iaas/investidor/compartilhado/enviar_dados_cadastrais)
- Enviar Documento Assinado (/documentation/iaas/investidor/compartilhado/enviar_documento_assinado)
- Enviar Endereço do Investidor (/documentation/iaas/investidor/compartilhado/enviar_endereco)
- Enviar Grupo de Assinantes (/documentation/iaas/investidor/compartilhado/enviar_grupos_assinantes)
- Enviar Documento do Investidor (/documentation/iaas/investidor/compartilhado/enviar_investor_document)
- Enviar Patrimônio do Investidor (/documentation/iaas/investidor/compartilhado/enviar_patrimonio)
- Consultar Feedback (/documentation/iaas/investidor/compartilhado/feedback/consultar_feedback)
- Enviar Mensagem em Feedback (/documentation/iaas/investidor/compartilhado/feedback/enviar_mensagem_feedback)
- Listar Feedbacks (/documentation/iaas/investidor/compartilhado/feedback/listar_feedbacks)
- Criar Investor Owner (/documentation/iaas/investidor/compartilhado/investor_owner/criar_investor_owner)
- Enviar Documento de Investor Owner (/documentation/iaas/investidor/compartilhado/investor_owner/enviar_documento_investor_owner)
- Atualizar Parte Relacionada (/documentation/iaas/investidor/compartilhado/related_party/atualizar_parte_relacionada)
- Atualizar Status da Parte Relacionada (/documentation/iaas/investidor/compartilhado/related_party/atualizar_status_parte_relacionada)
- Criar Parte Relacionada (/documentation/iaas/investidor/compartilhado/related_party/criar_parte_relacionada)
- Enviar Documento da Parte Relacionada (/documentation/iaas/investidor/compartilhado/related_party/enviar_documento_parte_relacionada)
- Consultar Formulário Suitability (/documentation/iaas/investidor/compartilhado/suitability/consultar_formulario_suitability)
- Enviar Resposta Suitability (/documentation/iaas/investidor/compartilhado/suitability/enviar_suitability)
- Introdução (/documentation/iaas/investidor/inicio)
- Aprovação do Gestor (/documentation/iaas/venda_ativos/assignment/aprovacao_recompra)
- Recuperando Transações de uma Conta (/documentation/iaas/visibildade_de_caixa/get_transaction_reversals)
- Introdução a Documentação (/documentation/introducao_api_reference)
- Bem Vindo à Seção de Manuais das API's da QI Tech (/documentation/introducao_manuais)
- Bem Vindo à Seção de Manuais das API's da QI Tech (/documentation/introducao_operational_guides)
- Manual Consignado da Aeronáutica (/documentation/manual_aeronautica/manual_consignado)
- Homologation Roadmap - BNPL (/documentation/manual_bnpl_ecommerce/manual_bnpl)
- Manual CertifiQI (/documentation/manual_certifiqi/dc37cf4f-adad-45c5-9251-9c957fb9ce8e)
- Cessão (/documentation/manual_cessao/)
- Conciliação (/documentation/manual_conciliacao/)
- Manual Consignado Privado - Contratos Legados (/documentation/manual_consignado_privado/manual_contratos_legados)
- Seguro (/documentation/manual_consignado_privado/manual_seguro)
- Manual Consignado Privado - Tombamento do Legado (/documentation/manual_consignado_privado/manual_tombamento_legado)
- Emissão Crédito Clean (/documentation/manual_credito_clean/emissao/)
- Emissão de Dívida PJ com Assinatura Imediata (/documentation/manual_emissao_pj_signed_debt/emissao_signed_debt_pj)
- Recálculo e Retentativa de Averbação (/documentation/manual_exercito/recalculo)
- Manual Leilão de propostas Meu INSS (/documentation/manual_leilao_meu_inss/)
- Aprovar transferência (/documentation/movimentacao_de_contas/aprovar_transferencia)
- Consulta de transações pendentes (/documentation/movimentacao_de_contas/consulta_de_transacoes_pendentes)
- Consulta de extrato (/documentation/movimentacao_de_contas/consulta_de_transferencias_realizadas)
- Realizar transferência (/documentation/movimentacao_de_contas/realizar_transferencia)
- Objeto Address (/documentation/objetos_compartilhados/address)
- Objeto Borrower (/documentation/objetos_compartilhados/borrower)
- Objeto Disbursement Account (/documentation/objetos_compartilhados/disbursement_account)
- Objeto Financial Institution (/documentation/objetos_compartilhados/financial_institution)
- Manual Operacional de Boletos (/documentation/operational_guide/boletos)
- Pix (/documentation/pix_v2)
- Aprovar transferência (/documentation/pix/2fa/aprovar_solicitacao_de_transferencia)
- Solicitar devolução de um Pix (/documentation/pix/2fa/solicitar_chargeback_pix)
- Solicitar Token de Aprovação da Transferência (/documentation/pix/2fa/solicitar_token_de_aprovacao)
- Solicitar Transferência Pix (/documentation/pix/2fa/solicitar_transferencia)
- Aprovar solicitação de transferência (/documentation/pix/aprovar_solicitacao_de_transferencia)
- Consulta de Dados de Chave Pix no Banco Central (/documentation/pix/baas_v2/consultar_chave_pix)
- Comprovante de transferência agendada (/documentation/pix/comprovante_de_transferencia_agendada)
- Consultar chaves Pix (/documentation/pix/consultar_chave)
- Consultar chaves Pix (/documentation/pix/consultar_chave_v2)
- Pesquisar por transferência Pix de saída (/documentation/pix/pesquisar_por_transferencia_pix_de_saida)
- Solicitar devolução de um Pix (/documentation/pix/solicitar_chargeback_pix)
- solicitar_transferencia (/documentation/pix/solicitar_transferencia)
- Renegociação internal e external (/documentation/renegociacao/criacao_renegociacao_internal)
- Simulação com valor por parcela (/documentation/renegociacao/simulacao_com_valor_por_parcela)
- Update de um pagamento manual (/documentation/renegociacao/update_de_um_pagamento_manual)
- Roteiro de Homologação - Circuito de Compras (/documentation/roteiros_de_homologacao/circuito_dd46f8d3-f078-41ba-a311-55be848f1c69)
- Roteiro de Homologação - BaaS Conta Digital (/documentation/roteiros_de_homologacao/conta_digital)
- Roteiro de Homologação - BaaS Conta Digital com Dupla Autenticação (/documentation/roteiros_de_homologacao/conta_digital_2fa)
- Roteiro de Homologação - BaaS Conta Digital com Dupla Autenticação (/documentation/roteiros_de_homologacao/conta_digital_2fa_baas)
- Roteiro de Homologação - BaaS Conta Digital (/documentation/roteiros_de_homologacao/conta_digital_baas)
- Roteiro de Homologação - BaaS Conta Digital Escrow (/documentation/roteiros_de_homologacao/conta_digital_escrow)
- Roteiro de Homologação - BaaS Conta Digital Escrow (/documentation/roteiros_de_homologacao/conta_digital_escrow_caas)
- Roteiro de Homologação - BaaS Cobrança (/documentation/roteiros_de_homologacao/roteiro_cobranca)
- Roteiro de Homologação - BaaS Conta Digital com Dupla Autenticação (/documentation/roteiros_de_homologacao/roteiro_conta_digital)
- Roteiro de Homologação - BaaS Conta Digital (/documentation/roteiros_de_homologacao/roteiro_conta_digital_d795dc71-05b2-4476-bfbc-07ef247abd90)
- Roteiro de Homologação - Conta Integrada (/documentation/roteiros_de_homologacao/roteiro_conta_integrada)
- Roteiro para construção do Backoffice (/documentation/roteiros_de_homologacao/roteiro_criacao_backoffice_cliente)
- Roteiro de Homologação - BaaS Conta Payments (/documentation/roteiros_de_homologacao/roteiro_payments)
- Roteiro de Homologação - Pix Conta Integrada (/documentation/roteiros_de_homologacao/roteiro_pix_conta_integrada)
- Roteiro de Homologação - Pix indireto (/documentation/roteiros_de_homologacao/roteiro_pix_indireto)
- Roteiro de Homologação - Emissão de dívida PF com desembolso pagando QR Code (/documentation/roteiros_laas/roteiro_00f2a5d3-39c2-4f3d-9234-7d1525daaaf2)
- Roteiro de Homologação - Emissão de dívida PF - Adiantamento de Precatório (/documentation/roteiros_laas/roteiro_5d068423-6094-49e4-b15b-7740038295a8)
- Homologation Roadmap - Credit Pay (/documentation/roteiros_laas/roteiro_cecdd0e2-081a-4590-b571-188c376a7c64)
- APP Integration (/documentation/roteiros_laas/roteiro_e7030e18-a9c7-452b-8236-1cf8edfb4de9)
- Webhooks INSS (/documentation/roteiros_laas/webhooks_inss)
- Consultar saldo disponível (/documentation/saque_aniversario_fgts/consultar_saldo_disponivel)
- Criar operação de crédito (/documentation/saque_aniversario_fgts/criacao_da_operacao)
- Introdução ao Saque Aniversário FGTS (/documentation/saque_aniversario_fgts/introducao)
- roteiro_de_homologacao (/documentation/saque_aniversario_fgts/roteiro_de_homologacao)
- Simulação do valor desejado (/documentation/saque_aniversario_fgts/simulacao_do_valor_desejado)
- Simulação do valor máximo (/documentation/saque_aniversario_fgts/simulacao_do_valor_maximo)
- Webhooks de Consulta de Saldo (/documentation/saque_aniversario_fgts/webhooks_de_consulta_de_saldo)
- Aprovar Transferência (/documentation/ted/2fa/aprovar_transferencia)
- Solicitar Transferência (/documentation/ted/2fa/solicitar_transferencia)
- TED (/documentation/ted/ted_v2)
- consulta_de_agenda_com_opt_in (/documentation/trava_de_domicilio_bancario/consulta_de_agenda_com_opt_in)
- consulta_de_agenda_sem_opt_in (/documentation/trava_de_domicilio_bancario/consulta_de_agenda_sem_opt_in)
- emissao_de_divida_com_trava_de_agenda (/documentation/trava_de_domicilio_bancario/emissao_de_divida_com_trava_de_agenda)
- introducao (/documentation/trava_de_domicilio_bancario/introducao)
- Criar lote de tombamento de boletos (/documentation/troca_de_titularidade/criar_lote_batch)
- Webhooks de Tombamento de Boletos (/documentation/troca_de_titularidade/notificacoes_webhooks)
- acg1 (/documentation/webhooks/acg1)
- agenda_de_recebiveis (/documentation/webhooks/agenda_de_recebiveis)
- Webhooks de boletos (/documentation/webhooks/boletos)
- notificacoes_baas_e_laas (/documentation/webhooks/notificacoes_baas_e_laas)
---
# Atualização uso de TAC
URL: /documentation/1bb151c7-735f-4449-bd9a-4780be271da8
## Consulta de elegibilidade de CPF
Em posse dos dados de **CPF**, é possível a consulta da elegibilidade do CPF.
### Request
ENDPOINT /debts/borrower/[document_number]/tac_eligibility
MÉTODO GET
### Path Params
| Campo | Descrição | Caracteres |
|---------------|----------------------------------------|------------|
| `document_number` | Número de CPF do devedor | 11 |
### Response
STATUS 200
Response Body
```json
{
"eligible": true
}
```
### Descrição
| Campo | Tipo |
|------------------------------|--------|
| `elegible` | boleean |
:::caution Atenção
Para um CPF com o retorno **"eligible": false**, tanto a simulação, quanto a emissão da dívida não serão possíveis com o envio de TAC na lista **rebates**.
:::
## Erro de elegibilidade durante a simulação e emissão de dívida
Ao enviar um valor de TAC tanto na simulação quanto na emissão de uma operação, para um CPF não elegível à cobrança de TAC, será retornado um erro síncrono.
STATUS 400
Response Body
```json
{
"title": "Bad Request",
"description": "Operation not eligible for tac fee charge. Please do not use this fee type for this borrower.",
"translation": "Operação não elegível para cobrança de taxa do tipo tac. Por favor, não use esse tipo de fee para esse tomador de crédito.",
"code": "COP000355"
}
```
## Cancelamento de operações inelegíveis
Em caso de operações simultâneas enviadas com TAC para o mesmo tomador, a primeira a desembolsar forçará o cancelamento das restantes. Dessa forma, será enviado um webhook de cancelamento com o payload abaixo.
Response Body
```json
{
"webhook_type": "debt",
"key": "27a099df-4688-43cb-87fa-515b1cf343a5",
"event_datetime": "2022-09-27 07:03:49",
"data": {
"cancel_reason": "Taxa da operação do tipo tac não permitida.",
"cancel_reason_enumerator": "tac_not_allowed"
},
"status": "canceled"
}
```
---
# Troca com Troco SIAPE/EXÉRCITO
URL: /documentation/6fabde14-8ce4-42ac-9f93-28246356e45d
## Consulta da lista de contratos
:::caution Atenção
Essa funcionalidade é **exclusiva** para integrações com a API de exército.
:::
Em posse dos dados de **CPF**, **Matrícula do militar** e a **Token**, o parceiro integrador pode realizar a consulta da lista de contratos do militar disponíveis para compra através do seguinte endpoint:
### Request
ENDPOINT /military_payroll/portability_contracts_report
MÉTODO POST
Request Body
```json
{
"document_number": "45507529710",
"registration_code": "146254221",
"token": "abc1234"
}
```
:::info
O CPF deve ser informado em formato de texto, com no máximo 11 caracteres, sem ".", sem "-" e alinhado com zeros à esquerda.
:::
#### Request Body Params
| Campo | Tipo | Descrição |
|------------------------------|--------|-------------------------------------------|
| `document_number` | string | CPF do militar. |
| `registration_code` | string | Matrícula do militar. |
| `token` | string | Senha do militar. |
### Response
ENDPOINT /military_payroll/portability_contracts_report
MÉTODO POST
STATUS 201
Response Body
```json
{
"portability_contracts_report_key": "3e41a8afb-e1b2-4215-8093-c4b5feab529c" ,
"status": "pending_search"
}
```
Os dados da consulta de margem serão retornados via webhook.
#### Response Body Params
| Campo | Tipo | Descrição |
|------------------------------------|--------|------------------------------------------------------------------------------------------------------------------------|
| `portability_contracts_report_key` | string | Chave de identificação da consulta da lista de contratos. |
| `status` | enum | [Enumeradores de status de consulta da lista de contratos.](#enumeradores-de-status-da-consulta-da-lista-de-contratos) |
#### Enumeradores de Status da Consulta da Lista de Contratos
| Enumerador | Descrição |
|--------------------|-----------------------------------------------------------------------------|
| `pending_search` | Consulta da lista de contratos pendente de resposta do sistema do exército. |
| `failed` | Falha na consulta da lista de contratos. |
| `succeeded` | Sucesso na consulta da lista de contratos. |
### Consulta com sucesso
O webhook de sucesso será retornado da seguinte forma:
WEBHOOK_TYPE military_payroll.portability_contracts_report
STATUS succeeded
Body
```json
{
"webhook_type": "military_payroll.portability_contracts_report.status_change",
"key": "3e41a8afb-e1b2-4215-8093-c4b5feab529c",
"event_datetime": "2023-05-28T08:43:29Z",
"status": "succeeded",
"data": {
"document_number": "45507529710",
"contracts" : [
{
"econsig_id": "2361529",
"installment_amount": 10.0,
"number_of_installments": 5,
"number_of_paid_installments": 1,
"consignatory": "BANCO XPTO",
"contract_date": "2022-01-03T15:01:57Z",
"contract_status": "accepted"
}
]
}
}
```
### Consulta com falha
O webhook de falha será retornado da seguinte forma:
WEBHOOK_TYPE military_payroll.portability_contracts_report
STATUS failed
Body
```json
{
"webhook_type": "military_payroll.portability_contracts_report.status_change",
"key": "3e41a8afb-e1b2-4215-8093-c4b5feab529c",
"event_datetime": "2023-05-28T08:43:29Z",
"status": "failed",
"data": {
"enumerator": "military_not_found"
}
}
```
Cada `enumerator` tem uma descrição mais detalhada e, para facilitar a consulta, a tabela abaixo relaciona ambas as coisas para cada caso.
#### Enumeradores failure_reason
| Enumerador | Descrição | Código Zetra |
|---------------------------|---------------------------------------------------------------|--------------|
| contracts_not_found | Nenhum contrato encontrado para os dados informados | 294 |
| invalid_registration_code | Matrícula informada não é válida | 210 |
| military_blocked | Consulta não pode ser concluída pois o militar está bloqueado | 352 |
| military_not_found | Nenhum servidor encontrado para os dados informados | 293 |
## Simulação da Operação de Crédito Pessoal
Primeiramente é preciso calcular o valor da operação de Crédtio Pessoal necessária para quitar a operação de crédito original.
O valor do saldo devedor da dívida original deve ser informado no campo _**disbursed_amount**_.
:::caution Aviso
A operação deve ser simulada com apenas 1 parcela, desembolso em **D0** e a parcela deve ter seu vencimento para **D+5 dias úteis**, contas a partir da data de desembolso (pagamento) da operação.
:::
### Request
ENDPOINT /debt_simulation
MÉTODO POST
```json title='Request Body'
{
"borrower": {
"person_type": "natural"
},
"financial": {
"disbursed_amount": 80492.95,
"monthly_interest_rate": 0.03,
"credit_operation_type": "ccb",
"disbursement_date": "2023-03-17",
"issue_date": "2023-03-17",
"fine_configuration": {
"contract_fine_rate": 0,
"interest_base": "workdays",
"monthly_rate": 0
},
"interest_grace_period": 0,
"interest_type": "pre_price_days",
"number_of_installments": 1,
"principal_grace_period": 0,
"first_due_date_delay": 5
}
}
```
---
## Simulação da Operação de Crédito Consignado do SIAPE/ EXÉRCITO
A simulação da Operação de Crédito Consignado do SIAPE, deverá simular a quitação do contrato original e o calculo do valor do troco liberado para o cliente em função da margem disponível e taxa do contrato.
Nesta simulação os campos informados terão seus valores atribuidos da seguinte forma:
_**installment_face_value**_ = Valor da margem consignável
_**disbursement_date**_ = **D+5 dias úteis** do momento da simulação
_**due_balance**_ = **total_amount** da 1ª parcela retornada na simulação da Operação de Crédito Pessoal
_**original_deadline**_ = Prazo total em dias da Operação de Crédito Pessoal (5 dias)
:::info IOF
O valor de IOF da Operação de Crédito Consignado do SIAPE, uma vez que ela refinancie a Operação de Crédito Pessoal, corresponderá apenas ao valor do troco liberado ao cliente (dinheiro novo).
:::
### Request
ENDPOINT /debt_simulation
MÉTODO POST
```json title='Request Body'
{
"borrower": {
"person_type": "natural"
},
"financial": {
"first_due_date": "2023-06-10",
"installment_face_value": 100.0,
"disbursement_date": "2023-03-22",
"number_of_installments": 96,
"monthly_interest_rate": 0.0205,
"interest_type": "pre_price_days",
"fine_configuration": {
"monthly_rate": 0.01,
"interest_base": "calendar_days",
"contract_fine_rate": 0.02
},
"credit_operation_type": "ccb",
"interest_grace_period": 0,
"principal_grace_period": 0
},
"collaterals": [{
"collateral_type": "federal_payroll/military_payroll"
}],
"refinanced_credit_operations": [
{
"due_balance": 1250.20,
"original_deadline": 120
}
]
}
```
O campo _**data.final_disbursement_amount**_ retornado na simulação será o valor do troco pago ao cliente.
---
### Consulta do valor de parcela da operação de Crédito Pessoal
#### Request
ENDPOINT /debt?key=[DEBT-KEY]&eval_present_value=True&calculate_delay=True&calculate_spread=False
MÉTODO GET
:::info Informação
A DEBT-KEY é a chave retornada na resposta da criação da operação (resposta do /debt)
:::
---
## Criação da conta de titularidade do devedor
Antes da digitação das propostas é necessário abrir uma conta para o devedor na QI Tech.
A conta será utilizada para receber o desembolso da Operação de Crédito Pessoal, realizar os pagamentos do saldo devedor da dívida original em outro banco (via Boleto, TED ou Pix).
### Request
ENDPOINT /account
MÉTODO POST
```json title='Request Body'
{
"is_operation_account": true,
"account_owner": {
"address": {
"city": "São Paulo",
"complement": "s/c",
"neighborhood": "Pinheiros",
"number": "215",
"postal_code": "12345012",
"state": "SP",
"street": "Gilberto Sabino"
},
"birth_date": "1961-01-30",
"document_identification": "261a8fbc-d998-4dd7-8515-ddebb212ae27",
"is_pep": false,
"mother_name": "Nome da Mãe do Devedor",
"nationality": "brasileiro",
"email": "email@email.com",
"individual_document_number": "12345678911",
"name": "Nome do Devedor",
"phone": {
"area_code": "11",
"country_code": "055",
"number": "900000000"
},
"person_type": "natural"
}
}
```
| Parâmetro | Descrição |
|--------------------------------------------------------------|----------------------------------------------------|
| **account_owner** | Dados do devedor |
| **is_operation_account** | Indicativo de que a conta é uma conta de operação. |
### Response
ENDPOINT /account
MÉTODO POST
```json title='Response Body'
{
"data": {
"account_info": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "1234567",
"financial_institution_code": "329"
},
"account_owner": {
"document_number": "12345678911",
"name": "Nome do Devedor"
}
},
"event_datetime": "2023-03-21 12:30:24",
"key": "8ff1e73f-e87b-4641-99a6-3267030c6034",
"status": "account_pending_operation",
"webhook_type": "account"
}
```
:::info
Os dados de conta retornados no /account deverão ser utilizados como conta de desembolso da Operação de Crédito Pessoal
:::
### Erro 5xx ou Timeout
O fluxo não deve prosseguir enquanto a conta não estiver abertua com sucesso.
Para os casos de falha, deve ser checado se a conta de fato não foi aberta para o cliente, antes de uma possível retentativa de abertura.
É possível checar se a conta foi aberta para o cliente, listando as conta abertas para um determinado CPF.
#### Request
ENDPOINT /account
MÉTODO POST
PARAMETER owner_document_number, requester_key
| Parâmetro | Descrição |
|---------------------------|------------------------------------|
| **owner_document_number** | CPF do devedor |
| **requester_key** | É uma chave interna da integração. |
#### Response
STATUS 200
```json title='Response Body'
{
"data": [{
...
"account_branch": "0001",
...
"account_digit": "2",
...
"account_key": "f600a6a9-0845-454f-b25c-a6d108ea582e",
"account_name": "Default",
"account_number": "1467576",
"account_status": {
"created_at": "2019-10-11T18:58:31",
"enumerator": "opened",
"translation_path": "account.AccountStatus.opened"
},
...
"owner_document_number": "09080702000105",
"owner_name": "Nome do Devedor",
...
}],
"pagination": {
"current_page": 1,
"next_page": null,
"rows_per_page": 100,
"total_pages": 1,
"total_rows": 1
}
}
```
:::info Informação
No payload de resposta acima, estão listados apenas os campos relevantes para leitura.
:::
---
## Emissão das Operações
A criação das operações de Crédito Pessoal e Crédito Consignado do SIAPE, **deverão ser realizadas no mesmo momento**, tendo cada uma as seguintes configurações
- **Operação de Crédito Pessoal**: Deve ser emitida com desembolso em D0 e com apenas uma parcela com vencimento para **D+5 dias úteis** do desembolso.
- **Operação de Crédito Consignado do SIAPE**: Deve ser emitida com desembolso em **D+0**, mas com opções de desembolso para até **D+15 dias corridos** e com o número de parcelas pretendidas.
:::danger Atenção
Para emissão da Operação de Crédito Pessoal o objeto "_**financial**_", deve ser enviado com exatamente as mesmas informações enviadas na sua simulação.
Para emissão da Operação de Crédito Consignado do SIAPE, o obejeto "_**financial**_" terá as seguintes diferenças:
- O campo _**disbursement_date**_ deve ser substituído pelos campos _**disbursement_start_date**_ e _**disbursement_end_date**_, onde a diferença entre um e outro deve ser de **15 dias corridos**.
- O campo _**refinanced_credit_operations[0].operation_key**_ deve conter a **DEBT-KEY**, retornada no retorno da criação da Operação de Crédito Pessoal.
:::
:::info Informação
A Operação de Crédito Pessoal, só pode desembolsar em **dias úteis** e nos seguintes horários, à depender do meio de pagamento do saldo devedor da dívida original:
- **TED**: desembolso entre **6:30 e 17:15**
- **Boleto**: desembolso entre **7:00 e 22:00**
- **Pix**: qualquer horário (mas é recomendado o desembolso em horário comercial, pois caso uma operação seja desembolsada de madrugada, por exemplo, a entrada do Pix pode ser rejeitada por suspeitas de fraude)
:::
### Emissão da Operação de Crédito Pessoal
Para emitir a Operação de Crédito Pessoal, é necessário enviar a informação dos Boletos/TEDs/Pix que precisam ser pagos após o desembolso da operação.
:::caution Atenção
O parceiro deve gerar uma chave interna de identificação da operação e enviá-la na requisição de emissão de dívida no campo "_**requester_identifier_key**_"
:::
#### Exemplos Resquests
ENDPOINT /debt
MÉTODO POST
**Boleto**
```json title='Request Body'
{
"borrower": {
"name": "Nome do Devedor",
"email": "email@email.com",
"phone": {
"number": "900000000",
"area_code": "11",
"country_code": "055"
},
"address": {
"city": "São Paulo",
"state": "SP",
"number": "215",
"street": "Gilberto Sabino",
"complement": "s/c",
"postal_code": "12345012",
"neighborhood": "Pinheiros"
},
"role_type": "issuer",
"birth_date": "1969-05-01",
"mother_name": "Nome da Mãe do Devedor",
"person_type": "natural",
"individual_document_number": "12345678911",
"gender": "male",
"nationality": "brasileiro",
"is_pep": false,
"marital_status": "married"
},
"financial": {
"disbursed_amount": 80492.95,
"annual_interest_rate": 0.20983,
"credit_operation_type": "ccb",
"disbursement_date": "2023-03-17",
"issue_date": "2023-03-17",
"fine_configuration": {
"contract_fine_rate": 0,
"interest_base": "workdays",
"monthly_rate": 0
},
"interest_grace_period": 0,
"interest_type": "pre_price_days",
"number_of_installments": 1,
"principal_grace_period": 0,
"first_due_date_delay": 5
},
"simplified": true,
"additional_data": {
"debt_payment": [{
"bank_slip": [{
"digitable_line": "10495419967200010004900031456924592920008049295",
"amount": "80492,95",
"beneficiary": "CAIXA ECONÔMICA FEDERAL",
"due_date": "2023-03-17"
}],
"funds_transfer": [],
"pix": [],
"financial_institution_code_number": "623"
}],
"issuer_account": {
"account_digit": "0",
"account_branch": "1234",
"account_number": "123456",
"financial_institution_code_number": "104"
},
"total_af_amount": 86186.52
},
"requester_identifier_key": "7ac52492-61c0-4dd6-a414-b0bf940fb7ca",
"disbursement_bank_account": {
"bank_code": "329",
"account_digit": "3",
"branch_number": "0001",
"account_number": "1234567"
},
"after_disbursement_actions": [{
"action_data": {
"digitable_line": "10495419967200010004900031456924592920008049295"
},
"action_type": "bankslip_payment"
}],
"modality": {
"code": "0203"
}
}
```
**TED**
```json title='Request Body'
{
"borrower": {
"name": "Nome do Devedor",
"email": "email@email.com",
"phone": {
"number": "900000000",
"area_code": "11",
"country_code": "055"
},
"address": {
"city": "São Paulo",
"state": "SP",
"number": "215",
"street": "Gilberto Sabino",
"complement": "s/c",
"postal_code": "12345012",
"neighborhood": "Pinheiros"
},
"role_type": "issuer",
"birth_date": "1969-05-01",
"mother_name": "Nome da Mãe do Devedor",
"person_type": "natural",
"individual_document_number": "12345678911",
"gender": "male",
"nationality": "brasileiro",
"is_pep": false,
"marital_status": "married"
},
"financial": {
"disbursed_amount": 80492.95,
"annual_interest_rate": 0.20983,
"credit_operation_type": "ccb",
"disbursement_date": "2023-03-17",
"issue_date": "2023-03-17",
"fine_configuration": {
"contract_fine_rate": 0,
"interest_base": "workdays",
"monthly_rate": 0
},
"interest_grace_period": 0,
"interest_type": "pre_price_days",
"number_of_installments": 1,
"principal_grace_period": 0,
"first_due_date_delay": 5
},
"simplified": true,
"additional_data": {
"debt_payment": [{
"bank_slip": [],
"funds_transfer": [{
"amount": "4736,07",
"account_digit": "0",
"account_branch": "0897",
"account_number": "20001",
"financial_institution_code_number": "341"
}],
"pix": [],
"financial_institution_code_number": "341"
}],
"issuer_account": {
"account_digit": "0",
"account_branch": "0491",
"account_number": "100021100",
"financial_institution_code_number": "104"
},
"total_af_amount": 86186.52
},
"requester_identifier_key": "7ac52492-61c0-4dd6-a414-b0bf940fb7ca",
"disbursement_bank_account": {
"bank_code": "329",
"account_digit": "3",
"branch_number": "0001",
"account_number": "1234567"
},
"after_disbursement_actions": [{
"action_data": {
"destination": {
"name": "Nome Credor Original",
"account_digit": "0",
"account_branch": "0897",
"account_number": "20001",
"document_number": "87163234000138",
"financial_institution_code_number": "341"
},
"transaction_amount": 4736.07
},
"action_type": "funds_transfer"
}],
"modality": {
"code": "0203"
}
}
```
**Chave Pix**
```json title='Request Body'
{
"borrower": {
"name": "Nome do Devedor",
"email": "email@email.com",
"phone": {
"number": "900000000",
"area_code": "11",
"country_code": "055"
},
"address": {
"city": "São Paulo",
"state": "SP",
"number": "215",
"street": "Gilberto Sabino",
"complement": "s/c",
"postal_code": "12345012",
"neighborhood": "Pinheiros"
},
"role_type": "issuer",
"birth_date": "1969-05-01",
"mother_name": "Nome da Mãe do Devedor",
"person_type": "natural",
"individual_document_number": "12345678911",
"gender": "male",
"nationality": "brasileiro",
"is_pep": false,
"marital_status": "married"
},
"financial": {
"disbursed_amount": 80492.95,
"annual_interest_rate": 0.20983,
"credit_operation_type": "ccb",
"disbursement_date": "2023-03-17",
"issue_date": "2023-03-17",
"fine_configuration": {
"contract_fine_rate": 0,
"interest_base": "workdays",
"monthly_rate": 0
},
"interest_grace_period": 0,
"interest_type": "pre_price_days",
"number_of_installments": 1,
"principal_grace_period": 0,
"first_due_date_delay": 5
},
"simplified": true,
"additional_data": {
"debt_payment": [{
"bank_slip": [],
"funds_transfer": [],
"pix": [{
"amount": "4736,07",
"account_digit": "0",
"account_branch": "0897",
"account_number": "20001",
"financial_institution_code_number": "341",
"ispb": "60701190"
}],
"financial_institution_code_number": "341"
}],
"issuer_account": {
"account_digit": "0",
"account_branch": "0491",
"account_number": "100021100",
"financial_institution_code_number": "104"
},
"total_af_amount": 86186.52
},
"requester_identifier_key": "7ac52492-61c0-4dd6-a414-b0bf940fb7ca",
"disbursement_bank_account": {
"bank_code": "329",
"account_digit": "3",
"branch_number": "0001",
"account_number": "1234567"
},
"after_disbursement_actions": [{
"action_data": {
"pix_transfer_type": "key",
"pix_key": "cahvepix@credororiginal.com.br",
"transaction_amount": 4736.07
},
"action_type": "pix"
}],
"modality": {
"code": "0203"
}
}
```
**Pix Manual**
```json title='Request Body'
{
"borrower": {
"name": "Nome do Devedor",
"email": "email@email.com",
"phone": {
"number": "900000000",
"area_code": "11",
"country_code": "055"
},
"address": {
"city": "São Paulo",
"state": "SP",
"number": "215",
"street": "Gilberto Sabino",
"complement": "s/c",
"postal_code": "12345012",
"neighborhood": "Pinheiros"
},
"role_type": "issuer",
"birth_date": "1969-05-01",
"mother_name": "Nome da Mãe do Devedor",
"person_type": "natural",
"individual_document_number": "12345678911",
"gender": "male",
"nationality": "brasileiro",
"is_pep": false,
"marital_status": "married"
},
"financial": {
"disbursed_amount": 80492.95,
"annual_interest_rate": 0.20983,
"credit_operation_type": "ccb",
"disbursement_date": "2023-03-17",
"issue_date": "2023-03-17",
"fine_configuration": {
"contract_fine_rate": 0,
"interest_base": "workdays",
"monthly_rate": 0
},
"interest_grace_period": 0,
"interest_type": "pre_price_days",
"number_of_installments": 1,
"principal_grace_period": 0,
"first_due_date_delay": 5
},
"simplified": true,
"additional_data": {
"debt_payment": [{
"bank_slip": [],
"funds_transfer": [],
"pix": [{
"amount": "4736,07",
"account_digit": "0",
"account_branch": "0897",
"account_number": "20001",
"financial_institution_code_number": "341",
"ispb": "60701190"
}],
"financial_institution_code_number": "341"
}],
"issuer_account": {
"account_digit": "0",
"account_branch": "0491",
"account_number": "100021100",
"financial_institution_code_number": "104"
},
"total_af_amount": 86186.52
},
"requester_identifier_key": "7ac52492-61c0-4dd6-a414-b0bf940fb7ca",
"disbursement_bank_account": {
"bank_code": "329",
"account_digit": "3",
"branch_number": "0001",
"account_number": "1234567"
},
"after_disbursement_actions": [{
"action_data": {
"pix_transfer_type": "manual",
"target_account": {
"name": "Nome Credor Original",
"account_digit": "0",
"account_branch": "0897",
"account_number": "20001",
"document_number": "87163234000138",
"financial_institution_code_number": "341"
},
"transaction_amount": 4736.07
},
"action_type": "pix"
}],
"modality": {
"code": "0203"
}
}
```
**QrCode Pix**
```json title='Request Body'
{
"borrower": {
"name": "Nome do Devedor",
"email": "email@email.com",
"phone": {
"number": "900000000",
"area_code": "11",
"country_code": "055"
},
"address": {
"city": "São Paulo",
"state": "SP",
"number": "215",
"street": "Gilberto Sabino",
"complement": "s/c",
"postal_code": "12345012",
"neighborhood": "Pinheiros"
},
"role_type": "issuer",
"birth_date": "1969-05-01",
"mother_name": "Nome da Mãe do Devedor",
"person_type": "natural",
"individual_document_number": "12345678911",
"gender": "male",
"nationality": "brasileiro",
"is_pep": false,
"marital_status": "married"
},
"financial": {
"disbursed_amount": 80492.95,
"annual_interest_rate": 0.20983,
"credit_operation_type": "ccb",
"disbursement_date": "2023-03-17",
"issue_date": "2023-03-17",
"fine_configuration": {
"contract_fine_rate": 0,
"interest_base": "workdays",
"monthly_rate": 0
},
"interest_grace_period": 0,
"interest_type": "pre_price_days",
"number_of_installments": 1,
"principal_grace_period": 0,
"first_due_date_delay": 5
},
"simplified": true,
"additional_data": {
"debt_payment": [{
"bank_slip": [],
"funds_transfer": [],
"pix": [{
"amount": "4736,07",
"account_digit": "0",
"account_branch": "0897",
"account_number": "20001",
"financial_institution_code_number": "341",
"ispb": "60701190"
}],
"financial_institution_code_number": "341"
}],
"issuer_account": {
"account_digit": "0",
"account_branch": "0491",
"account_number": "100021100",
"financial_institution_code_number": "104"
},
"total_af_amount": 86186.52
},
"requester_identifier_key": "7ac52492-61c0-4dd6-a414-b0bf940fb7ca",
"disbursement_bank_account": {
"bank_code": "329",
"account_digit": "3",
"branch_number": "0001",
"account_number": "1234567"
},
"after_disbursement_actions": [{
"action_data": {
"pix_transfer_type": "qr_code",
"qr_code": "00020126870014br.gov.bcb.pix2565qrcode.qitech.app/bacen/cobv/4ec760c4-b950-4afd-af10-92c1bb7804015204000053039865802BR5925SECURITIZADORA DE CREDITO6009SAO PAULO61080540700362070503***63042FA4"
},
"action_type": "pix"
}],
"modality": {
"code": "0203"
}
}
```
#### Enumeradores Marital Status
| Enumerador | Descrição |
|--------------|---------------|
| **single** | Solteiro(a) |
| **married** | Casado(a) |
| **widower** | Viúvo(a) |
| **divorced** | Divorciado(a) |
#### Erro 5xx ou Timeout
Caso seja retornado algum 5xx ou Timeout na requisição, afim de certificar que a operação de fato não foi criada na QI, é recomendado que o parceiro realize uma consulta da operação que teve retorno 5xx ou timeout.
ENDPOINT /debt?requester_identifier_key=34427233-925d-416d-93eb-c7f5084e8359
MÉTODO GET
Caso o retorno do GET seja um 200, o parceiro não deve retentar a criação da operação e seguir o fluxo da operação.
Caso seja retornado um 404 - Not Found, o parceiro deve retentar a criação da operação.
STATUS 200
```json title='Response Body'
{
"data": {
"additional_iof": 307.166388,
"annual_cet": "60,4731%",
"assignment_amount": 80833.26,
"base_iof": 33.141637696905995,
"borrower": {
"document_number": "12345678911",
"name": "Nome do Devedor"
},
"cet": "4,0200%",
"collaterals": [],
"contract": {
"external_contract_key": "351eada5-a626-404c-a3a3-f91c123270ce",
"number": "0000000001/NDD",
"signature_information": [{
"signature_url": "https://sign.qitech.com.br/s/hNrwjda",
"signer_document_number": "12345678911",
"signer_email": "email@email.com",
"signer_external_key": "56d105f3-a7f6-4442-95e9-71f44d2ae5fc",
"signer_name": "Nome do Devedor",
"signer_role": "issuer"
}],
"urls": [
"https://storage.googleapis.com/live-doc-api/documents/45e5b9c0-0f56-40a8-aace-d206f72c164d/QISCD-NOME_DO_DEVEDOR-CCB-0001212121-20230317194512.pdf"
]
},
"contract_fee_amount": 0,
"contract_fees": [],
"external_contract_fee_amount": 0,
"external_contract_fees": [],
"installments": [{
"accrual_reference_date": null,
"additional_costs": [],
"advanced_paid_amount": 0,
"bank_slip_key": null,
"business_due_date": "2023-03-22",
"calendar_days": 5,
"digitable_line": null,
"due_date": "2023-03-22",
"due_interest": 0,
"due_principal": 80833.26,
"fine_amount": null,
"has_interest": true,
"installment_history": [],
"installment_key": "75460851-2e82-4e3d-a805-b3e55b6b31d4",
"installment_number": 1,
"installment_payment": [],
"installment_status": "created",
"installment_type": "principal",
"original_due_principal": 80833.26,
"original_pre_fixed_amount": 183.5073246195304,
"original_principal_amortization_amount": 80833.26267538047,
"original_total_amount": 81016.77,
"paid_amount": 0,
"paid_at": null,
"post_fixed_amount": 0,
"pre_fixed_amount": 183.5073246195304,
"principal_amortization_amount": 80833.26267538047,
"qr_code_key": null,
"qr_code_url": null,
"renegotiation_proposal_key": null,
"tax_amount": 33.141637696905995,
"total_accrual_amount": null,
"total_amount": 81016.77,
"total_paid_amount": 0,
"workdays": 3
}],
"iof_charge_method": "financed",
"issue_amount": 80833.26,
"net_external_contract_fee_amount": 0,
"number_of_installments": 1,
"prefixed_interest_rate": {
"annual_rate": 0.20983,
"created_at": "2023-03-17T19:45:11",
"daily_rate": 0.00075616,
"interest_base": "workdays",
"monthly_rate": 0.01599997
},
"requester_identifier_key": "34427233-925d-416d-93eb-c7f5084e8359",
"total_iof": 340.31,
"total_pre_fixed_amount": 183.5073246195304
},
"event_datetime": "2023-03-17 19:45:19",
"key": "052fe83c-37f6-4339-a831-127b50566745",
"status": "waiting_signature",
"webhook_type": "debt"
}
```
:::info Informação
O campo "key" da resposta de criação da operação é a **DEBT-KEY**, que é a chave única da operação dentro da QI.
:::
#### Assinatura
**Mesmo procedimento de assinatura ativo para a operação de SIAPE ML**
#### Autorizar desembolso
Após assinatura da operação, é necessário autorizar a operação para desembolso.
:::danger Atenção
A autorização de desembolso da Operação de Crédito Pessoal, deve ser enviada após o recebimento do webhook de confirmação da digitação da proposta no SIAPE.
:::
ENDPOINT /debt/ [DEBT-KEY] /allow_disbursement
MÉTODO POST
```json title='Request Body'
{
"allow_disbursement": true
}
```
#### Desembolso
Após ser assinada e autorizada para desembolso, a operação seguirá automaticamente para esteira de desembolso.
Após o desembolso ser processado o parceiro receberá o seguinte webhook:
#### Sucesso no desembolso
WEBHOOK_TYPE debt
STATUS Disbursed
```json title='Webhook Body'
{
"key": "052fe83c-37f6-4339-a831-127b50566745",
"data": {
"installments": [{
"due_date": "2023-03-22",
"total_amount": 81016.77,
"installment_key": "75460851-2e82-4e3d-a805-b3e55b6b31d4",
"pre_fixed_amount": 183.5073246195304,
"principal_amortization_amount": 80833.26267538047
}],
"ted_receipt_list": []
},
"status": "disbursed",
"webhook_type": "debt",
"event_datetime": "2023-03-17 13:20:40"
}
```
#### Ações pós-desembolso
Após o desembolso da Operação de Crédito Pessoal na conta do devedor criada na QI, serão executados os pagamentos de boleto/TED/Pix referente à quitação do saldo devedor da dívida original do devedor (ações pós-desembolso)
#### Sucesso
WEBHOOK_TYPE after_disbursement_action_update
STATUS Success
**Boleto**
```json title='Webhook Body'
{
"key": "3bce3113-3644-4491-b87a-fe6551edff70",
"data": {
"status": "done",
"action_key": "d25097e2-09f1-47fc-8b7f-d1988b1a7669",
"error_data": null,
"action_data": {
"digitable_line": "10495419967200010004900031456924592920008049295"
},
"action_type": "bankslip_payment",
"execution_data": {
"bank_slip": {
"payer": {
"name": "Nome do Devedor",
"document_number": "12345678911",
"document_number_formatted": "123.456.789-11"
},
"beneficiary": {
"name": "CAIXA ECONÔMICA FEDERAL",
"document_number": "00360305000104",
"document_number_formatted": "00.360.305/0001-04"
},
"payment_key": "500a496e-4cca-4b12-9dc8-254932ebbcac",
"payment_date": "2023-03-08",
"digitable_line": "10495419967200010004900031456924592920008049295",
"expiration_date": "2023-03-10",
"payment_date_formatted": "08/03/2023",
"expiration_date_formatted": "10/03/2023",
"financial_institution_name": "CAIXA ECONÔMICA FEDERAL",
"financial_institution_compe_number": "104"
},
"origin_key": "dfac205a-bdef-4820-8608-2dc81d9e10d4",
"transacted_at": "2023-03-08 16:07:58",
"source_account": {
"owner_name": "Nome do Devedor",
"account_digit": "3",
"account_branch": "0001",
"account_number": "1234567",
"owner_document_number": "12345678911",
"financial_institution_name": "QI SCD S.A.",
"owner_document_number_formatted": "123.456.789-11",
"financial_institution_compe_number": 329
},
"source_subtype": "bank_slip_payment",
"transaction_key": "86a4320d-a69d-4c14-8300-9a6f22d35fcb",
"transacted_at_br": "2023-03-08 13:07:58",
"pdf_encoded_string": "\",
"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"
}
```
#### Erro na ação pós-desembolso
Em caso de erro no pagamento da ação pós-desembolso, o parceiro será notificado através do seguinte webhook:
WEBHOOK_TYPE after_disbursement_action_update
STATUS Error
**Boleto**
```json title='Webhook Body'
{
"key": "e358e7e3-17b8-4aab-9da1-92f6b78dea00",
"data": {
"status": "error",
"action_key": "e2495e5a-df32-4826-b6f0-419014d3c35a",
"error_data": {
"error_code": "QIT000007",
"description": "Account blocked balance cannot be negative."
},
"action_data": {
"digitable_line": "10495419967200010004900031456924592920008049295"
},
"action_type": "bankslip_payment",
"execution_data": null
},
"webhook_type": "after_disbursement_action_update",
"event_datetime": "2023-03-22 12:06:38"
}
```
**TED**
```json title='Webhook Body'
{
"key": "e358e7e3-17b8-4aab-9da1-92f6b78dea00",
"data": {
"status": "error",
"action_key": "e2495e5a-df32-4826-b6f0-419014d3c35a",
"error_data": {
"error_code": "QIT000007",
"description": "Account blocked balance cannot be negative."
},
"action_data": {
"destination": {
"name": "Nome Credor Original",
"account_digit": "0",
"account_branch": "0897",
"account_number": "20001",
"document_number": "87163234000138",
"financial_institution_code_number": "341"
},
"transaction_amount": 1000
},
"action_type": "funds_transfer",
"execution_data": null
},
"webhook_type": "after_disbursement_action_update",
"event_datetime": "2023-03-22 12:06:38"
}
```
#### Estorno da TED da ação pós-desembolso
Caso a TED realizada na ação pós-desembolso seja devolvida pela instituição financeira destinatária, o parceiro será notificado através do seguinte webhook:
WEBHOOK_TYPE after_disbursement_action_update
STATUS Refused
```json title='Webhook Body'
{
"key": "f4b5c36a-2aa1-4865-9678-e5a6fa585845",
"data": {
"status": "refused",
"action_key": "cf3b8809-36dc-4574-8763-3600e413cf5c",
"error_data": {
"code": "agencia_conta_invalida",
"description": "Agência ou Conta Destinatária do Crédito Inválida"
},
"action_data": {
"destination": {
"name": "SILVANA RAMOS DOS SANTOS",
"account_digit": "1",
"account_branch": "0150",
"account_number": "301771620",
"document_number": "30874011884",
"financial_institution_code_number": "237"
},
"transaction_amount": 3200
},
"action_type": "funds_transfer",
"action_amount": 3200.0
},
"webhook_type": "after_disbursement_action_update",
"event_datetime": "2023-03-23 14:46:39"
}
```
#### Retentar ação pós-desembolso com falha
Caso ocorra um erro/estorno no pagamento da ação pós-desembolso, ela pode ser retentada através do seguinte endpoint [/baas/action/**[ACTION-KEY]**](/documentation/emissao_de_divida/reprocessar_acao_pos_desembolso)
### Emissão da Operação de Crédito Consignado do SIAPE
A Operação de Crédito Consignado do SIAPE deve quitar a Operação de Crédito Pessoal e liberar (caso exista) o troco para o cliente
#### Request
ENDPOINT /debt
MÉTODO POST
**Digitação Margem Livre**
```json title='Request Body'
{
"borrower": {
"name": "Nome do Devedor",
"email": "email@email.com",
"phone": {
"number": "900000000",
"area_code": "11",
"country_code": "055"
},
"address": {
"city": "São Paulo",
"state": "SP",
"number": "215",
"street": "Gilberto Sabino",
"complement": "s/c",
"postal_code": "12345012",
"neighborhood": "Pinheiros"
},
"role_type": "issuer",
"birth_date": "1969-05-01",
"mother_name": "Nome da Mãe do Devedor",
"person_type": "natural",
"individual_document_number": "12345678911",
"gender": "male",
"nationality": "brasileiro",
"is_pep": false,
"marital_status": "married"
},
"financial": {
"first_due_date": "2023-05-07",
"installment_face_value": 100.0,
"disbursement_date": "2023-03-22",
"limit_days_to_disburse": 3,
"number_of_installments": 96,
"monthly_interest_rate": 0.0205,
"interest_type": "pre_price_days",
"fine_configuration": {
"monthly_rate": 0.01,
"interest_base": "calendar_days",
"contract_fine_rate": 0.02
},
"credit_operation_type": "ccb",
"interest_grace_period": 0,
"principal_grace_period": 0
},
"simplified": true,
"collaterals": [{
"percentage": 1,
"collateral_data": {
"reservation_type": "new_credit",
"authority_code": "17000",
"pensioner_registration_code": "",
"registration_code": "12345678",
"authority": {
"description": "teste",
"authority_document_number": "1234"
}
},
"collateral_type": "federal_payroll"
}],
"requester_identifier_key": "13176f51-3cc8-46a3-96e9-df59d7e3960c",
"disbursement_bank_account": {
"bank_code": "329",
"account_digit": "3",
"branch_number": "0001",
"account_number": "1234567"
},
"purchaser_document_number": "32402502000135",
"modality": {
"code": "0202"
},
"refinanced_credit_operations": [
{
"operation_key": "052fe83c-37f6-4339-a831-127b50566745"
}
]
}
```
**Digitação Portabilidade**
```json title='Request Body'
{
"borrower": {
"name": "Nome do Devedor",
"email": "email@email.com",
"phone": {
"number": "900000000",
"area_code": "11",
"country_code": "055"
},
"address": {
"city": "São Paulo",
"state": "SP",
"number": "215",
"street": "Gilberto Sabino",
"complement": "s/c",
"postal_code": "12345012",
"neighborhood": "Pinheiros"
},
"role_type": "issuer",
"birth_date": "1969-05-01",
"mother_name": "Nome da Mãe do Devedor",
"person_type": "natural",
"individual_document_number": "12345678911",
"gender": "male",
"nationality": "brasileiro",
"is_pep": false,
"marital_status": "married"
},
"financial": {
"first_due_date": "2023-05-07",
"installment_face_value": 100.0,
"disbursement_date": "2023-03-22",
"limit_days_to_disburse": 3,
"number_of_installments": 96,
"monthly_interest_rate": 0.0205,
"interest_type": "pre_price_days",
"fine_configuration": {
"monthly_rate": 0.01,
"interest_base": "calendar_days",
"contract_fine_rate": 0.02
},
"credit_operation_type": "ccb",
"interest_grace_period": 0,
"principal_grace_period": 0
},
"simplified": true,
"collaterals": [{
"percentage": 1,
"collateral_data": {
"reservation_method": "creation",
"authority": {
"description": "",
"authority_document_number": ""
},
"reservation_type": "portability",
"authority_code": "17000",
"pensioner_registration_code": "",
"registration_code": "12345678",
"portability_data": {
"start_date": "",
"control_number": "",
"origin_contract": {
"contract_number": "",
"financial_institution_document_number": ""
}
}
},
"collateral_type": "federal_payroll"
}],
"requester_identifier_key": "13176f51-3cc8-46a3-96e9-df59d7e3960c",
"disbursement_bank_account": {
"bank_code": "329",
"account_digit": "3",
"branch_number": "0001",
"account_number": "1234567"
},
"purchaser_document_number": "32402502000135",
"modality": {
"code": "0202"
},
"refinanced_credit_operations": [
{
"operation_key": "052fe83c-37f6-4339-a831-127b50566745"
}
]
}
```
#### Response
STATUS 200
```json title='Response Body'
{
"data": {
"borrower": {
"document_number": "12345678911",
"name": "Nome do Devedor",
"related_party_key": "c5584ee3-e077-41dc-a28e-c2ba97390bf1"
},
"collaterals": [{
"absolute_amount": null,
"collateral_constituted": false,
"collateral_data": {
"authority_code": "17000",
"pensioner_registration_code": null,
"registration_code": "12345678"
},
"collateral_key": "5e40c191-06ae-4da2-9d4b-3c0bf6eeb1a3",
"collateral_type": "federal_payroll",
"created_at": "2023-03-17T20:56:09.200482",
"external_key": "8cda40d8-1593-4a1e-938f-5e1488e734d8",
"percentage": 1,
"updated_at": "2023-03-17T20:56:09.200474"
}],
"contract": {
"number": "0000000002/NDD",
"signature_information": [{
"signature_url": null,
"signer_document_number": "12345678911",
"signer_email": "email@email.com",
"signer_external_key": null,
"signer_name": "Nome do Devedor",
"signer_role": "issuer"
}],
"urls": [
"https://storage.googleapis.com/live-doc-api/documents/45e5b9c0-0f56-40a8-aace-d206f72c164d/QISCD-NOME_DO_DEVEDOR-CCB-0000000002-20230317183044.pdf"
]
},
"disbursement_options": [{
"additional_iof": 24.220242,
"annual_cet": "26.1457%",
"assignment_amount": 3205.12,
"base_iof": 176.6603785598479778,
"cet": "1,9544%",
"contract_fee_amount": 17.68,
"contract_fees": [{
"amount": 17.68,
"amount_type": "absolute",
"fee_amount": 17.68,
"fee_type": "spread_cip_cost"
}],
"disbursement_date": "2023-03-22",
"external_contract_fee_amount": 0,
"external_contract_fees": [],
"first_due_date": "2023-05-07",
"installments": [{
"additional_costs": [],
"business_due_date": "2022-05-08",
"calendar_days": 34,
"due_date": "2023-05-07",
"due_interest": 0,
"due_principal": 3187.44,
"fine_amount": null,
"has_interest": true,
"installment_number": 1,
"installment_status": null,
"installment_type": null,
"post_fixed_amount": 0,
"pre_fixed_amount": 64.20069301315790,
"principal_amortization_amount": 35.79930698684210,
"tax_amount": 0.10014353287723266,
"total_amount": 100,
"workdays": 23
},
...
x 96
],
"issue_amount": 3187.44,
"net_external_contract_fee_amount": 0,
"total_iof": 100.44,
"total_pre_fixed_amount": 3225.1656904289435
},
...
x 15
],
"iof_charge_method": "financed",
"requester_identifier_key": "13176f51-3cc8-46a3-96e9-df59d7e3960c"
},
"event_datetime": "2023-03-17 13:54:58",
"key": "32f99efe-7654-4e74-a509-c7413341a831",
"status": "waiting_signature",
"webhook_type": "debt"
}
```
#### Webhook de Anuência Pendente
WEBHOOK_TYPE credit_operation.collateral
STATUS Pending Consent
Body
```json
{
"key": "\",
"data": {
"collateral_data": {
"reservation_status": "pending_consent"
},
"collateral_type": "federal_payroll",
"collateral_constituted": false
},
"event_time": "2022-10-31 15:23:46",
"webhook_type": "credit_operation.collateral"
}
```
#### Averbação
Após a criação da Operação de Crédito Consignado do SIAPE, a QI iniciará o processo de averbação da operação.
O processo de tentativa de averbação inicia no momento da criação da operação, e será retentado até a última data de opção de desembolso da operação.
Assim que a digitação for concluída a QI informará o parceiro sobre a pendência de anuência da averbação:
WEBHOOK_TYPE credit_operation.collateral
STATUS Pending Consent
Body
```json
{
"key": "\",
"data": {
"collateral_data": {
"reservation_status": "pending_consent"
},
"collateral_type": "federal_payroll",
"collateral_constituted": false
},
"event_time": "2022-10-31 15:23:46",
"webhook_type": "credit_operation.collateral"
}
```
A após a conclusão da anuência e confirmação da averbação da margem, a QI notificará o parceiro através do seguinte webhook:
WEBHOOK_TYPE credit_operation.collateral
STATUS Success
```json title='Webhook Body'
{
"key": "32f99efe-7654-4e74-a509-c7413341a831",
"data": {
"collateral_type": "federal_payroll",
"collateral_constituted": true
},
"event_time": "2022-03-22 15:23:46",
"webhook_type": "credit_operation.collateral"
}
```
---
### Emissão da Operação de Crédito Consignado do Exército
A Operação de Crédito Consignado do Exército deve quitar a Operação de Crédito Pessoal e liberar (caso exista) o troco para o cliente
#### Request
ENDPOINT /debt
MÉTODO POST
**Digitação Portabilidade (Deprecada a partir de 30/11/2023)**
```json title='Request Body'
{
"borrower": {
"name": "Nome do Devedor",
"email": "email@email.com",
"phone": {
"number": "900000000",
"area_code": "11",
"country_code": "055"
},
"address": {
"city": "São Paulo",
"state": "SP",
"number": "215",
"street": "Gilberto Sabino",
"complement": "s/c",
"postal_code": "12345012",
"neighborhood": "Pinheiros"
},
"role_type": "issuer",
"birth_date": "1969-05-01",
"mother_name": "Nome da Mãe do Devedor",
"person_type": "natural",
"individual_document_number": "12345678911",
"gender": "male",
"nationality": "brasileiro",
"is_pep": false,
"marital_status": "married"
},
"financial": {
"first_due_date": "2023-05-07",
"installment_face_value": 100.0,
"disbursement_date": "2023-03-22",
"limit_days_to_disburse": 3,
"number_of_installments": 72,
"monthly_interest_rate": 0.017,
"interest_type": "pre_price_days",
"fine_configuration": {
"monthly_rate": 0.01,
"interest_base": "calendar_days",
"contract_fine_rate": 0.02
},
"credit_operation_type": "ccb",
"interest_grace_period": 0,
"principal_grace_period": 0
},
"simplified": true,
"collaterals": [{
"percentage": 1,
"collateral_data": {
"reservation_type": "portability",
"portability_data":{
"token":"hw342y1h24",
"origin_econsig_id":"2016587"
},
"registration_code": "12345678",
"reservation_method": "creation"
},
"collateral_type": "military_payroll"
}],
"requester_identifier_key": "7e000c2d-d381-470e-b233-416097504866",
"disbursement_bank_account": {
"bank_code": "341",
"account_digit": "3",
"branch_number": "1234",
"account_number": "1234567"
},
"purchaser_document_number": "32402502000135",
"modality": {
"code": "0202"
},
"refinanced_credit_operations": [
{
"operation_key": "d2fd3f63-3d11-42a8-ab5c-9a84b5c58b6c"
}
]
}
```
**Digitação Portabilidade(s) (Vigente a partir de 21/11/2023)**
```json title='Request Body'
{
"borrower": {
"name": "Nome do Devedor",
"email": "email@email.com",
"phone": {
"number": "900000000",
"area_code": "11",
"country_code": "055"
},
"address": {
"city": "São Paulo",
"state": "SP",
"number": "215",
"street": "Gilberto Sabino",
"complement": "s/c",
"postal_code": "12345012",
"neighborhood": "Pinheiros"
},
"role_type": "issuer",
"birth_date": "1969-05-01",
"mother_name": "Nome da Mãe do Devedor",
"person_type": "natural",
"individual_document_number": "12345678911",
"gender": "male",
"nationality": "brasileiro",
"is_pep": false,
"marital_status": "married"
},
"financial": {
"first_due_date": "2023-05-07",
"installment_face_value": 100.0,
"disbursement_date": "2023-03-22",
"limit_days_to_disburse": 3,
"number_of_installments": 72,
"monthly_interest_rate": 0.017,
"interest_type": "pre_price_days",
"fine_configuration": {
"monthly_rate": 0.01,
"interest_base": "calendar_days",
"contract_fine_rate": 0.02
},
"credit_operation_type": "ccb",
"interest_grace_period": 0,
"principal_grace_period": 0
},
"simplified": true,
"collaterals": [{
"percentage": 1,
"collateral_data": {
"reservation_type": "portability",
"portability_data":{
"token":"hw342y1h24",
"origin_econsig_ids": [
"2016587",
"2016588",
"2016589",
]
},
"registration_code": "12345678",
"reservation_method": "creation"
},
"collateral_type": "military_payroll"
}],
"requester_identifier_key": "7e000c2d-d381-470e-b233-416097504866",
"disbursement_bank_account": {
"bank_code": "341",
"account_digit": "3",
"branch_number": "1234",
"account_number": "1234567"
},
"purchaser_document_number": "32402502000135",
"modality": {
"code": "0202"
},
"refinanced_credit_operations": [
{
"operation_key": "d2fd3f63-3d11-42a8-ab5c-9a84b5c58b6c"
}
]
}
```
**Digitação Margem Livre**
```json title='Request Body'
{
"borrower": {
"name": "Nome do Devedor",
"email": "email@email.com",
"phone": {
"number": "900000000",
"area_code": "11",
"country_code": "055"
},
"address": {
"city": "São Paulo",
"state": "SP",
"number": "215",
"street": "Gilberto Sabino",
"complement": "s/c",
"postal_code": "12345012",
"neighborhood": "Pinheiros"
},
"role_type": "issuer",
"birth_date": "1969-05-01",
"mother_name": "Nome da Mãe do Devedor",
"person_type": "natural",
"individual_document_number": "12345678911",
"gender": "male",
"nationality": "brasileiro",
"is_pep": false,
"marital_status": "married"
},
"financial": {
"first_due_date": "2023-05-07",
"installment_face_value": 100.0,
"disbursement_date": "2023-03-22",
"limit_days_to_disburse": 3,
"number_of_installments": 72,
"monthly_interest_rate": 0.017,
"interest_type": "pre_price_days",
"fine_configuration": {
"monthly_rate": 0.01,
"interest_base": "calendar_days",
"contract_fine_rate": 0.02
},
"credit_operation_type": "ccb",
"interest_grace_period": 0,
"principal_grace_period": 0
},
"simplified": true,
"collaterals": [{
"percentage": 1,
"collateral_data": {
"reservation_type": "new_credit",
"registration_code": "123456789",
"reservation_method": "creation"
},
"collateral_type": "military_payroll"
}],
"requester_identifier_key": "7e000c2d-d381-470e-b233-416097504866",
"disbursement_bank_account": {
"bank_code": "341",
"account_digit": "3",
"branch_number": "1234",
"account_number": "1234567"
},
"purchaser_document_number": "32402502000135",
"modality": {
"code": "0202"
},
"refinanced_credit_operations": [
{
"operation_key": "d2fd3f63-3d11-42a8-ab5c-9a84b5c58b6c"
}
]
}
```
**Digitação Refinanciamento**
```json title='Request Body'
{
"borrower": {
"name": "Nome do Devedor",
"email": "email@email.com",
"phone": {
"number": "900000000",
"area_code": "11",
"country_code": "055"
},
"address": {
"city": "São Paulo",
"state": "SP",
"number": "215",
"street": "Gilberto Sabino",
"complement": "s/c",
"postal_code": "12345012",
"neighborhood": "Pinheiros"
},
"role_type": "issuer",
"birth_date": "1969-05-01",
"mother_name": "Nome da Mãe do Devedor",
"person_type": "natural",
"individual_document_number": "12345678911",
"gender": "male",
"nationality": "brasileiro",
"is_pep": false,
"marital_status": "married"
},
"financial": {
"first_due_date": "2023-05-07",
"installment_face_value": 100.0,
"disbursement_date": "2023-03-22",
"limit_days_to_disburse": 3,
"number_of_installments": 72,
"monthly_interest_rate": 0.017,
"interest_type": "pre_price_days",
"fine_configuration": {
"monthly_rate": 0.01,
"interest_base": "calendar_days",
"contract_fine_rate": 0.02
},
"credit_operation_type": "ccb",
"interest_grace_period": 0,
"principal_grace_period": 0
},
"simplified": true,
"collaterals": [{
"percentage": 1,
"collateral_data": {
"reservation_type": "refinancing",
"registration_code": "123456789",
"reservation_method": "issuing"
},
"collateral_type": "military_payroll"
}],
"requester_identifier_key": "7e000c2d-d381-470e-b233-416097504866",
"disbursement_bank_account": {
"bank_code": "341",
"account_digit": "3",
"branch_number": "1234",
"account_number": "1234567"
},
"purchaser_document_number": "32402502000135",
"modality": {
"code": "0202"
},
"refinanced_credit_operations": [
{
"operation_key": "d2fd3f63-3d11-42a8-ab5c-9a84b5c58b6c"
}
]
}
```
### Detalhamento de campos no objeto collateral_data
| Campo | Descrição | Valores |
|-----------------------|-----------------------------------------------|-------------------------------------------------------|
| reservation_type | Tipo da reserva | [Enumeradores](#reservation_type_enumerator) |
| registration_code | Matrícula do militar | 123456789 |
| reservation_method | Determina quando deve-se iniciar a tentativa de averbação do consignado, seja no momento da criação da operação de crédito ou no momento da emissão da mesma. | [Enumeradores](#reservation_method_enumerator) |
| portability_data | Dados de portabilidade | [Objeto de Portabilidade](#portability_data_object) |
### Tabela de tipos de reserva {#reservation_type_enumerator}
| Enumerador | Descrição |
|-------------|-----------------|
| new_credit | Crédito Novo |
| portability | Portabilidade |
| refinancing | Refinanciamento |
### Tabela de metodos de criação de reserva {#reservation_method_enumerator}
:::caution Atenção
Campo muito importante, pois ele determina diretamente quando o pedido de intensão de reserva na Zetra será feito.
:::
| Enumerator | Descrição |
|---------------|-----------------------------------------------------------------------------------------------------------------------|
| creation | A tentativa de averbação começará quando a operação de crédito for criada. |
| issuing | A tentativa de averbação começará quando a operação de crédito for emitida, ou seja, após a formalização da mesma. |
### Detalhamento de campos no objeto portability_data {#portability_data_object}
| Campo | Descrição | Valores |
|-----------------------|-----------------------------------------------------------|-------------------------------|
| token | Senha fornecida pelo militar | 1234abcd |
| origin_econsig_id | Código identificador de contrato da Zetra | 1234567 |
| origin_econsig_ids | Lista de códigos identificadores de contratos da Zetra | [1234567, 1234568, 1234569] |
#### Response
STATUS 200
```json title='Response Body'
{
"data": {
"borrower": {
"document_number": "12345678911",
"name": "Nome do Devedor",
"related_party_key": "1fe936e7-0917-4c3d-9206-87958254fa1d"
},
"collaterals": [{
"absolute_amount": null,
"collateral_constituted": false,
"collateral_data": {
"reservation_type": "new_credit",
"registration_code": "123456789"
},
"collateral_key": "c6006572-d66a-45f6-862d-4ecb5b9b5d2d",
"collateral_type": "military_payroll",
"created_at": "2023-03-17T20:56:09.200482",
"external_key": "1c736cd8-a4c7-43d4-8abd-c00ed0cd6450",
"percentage": 1,
"updated_at": "2023-03-17T20:56:09.200474"
}],
"contract": {
"number": "0000000003/NDD",
"signature_information": [{
"signature_url": null,
"signer_document_number": "12345678911",
"signer_email": "email@email.com",
"signer_external_key": null,
"signer_name": "Nome do Devedor",
"signer_role": "issuer"
}],
"urls": [
"https://storage.googleapis.com/live-doc-api/documents/ae66d0cd-1054-4ff5-b1d6-e03aaaa2ff1b/QISCD-NOME_DO_DEVEDOR-CCB-0000000002-20230317183044.pdf"
]
},
"disbursement_options": [{
"additional_iof": 24.220242,
"annual_cet": "26.1457%",
"assignment_amount": 3205.12,
"base_iof": 176.6603785598479778,
"cet": "1,9544%",
"contract_fee_amount": 17.68,
"contract_fees": [{
"amount": 17.68,
"amount_type": "absolute",
"fee_amount": 17.68,
"fee_type": "spread_cip_cost"
}],
"disbursement_date": "2023-03-22",
"external_contract_fee_amount": 0,
"external_contract_fees": [],
"first_due_date": "2023-05-07",
"installments": [{
"additional_costs": [],
"business_due_date": "2022-05-08",
"calendar_days": 34,
"due_date": "2023-05-07",
"due_interest": 0,
"due_principal": 3187.44,
"fine_amount": null,
"has_interest": true,
"installment_number": 1,
"installment_status": null,
"installment_type": null,
"post_fixed_amount": 0,
"pre_fixed_amount": 64.20069301315790,
"principal_amortization_amount": 35.79930698684210,
"tax_amount": 0.10014353287723266,
"total_amount": 100,
"workdays": 23
},
...
x 96
],
"issue_amount": 3187.44,
"net_external_contract_fee_amount": 0,
"total_iof": 100.44,
"total_pre_fixed_amount": 3225.1656904289435
},
...
x 15
],
"iof_charge_method": "financed",
"requester_identifier_key": "f7fa079e-e02f-469f-a9ba-7a550f8f665f"
},
"event_datetime": "2023-03-17 13:54:58",
"key": "23c89acf-b11b-4988-b738-a0f5ba238c33",
"status": "waiting_signature",
"webhook_type": "debt"
}
```
#### Averbação
Após a criação da Operação de Crédito Consignado do EXÉRCITO, a QI iniciará o processo de averbação da operação.
O processo de tentativa de averbação inicia no momento da criação da operação, e será retentado até a última data de opção de desembolso da operação.
A após a conclusão da averbação da margem consignável do exército, a QI notificará o parceiro através do seguinte webhook:
WEBHOOK_TYPE credit_operation.collateral
STATUS Success
```json title='Webhook Body'
{
"key": "23c89acf-b11b-4988-b738-a0f5ba238c33",
"data": {
"collateral_type": "military_payroll",
"collateral_constituted": true
},
"event_time": "2022-10-31 15:23:46",
"webhook_type": "credit_operation.collateral"
}
```
Caso o token informado não seja válido, enviaremos o seguinte webhook. Esse webhook também será enviado caso o token informado já tenha sido utilizado e seja necessário um novo.
WEBHOOK_TYPE credit_operation.collateral
STATUS Pending Valid Token
```json title='Webhook Body'
{
"key": "23c89acf-b11b-4988-b738-a0f5ba238c33",
"data": {
"collateral_type": "military_payroll",
"collateral_data": {
"reservation_status": "pending_valid_token",
"cancel_reason": "invalid_token",
},
"collateral_constituted": false,
},
"event_time": "2022-10-31 15:23:46",
"webhook_type": "credit_operation.collateral"
}
```
#### Resposta que ocasionam cancelamento automático
Dependendo da resposta da Zetra, a operação será cancelada automaticamente.
Quando isso ocorrer enviaremos um webhook no formato abaixo, o motivo do cancelamento é informado no campo "cancel_reason"
WEBHOOK_TYPE credit_operation.collateral
STATUS Canceled
```json title='Webhook Body'
{
"data": {
"cancel_reason": "Contrato de origem não encontrato.",
"cancel_reason_enumerator": "military_payroll_portability_not_found"
},
"event_datetime": "2023-10-10 15:45:21",
"key": "\",
"status": "canceled",
"webhook_type": "debt"
}
```
#### Tabela de enumeradores
| Enumerador | Descrição | Código da Zetra |
|-----------------------------------------------|---------------------------------------|------------------|
| military_payroll_military_not_found | Militar não encontrado. | 293 |
| military_payroll_portability_not_found | Contrato de origem não encontrato. | 294 |
| military_payroll_consignable_margin_exceeded | Margem disponível excedida. | 359 |
#### Expiração da Portabilidade
Após 10 dias, a Zetra cancela os pedidos de portabilidades que estão aguardando confirmação.
Desta forma, para reiniciar o fluxo de portabilidade, faz-se necessário um novo token válido. Caso exista um novo token válido, a proposta retorna para o passo de intenção de portabilidade (status da reserva: pending_reservation). No entanto, caso não exista um token válido, geralmente porque o token enviado já foi utilizado na intenção de portabilidade anterior, a proposta é atualizada para o status de pending_valid_token, aguardando o envio de um novo token. Com o envio de um novo token válido, a proposta segue normalmente o fluxo de intenção de portabilidade e confirmação.
Para informar a situação será enviado o seguinte webhook:
WEBHOOK_TYPE credit_operation.collateral
STATUS Pending Reservation/Pending Valid Token
```json title='Webhook Body'
{
"key": "23c89acf-b11b-4988-b738-a0f5ba238c33",
"data": {
"collateral_type": "military_payroll",
"collateral_data": {
"reservation_status": "pending_reservation" ou "pending_valid_token",
"cancel_reason": "expired_portability",
},
},
"event_time": "2022-10-31 15:23:46",
"webhook_type": "credit_operation.collateral"
}
```
## Cancelamento
Para realizar o cancelamento definitivo de uma operação, com a desaverbação da margem consignável, deve ser utilizado o seguinte endpoint:
:::caution Atenção
Vale ressaltar que o processo de desaverbação é assíncrono, ou seja, o cancelamento da operação de crédito, NÃO signifca necessáriamente que a desaverbação foi concluída. Para consultar o status da desaverbação vide [Recuperar resposta da última request](#recuperar_ultima_request)".
:::
:::caution Atenção
O cancelamento definitivo também pode ocorrer de forma automática, isso acontece quando uma operação está no status "canceled" por mais de 7 dias.
:::
### Request
ENDPOINT /debt/[DEBT-KEY]/cancel_permanently
MÉTODO POST
### Cancelamento da operação com sucesso:
Após a conclusão do cancelamento da operação, o parceiro receberá o seguinte webhook:
WEBHOOK_TYPE debt
STATUS Canceled Permanently
Body
```json
{
"key": "\",
"data": {},
"status": "canceled_permanently",
"webhook_type": "debt",
"event_datetime": "2022-11-01 03:46:31"
}
```
## Envio de novo Token de Portabilidade
O token de portabilidade é de uso único, portanto, é necessário que um novo token seja enviado quando o anterior for utilizado ou no caso de token inválido.
A forma de envio é uma chamada simples:
### Request
ENDPOINT /debt/[DEBT-KEY]/collateral
MÉTODO PATCH
Request Body
```json
{
"portability_data": {
"token": "12345678"
}
}
```
### Casos de sucesso
#### Response 204
Response Body
```json
{}
```
### Caso de erro
:::info
Somente o token deverá ser enviado nessa requisição, caso contrário o processo retornará um erro
:::
#### Response
Response Body
```json
{
"title": "Bad Request",
"description": "Additional properties are not allowed ( was unexpected)",
"translation": "Schema Inválido",
"code": "QIT000001"
}
```
## Alteração do tipo de averbação da operação
Alterar, exclusivamente, o tipo de averbação de uma operação de portabilidade para crédito novo.
Após a alteração, a reserva seguirá, automaticamente, o fluxo e regras de averbação de uma reserva do tipo crédito novo.
### Request
ENDPOINT /debt/[DEBT-KEY]/collateral
MÉTODO PATCH
Request Body
```json
{
"reservation_type": "new_credit"
}
```
### Casos de sucesso
#### Response 204
Response Body
```json
{}
```
### Caso de erro
#### Response
Response Body
```json
{
"title": "Bad Request",
"description": "Additional properties are not allowed ( was unexpected)",
"translation": "Schema Inválido",
"code": "QIT000001"
}
```
## Recuperar resposta da última request {#recuperar_ultima_request}
O last response é uma forma de mapear, de forma simples e objetiva, a resposta da comunicação entre a QI e a Zetra, possibilitando saber quando essa requisição foi feita e qual o retorno obtido (através de um enumerador).
Cada enumerador tem uma descrição detalhada. Podemos conferir abaixo, com mais detalhes, como serão apresentados os dados do last response.
### Casos de sucesso
#### Request
ENDPOINT /debt/[DEBT-KEY]/collateral
MÉTODO GET
#### Response
Response Body
```json
{
"collateral_constituted": true,
"collateral_type": "military_payroll",
"updated_at": "2023-05-24 19:13:02",
"collateral_data": {
"status": "reserved",
"last_response": {
"success": [
{
"enumerator": "succesfully_reserved"
}
]
},
"last_response_event_datetime": "2023-05-22T19:13:02Z"
}
}
```
Response Body Portability
```json
{
"collateral_constituted": true,
"collateral_type": "military_payroll",
"collateral_data": {
"status": "reserved",
"last_response": {
"success": [
{
"enumerator": "successfully_reserved"
}
]
},
"last_response_event_datetime": "2023-08-09T19:25:09Z",
"portability_data": {
"origin_econsig_id": "2016587",
"token": "123456"
}
}
}
```
#### Tabela de enumeradores
| Enumerador | Descrição | Detalhes | Status da reserva |
|-----------------------------------|----------------------------------|--------------------------------------------------------------------| ---------------------|
| successfully_accepted | Reservation request accepted | O pedido de averbação foi aceito e está aguardando confirmação | pending_confirmation |
| successfully_reserved | Reservation made successfully | A reserva foi averbada com sucesso | reserved |
| successfully_deleted | Reservation successfully deleted | A reserva foi desaverbada com sucesso | deleted |
### Casos de erro
#### Request
ENDPOINT /debt/[DEBT-KEY]/collateral
MÉTODO GET
#### Response
Response Body
```json
{
"collateral_constituted": false,
"collateral_type": "military_payroll",
"updated_at": "2023-05-24 19:13:02",
"collateral_data": {
"status": "pending_reservation",
"last_response": {
"errors": [
{
"enumerator": "invalid_portability_token"
}
]
},
"last_response_event_datetime": "2023-05-22T19:13:02Z"
}
}
```
#### Tabela de enumeradores
| Enumerador | Descrição | Ação QI | Código correspondente da Zetra |
|-----------------------------|-------------------------------------------|---------|---------------------------------|
| waiting_confirmation | Waiting Confirmation on Portability | retry | |
| communication_error | Communication Error with Zetra | retry | 241 |
| consignable_margin_excceded | Exceeded consignable margin | retry | 359 |
## Informe de Saldo Devedor
O informe de saldo devedor acontece no 5º dia útil após o dia da solicitação, e todos os informados são enviados pelo webhook com as seguintes informações:
WEBHOOK_TYPE military_payroll.due_balance.status_change
STATUS processed
Response Body
```json
{
"webhook_type": "military_payroll.due_balance.status_change",
"status": "processed",
"event_datetime": "2024-03-12T19:23:12Z",
"data": [
{
"contract_number": "0000086715/TA",
"payment_amount": 284.28,
"balance_limit_date": "2024-03-12"
},
{
"contract_number": "0000086715/BE",
"payment_amount": 134.00,
"balance_limit_date": "2024-03-12"
}
]
}
```
---
# Abertura de Conta em Duas Etapas
URL: /documentation/account_request
## Solicitar Reserva de Conta de Livre Movimentação
### Request
ENDPOINT /account_request/checking
MÉTODO POST
Request Body - Titular PJ
```json
{
"account_owner": {
"company_document_number": "64669455000187",
"email": "marcos.alves@yopmail.com",
"foundation_date": "2017-09-16",
"name": "NOME DA EMPRESA"
}
}
```
Request Body - Titular PF
```json
{
"account_owner": {
"document_number": "64669455000187",
"email": "marcos.alves@yopmail.com",
"birthdate": "2017-09-16",
"name": "NOME DA EMPRESA"
}
}
```
## Solicitar Reserva de Conta Escrow
ENDPOINT /account_request/escrow
MÉTODO POST
Request Body - Titular PJ
```json
{
"account_owner": {
"company_document_number": "64669455000187",
"email": "marcos.alves@yopmail.com",
"foundation_date": "2017-09-16",
"name": "NOME DA EMPRESA"
}
}
```
Request Body - Titular PF
```json
{
"account_owner": {
"document_number": "64669455000187",
"email": "marcos.alves@yopmail.com",
"birthdate": "2017-09-16",
"name": "NOME DA EMPRESA"
}
}
```
### Body Params Titular PJ
| Campo | Tipo | Descrição | Caracteres |
|------------------|------------|------------------------------------------------|-----------------------------------------------------------------------------------|
| **account_owner** | object | Informações simplificadas da pessoa jurídica titular da conta | [Objeto account_owner PJ](#objeto-account_owner-solicitar-reserva-pj)
[Objeto account_owner PF](#objeto-account_owner-solicitar-reserva-pf) |
### Objeto account_owner Solicitar Reserva PJ
| Campo | Tipo | Descrição | Caracteres |
|-------------------------------|--------|-------------------------------------------|------------|
| **company_document_number** * | string | CNPJ do titualar da conta. | 14 |
| **email** * | string | E-mail da empresa titular da contato. | 200 |
| **foundation_date** | string | Data de abertura da empresa. | 10 |
| **name** * | string | Razão Social da empresa titular da conta. | 50 |
### Objeto account_owner Solicitar Reserva PF
| Campo | Tipo | Descrição | Caracteres |
|------------------------|--------|-------------------------------------------|------------|
| **document_number** * | string | CPF do titualar da conta. | 14 |
| **email** * | string | E-mail da empresa titular da contato. | 200 |
| **birthdate** | string | Data de nascimento. | 10 |
| **name** * | string | Razão Social da empresa titular da conta. | 50 |
### Response
STATUS 201
Response Body
```json
{
"account_info": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "1638634"
},
"account_request_key": "e48eb139-448e-43b9-9aee-df5f4b51158c",
"account_request_status": "pending_kyc_analysis"
}
```
### Webhook aprovação KYC
Webhook Body
```json
{
"data": {
"account_info": {
"account_digit": "3",
"account_branch": "0001",
"account_number": "1638634"
},
"account_request_key": "dc575950-dcce-48e1-99a6-5fb0ada63d86"
},
"event_datetime": "2022-09-02 22:39:39",
"key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
"status": "pending_additional_data",
"webhook_type": "account_request.status_change"
}
```
### Enumeradores account_request_status
| Enum | Description |
|-----------------------------|---------------------------------|
| **pending_kyc_analysis** | Pendente aprovação KYC |
| **pending_additional_data** | Pendente informações adicionais |
| **rejected** | Abertura rejeitada |
## Abertura de Conta Livre Movimentação
### Request
ENDPOINT /account_request/ACCOUNT_REQUEST_KEY/checking
MÉTODO PATCH
Request Body - Titular PJ
```json
{
"account_owner": {
"address": {
"city": "Caraguatatuba",
"complement": "complemento",
"neighborhood": "Jaraguazinho",
"number": "924",
"postal_code": "11675200",
"state": "SP",
"street": "Praça Jorge Vitório de Souza"
},
"cnae_code": "4721-1/02",
"company_document_number": "64669455000187",
"company_statute": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
"company_type": "ltda",
"email": "marcos.alves@yopmail.com",
"foundation_date": "2017-09-16",
"name": "NOME DA EMPRESA",
"person_type": "legal",
"phone": {
"area_code": "19",
"country_code": "055",
"number": "988888888"
},
"trading_name": "Pães e Doces",
"company_representatives": [
{
"name": "Marcos Felipe Henrique Alves",
"address": {
"city": "Recife",
"complement": null,
"neighborhood": "Fundão",
"number": "137",
"postal_code": "52221110",
"state": "PE",
"street": "Rua Camapuã"
},
"email": "marcos.alves@yopmail.com",
"birth_date": "1972-02-02",
"individual_document_number": "08531309069",
"document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
"document_identification_number": "339122924",
"is_pep": false,
"final_beneficiary": true,
"marital_status": "single",
"mother_name": "Sueli Isadora Alves",
"nationality": "Brasileira",
"person_type": "natural",
"phone": {
"area_code": "88",
"country_code": "055",
"number": "995924634"
}
}
]
},
"signed_contract": {
"document_key": "4d7f4e29-4b58-4905-9a69-b1f9215263f5",
"signatures": [
{
"authenticity": {
"timestamp": "1970-01-01T00:00:01.080100Z",
"facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb",
"lang": "-35.8916627",
"lat": "-7.2226067",
"ip_address": "177.51.1.186",
"session_id": "jdifj329842"
},
"signer": {
"name": "IVANILDO DE SENA LIMA",
"email": "ivanlima2604@gmail.com",
"phone": {
"country_code": "055",
"area_code": "11",
"number": "999999999"
},
"document_number": "61766976204"
},
"authentication_type": "opt-in"
}
]
},
"additional_documents": ["b12c8807-8f3f-4083-9cb1-7cce641f3786"],
"guarantee_document_key": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d"
}
```
Request Body - Titular PF
```json
{
"account_owner": {
"address": {
"street": "Av. Brigadeiro Faria Lima",
"state": "SP",
"city": "São Paulo",
"neighborhood": "Jardim Paulistano",
"number": "2391",
"postal_code": "01452905",
"complement": "1o. Andar"
},
"birth_date": "1990-05-06",
"document_identification": "3c24579b-9810-4fa6-9b08-fe67d237160a",
"email": "ivanlima2604@gmail.com",
"individual_document_number": "34651104630",
"is_pep": false,
"mother_name": "Dona Maria Mariane",
"name": "Nome do Titular da Conta",
"nationality": "nationality",
"person_type": "natural",
"phone": {
"country_code": "055",
"area_code": "11",
"number": "999999999"
},
"proof_of_residence": "780456bd-1eec-4e5f-82c0-d8c3921497ea"
},
"signed_contract": {
"document_key": "4d7f4e29-4b58-4905-9a69-b1f9215263f5",
"signatures": [
{
"authenticity": {
"timestamp": "1970-01-01T00:00:01.080100Z",
"facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb",
"lang": "-35.8916627",
"lat": "-7.2226067",
"ip_address": "177.51.1.186",
"session_id": "jdifj329842"
},
"signer": {
"name": "Nome do Titular da Conta",
"email": "ivanlima2604@gmail.com",
"phone": {
"country_code": "055",
"area_code": "11",
"number": "999999999"
},
"document_number": "61766976204"
},
"authentication_type": "opt-in"
}
]
},
"additional_documents": ["b12c8807-8f3f-4083-9cb1-7cce641f3786"],
"guarantee_document_key": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d"
}
```
### Response
STATUS 201
Response Body
```json
{
"account_key": "e48eb139-448e-43b9-9aee-df5f4b51158c"
}
```
:::info ACCOUNT_KEY
A `account_key` será a chave única de identificação da conta. Toda interação com a conta se dará através dela.
:::
## Abertura de Conta Escrow
### Request
ENDPOINT /account_request/ACCOUNT_REQUEST_KEY/escrow
MÉTODO PATCH
Request Body - Titular PJ
```json
{
"account_owner": {
"address": {
"city": "Caraguatatuba",
"complement": "complemento",
"neighborhood": "Jaraguazinho",
"number": "924",
"postal_code": "11675200",
"state": "SP",
"street": "Praça Jorge Vitório de Souza"
},
"cnae_code": "4721-1/02",
"company_document_number": "64669455000187",
"company_statute": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
"company_type": "ltda",
"email": "marcos.alves@yopmail.com",
"foundation_date": "2017-09-16",
"name": "NOME DA EMPRESA",
"person_type": "legal",
"phone": {
"area_code": "19",
"country_code": "055",
"number": "988888888"
},
"trading_name": "Pães e Doces",
"company_representatives": [
{
"name": "Marcos Felipe Henrique Alves",
"address": {
"city": "Recife",
"complement": null,
"neighborhood": "Fundão",
"number": "137",
"postal_code": "52221110",
"state": "PE",
"street": "Rua Camapuã"
},
"email": "marcos.alves@yopmail.com",
"birth_date": "1972-02-02",
"individual_document_number": "08531309069",
"document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
"document_identification_number": "339122924",
"is_pep": false,
"final_beneficiary": true,
"marital_status": "single",
"mother_name": "Sueli Isadora Alves",
"nationality": "Brasileira",
"person_type": "natural",
"phone": {
"area_code": "88",
"country_code": "055",
"number": "995924634"
}
}
]
},
"signed_contract": {
"document_key": "4d7f4e29-4b58-4905-9a69-b1f9215263f5",
"signatures": [
{
"authenticity": {
"timestamp": "1970-01-01T00:00:01.080100Z",
"facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb",
"lang": "-35.8916627",
"lat": "-7.2226067",
"ip_address": "177.51.1.186",
"session_id": "jdifj329842"
},
"signer": {
"name": "IVANILDO DE SENA LIMA",
"email": "ivanlima2604@gmail.com",
"phone": {
"country_code": "055",
"area_code": "11",
"number": "999999999"
},
"document_number": "61766976204"
},
"authentication_type": "opt-in"
}
]
},
"destinations": [
{
"account_branch": "0001",
"account_number": "1234567",
"account_digit": "1",
"document_number": "04252012000123",
"name": "Conta do FIDC",
"ispb_number": "32402502",
"financial_institution_code_number": "329"
}
],
"additional_documents": ["b12c8807-8f3f-4083-9cb1-7cce641f3786"],
"guarantee_document_key": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d"
}
```
Request Body - Titular PF
```json
{
"account_owner": {
"address": {
"street": "Av. Brigadeiro Faria Lima",
"state": "SP",
"city": "São Paulo",
"neighborhood": "Jardim Paulistano",
"number": "2391",
"postal_code": "01452905",
"complement": "1o. Andar"
},
"birth_date": "1990-05-06",
"document_identification": "3c24579b-9810-4fa6-9b08-fe67d237160a",
"email": "ivanlima2604@gmail.com",
"individual_document_number": "34651104630",
"is_pep": false,
"mother_name": "Dona Maria Mariane",
"name": "Nome do Titular da Conta",
"nationality": "nationality",
"person_type": "natural",
"phone": {
"country_code": "055",
"area_code": "11",
"number": "999999999"
},
"proof_of_residence": "780456bd-1eec-4e5f-82c0-d8c3921497ea"
},
"signed_contract": {
"document_key": "4d7f4e29-4b58-4905-9a69-b1f9215263f5",
"signatures": [
{
"authenticity": {
"timestamp": "1970-01-01T00:00:01.080100Z",
"facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb",
"lang": "-35.8916627",
"lat": "-7.2226067",
"ip_address": "177.51.1.186",
"session_id": "jdifj329842"
},
"signer": {
"name": "Nome do Titular da Conta",
"email": "ivanlima2604@gmail.com",
"phone": {
"country_code": "055",
"area_code": "11",
"number": "999999999"
},
"document_number": "34651104630"
},
"authentication_type": "opt-in"
}
]
},
"destinations": [
{
"account_branch": "0001",
"account_number": "1234567",
"account_digit": "1",
"document_number": "04252012000123",
"name": "Conta do FIDC",
"ispb_number": "32402502",
"financial_institution_code_number": "329"
}
],
"additional_documents": ["b12c8807-8f3f-4083-9cb1-7cce641f3786"],
"guarantee_document_key": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d"
}
```
### Response
STATUS 201
Response Body
```json
{
"account_key": "e48eb139-448e-43b9-9aee-df5f4b51158c"
}
```
:::info ACCOUNT_KEY
A `account_key` será a chave única de identificação da conta. Toda interação com a conta se dará através dela.
:::
### Body Params Abertura de Conta
| Campo | Tipo | Descrição | Caracteres |
|----------------------------|--------|-----------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **account_owner** * | object | Informações completas do titular da conta | **[Objeto account_owner PJ](#objeto-account_owner-abertura-de-conta-pj)**
**[Objeto account_owner PF](#objeto-account_owner-abertura-de-conta-pf)** |
| **signed_contract** * | object | Objeto contendo os dados de contrato e dos assinantes do contrato da conta. | **[Objeto signed_contract](#objeto-signed_contract)** |
| **destinations** ** | list | Lista de contas destino autorizadas a receber transaferências. | **[Objeto destinations](#objeto-destinations)** |
| **additional_documents** | list | Lista de id's de documentos extras/opcionais . | Array de UUID's |
| **guarantee_document_key** | uuidv4 | DOCUMENT_KEY do PDF do documento de caução/garantia do contrato de conta escrow (enviado previamente). (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36 |
`(**) Obrigatório para conta Escrow`
### Objeto account_owner Abertura de Conta PJ
| Campo | Tipo | Descrição | Caracteres |
|-------------------------------|------------|-----------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|
| **address** * | object | Objeto endereço do titular da conta | **[Objeto address](#objeto-address)** |
| **cnae_code** * | string | Classificação Nacional de Atividades Econômicas | 9 |
| **company_document_number** * | string | CNPJ | 14 |
| **company_statute** * | uuidv4 | DOCUMENT_KEY do PDF do estatuto da empresa (enviado previamente). | 36 |
| **company_type** * | enumerator | Tipo da empresa | **[Enumeradores company_type](#enumeradores-company_type)** |
| **email** * | string | Email institucional da empresa. | 200 |
| **foundation_date** * | string | Data de abertura da empresa (formato "AAAA-MM-DD"). | 10 |
| **name** * | string | Razão social do titular da conta. | 50 |
| **person_type** * | enumerator | Identificador de que o objeto enviado é uma pessoa jurídica. Deve conter SEMPRE o valor "legal" para Objeto PJ. | **[Enumeradores person_type](#enumeradores-person_type)** |
| **phone** * | object | Telefone do titular da conta. | **[Objeto phone](#objeto-phone)** |
| **trading_name** * | string | Nome fantasia. | 200 |
| **company_representatives** * | list | Lista dos representantes legais da empresa | **[Objeto company_representatives](#objeto-company_representatives)** |
### Objeto account_owner Abertura de Conta PF
| Campo | Tipo | Descrição | Caracteres |
|----------------------------------|---------|-------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------|
| **address** | string | Objeto endereço do titular da conta | **[Objeto address](#objeto-address)** |
| **birth_date** * | string | Data de nascimento da pessoa (formato "AAAA-MM-DD") | - |
| **document_identification** * | uuidv4 | DOCUMENT_KEY do PDF do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) | 36 |
| **email** * | string | Email do titular da conta. | 200 |
| **individual_document_number** * | string | CPF da pessoa (apenas números). | 11 |
| **is_pep** * | boolean | Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep). | - |
| **mother_name** * | string | Nome da mãe do titular da conta. | - |
| **name** * | string | Nome do titular da conta. | - |
| **nationality** * | string | Nacionalidade do cliente. | - |
| **person_type** * | string | Identificador de que o objeto enviado é uma pessoa jurídica. Deve conter SEMPRE o valor "natural" para Objeto PF. | **[Enumeradores person_type](#enumeradores-person_type)** |
| **phone** | string | Objeto com dados do telefone do titular da conta | 36 |
| **proof_of_residence** | uuidv4 | DOCUMENT_KEY do PDF do comprovante de endereço do endereço enviado (enviado previamente). | |
### Objeto address
| Campo | Descrição | Exemplo | Caracteres |
|--------------------|-----------|-------------------------------------------------------------------------------------------|------------|
| **street** * | string | Rua do endereço | 500 |
| **state** * | enum | Estado do endereço (com dois caracteres maiúsculos) | 2 |
| **city** * | string | Cidade do endereço | 255 |
| **neighborhood** * | string | Bairro do endereço | 500 |
| **number** * | string | Número da rua | 10 |
| **postal_code** * | string | CEP do endereço (http://www.buscacep.correios.com.br/sistemas/buscacep/) (apenas números) | 8 |
| **complement** | string | Complemento do endereço (texto livre) | 500 |
### Objeto phone
| Campo | Descrição | Exemplo | Caracteres |
|--------------------|-----------|-------------------------------------------------------|--------------|
| **country_code** * | string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 |
| **area_code** * | string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 3 |
| **number** * | string | Número de telefone (apenas números) | 10 |
### Objeto company_representatives
| Campo | Tipo | Descrição | Caracteres |
|------------------------------------|---------|--------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
| **name** * | string | Nome do representante da empresa | 100 |
| **address** * | object | Objeto endereço do representante da empresa | **[Objeto address](#objeto-address)** |
| **email** * | string | Email do representante da empresa | 254 |
| **birth_date** * | string | Data de nascimento representante da empresa (formato "AAAA-MM-DD") | 10 |
| **individual_document_number** * | string | CPF do representante da empresa (apenas números). | 11 |
| **document_identification** * | uuidv4 | DOCUMENT_KEY do PDF do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) | 36 |
| **document_identification_number** | string | Número do documento de identificação com foto da pessoa (RG ou CNH) | 16 |
| **document_identification_type** | enum | Tipo do documento de identificação com foto da pessoa (RG ou CNH) | [Enumeradores document_identification_type](#enumeradores-document_identification_type) |
| **is_pep** * | boolean | Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep). | - |
| **final_beneficiary** | boolean | Declaração se o representante é beneficiário final da empresa. | - |
| **marital_status** | enum | Estado civil do representante da empresa | **[Enumeradores marital status](#enumeradores-marital_status)** |
| **mother_name** * | string | Nome da mãe do representante da empresa | 100 |
| **nationality** | string | Nacionalidade do representante da empresa | 50 |
| **person_type** * | enum | Identificador de que o objeto enviado é uma pessoa física | **[Enumeradores person_type](#enumeradores-person_type)** |
| **phone** * | object | Objeto com dados do telefone do representante da empresa | **[Objeto phone](#objeto-phone)** |
### Objeto signed_contract conta livre
| Campo | Tipo | Descrição | Caracteres |
|--------------------|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------|
| **document_key** * | uuidv4 | Chave única de identificação do documento do **Termo de Abertura de Conta** ou **Contrato de Conta Escrow**. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36 |
| **signatures** * | list | Dados de assinatura do documento enviado. Cada item da lista, corresponde a um assinante do documento. | [Objeto signatures](#objeto-signatures) |
### Objeto signatures
| Campo | Tipo | Descrição | Caracteres |
|--------------------|------------|------------------------------------------------------------------------------------|---------------------------------------------|
| **authenticity** * | object | Conjunto de dados que evidenciam a assinatura eletrônica realizada pelo assinante. | [Objeto authenticity](#objeto-authenticity) |
| **signer** * | object | Objeto contendo os dados de um dos assinantes do documento. | [Objeto signer](#objeto-signer) |
| **authentication_type** * | enumerator | Tipo de assinatura. Sempre será "**opt-in**" | "**opt-in**" |
### Objeto authenticity
| Campo | Tipo | Descrição | Caracteres |
|----------------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| **timestamp** * | string | Data e hora do momento da assinatura do documento. | 27 |
| **facial_recognition_key** | uuidv4 | Chave única de identificação da foto da selfie do titular da conta. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36 |
| **lang** | string | Coordenada de longitude da geolocalização do assinante capturada no momento da assinatura. | - |
| **lat** | string | Coordenada de latitude da geolocalização do assinante capturada no momento da assinatura. | - |
| **ip_address** | string | Endereço IP do dispositivo do assinante. | - |
| **session_id** | string | ID da seção do assinante no momento da assinatura. | - |
### Objeto signer
| Campo | Tipo | Descrição | Caracteres |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| **name** * | string | Nome do assinante. | - |
| **email** * | string | Email do assinante. | - |
| **phone** * | object | Objeto com dados do telefone do assinante | **[Objeto phone](#objeto-phone)** |
| **document_number** * | string | CPF do assinante. | 11 |
### Objeto destinations
| Campo | Tipo | Descrição | Caracteres |
|-----------------------------------------|--------|-----------------------------------------------------------------|------------|
| **account_branch** * | string | Número da Agência da conta destino. | 4 |
| **account_number** * | string | Número da conta destino. | - |
| **account_digit** * | string | Dígito verificador do número da conta destino. | 1 |
| **document_number** * | string | CPF/CNPJ do titular da conta destino. | - |
| **name** * | string | Nome/Razão Social do titular da conta destino. | - |
| **ispb_number** * | string | ISPB (base do CNPJ) da instituição financeira da conta destino. | 8 |
| **financial_institution_code_number** * | string | Código da instituição financeira da conta destino. | 3 |
### Enumeradores person_type
| Enum | Description |
|-------------|-------------------|
| **natural** | Pessoa física |
| **legal** | Pessoa jurídica |
### Enumeradores document_identification_type
| Enum | Description |
|---------|----------------------------------------|
| **rg** | RG - Registro Geral |
| **cnh** | CNH - Carteira Nacional de Habilitação |
### Enumeradores company_type
| Enum | Description |
|-------------------------|---------------------------------------------------------------------------|
| **ltda** | Limitada |
| **sa** | Sociedade Anônima |
| **micro_enterprise** | Micro Empresa |
| **freelancer** | Freelancer |
| **sa_opened** | Sociedade Anônima de Capital Aberto |
| **sa_closed** | Sociedade Anônima de Capital Fechado |
| **se_ltda** | Sociedade Empresária Limitada |
| **se_cn** | Sociedade Empresária em Nome Coletivo |
| **se_cs** | Sociedade Empresária em Comandita Simples |
| **se_ca** | Sociedade Empresária em Comandita por Ações |
| **scp** | Sociedade em Conta de Participação |
| **ei** | Empresário Individual |
| **ese** | Estabelecimento, no Brasil, de Sociedade Estrangeira |
| **eeab** | Estabelecimento, no Brasil, de Empresa Binacional Argentino-Brasileira |
| **ssp** | Sociedade Simples Pura |
| **ss_ltda** | Sociedade Simples Limitada |
| **ss_cn** | Sociedade Simples em Nome Coletivo |
| **ss_cs** | Sociedade Simples em Comandita Simples |
| **eireli_ne** | Empresa Individual de Responsabilidade Limitada (de Natureza Empresária) |
| **eireli_ns** | Empresa Individual de Responsabilidade Limitada (de Natureza Simples) |
| **eireli** | Empresa de Responsabilidade Individual |
| **mei** | Micro Empreendedor Individual |
| **me** | Micro Empresa |
| **cop** | Cooperativa |
| **private_association** | Sociedade Privada |
| **association** | Associação |
| **others** | Outros |
### Enumeradores marital_status
| Enum | Description |
|--------------|---------------|
| **single** | Solteiro(a) |
| **married** | Casado(a) |
| **widower** | Viúvo(a) |
| **divorced** | Divorciado(a) |
| **separated** | Separado(a) |
---
# Manual de Aditamento
URL: /documentation/aditamento/manual_aditamento
Este manual descreve o passo a passo envolvido no processo de aditamento. Trata-se do postergamento do prazo da dívida, em que ocorre a mudança na data de vencimento das parcelas e se mantém o número de contrato.
Nesse processo de aditamento, a `final_debt_key` retornada no webhook de desembolso é a nova chave da operação e, após esse processo, novos boletos das parcelas aditadas serão gerados.
O aditamento só é válido para operações pré-fixadas.
## 1 - Criação da operação de aditamento
O campo `desired_installments` é uma lista de objetos com o atributo `due_date`.
O campo de `calculate_delay` só está disponível no Response Body se for enviado na requisição de POST.
Nesse momento, como ainda não houve desembolso da operação originada do aditamento, os campos relacionados ao boleto, como `bank_slip_key`, `digitable_line`, `qr_code_key` e `qr_code_url`, serão nulos.
**1.1.** Simulação:
**Request**
ENDPOINT /amendment_simulation
MÉTODO POST
Request Body
```json
{
"amendment_debt_key": "\",
"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.** Criação:
**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": "\"
}
}
```
Em relação a simulação, o Response Body da criação se diferencia pela presença da `amendment_key`, da `amendment_status`, da `document_key` e da `document_url`.
Na criação do operação de aditamento, sempre se retorna o `amendment_status` como "waiting_signature".
## 2 - GET da operação de aditamento
**Request**
ENDPOINT /amendment/[AMENDMENT_KEY]
MÉTODO GET
O `amendment_key` que deve ser enviado para realização do GET é o valor do campo, de mesmo nome, retornado na criação da operação de aditamento e que representa a chave unitária característica do aditamento.
**Response**
Response Body
```json
{
"amendment_key": "\",
"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 - Cancelamento da operação de aditamento
**Request**
ENDPOINT /amendment/[AMENDMENT_KEY]
MÉTODO DELETE
O `amendment_key` que deve ser enviado para realização do DELETE é o valor do campo, de mesmo nome, retornado na criação da operação de aditamento e que representa a chave unitária característica do aditamento.
No DELETE do aditamento, não há payload de resposta e o status da operação de aditamento é alterado para "canceled".
## 4 - Webhooks
:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita.
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::
:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::
Abaixo estão descritos os webhooks que serão enviados nas situações de assinatura, de desembolso e de cancelamento da operação de aditamento.
**4.1.** Assinatura:
Body
```json
{
"webhook_type": "amendment",
"amendment_key": "\",
"event_datetime": "\",
"data": {
"amendment_status": "signed",
"document_key": "\",
"signed_document_url": "\"
}
}
```
**4.2.** Desembolso:
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.** Cancelamento:
Body
```json
{
"webhook_type": "amendment",
"amendment_key": "\",
"event_datetime": "\",
"data": {
"amendment_status": "canceled",
"cancel_reason": {
"enumerator": "\",
"description": "\",
"translation": "\"
}
}
}
```
A cancel_reason segue os seguintes enumeradores: **[Enumerador Cancel Reason](#enumerador-cancel-reason)**.
## 5 - Informações Gerais
A referência anterior nos campos `calendar_days` ou `workdays` é a data de desembolso na primeira parcela e a data de vencimento da parcela anterior nos demais casos.
O campo installments é uma lista preenchida de objetos. Nesse caso, para cada parcela do aditamento, deve haver um objeto com as respectivas informações.
| Campo | Tipo | Exemplo | Observações |
|---| ---| ---| ---|
| `additional_data` | json | { } | Não é obrigatório seu envio |
| `amendment_key` | string | 5fd3ecc8-1ea5-4d23-835c-37338da96181 | |
| `amendment_date` | string | "2023-06-05" | |
| `amendment_debt_key` | string | 31327efa-a96e-4a17-b703-e9fc39e17902 | |
| `amendment_status` | enumerador | **[Enumerador Amendment Status](#enumerador-amendment-status)** | |
| `annual_cet` | float | 0.0012 | |
| `annual_rate` | float | 0.0012 | |
| `bank_slip_key` | string | aea9ab16-d211-4c17-8f46-8a2669154a37 | |
| `business_due_date` | string | "2023-10-05" | |
| `calculate_delay` | bool | True | Não é obrigatório seu envio e é default como Falso |
| `calendar_days` | int | 27 | |
| `cet` | float | 0.0012 | |
| `daily_rate` | float | 0.0012 | |
| `digitable_line` | string | 32990001031000699925351000000201192690000055231 | |
| `document_key` | string | 7f49d9ff-0878-4d48-8cc3-cb0c3c6769d2 | |
| `document_url` | string | "https://storage.googleapis.com/sandbox-doc-api/documents/7f49d9ff-0878-4d48-8cc3-cb0c3c6769d2/image_166618030043.jpg" | |
| `due_date` | string | "2023-06-05" | |
| `due_interest` | float | 0.0 | |
| `due_principal` | float | 1000.10 | |
| `event_datetime` | string | "2023-05-05T22:20:10Z" | |
| `final_debt_key` | string | 8779a554-1ec9-40ec-8ff2-cbd52fc776ef | Essa é a nova debt key |
| `installment_number` | int | 3 | |
| `installment_key` | string | 1b65d775-b5ab-49d5-a833-46980387afb1 | |
| `interest_base` | enumerador | **[Enumerador Interest Base](#enumerador-interest-base)** | |
| `issue_amount` | float | 1000.00 | |
| `monthly_rate` | float | 0.0012 | |
| `number_of_installments` | int | 3 | |
| `post_fixed_amount` | int | 0 | Sempre zero, já que o aditamento só é válido para operações pré-fixadas |
| `pre_fixed_amount` | float | 2.00 | |
| `principal_amortization_amount` | float | 20.00 | |
| `qr_code_key` | string | 003590d0-29f8-4d18-93bb-a7c36f0f1785 | |
| `qr_code_url` | string | "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/cf7d2d2e-003a-4296-9daf-350864d282245204000053039865802BR5925QI SOCIEDADE DE CREDITO D6009Sao Paulo61080145200062070503***63047335"| |
| `signed_document_url` | string | "https://storage.googleapis.com/sandbox-doc-api/documents/7f49d9ff-0878-4d48-8cc3-cb0c3c6769d2/image_166618030043.jpg" | |
| `total_amount` | float | 100.00 | |
| `total_iof` | float | 11.03 | |
| `workdays` | int | 10 | |
### Enumerador _Interest Base_
| Enumerador | Descrição |
|-----------------------|---------------------------------------------------------------------------|
| **workdays** | Base de cálculo de juros em dias úteis considerando um ano de 252 dias |
| **calendar_days** | Base de cálculo de juros em dias corridos considerando um ano de 360 dias |
| **calendar_days_365** | Base de cálculo de juros em dias corridos considerando um ano de 365 dias |
### Enumerador _Amendment Status_
| Enumerador | Descrição |
|-----------------------|---------------------------------------------------------------------------|
| **waiting_signature** | Aguardando assinatura |
| **signed** | Assinada |
| **disbursed** | Desembolsada |
| **canceled** | Cancelada |
| **disbursing_error** | Erro no momento do desembolso |
:::caution Atenção!
O status 'disbursing_error' representa um status intermediário, o contrato de aditamento será cancelado ou desembolsado.
:::
### Enumerador _Cancel Reason_
| Enumerador | Descrição |
|---------------------------|------------------------------------------------------------------------------|
| **delete_amendment** | Requisição no endpoint de DELETE |
| **non_signed_amendment** | Operação de aditamento não foi assinada até a data de referência enviada (amendment_date) |
| **different_balance_due** | Saldo devedor diferente entre a criação da operação de aditamento e o desembolso |
| **different_installments_number** | Número de parcelas em aberto diferente entre a criação da operação de aditamento e o desembolso |
---
# arranjos_e_adquirentes
URL: /documentation/arranjos_e_adquirentes/
## Arranjos e Adquirentes
### Adquirentes
As adquirentes são empresas como a Stone, a Cielo e a Rede, e seu papel é liquidar as transações financeiras por meio de cartão de crédito e débito. Para isso, elas se comunicam com as bandeiras de cartão e os bancos emissores (como Nubank, Itaú, Santander etc.) para processar as transações.
Lista de adquirentes:
| Nome | CNPJ |
|---|---|
|BRB – BANCO DE BRASÍLIA S.A|208000100|
|CIELO S.A.|1027058000191|
|BANCO COOPERATIVO SICREDI S.A.|1181521000155|
|REDECARD S.A.|1425787000104|
|CREDICARD|1425787003383|
|VERDECARD ADMINISTRADORA DE CARTÕES S.A.|1722480000167|
|WORLDPAY DO BRASIL PROCESSAMENTO DE PAGAMENTOS LTDA|991143000102|
|BANCO COOPERATIVO DO BRASIL S.A.|2038232000164|
|CABAL BRASIL LTDA|3766873000106|
|CRED-SYSTEM|4670195000138|
|FD DO BRASIL SOLUÇÕES DE PAGAMENTO LTDA|4962772000165|
|PAGSEGURO INTERNET S.A.|8561701000101|
|ELO SERVIÇOS S.A|9227084000175|
|GETNET ADQUIRENCIA E SERVIÇOS PARA MEIOS DE PAGAMENTO S.A.|10440482000154|
|MERCADO.COM REPRESENTAÇÕES LTDA|10573521000515|
|ELAVON DO BRASIL SA|12592831000189|
|SAQUE E PAGUE REDE DE AUTOATENDIMENTO|12901364000121|
|HUB PAGAMENTOS S.A.|13884775000119|
|ADYEN DO BRASIL LTDA|14796606000190|
|STONE PAGAMENTOS S.A.|16501555000157|
|BANCO TRIÂNGULO S.A|17351180000159|
|CLOUDWALK MEIOS DE PAGAMENTOS E SERVICOS LTDA|18189547000142|
|BANCO BONSUCESSO S.A. ADQUIRENTE|20520298000178|
|BANCO BONSUCESSO S.A. ADQUIRENTE|20520298000178|
|STRIPE BRASIL SOLUÇÕES DE PAGAMENTO LTDA|22121209000146|
|BMG GRANITO SOLUÇÕES EM PAGAMENTO S.A|22177858000169|
|BOLT CARD CREDENCIADORA DE CARTAO DE CREDITO LTDA|28080769000186|
|BEN BENEFÍCIOS E SERVIÇOS S.A.|30798783000161|
|LISTO INSTITUIÇÃO DE PAGAMENTO LTDA|32971064000126|
|ACQIO ADQUIRÊNCIA S.A|33171211000146|
|BANCO SAFRA S.A.|58160789000128|
|BANCO SMARTBANK S.A.|58497702000102|
|SOROCRED MEIOS DE PAGAMENTO|60114865000100|
|BANCO CREFISA S.A|61033106000186|
|BANCO RENDIMENTO S.A|68900810000138|
|BANRISUL CARTÕES S.A|92934215000106|
|Global Payments - Servicos de Pagamentos S.a.|17887874000105|
|POVIG TECNOLOGIA EM PAGAMENTOS ELETRONICOS LTDA.|35524559000103|
### Arranjos de Pagamentos
Os arranjos de pagamentos são, basicamente, um conjunto de regras, regulamentos e processos que permitem a realização de serviços financeiros, como saques, transferências, emissão de cartão de crédito, débito e outras soluções de pagamento.
Lista de arranjos:
| Código | Descrição |
|---|---|
|ACC|Amex Cartão de Crédito|
|BCC|Banescard Cartão de Crédito|
|BCD|Banescard Cartão de Débito|
|BVV|Banescard Cartão de Débito|
|BVV|Ben Visa Vale|
|CAC|Cielo Amex Crédito|
|CBC|Cabal Crédito|
|CBD|Cabal Débito|
|CBP|Cabal Pré-pago|
|CDC|Cielo Diners Cartão de Crédito|
|CEC|Cielo Elo Cartão de Crédito|
|CED|Cielo Elo Cartão de Débito|
|CHC|Cielo Hipercard Crédito|
|CMC|Cielo Mastercard Crédito|
|CMD|Cielo Mastercard Débito|
|CZC|Credz Crédito|
|DCC|Diners Cartão de Crédito|
|ECC|Elo Cartão de Crédito|
|ECD|Elo Cartão de Débito|
|GCC|Goodcard Crédito|
|GDC|Global Payments Diners Crédito|
|GMC|Global Payments Mastercard Crédito|
|GMD|Global Payments Mastercard Débito|
|GVC|Global Payments Visa Crédito|
|GVD|Global Payments Visa Débito|
|HCC|Hipercard Cartão de Crédito|
|JCC|JCB Cartão de Crédito|
|MAC|Mais Cartão de Crédito|
|MCA|Mastercard Cartão ATM|
|MCC|Mastercard Cartão de Crédito|
|MCD|Mastercard Cartão de Débito|
|MCP|Mastercard Cartão Pré-pago|
|OCD|Ourocard Cartão de Débito|
|SCC|Sorocred Cartão de Crédito|
|SCD|Sorocred Cartão de Débito|
|VCA|Visa Cartão ATM|
|VCC|Visa Cartão de Crédito|
|VCD|Visa Cartão de Débito|
|VCP|Visa Cartão Pré-pago|
|VDC|Verdecard Cartão de Crédito|
|VIC|Visa Internacional Compra Crédito|
|VID|Visa Internacional Compra Débito|
|HCD|Hiper Débito|
|SIC|Sicredi|
|BRS|Banrisul|
|CUP|Cup Crédito|
|FRC|Fortbrasil|
|MXC|Maxifrota|
|SFC|Senff|
|TKC|TicketLog|
|BNC|Banese Card|
|BRC|Brasil Card|
|SPC|Sem Parar|
|CSC|Credi-Shop|
|DAC|Dacasa|
|AGC|Agiplan|
|AUC|Aura|
|RCC|Redesplan|
|AVC|Avista|
|CCD|Calcard|
|DBC|Discover|
|99T|Todas|
---
# Criar uma renegociação
URL: /documentation/arranjos_e_adquirentes/consulta_de_agenda
## Request
ENDPOINT /debt
MÉTODO POST
Request Body
```json
{
"notification_type": "webhook",
"owner_person_type": "legal",
"owner_person_name": "John Sample Inc",
"owner_document_number": "86498542000151",
"reference_code": "5830c2f9-fd17-4c9c-b30c-68ddd1a92751",
"signature": {
"signers": [
{
"name": "John Sample",
"email": "john.sample@yopmail.com",
"person_type": "natural",
"document_number": "42889916090"
}
]
},
"agenda": {
"acquirers": [
"cdc"
],
"card_schemes": [
"cdc"
],
"end_date": "2021-06-23",
"start_date": "2021-06-23"
}
}
```
:::caution Atenção!
O payload ultilizado na emissão de um refinanciamento é o mesmo ultilizado na emissã de uma divida simples, com a adição da lista de operações que serão quitadas em **"refinanced_credit_operations"**.
:::
### Body Params
| Campo | Tipo | Descrição | Máx. Caract. |
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **notification_type** * | enum | tipo de notificação | - |
| **owner_person_type** * | enum |Tipo de pessoa (natural ou juridica) objeto da consulta de agenda. | - |
| **owner_person_name** * | string | Nome do objeto da consulta de agenda. | - |
| **owner_document_number** * | string | Numero de documento do objeto da consulta de agenda. | - |
| **reference_code** * | object | Identificador único do opt-in. | - |
| **signature** * | object | Informações do opt-in. refinanciadas. | - |
| **agenda** * | object | Parâmetros para a consulta de agenda. | - |
## Definições
### Objeto agenda
| Campo | Tipo | Descrição | Máx. Caract. |
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **acquirers** * | array | Lista de números de documentos da Credenciadoras. | - |
| **card_schemes** * | array | Lista de arranjos de pagamento. | - |
| **end_date** * | string | Data de termino da consulta. | - |
| **start_date** * | string | Data de início da consulta. | - |
# Enumeradores
### Enumerador _Person Type_
| Enumerador | Descrição |
|------------------------|-----------------------|
| **legal** | Pessoa juridica |
| **natural** | Pesso física |
### Enumerador _Account Type_
| Enumerador | Descrição |
|------------------------|-----------------------|
| **webhook** | Conta corrente |
## Response
STATUS 200
Response Body
```json
{}
```
STATUS 400
Response Body
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
---
# trava_de_domicilio_bancario
URL: /documentation/arranjos_e_adquirentes/trava_de_domicilio_bancario
Caso o cliente deseje realizar uma operação de crédito com garantia em recebíveis, a QI Tech juntamente com a CERC, está preparada para criar essa operação de maneira muito semelhante ao fluxo de emissão de dívida comum.
# Criar uma renegociação
## Request
ENDPOINT /baas/debt_receivables
MÉTODO POST
Request Body
```json
{
"borrower": {
"name": "Alan Mathison Turing",
"email": "alan.turing@email.com",
"phone": {
"number": "912345678",
"area_code": "11",
"country_code": "055"
},
"is_pep": false,
"address": {
"city": "São Paulo",
"state": "SP",
"number": "1000",
"street": "Avenida Feliz",
"complement": "AP 801",
"postal_code": "49026100",
"neighborhood": "Centro"
},
"role_type": "issuer",
"birth_date": "1990-11-20",
"mother_name": "Nome da Mãe do Alan",
"nationality": "brasileiro",
"person_type": "natural",
"individual_document_number": "96969879003",
"document_identification": "494598fd-c226-4332-a500-591ae3884673"
},
"financial": {
"amount": 123456,
"interest_type": "pre_price_days",
"credit_operation_type": "ccb",
"annual_interest_rate": 2.32,
"disbursement_date": "2023-03-01",
"interest_grace_period": 0,
"principal_grace_period": 0,
"number_of_installments": 2,
"fine_configuration": {
"contract_fine_rate": 0.02,
"interest_base": "calendar_days",
"monthly_rate": 0.01
}
},
"disbursement_bank_account": {
"name": "Alan Mathison Turing",
"document_number": "96969879003",
"bank_code": "341",
"branch_number": "8615",
"account_number": "22110",
"account_digit": "2",
"account_type": "checking_account"
},
"purchaser_document_number": "32402502000135",
"contract": {
"payment_account": {
"account_number": "48391",
"account_branch": "0001",
"account_digit": "6",
"owner_document_number": "86498542000151"
},
"collaterals": [
{
"card_scheme": [
"abc"
],
"initial_date": "2021-06-28",
"final_date": "2021-07-06",
"division_rule": 2,
"encumbered_amount": 30
}
],
"collateral_management": {
"collateral_management_type": "absolute",
"amount": 2000,
"maximum_value": 2000,
"maximum_daily_value": 200,
"minimum_date": "2021-06-28",
"contract_payment_type": "partial_payment"
}
}
}
```
## Response
STATUS 200
Response Body
```json
{
"data": {
"additional_iof": 38000,
"annual_cet": "253,2642%",
"assignment_amount": 10000000,
"base_iof": 69331,
"borrower": {
"document_number": "89940878025962",
"name": "Parmalat"
},
"cet": "11,0900%",
"collaterals": [],
"contract": {
"external_contract_key": "2f0b8b6e-0b60-47f0-b27f-e291c028549b",
"number": "1907258737/P",
"signature_information": [
{
"signature_url": "https://sign.qitech.com.br/s/hNrwjda",
"signer_document_number": "94632180173",
"signer_email": "pedro.alves@yopmail.com",
"signer_external_key": "07a1c438-43a4-49a9-85a9-29667507453b",
"signer_name": "Pedro Felipe Henrique Alves",
"signer_role": "issuer"
},
{
"signature_url": "https://sign.qitech.com.br/s/EaTajda",
"signer_document_number": "34651104630",
"signer_email": "patricia.tereza@yopmail.com",
"signer_external_key": "61a1ea50-769a-410a-8ef8-09f0ce4611f6",
"signer_name": "Patrícia Tereza Bernardes",
"signer_role": "guarantor"
}
],
"urls": [
"https://storage.googleapis.com/sandbox-doc-api/documents/abedfeab-dcf8-4e13-897b-da02c222cef4/SALGADINHO_SALETE_LTDA-PARMALAT-CCB-1907258737-20220512165254.pdf"
]
},
"contract_fee_amount": 50000,
"contract_fees": [
{
"fee_amount": 50000,
"fee_type": "tac"
}
],
"external_contract_fee_amount": 0,
"external_contract_fees": [],
"installments": [
{
"additional_costs": [],
"advanced_paid_amount": 0,
"bank_slip_key": null,
"business_due_date": "2019-08-26",
"calendar_days": 32,
"digitable_line": null,
"due_date": "2019-08-26",
"due_interest": null,
"due_principal": 10000000,
"fine_amount": null,
"has_interest": true,
"installment_key": "81e4a732-d300-4e39-b6d5-2d9ac8df429b",
"installment_number": 1,
"installment_payment": [],
"installment_status": "created",
"installment_type": "principal",
"original_due_principal": 10000000,
"original_pre_fixed_amount": 1125598.54,
"original_principal_amortization_amount": 1000000,
"original_total_amount": null,
"paid_amount": 0,
"paid_at": null,
"payments": [],
"post_fixed_amount": null,
"pre_fixed_amount": 1125598.54,
"principal_amortization_amount": 1000000,
"tax_amount": 1312,
"total_amount": null,
"total_paid_amount": 0,
"workdays": 22
},
{
"additional_costs": [],
"advanced_paid_amount": 0,
"bank_slip_key": null,
"business_due_date": "2019-09-25",
"calendar_days": 30,
"digitable_line": null,
"due_date": "2019-09-25",
"due_interest": null,
"due_principal": 9000000,
"fine_amount": null,
"has_interest": true,
"installment_key": "bac4fe3e-9559-4380-9f4b-bdda3492738e",
"installment_number": 2,
"installment_payment": [],
"installment_status": "created",
"installment_type": "principal",
"original_due_principal": 9000000,
"original_pre_fixed_amount": 946509.06,
"original_principal_amortization_amount": 1000000,
"original_total_amount": null,
"paid_amount": 0,
"paid_at": null,
"payments": [],
"post_fixed_amount": null,
"pre_fixed_amount": 946509.06,
"principal_amortization_amount": 1000000,
"tax_amount": 2542,
"total_amount": null,
"total_paid_amount": 0,
"workdays": 22
},
{
"additional_costs": [],
"advanced_paid_amount": 0,
"bank_slip_key": null,
"business_due_date": "2019-10-25",
"calendar_days": 30,
"digitable_line": null,
"due_date": "2019-10-25",
"due_interest": null,
"due_principal": 8000000,
"fine_amount": null,
"has_interest": true,
"installment_key": "aaaec4d7-94a0-418d-8a8e-ac7af6787aec",
"installment_number": 3,
"installment_payment": [],
"installment_status": "created",
"installment_type": "principal",
"original_due_principal": 8000000,
"original_pre_fixed_amount": 841341.39,
"original_principal_amortization_amount": 1000000,
"original_total_amount": null,
"paid_amount": 0,
"paid_at": null,
"payments": [],
"post_fixed_amount": null,
"pre_fixed_amount": 841341.39,
"principal_amortization_amount": 1000000,
"tax_amount": 3772,
"total_amount": null,
"total_paid_amount": 0,
"workdays": 22
},
{
"additional_costs": [],
"advanced_paid_amount": 0,
"bank_slip_key": null,
"business_due_date": "2019-11-25",
"calendar_days": 31,
"digitable_line": null,
"due_date": "2019-11-25",
"due_interest": null,
"due_principal": 7000000,
"fine_amount": null,
"has_interest": true,
"installment_key": "bead5a38-c56e-4cfc-98f9-af6d71ec7d65",
"installment_number": 4,
"installment_payment": [],
"installment_status": "created",
"installment_type": "principal",
"original_due_principal": 7000000,
"original_pre_fixed_amount": 762003.23,
"original_principal_amortization_amount": 1000000,
"original_total_amount": null,
"paid_amount": 0,
"paid_at": null,
"payments": [],
"post_fixed_amount": null,
"pre_fixed_amount": 762003.23,
"principal_amortization_amount": 1000000,
"tax_amount": 5043,
"total_amount": null,
"total_paid_amount": 0,
"workdays": 20
},
{
"additional_costs": [],
"advanced_paid_amount": 0,
"bank_slip_key": null,
"business_due_date": "2019-12-26",
"calendar_days": 31,
"digitable_line": null,
"due_date": "2019-12-26",
"due_interest": null,
"due_principal": 6000000,
"fine_amount": null,
"has_interest": true,
"installment_key": "350a89e3-58a7-4879-b7ff-5fa0391da39c",
"installment_number": 5,
"installment_payment": [],
"installment_status": "created",
"installment_type": "principal",
"original_due_principal": 6000000,
"original_pre_fixed_amount": 653145.63,
"original_principal_amortization_amount": 1000000,
"original_total_amount": null,
"paid_amount": 0,
"paid_at": null,
"payments": [],
"post_fixed_amount": null,
"pre_fixed_amount": 653145.63,
"principal_amortization_amount": 1000000,
"tax_amount": 6314,
"total_amount": null,
"total_paid_amount": 0,
"workdays": 22
},
{
"additional_costs": [],
"advanced_paid_amount": 0,
"bank_slip_key": null,
"business_due_date": "2020-01-27",
"calendar_days": 32,
"digitable_line": null,
"due_date": "2020-01-27",
"due_interest": null,
"due_principal": 5000000,
"fine_amount": null,
"has_interest": true,
"installment_key": "bf935dc2-3151-4f66-91c6-35e446b57f2e",
"installment_number": 6,
"installment_payment": [],
"installment_status": "created",
"installment_type": "principal",
"original_due_principal": 5000000,
"original_pre_fixed_amount": 562799.27,
"original_principal_amortization_amount": 1000000,
"original_total_amount": null,
"paid_amount": 0,
"paid_at": null,
"payments": [],
"post_fixed_amount": null,
"pre_fixed_amount": 562799.27,
"principal_amortization_amount": 1000000,
"tax_amount": 7626,
"total_amount": null,
"total_paid_amount": 0,
"workdays": 20
},
{
"additional_costs": [],
"advanced_paid_amount": 0,
"bank_slip_key": null,
"business_due_date": "2020-02-26",
"calendar_days": 30,
"digitable_line": null,
"due_date": "2020-02-26",
"due_interest": null,
"due_principal": 4000000,
"fine_amount": null,
"has_interest": true,
"installment_key": "76aad8ce-3ee1-464c-90db-d72a2729560e",
"installment_number": 7,
"installment_payment": [],
"installment_status": "created",
"installment_type": "principal",
"original_due_principal": 4000000,
"original_pre_fixed_amount": 420670.69,
"original_principal_amortization_amount": 1000000,
"original_total_amount": null,
"paid_amount": 0,
"paid_at": null,
"payments": [],
"post_fixed_amount": null,
"pre_fixed_amount": 420670.69,
"principal_amortization_amount": 1000000,
"tax_amount": 8856,
"total_amount": null,
"total_paid_amount": 0,
"workdays": 20
},
{
"additional_costs": [],
"advanced_paid_amount": 0,
"bank_slip_key": null,
"business_due_date": "2020-03-25",
"calendar_days": 28,
"digitable_line": null,
"due_date": "2020-03-25",
"due_interest": null,
"due_principal": 3000000,
"fine_amount": null,
"has_interest": true,
"installment_key": "fc190222-5baf-4023-9e93-95b25774a37e",
"installment_number": 8,
"installment_payment": [],
"installment_status": "created",
"installment_type": "principal",
"original_due_principal": 3000000,
"original_pre_fixed_amount": 293473.82,
"original_principal_amortization_amount": 1000000,
"original_total_amount": null,
"paid_amount": 0,
"paid_at": null,
"payments": [],
"post_fixed_amount": null,
"pre_fixed_amount": 293473.82,
"principal_amortization_amount": 1000000,
"tax_amount": 10004,
"total_amount": null,
"total_paid_amount": 0,
"workdays": 20
},
{
"additional_costs": [],
"advanced_paid_amount": 0,
"bank_slip_key": null,
"business_due_date": "2020-04-27",
"calendar_days": 33,
"digitable_line": null,
"due_date": "2020-04-27",
"due_interest": null,
"due_principal": 2000000,
"fine_amount": null,
"has_interest": true,
"installment_key": "7c2972a8-def7-4b76-b215-0ade0a5bca13",
"installment_number": 9,
"installment_payment": [],
"installment_status": "created",
"installment_type": "principal",
"original_due_principal": 2000000,
"original_pre_fixed_amount": 232548.93,
"original_principal_amortization_amount": 1000000,
"original_total_amount": null,
"paid_amount": 0,
"paid_at": null,
"payments": [],
"post_fixed_amount": null,
"pre_fixed_amount": 232548.93,
"principal_amortization_amount": 1000000,
"tax_amount": 11357,
"total_amount": null,
"total_paid_amount": 0,
"workdays": 21
},
{
"additional_costs": [],
"advanced_paid_amount": 0,
"bank_slip_key": null,
"business_due_date": "2020-05-25",
"calendar_days": 28,
"digitable_line": null,
"due_date": "2020-05-25",
"due_interest": null,
"due_principal": 1000000,
"fine_amount": null,
"has_interest": true,
"installment_key": "d848c880-f489-4bc1-a9e4-101f8d664317",
"installment_number": 10,
"installment_payment": [],
"installment_status": "created",
"installment_type": "principal",
"original_due_principal": 1000000,
"original_pre_fixed_amount": 97824.6,
"original_principal_amortization_amount": 1000000,
"original_total_amount": null,
"paid_amount": 0,
"paid_at": null,
"payments": [],
"post_fixed_amount": null,
"pre_fixed_amount": 97824.6,
"principal_amortization_amount": 1000000,
"tax_amount": 12505,
"total_amount": null,
"total_paid_amount": 0,
"workdays": 19
}
],
"iof_charge_method": "financed",
"issue_amount": 10000000,
"net_external_contract_fee_amount": 0,
"number_of_installments": 10,
"post_fixed_interest_base": "workdays",
"post_fixed_interest_rate": 1,
"prefixed_interest_rate": {
"annual_rate": 2.32,
"created_at": null,
"daily_rate": 0.0033388,
"interest_base": "calendar_days",
"monthly_rate": 0.10516767
},
"requester_identifier_key": "b7ddbcfb-3de0-49d8-8014-07972d8b27f2",
"total_iof": 107331,
"total_pre_fixed_amount": 5935915.16
},
"event_datetime": "2022-05-12 16:53:10",
"key": "b7ddbcfb-3de0-49d8-8014-07972d8b27f2",
"status": "waiting_signature",
"webhook_type": "debt"
}
```
:::caution Atenção!
O payload ultilizado na emissão de um refinanciamento é o mesmo ultilizado na emissã de uma divida simples, com a adição da lista de operações que serão quitadas em **"refinanced_credit_operations"**.
:::
### Body Params
| Campo | Tipo | Descrição | Máx. Caract. |
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **borrower** * | object | **[Objeto Borrower](#objeto-borrower)** - Devedor da operação de crédito. | - |
| **disbursement_bank_account** * | object | **[Objeto Disbursement Bank Account](#objeto-disbursement_bank_accounts)** - Dados da conta bancária para desembolso da operação. | - |
| **financial** * | object | **[Objeto Financial](#objeto-financial)** - Dados da conta bancária para desembolso da operaçãoIdentificador de que o objeto enviado é uma pessoa física. Deve conter SEMPRE o valor "natural" para borrower PF. | - |
| **purchaser_document_number** * | string | CNPJ do cessionário (comprador) da operação de crédito. | - |
| **refinanced_credit_operations** * | array of objects | Lista de **[Objetos Refinanced Credit Operations](#objeto-refinanced_credit_operations)** contendo as operações refinanciadas. | - |
## Definições
### Objeto Request Body
| Campo | Tipo | Descrição | Máx. Caract. |
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **borrower** * | object | **[Objeto Borrower](#objeto-borrower)** - Devedor da operação de crédito | - |
| **disbursement_bank_account** * | object | **[Objeto Disbursement Bank Account](#objeto-disbursement_bank_accounts)** - Dados da conta bancária para desembolso da operação | - |
| **financial** * | object | **[Objeto Financial](#objeto-financial)** - Dados da conta bancária para desembolso da operaçãoIdentificador de que o objeto enviado é uma pessoa física. Deve conter SEMPRE o valor "natural" para borrower PF | - |
| **purchaser_document_number** * | string | CNPJ do cessionário (comprador) da operação de crédito | - |
| **contract** * | object | **[Objeto Financial](#objeto-contract)** com dados da garantia. | - |
### Objeto Borrower
| Campo | Tipo | Descrição | Máx. Caract. |
|----------------------------------|---------|---------------------------------------------------------------------------------------|--------------|
| **name** * | string | Nome do devedor | 100 |
| **email** | string | Email do devedor | 254 |
| **phone** | object | **[Objeto Phone](#objeto-phone)** - Telefone de contato do devedor | - |
| **is_pep** * | boolean | Indicador de PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep) | - |
| **address** * | object | **[Objeto Address](#objeto-address)** - Endereço do devedor | - |
| **role_type** * | enum | default: _issuer_ | - |
| **birth_date** * | date | Data de nascimento do devedor (formato "AAAA-MM-DD") | - |
| **mother_name** * | string | Nome da mãe do devedor | 100 |
| **nationality** | string | Nacionalidade do devedor | 50 |
| **person_type** * | string | Indicador de pessoa física - default: _natural_ | - |
| **individual_document_number** * | string | CPF do devedor (apenas números) | 11 |
| **document_identification** * | string | **DOCUMENT_KEY** do PDF do documento de identificação do devedor com foto (RG ou CNH) | - |
| **document_identification_back** |string | DOCUMENT_KEY do PDF da parte de trás do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente). | 11 |
| **wedding_certificate** | string | DOCUMENT_KEY do PDF do certificado de casamento da pessoa (enviado previamente). No caso de marital_status ser "single", o valor deste campo deve ser NULL. | 11 |
| **proof_of_residence** * |string | DOCUMENT_KEY do PDF do comprovante de endereço do endereço enviado (enviado previamente). | 11 |
### Objeto Address
| Campo | Tipo | Descrição | Máx. Caract. |
|--------------------|--------|--------------------------------------------------------------------------|--------------|
| **city** * | string | Cidade do endereço | 100 |
| **state** * | string | Estado do endereço (com dois caracteres maiúsculos) | 2 |
| **number** * | string | Número do endereço | 10 |
| **street** * | string | Rua do endereço | 100 |
| **complement** * | string | Complemento do endereço (texto livre) | 100 |
| **postal_code** * | string | CEP do endereço (http://www.buscacep.correios.com.br/sistemas/buscacep/) | 8 |
| **neighborhood** * | string | Bairro do endereço | 100 |
### Objeto Phone
| Campo | Descrição | Exemplo | Máx. Caract. |
|--------------------|-----------|-------------------------------------------------------|--------------|
| **number** * | string | Número de telefone | 10 |
| **area_code** * | string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2 |
| **country_code** * | string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 |
### Objeto Disbursement Bank Account
Uma emissão de dívida deve conter as informações bancárias para desembolso, por padrão, uma conta de titularidade do devedor.
| Campo | Tipo | Descrição | Máx. Caract. |
|-----------------------|--------|----------------------------------------------------------------------------------------------------|--------------|
| name | string | Nome do titular da conta | 50 |
| document_number | string | CPF do titular da conta | 11 |
| bank_code * | string | Código COMPE da instituição financeira (https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf) | 3 |
| branch_number * | string | Número da agência (não informar o dígito verificador da agência!) | 4 |
| account_number * | string | Número da conta (sem o dígito verificador da conta!) | 10 |
| account_digit * | string | Dígito verificador da conta (informar zero no lugar de letras) | 1 |
| account_type | enum | [Enumerador Account Type](#enumerador-account-type) Tipo da conta | 1 |
### Objeto Financial
O objeto financial descreve as informações financeiras da operação de crédito.
| Campo | Tipo | Descrição | Máx. Caract. |
|----------------------------|--------|---------------------------------------------------------------------------------------------------------------|--------------|
| **amout** | float | Valor de emissão/nominal da operação de crédito | - |
| **interest_type** | object | **[Enumerador Interest Type](#enumerador-interest-type)** - Método de amortização e forma de cálculo de juros | - |
| **credit_operation_type** | object | **[Enumerador Credit Operation Type](#enumerador-credit-operation-type)** - Tipo do contrato de crédito | - |
| **annual_interest_rate** | float | Taxa de juros pré-fixada expressa em decimal ao ano | - |
| **disbursement_date** | date | Data do desembolso da operação | - |
| **interest_grace_period** | int | Carência de juros (em meses) | - |
| **principal_grace_period** | int | Período carência de principal | - |
| **number_of_installments** | int | Número de parcelas da operação de crédito | - |
| **fine_configuration** | object | **[Objeto Fine Configuration](#objeto-fine-configuration)** - Configuração de juros e multa por atraso | - |
### Objeto Fine Configuration
No Objeto Fine Configuration são informados os valor de multa e juros por atraso da operação de crédito.
| Campo | Tipo | Descrição | Máx. Caract. |
|------------------------|-------|--------------------------------------------------------------------------------------|--------------|
| **contract_fine_rate** | float | Percentual de multa por atraso | - |
| **interest_base** | enum | **[Enumerador Interest Base](#enumerador-interest-base)** - Base de cálculo de juros | - |
| **monthly_rate** | float | Percentual de juros de atraso ao mês | - |
### Objeto Contract
O objeto financial descreve as informações financeiras da operação de crédito.
| Campo | Tipo | Descrição | Máx. Caract. |
|----------------------------|--------|---------------------------------------------------------------------------------------------------------------|--------------|
| **payment_account** | object | Conta de pagamentos para os recebíveis. | - |
| **collaterals** | array | Listas de garantias. | - |
| **collateral_management** | object | **[Objeto Collateral Management](#objeto-collateral-management)** - Configurações de garantia. | - |
### Objeto Collateral Management
O objeto financial descreve as informações financeiras da operação de crédito.
| Campo | Tipo | Descrição | Máx. Caract. |
|----------------------------|--------|---------------------------------------------------------------------------------------------------------------|--------------|
| **collateral_management_type** | enum | **[Enumerador Collateral Management Type](#enumerador-collateral-management-type)** - Tipo de gestão a ser utilizada para amortizar a divida. | - |
| **amount** | float | Valor a ser utilizado. | - |
| **maximum_value** | float | Valor máximo que será utilizado para pagamento da operação. | - |
| **maximum_daily_value** | float | Valor máximo que será utilizado por dia. | - |
| **minimum_date** | string | Data mínima para começar à utilizar os recebiveis. | - |
| **contract_payment_type** | enum | **[Enumerador Credit Operation Type](#enumerador-credit-operation-type)** - Tipo de pagamento para o contrato | - |
# Enumeradores
### Enumerador _Person Type_
| Enumerador | Descrição |
|------------------------|-----------------------|
| **legal** | Pessoa juridica |
| **natural** | Pesso física |
### Enumerador _Account Type_
| Enumerador | Descrição |
|------------------------|-----------------------|
| **checking_account** | Conta corrente |
| **deposit_account** | Conta de depósito |
| **guaranteed_account** | Conta de garantia |
| **investment_account** | Conta de investimento |
| **payment_account** | Conta de pagamento |
| **saving_account** | Conta poupança |
| **salary_account** | Conta salário |
### Enumerador _Interest Type_
| Enumerador | Descrição |
|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **pre_price_days** | Método de amortização Price (parcelas iguais) com cálculo do juros pré-fixado ao dia |
| **pre_price** | Método de amortização Price (parcelas iguais) com cálculo do juros pré-fixado em períodos fixos (30 dias) |
| **pre_sac** | Método de amortização SAC (amortização constante) com cálculo do juros pré-fixado ao dia |
| **post_sac** | Método de amortização SAC (amortização constante) com cálculo do juros baseado em uma taxa pré-fixada + indexador pós-fixado (cdi, ipca ou igpm) ao dia |
| **post_price** | Método de amortização Price (parcelas iguais) com cálculo do juros baseado em uma taxa pré-fixada + indexador pós-fixado (cdi, ipca ou igpm) em períodos fixos (30 dias) |
| **post_price_days** | Método de amortização Price (parcelas iguais) com cálculo do juros baseado em uma taxa pré-fixada + indexador pós-fixado (cdi, ipca ou igpm) ao dia |
### Enumerador _Credit Operation Type_
| Enumerador | Descrição |
|---------------|--------------------------------|
| **ccb** | Cédula de Crédito Bancário |
| **cce** | Cédula de Crédito à Exportação |
| **cci** | Cédula de Crédito Imobiliário |
| **nce** | Nota de Crédito à Exportação |
### Enumerador _Interest Base_
| Enumerador | Descrição |
|-----------------------|---------------------------------------------------------------------------|
| **workdays** | Base de cálculo de juros em dias úteis considerando um ano de 252 dias |
| **calendar_days** | Base de cálculo de juros em dias corridos considerando um ano de 360 dias |
| **calendar_days_365** | Base de cálculo de juros em dias corridos considerando um ano de 365 dias |
### Enumerador _Fee Type_
Cada tipo de fee deve ser previamente habilitado e configurado pela QI Tech
| Enumerador | Descrição |
|-----------------------|----------------------------------------------------------------------------|
| **tac** | Tarifa de abertura de cadastro |
| **spread** | Ágio cobrado no valor de aquisição da operação de crédito |
| **warranty_analysis** | Tarifa de análise de garantias |
| **ted_fee** | Tarifa de TED |
| **spread_ted_fee** | Ágio da tarifa de TED cobrado no valor de aquisição da operação de crédito |
### Enumerador _Collateral Management Type_
| Enumerador | Descrição |
|------------------------|-----------------------|
| **absolute** | Valor absoluto |
| **percentage** | Valor percentual |
### Enumerador _Person Type_
| Enumerador | Descrição |
|------------------------|-----------------------|
| **partial_payment** | Pagamento parcial |
| **total_payment** | Pagamento total |
| **monthly_payment** | Pagamento mensal |
## Response
STATUS 200
Response Body
```json
{
"data": {
"additional_iof": 469.1328,
"annual_cet": "283,3821%",
"assignment_amount": 124690.56,
"base_iof": 473.6829374063069,
"borrower": {
"document_number": "96969879003",
"name": "Alan Mathison Turing"
},
"cet": "11,8500%",
"collaterals": [],
"contract": {
"number": "0000067563/AMT",
"signature_information": [
{
"signature_url": null,
"signer_document_number": "15627918004",
"signer_email": "alan.turing@email.com",
"signer_external_key": null,
"signer_name": "Alan Mathison Turing",
"signer_role": "issuer"
}
],
"urls": [
"https://storage.googleapis.com/sandbox-doc-api/documents/5af36fcd-8e4c-4421-ad45-7bcba899c0d3/SYNGENTASANDBOX-ALAN_MATHISON_TURING-CCB-0000067563-20230302234816.pdf"
]
},
"contract_fee_amount": 1234.56,
"contract_fees": [
{
"fee_amount": 1234.56,
"fee_type": "tac"
}
],
"external_contract_fee_amount": 1234.56,
"external_contract_fees": [
{
"fee_amount": 1234.56,
"fee_type": "spread",
"net_fee_amount": 1120.36,
"tax_amount": 114.2
}
],
"installments": [
{
"accrual_reference_date": null,
"additional_costs": [],
"advanced_paid_amount": 0,
"bank_slip_key": null,
"business_due_date": "2023-04-03",
"calendar_days": 31,
"digitable_line": null,
"due_date": "2023-04-02",
"due_interest": 0,
"due_principal": 123456,
"fine_amount": null,
"has_interest": true,
"installment_history": [],
"installment_key": "da264e95-2bbd-47de-876b-bfea7d25e266",
"installment_number": 1,
"installment_payment": [],
"installment_status": "created",
"installment_type": "principal",
"original_due_principal": 123456,
"original_pre_fixed_amount": 13245.468714162304,
"original_principal_amortization_amount": 58473.151285837695,
"original_total_amount": 71718.62,
"paid_amount": 0,
"paid_at": null,
"post_fixed_amount": 0,
"pre_fixed_amount": 13245.468714162304,
"principal_amortization_amount": 58473.151285837695,
"qr_code_key": null,
"qr_code_url": null,
"renegotiation_proposal_key": null,
"tax_amount": 148.63875056859942,
"total_accrual_amount": null,
"total_amount": 71718.62,
"total_paid_amount": 0,
"workdays": 21
},
{
"accrual_reference_date": null,
"additional_costs": [],
"advanced_paid_amount": 0,
"bank_slip_key": null,
"business_due_date": "2023-05-02",
"calendar_days": 30,
"digitable_line": null,
"due_date": "2023-05-02",
"due_interest": 0,
"due_principal": 64982.848714162305,
"fine_amount": null,
"has_interest": true,
"installment_history": [],
"installment_key": "cac7064b-2310-45e1-a91f-5e8f39f0f0ea",
"installment_number": 2,
"installment_payment": [],
"installment_status": "created",
"installment_type": "principal",
"original_due_principal": 64982.848714162305,
"original_pre_fixed_amount": 6735.77577015044,
"original_principal_amortization_amount": 64982.84422984956,
"original_total_amount": 71718.62,
"paid_amount": 0,
"paid_at": null,
"post_fixed_amount": 0,
"pre_fixed_amount": 6735.77577015044,
"principal_amortization_amount": 64982.84422984956,
"qr_code_key": null,
"qr_code_url": null,
"renegotiation_proposal_key": null,
"tax_amount": 325.0441868377075,
"total_accrual_amount": null,
"total_amount": 71718.62,
"total_paid_amount": 0,
"workdays": 19
}
],
"iof_charge_method": "financed",
"issue_amount": 123456,
"net_external_contract_fee_amount": 1120.36,
"number_of_installments": 2,
"prefixed_interest_rate": {
"annual_rate": 2.32,
"created_at": "2023-03-02T23:48:15",
"daily_rate": 0.00329298,
"interest_base": "calendar_days_365",
"monthly_rate": 0.10516767
},
"requester_identifier_key": "1c2ca4dc-2a20-4dd4-bd5f-af143fadadf4",
"total_iof": 942.82,
"total_pre_fixed_amount": 19981.244484312745
},
"event_datetime": "2023-03-02 23:48:20",
"key": "1c2ca4dc-2a20-4dd4-bd5f-af143fadadf4",
"status": "waiting_signature",
"webhook_type": "debt"
}
```
STATUS 400
Response Body
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
---
# emissao_de_divida
URL: /documentation/auxilio_brasil/emissao_de_divida
## Emissão de dívida
## Request
- ENDPOINT /debt
- MÉTODO POST
- BODY (antes de ser assinado):
YOUR REQUEST HISTORY
**body.json**
```json
{
"borrower": {
"person_type": "natural",
"name": "Qi Tech Ltda.",
"mother_name": "Maria Mariane",
"birth_date": "1990-05-06",
"profession": "Deputada",
"nationality": "nationality",
"marital_status": "married",
"wedding_certificate": "56ab7849-4d90-490b-b539-96ac3c5a619b",
"spouse": {
"person_type": "natural",
"name": "Qi Tech Ltda.",
"mother_name": "Maria Mariane",
"birth_date": "1990-05-06",
"profession": "Deputada",
"nationality": "nationality",
"marital_status": "married",
"wedding_certificate": "56ab7849-4d90-490b-b539-96ac3c5a619b",
"is_pep": False,
"individual_document_number": "34651104630",
"document_identification": "3c24579b-9810-4fa6-9b08-fe67d237160a",
"document_identification_back": "2f43456a-3664-4805-82b8-96a2ec72c04c",
"document_identification_type": "cnh",
"document_identification_number": "232479719",
"email": "api@qitech.com.br",
"phone": {
"country_code": "055",
"area_code": "11",
"number": "999999999"
},
"proof_of_residence": "780456bd-1eec-4e5f-82c0-d8c3921497ea",
"address": {
"street": "Av. Brigadeiro Faria Lima",
"state": "SP",
"city": "São Paulo",
"neighborhood": "Jardim Paulistano",
"number": "2391",
"postal_code": "01452905",
"complement": "1o. Andar"
}
},
"is_pep": False,
"individual_document_number": "34651104630",
"document_identification": "3c24579b-9810-4fa6-9b08-fe67d237160a",
"document_identification_back": "2f43456a-3664-4805-82b8-96a2ec72c04c",
"document_identification_type": "cnh",
"document_identification_number": "232479719",
"email": "api@qitech.com.br",
"phone": {
"country_code": "055",
"area_code": "11",
"number": "999999999"
},
"proof_of_residence": "780456bd-1eec-4e5f-82c0-d8c3921497ea",
"address": {
"street": "Av. Brigadeiro Faria Lima",
"state": "SP",
"city": "São Paulo",
"neighborhood": "Jardim Paulistano",
"number": "2391",
"postal_code": "01452905",
"complement": "1o. Andar"
}
},
"financial": {
"interest_type": "pre_price_days",
"disbursement_start_date": "2019-07-25",
"disbursement_end_date": "2019-07-29",
"fine_configuration": {
"contract_fine_rate": 0.02,
"interest_base": "workdays",
"monthly_rate": 0.01
},
"annual_interest_rate": 0.02,
"credit_operation_type": "ccb",
"interest_grace_period": 0,
"number_of_installments": 10,
"principal_grace_period": 0
}
}
```
### Body Params
| Campo | Descrição |
|---|---|
| `borrower` *(obrigatório)* | Dados do mutuário. |
| `guarantors` | Garantidores da operação (que pode ser uma lista de Objeto PF e/ou Objeto PJ e não é um campo obrigatório). |
| `collaterals` *(obrigatório)* | Informações das parcelas de pagamento. |
| `financial` *(obrigatório)* | O objeto financeiro descreve as informações financeiras da emissão. Aqui são definidas a taxa de juros, carência e valor da dívida entre outros. |
| `disbursement_bank_accounts` | Lista de informações bancárias para o desembolso (Objeto Conta Bancária). |
### BORROWER OBJECT
| Campo | Descrição |
|---|---|
| `person_type` *(obrigatório)* | Identificador de que o objeto enviado é uma pessoa física ou jurídica. |
| `name` *(obrigatório)* | Nome da pessoa. Limitado a 100 caracteres. |
| `mother_name` | mother_name |
| `birth_date` | Data de nascimento da pessoa (formato "AAAA-MM-DD") |
| `profession` | Profissão da pessoa |
| `nationality` | Nacionalidade do cliente. Limitado a 50 caracteres. |
| `marital_status` | Estado civil do cliente. |
| `property_system` | Regime de separação de bens (obrigatório apenas para pessoas com marital_status "married"). |
| `wedding_certificate` | DOCUMENT_KEY do PDF do certificado de casamento da pessoa (enviado previamente). No caso de marital_status ser "single", o valor deste campo deve ser NULL.|
| `spouse` | Objeto PF do esposo/esposa da pessoa (obrigatório apenas quando "compulsory_separation_of_goods" for "total_communion_of_goods", "partial_communion_of_goods", "final_participation_of_acquisitions" ou "compulsory_separation_of_goods"). No caso de marital_status ser "single", o valor deste campo deve ser NULL. |
| `is_pep` *(obrigatório)* | Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep) valor booleano |
| `individual_document_number` | CPF da pessoa (apenas números) |
| `document_identification` *(obrigatório)* | DOCUMENT_KEY do PDF do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) |
| `document_identification_back` | DOCUMENT_KEY do PDF da parte de trás do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) |
| `document_identification_type` | Tipo do documento de identificação. Valores aceitos: `rg`, `rne`, `cnh`, `ctps`, `class_document`, `passport`, `other`, `cin`. Quando `cin`, o campo `document_identification_number` deve ser igual ao CPF. |
| `document_identification_number` *(obrigatório)* | Número do documento de identificação da pessoa enviado em document_identification. Quando `document_identification_type` for `cin`, deve ser igual ao CPF. |
| `email` | Email da pessoa |
| `phone` | Telefone da pessoa |
| `address` | Endereço da pessoa |
| `proof_of_residence` *(obrigatório)* | DOCUMENT_KEY do PDF do comprovante de endereço do endereço enviado (enviado previamente) |
### GUARANTORS OBJECT
| Campo | Descrição |
|---|---|
| `person_type` *(obrigatório)* | Identificador de que o objeto enviado é uma pessoa física ou jurídica. |
| `name` *(obrigatório)* | Nome da pessoa. Limitado a 100 caracteres. |
| `mother_name` *(obrigatório)* | Nome da mãe do cliente em caso de PF. Limitado a 100 caracteres. |
| `birth_date` *(obrigatório)* | Data de nascimento da pessoa (formato "AAAA-MM-DD") |
| `profession` *(obrigatório)* | Profissão do cliente. Limitado a 64 caracteres. |
| `nationality` *(obrigatório)* | Nacionalidade do cliente. Limitado a 50 caracteres. |
| `marital_status` *(obrigatório)* | Estado civil do cliente. |
| `property_system` | Regime de separação de bens (obrigatório apenas para pessoas com marital_status "married"). |
| `wedding_certificate` *(obrigatório)* | DOCUMENT_KEY do PDF do certificado de casamento da pessoa (enviado previamente). No caso de marital_status ser "single", o valor deste campo deve ser NULL. |
| `spouse` *(obrigatório)* | Objeto PF do esposo/esposa da pessoa (obrigatório apenas quando "compulsory_separation_of_goods" for "total_communion_of_goods", "partial_communion_of_goods", "final_participation_of_acquisitions" ou "compulsory_separation_of_goods"). No caso de marital_status ser "single", o valor deste campo deve ser NULL. |
| `is_pep` *(obrigatório)* | Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep). |
| `individual_document_number` *(obrigatório)* | CPF da pessoa (apenas números). Limitado a 11 caracteres. |
| `document_identification` *(obrigatório)* | DOCUMENT_KEY do PDF do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) |
| `document_identification_back` | DOCUMENT_KEY do PDF da parte de trás do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) |
| `document_identification_type` | Qual o tipo do documento de identificação enviado. |
| `document_identification_number` *(obrigatório)* | Número do documento de identificação da pessoa enviado em "document_identification". Limitado a 16 caracteres. |
| `email` | Email da pessoa |
| `phone` | Telefone da pessoa |
| `proof_of_residence` *(obrigatório)* | DOCUMENT_KEY do PDF do comprovante de endereço do endereço enviado (enviado previamente) |
| `address` | Endereço da pessoa |
### SPOUSE OBJECT
| Campo | Descrição |
|---|---|
| `person_type` *(obrigatório)* | Identificador de que o objeto enviado é uma pessoa física. Deve conter SEMPRE o valor "natural" para Objeto PF |
| `name` *(obrigatório)* | Nome da pessoa |
| `mother_name` *(obrigatório)* | mother_name |
| `birth_date` *(obrigatório)* | Data de nascimento da pessoa (formato "AAAA-MM-DD") |
| `profession` *(obrigatório)* | Profissão da pessoa |
| `nationality` *(obrigatório)* | Nacionalidade da pessoa |
| `marital_status` *(obrigatório)* | Estado civil da pessoa: "single", "married", "widower" ou "divorced" |
| `property_system` | Regime de separação de bens (obrigatório apenas para pessoas com marital_status "married"): "total_communion_of_goods", "partial_communion_of_goods", "total_separation_of_goods", "final_participation_of_acquisitions" ou "compulsory_separation_of_goods" |
| `wedding_certificate` *(obrigatório)* | DOCUMENT_KEY do PDF do certificado de casamento da pessoa (enviado previamente). No caso de marital_status ser "single", o valor deste campo deve ser null |
| `spouse` *(obrigatório)* | Objeto PF do esposo/esposa da pessoa (obrigatório apenas quando "compulsory_separation_of_goods" for "total_communion_of_goods", "partial_communion_of_goods", "final_participation_of_acquisitions" ou "compulsory_separation_of_goods"). No caso de marital_status ser "single", o valor deste campo deve ser null |
| `is_pep` *(obrigatório)* | Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep) valor booleano |
| `individual_document_number` *(obrigatório)* | CPF da pessoa (apenas números) |
| `document_identification` *(obrigatório)* | DOCUMENT_KEY do PDF do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) |
| `document_identification_back` | DOCUMENT_KEY do PDF da parte de trás do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) |
| `document_identification_type` | Tipo do documento de identificação. Valores aceitos: `rg`, `rne`, `cnh`, `ctps`, `class_document`, `passport`, `other`, `cin`. Quando `cin`, o campo `document_identification_number` deve ser igual ao CPF. |
| `document_identification_number` *(obrigatório)* | Número do documento de identificação da pessoa enviado em document_identification. Quando `document_identification_type` for `cin`, deve ser igual ao CPF. |
| `email` | Email da pessoa |
| `phone` | Telefone da pessoa |
| `proof_of_residence` *(obrigatório)* | DOCUMENT_KEY do PDF do comprovante de endereço do endereço enviado (enviado previamente) |
| `address` | Endereço da pessoa |
### PHONE OBJECT
| Campo | Descrição |
|---|---|
| `country_code` *(obrigatório)* | Código DDI do telefone (https://ddi.guiamais.com.br/)(deve ter obrigatoriamente 3 dígitos). |
| `area_code` *(obrigatório)* | Código DDD do telefone (https://ddd.guiamais.com.br/).) |
| `number` *(obrigatório)* | Número de telefone (apenas números). |
| `document_number` *(obrigatório)* | Numero de documento do signatário. |
### ADDRESS OBJECT
| Campo | Descrição |
|---|---|
| `street` *(obrigatório)* | Rua do endereço. |
| `state` *(obrigatório)* | Estado do endereço (com dois caracteres maiúsculos). |
| `city` *(obrigatório)* | Cidade do endereço. |
| `neighborhood` *(obrigatório)* | Bairro do endereço. |
| `number` *(obrigatório)* | Número da rua. |
| `postal_code` *(obrigatório)* | CEP do endereço (http://www.buscacep.correios.com.br/sistemas/buscacep/) (apenas números). |
| `complement` *(obrigatório)* | Complemento do endereço (texto livre). |
### OCR OBJECT
| Campo | Descrição |
|---|---|
| `ocr` | Objeto para entrega das chaves geradas pelo SDK de OCR |
### COLLATERALS OBJECT
| Campo | Descrição |
|---|---|
| `collateral_data` | Lista de garantias da operação. |
| `percentage` | |
| `collateral_type` *(obrigatório)* | Tipo de collateral. No caso do Auxílio Brasil, precisa ser "social_benefit" |
### COLLATERAL DATA OBJECT
| Campo | Descrição |
|---|---|
| `reservation_period` | Período do beneficio bloqueado como garantia. |
| `reservation_amount` | Valor do beneficio bloqueado como garantia. |
| `family_code` | Código da Família do beneficio. |
| `state` | UF da família do beneficio. |
| `financial_education_term` | Respostas do Termo de Educação Financeira exigido pelo Ministério da Cidadania |
### FINANCIAL EDUCATION TERM OBJECT
| Campo | Descrição |
|---|---|
| `questions` | |
### QUESTIONS OBJECT
| Campo | Descrição |
|---|---|
| `answer` | |
### FINANCIAL OBJECT
| Campo | Descrição |
|---|---|
| `desired_installments` | Lista de parcelas. |
| `interest_type` *(obrigatório)* | Tipo de juros da operação. |
| `disbursement_start_date` | Data início do período de desembolso (formato "AAAA-MM-DD"). |
| `disbursement_end_date` | Data final do período de desembolso (formato "AAAA-MM-DD"). |
| `annual_interest_rate` *(obrigatório)* | Valor porcentual da parcela prefixada de juros (atenção: 1 = 100%) |
| `credit_operation_type` *(obrigatório)* | Tipo de operação de crédito. |
| `interest_grace_period` | Carência de juros (em meses) |
| `number_of_installments` | Número de parcelas (mensais) |
| `principal_grace_period` | Carência do principal (em meses) |
### DESIRED INSTALLMENTS OBJECT
| Campo | Descrição |
|---|---|
| `due_date` | Data da parcela. |
| `total_amount` | Valor total da parcela |
### REBATES OBJECT
| Campo | Descrição |
|---|---|
| `amount` | Valor do rebate. |
| `fee_type` | Tipo de fee |
| `amount_type` | Tipo do valor inserido (valor absoluto, valor em porcentagem) |
| `rebate_bank_account` | Objeto conta bancária de rebate. |
### FINE CONFIGURATION OBJECT
| Campo | Descrição |
|---|---|
| `contract_fine_rate` *(obrigatório)* | Valor porcentual fixo da multa |
| `interest_base` | Contagem do tempo para multa ("calendar_days" para dias corridos, "workdays" para dias úteis) |
| `monthly_rate` | Valor porcentual mensal da multa |
### DISBURSEMENT BANK ACCOUNT OBJECT
| Campo | Descrição |
|---|---|
| `name` | Nome do dono da conta para desembolso - Obrigatório apenas se o método de transferência for ted ou pix. e caso haja mais de uma conta para desembolso (Limite de 80 caracteres). |
| `bank_code` | Código COMPE da instituição financeira (https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf) com 3 dígitos - Obrigatório apenas se o método de transferência for ted ou pix e se "ispb_number" não for enviado. |
| `branch_number` | Número da agência - Obrigatório apenas se o método de transferência for ted ou pix. |
| `account_number` | Número da conta - Obrigatório apenas se o método de transferência for ted ou pix - Obrigatório apenas se o método de transferência for ted ou pix. |
| `document_number`| CPF ou CNPJ do dono da conta para desembolso - Obrigatório apenas se o método de transferência for ted ou pix. e caso haja mais de uma conta para desembolso. |
| `percentage_receivable` | Valor em porcentagem que a conta receberá no desembolso. Este campo é utilizado para definir a quantidade a ser dividida caso haja mais de uma conta para desembolso (no caso de ser somente uma conta, o valor integral será transferido). Caso a porcentagem não seja enviada (de uma, ou de todas as contas), a porcentagem restante será dividida igualmente entre as contas sem porcentagem definida. Caso todas as porcentagens sejam enviadas, a soma delas não pode passar de 100 - Obrigatório apenas se o método de transferência for ted ou pix. |
| `ispb_number` | Identificador da instituição no Sistema de Pagamentos Brasileiro - Obrigatório apenas se o método de transferência for ted ou pix e se o "bank_code" não for enviado. |
| `qr_code_key` | Chave fornecida no momento da criação de um QR Code PIX - Pode ser enviado como o único parâmetro deste objeto, assim o desembolso acontece como pagamento desse QR code PIX. |
| `digitable_line` | Representação numérica de um código de barras de um boleto - Pode ser enviado como o único parâmetro deste objeto, assim o desembolso acontece como pagamento desse boleto. |
| `transfer_method` | Por padrão as operações são desembolsadas via PIX, então quando existr a necessidade de que uma operação seja desembolsada via TED este campo pode ser enviado. |
---
# webhook_auxilio_brasil
URL: /documentation/auxilio_brasil/webhook_auxilio_brasil
## Webhook auxílio brasil
**Criação de uma operação**
Na criação de uma operação do Auxílio Brasil dentro do nosso sistema, são possíveis os seguintes status:
- **success**: Informa o sucesso na consulta do benefício.
- **failure**: Informa que ocorreu um erro na consulta do benefício.
**Exemplos**
Webhook de sucesso na consulta
**body.json**
```json
{
"callback": {
"key": "bfbe918d-fe58-55a0-bdaf-5a3733b7a12d",
"data": {
"name": "LUIZ ANTONIO DA SILVA",
"state": "RJ",
"balance": "111",
"family_code": 8553463416,
"reference_date": "2022-08-03",
"benefit_net_amount": 294,
"benefit_total_amount": 294,
"disbursement_bank_account": {
"bank_code": "103",
"account_digit": "5",
"account_branch": "3880",
"account_number": "000925559475"
},
"number_of_active_reservations": 0
},
"status": "success",
"webhook_type": "social_benefit_balance",
"event_datetime": "2022-08-29T20:47:48"
}
}
```
Webhook de erro na consulta
**body.json**
```json
{
"callback": {
"key": "5d85a8eb-94c1-4fcc-8f66-15b6301f6kfe",
"data": {
"enumerator": "not_found_family_member",
"description": "there is not an active authorization for person"
},
"status": "failure",
"webhook_type": "social_benefit_balance",
"event_datetime": "2022-10-17T21:54:16"
}
}
```
| Enumerators | Descrição |
|---|---|
| `dataprev_error` | erro inesperado no Dataprev |
| `not_found_family_member` | não há uma autorização ativa para pessoa |
| `benefit_deleted` | benefício foi excluído |
**Cancelamento de uma operação**
Existem alguns processos que cancelam uma operação de crédito, majoritariamente:
1. PIX/TED falhou ou foi estornado;
2. Passamos da data de desembolso;
3. Tentativa de averbação foi rejeitada;
Toda operação que está cancelada em nosso sistema pode voltar ao seu estado anterior através do método de mudança da data de desembolso.
Alguns casos não são possíveis de voltarem ao estado inicial porque nunca será desembolsada, como é o caso 3, cuja tentativa de averbação foi rejeitada.
Para o primeiro caso:
**body.json**
```json
{
"key": "\",
"data": {
"pix_refusal": {
"reason": "Número da conta de destino é inexistente ou inválido.",
"reason_enumerator": "invalid_account"
},
"cancel_reason": "pix_refusal"
},
"status": "canceled",
"webhook_type": "debt",
"event_datetime": "2022-11-01 13:39:44"
}
```
A reason_enumerator pode ser conforme a lista abaixo:
| Enumerators | Descrição |
|---|---|
| `invalid_document_number` | Documento inválido |
| `invalid_account` | Conta inválida |
| `unsupported_transaction` | Transação não suportada |
| `blocked_account` | Conta bloqueada |
| `closed_account` | Conta fechada |
| `rejected_payment` | Pagamento rejeitado |
| `amount_too_great` | Valor monetário muito alto |
| `spi_timeout` | Timeout do prestador de serviço |
| `receiver_error` | Erro do receptor |
| `incorrect_account_type` | Tipo de conta incorreta |
| `duplicity_of_payment_order` | Ordem de pagamento duplicado |
| `refund_after_unexpected_value` | Reembolso depois de valor inesperado |
| `refund_after_psp_error` | Reembolso depois de erros no PSP |
| `refund_after_technical_issues` | Reembolso depois de problemas técnicos |
| `refund_after_cancellation` | Reembolso depois de cancelamento |
| `refund_after_fraud` | Reembolso depois de fraude |
| `refund_after_payee_request` | Reembolso após solicitação do beneficiário |
| `refund_after_fraud_report` | Reembolso depois de relatório de fraude |
| `payee_not_in_allowed_list` | Beneficiário não se encontra na lista permitida |
| `payee_in_blocked_list` | Beneficiário se encontra na lista bloqueada |
| `unjustified_payment_order` | Ordem de pagamento não justificado |
O segundo caso, ocorre quando algum processo interno dispara o cancelamento da Operação:
**body.json**
```json
{
"key": "\",
"data": {
"cancel_reason": "Operacao cancelada manualmente",
"cancel_reason_enumerator": "manual"
},
"status": "canceled",
"webhook_type": "debt",
"event_datetime": "2022-11-01 03:46:31"
}
```
Aqui podemos ter os seguintes "cancel_reason_enumerators":
- Cancel Reason Enumerators em rejeição de PAB:
| Enumerators | Descrição |
|---|---|
| `social_benefit_ineligible_benefit` | Beneficio inelegível |
| `social_benefit_invalid_beneficiary_data` | Dados do beneficiário inválidos |
| `social_benefit_invalid_balance` | Margem indisponível |
| `social_benefit_contract_limit_exceeded` | O cliente não pode ter mais contratos |
| `social_benefit_installments_limit_exceeded` | O cliente não pode ter esse numero de parcelas em um contrato |
| `social_benefit_invalid_disbursement_account` | Conta divergente com o DataPrev |
- Cancel Reason Enumerators mudança de dia
| Enumerators | Descrição |
|---|---|
| `not_collateral_constituted_social_benefit` | Mudou de dia e a operação não teve a garantia averbada |
| `waiting_signature` | Mudou de dia e a operação não foi assinada |
| `not_assigned` | Mudou de dia e a CCB está configurada para desembolsar após a cessão, mas nao foi cedida |
| `disburse_is_not_allowed` | Mudou de dia e a CCB está configurada com o fluxo de "Liberar o desembolso" mas não foi liberado |
| `manual` | Mudou de dia e a operação não foi desembolsada. |
Os cancel reason começados com "social_benefit" são permanentes, então a reserva foi de fato rejeitada. Mas em relação aos outros, ainda podem retornar ao estado inicial então deve ser devidamente analisado.
---
# Confirmar Abertura de Conta de Pessoa Física
URL: /documentation/baas/account/2fa_v2/abrir_conta_pf
Como segunda etapa da abertura de conta pessoa física, [após a reserva de conta](/documentation/baas/account/abrir_conta_pf), devem ser enviados os dados cadastrais completos do titular e evidências do aceite nos termos de abertura da conta.
## Request
ENDPOINT /account_request/checking
MÉTODO POST
## Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_request_key` | uuidv4 | Chave única de identificação solicitação de reserva da conta. | 36 |
Request Body
```json
{
"account_owner": {
"address": {
"street": "Av. Brigadeiro Faria Lima",
"state": "SP",
"city": "São Paulo",
"neighborhood": "Jardim Paulistano",
"number": "2391",
"postal_code": "01452905",
"complement": "Complemento"
},
"birth_date": "1990-05-06",
"document_identification": "3884579b-9810-4fa6-9b08-fe67d237160a",
"email": "teste@gmail.com",
"individual_document_number": "99999999999",
"is_pep": false,
"mother_name": "Dona Maria Mariane",
"name": "Nome do Titular da Conta",
"nationality": "nationality",
"person_type": "natural",
"phone": {
"country_code": "055",
"area_code": "11",
"number": "999999999"
},
"proof_of_residence": "4d7f4e-1eec-4e5f-82c0-d8c3921497ea"
},
"signed_contract": {
"document_key": "48a8f4g9-4b58-4905-9a69-b1f9215263f5",
"signatures": [
{
"authenticity": {
"timestamp": "1970-01-01T00:00:01.080100Z",
"facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb",
"lang": "-35.8916627",
"lat": "-7.2226067",
"ip_address": "177.51.1.186",
"session_id": "jdifj329842"
},
"signer": {
"name": "Nome do Titular da Conta",
"email": "teste@gmail.com",
"phone": {
"country_code": "055",
"area_code": "11",
"number": "999999999"
},
"document_number": "999999999"
},
"authentication_type": "opt-in"
}
]
},
"additional_documents": ["b12c8807-8f3f-4083-9cb1-7cce641f3786"]
}
```
### Request Body Params
| Campo | Tipo | Descrição | Caracteres |
|---|---|--------------------------------------------------------------------------------------------|---|
| `account_owner` * | object | Objeto contendo as informações do Titular da Conta | **[Objeto account_owner](#objeto-account_owner)** |
| `signed_contract` * | object | Objeto contendo as evidências do aceito do Titular quanto aos termos de abertura da conta. | **[Objeto signed_contract](#objeto-signed_contract)** |
### Objeto account_owner
| Campo | Tipo | Descrição | Caracteres |
|---| ---| ---|---------------------------------------|
| `address` * | string | Endereço do cliente. | **[Objeto address](#objeto-address)** | |
| `birth_date` * | string | Data de nascimento da pessoa (formato "AAAA-MM-DD") | |
| `document_identification` * | string | DOCUMENT_KEY do PDF do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) | |
| `document_identification_type` * | string | Tipo do documento enviado previamente (RG ou CNH) | |
| `email` * | string | Email do cliente. | |
| `individual_document_number` | string | CPF da pessoa (apenas números). Limitado a 11 caracteres. | |
| `is_pep` * | string | Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep).| |
| `mother_name` * | string | Nome da mãe do cliente em caso de PF. | 100 |
| `name` * | string | Razão social em caso de operações PJ ou Nome da pessoa em caso de operações PF. | 100 |
| `nationality` * | string | Nacionalidade do cliente. | 50 |
| `person_type` * | string | Identificador de que o objeto enviado é uma pessoa física ou jurídica.| |
| `phone` * | string | Objeto com dados do telefone | **[Objeto phone](#objeto-phone)** |
| `proof_of_residence` | string | DOCUMENT_KEY do PDF do comprovante de endereço do endereço enviado (enviado previamente).| |
### Objeto address
Este objeto, presente tanto no objeto PF quanto no objeto PJ, é um simples objeto para representar um endereço.
| Campo | Descrição | Exemplo | Máx. Caracteres |
|---|---|---|---|
| `street` *| string | Rua do endereço | 100 |
| `state` *| string | Estado do endereço (com dois caracteres maiúsculos) | 2 |
| `city` *| string | Cidade do endereço | 100 |
| `neighborhood` *| string |Bairro do endereço | 100 |
| `number` *| string | Número da rua | 10 |
| `postal_code` *| string |CEP do endereço (http://www.buscacep.correios.com.br/sistemas/buscacep/) (apenas números) | 8 |
| `complement` *| string |Complemento do endereço (texto livre) | 100 |
### Objeto signed_contract
| Campo | Tipo | Descrição | Caracteres |
|-------|--------|------------------|---------------|
| **document_key** * | uuidv4 | Chave única de identificação do documento do **Termo de Abertura de Conta** ou **Contrato de Conta Escrow**. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36 |
| **signatures** * | list | Dados de assinatura do documento enviado. Cada item da lista, corresponde a um assinante do documento. | [Objeto signatures](#objeto-signatures) |
### Objeto signatures
| Campo | Tipo | Descrição | Caracteres |
|-------|------------|-------------------|-------------------|
| **authenticity** * | object | Conjunto de dados que evidenciam a assinatura eletrônica realizada pelo assinante. | [Objeto authenticity](#objeto-authenticity) |
| **signer** * | object | Objeto contendo os dados de um dos assinantes do documento. | [Objeto signer](#objeto-signer)|
| **authentication_type** * | enumerator | Tipo de assinatura. Sempre será "**opt-in**"| "**opt-in**" |
### Objeto authenticity
| Campo | Tipo | Descrição | Caracteres |
|-------|--------|-------------------------|------------|
| **timestamp** * | string | Data e hora do momento da assinatura do documento. | 27 |
| **facial_recognition_key** | uuidv4 | Chave única de identificação da foto da selfie do titular da conta. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36 |
| **lang** | string | Coordenada de longitude da geolocalização do assinante capturada no momento da assinatura. | - |
| **lat** | string | Coordenada de latitude da geolocalização do assinante capturada no momento da assinatura. | - |
| **ip_address** | string | Endereço IP do dispositivo do assinante. | - |
| **session_id** | string | ID da seção do assinante no momento da assinatura. | - |
### Objeto signer
| Campo | Tipo | Descrição | Caracteres |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| **name** * | string | Nome do assinante. | - |
| **email** * | string | Email do assinante. | - |
| **phone** * | object | Objeto com dados do telefone do assinante | **[Objeto phone](#objeto-phone)** |
| **document_number** * | string | CPF do assinante. | 11 |
### Objeto phone
| Campo | Descrição | Exemplo | Máx. Caracteres |
| --- | --- | --- | --- |
|`country_code` *| string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 |
| `area_code` *| string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2 |
| `number` *| string |Número de telefone (apenas números) | 10 |
## Response
STATUS 201
Response Body
```json
{
"account_info": {
"account_branch": "0001",
"account_digit": "0",
"account_number": "1693580"
},
"account_request_key": "f230f1b5-07af-4737-b0e3-8a472304f5e7",
"account_request_status": "pending_kyc_analysis"
}
```
:::warning Atenção
O campo `account_request_key` deve ser armazenado e será utilizado para a confirmação da abertura da conta.
:::
### Response Body Params
| Campo | Tipo | Descrição | Caracteres|
|---|---| ---|---|
| `account_info` * | object | Objeto contendo as informações do Titular da Conta |**[Objeto account_info](#objeto-account_info)** | - |
| `account_request_key` * | string | Chave de identificação da requisição de criação | - | - |
| `account_request_status` * | string | Status de KYC | - | - |
### Objeto account_info
| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| --- |
| `account_branch` * | string | Número da Agência | 4 |
| `account_digit` * | string | Email | 11 |
| `account_number` * | string | Nome Completo do Titular da Conta | 50 |
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição(ptbr)
`translation`|
|---| --- | --- | --- | --- |
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema|
| 404 | QIT000404 | Not Found | Resource could not be found | Recurso não encontrado|
---
# Abertura de Conta de Pessoa Jurídica
URL: /documentation/baas/account/2fa_v2/abrir_conta_pj
A abertura de conta ocorre em duas etapas obrigatórias. Primeiro, uma requisição POST envia dados preliminares para reservar a conta. Em seguida, um webhook do tipo `account_request.status_change` com o status `pending_additional_data` é disparado. Na segunda etapa, uma requisição PATCH finaliza a abertura, oficializando a conta com as informações complementares.
## Request
ENDPOINT /account_request/checking
MÉTODO POST
## Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_request_key` | uuidv4 | Chave única de identificação solicitação de reserva da conta. | 36 |
## Abertura da Conta de Livre Movimentação
Request Body
```json
{
"account_owner": {
"phone": {
"country_code": "55",
"area_code": "11",
"number": "999999999"
},
"email": "email@teste.com.br",
"person_type": "legal",
"name": "Empresa de Teste",
"address": {
"street": "Rua Abrahão Calux",
"state": "SP",
"city": "São Paulo",
"neighborhood": "Vila Teste",
"number": "116",
"postal_code": "04286100",
"complement": "Complemento"
},
"trading_name": "Nome fantasia",
"company_document_number": "99999999000130",
"cnae_code": "4721102",
"foundation_date": "1980-07-11",
"company_statute": "99999999-01c9-4cf5-a0fa-1d2a96f4b34d",
"company_representatives": [
{
"name": "Nome do Socio",
"individual_document_number": "99999999999",
"document_identification_number": "999999999",
"birth_date": "1989-09-01",
"mother_name": "Maria da Silva",
"email": "teste@gmail.com",
"is_pep": false,
"final_beneficiary": true,
"person_type": "natural",
"nationality": "brasileiro(a)",
"marital_status": "single",
"document_identification": "88888-0ddf-4932-874f-9231794963da",
"phone": {
"country_code": "055",
"area_code": "19",
"number": "999999999"
},
"address": {
"street": "Rua dos Limões",
"neighborhood": "Vila Moinho Velho",
"city": "São Paulo",
"state": "SP",
"postal_code": "04286100",
"number": "116",
"complement": "complemento"
}
}
],
"company_type": "ltda"
},
"signed_contract": {
"document_key": "57cda530-d469-4427-a9d4-2523a510dee1",
"signatures": [
{
"authenticity": {
"timestamp": "2024-05-10T14:15:03.114895Z",
"ip_address": "192168161",
"lang": "-35.8916627",
"lat": "-7.2226067",
"session_id": "54b8e3cf-15de-41e5-9305-0ecf059d6e2a",
"facial_recognition_key": "c367a540-2e7e-4373-a167-61bc43c30dc1"
},
"signer": {
"name": "Nome do assinante",
"email": "teste@gmail.com.br",
"phone": {
"country_code": "55",
"area_code": "11",
"number": "999999999"
},
"document_number": "99999999"
},
"authentication_type": "opt-in"
}
]
},
"additional_documents": [
"61f2a65e-0ddf-4932-874f-9231794963da"
]
}
```
### Request Body Params
| Campo | Tipo | Descrição | Caracteres |
|-----------------------|--------|------------------------------------------------------------------------------|-------------------------------------------------------|
| **account_owner** * | object | Objeto Dono da conta | **[Objeto account_owner](#objeto-account_owner)** |
| **allowed_user** * | object | Usuário vinculado a conta. | **[Objeto allowed_user](#objeto-allowed_user)** |
| **account_manager** | object | Dados do parceiro integrador que realizará a movimentação da conta via API. | **[Objeto account_manager](#objeto-account_manager)** |
| `signed_contract` *| object | Objeto contento as informações da assinatura do contrato. | **[Objeto signed_contract](#objeto-signed_contract)** |
### Objeto account_owner
| Campo | Tipo | Descrição | Caracteres |
|-------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|
| **address** * | object | Objeto endereço do titular da conta | **[Objeto address](#objeto-address)** |
| **cnae_code** * | string | Classificação Nacional de Atividades Econômicas | 9 |
| **company_document_number** * | string | CNPJ | 14 |
| **company_statute** * | string | DOCUMENT_KEY do PDF do estatuto da empresa (enviado previamente). | 36 |
| **company_type** | enum | Tipo da empresa | **[Enumeradores company_type](#enumeradores-company_type)** |
| **company_representatives** * | list | Lista dos representantes legais da empresa | **[Objeto company_representatives](#objeto-company_representatives)** |
| **email** * | string | Email institucional da empresa. | 254 |
| **foundation_date** * | string | Data de abertura da empresa (formato "AAAA-MM-DD"). | 10 |
| **name** * | string | Razão social. | 100 |
| **person_type** * | enum | Identificador de que o objeto enviado é uma pessoa jurídica. Deve conter SEMPRE o valor "legal" para Objeto PJ. | **[Enumeradores person_type](#enumeradores-person_type)** |
| **phone** * | object | Telefone do titular da conta. | **[Objeto phone](#objeto-phone)** | - |
| **trading_name** * | string | Nome fantasia. | 200 |
### Objeto company_representatives
| Campo | Tipo | Descrição | Caracteres |
|------------------------------------|---------|--------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
| **name** * | string | Nome do representante da empresa | 100 |
| **address** * | object | Objeto endereço do representante da empresa | **[Objeto address](#objeto-address)** |
| **email** * | string | Email do representante da empresa | 254 |
| **birth_date** * | string | Data de nascimento representante da empresa (formato "AAAA-MM-DD") | 10 |
| **individual_document_number** * | string | CPF do representante da empresa (apenas números). | 11 |
| **document_identification** | string | DOCUMENT_KEY do PDF do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) | 36 |
| **document_identification_number** | string | Número do documento de identificação com foto da pessoa (RG ou CNH) | 16 |
| **document_identification_type** | enum | Tipo do documento de identificação com foto da pessoa (RG ou CNH) | [Enumeradores document_identification_type](#enumeradores-document_identification_type) |
| **is_pep** * | boolean | Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep). | - |
| **final_beneficiary** | boolean | Declaração se o representante é beneficiário final da empresa. | - |
| **marital_status** | enum | Estado civil do representante da empresa | **[Enumeradores marital status](#enumeradores-marital_status)** |
| **mother_name** * | string | Nome da mãe do representante da empresa | 100 |
| **nationality** | string | Nacionalidade do representante da empresa | 50 |
| **person_type** * | enum | Identificador de que o objeto enviado é uma pessoa física | **[Enumeradores person_type](#enumeradores-person_type)** |
| **phone** * | object | Objeto com dados do telefone do representante da empresa | **[Objeto phone](#objeto-phone)** |
### Objeto address
Este objeto, presente tanto no objeto PF quanto no objeto PJ, é um simples objeto para representar um endereço.
| Campo | Descrição | Exemplo | Caracteres |
|--------------------|-----------|-------------------------------------------------------------------------------------------|------------|
| **street** * | string | Rua do endereço | 500 |
| **state** * | enum | Estado do endereço (com dois caracteres maiúsculos) | 2 |
| **city** * | string | Cidade do endereço | 255 |
| **neighborhood** * | string | Bairro do endereço | 500 |
| **number** * | string | Número da rua | 10 |
| **postal_code** * | string | CEP do endereço (http://www.buscacep.correios.com.br/sistemas/buscacep/) (apenas números) | 8 |
| **complement** | string | Complemento do endereço (texto livre) | 500 |
### Objeto signed_contract
| Campo | Tipo | Descrição | Caracteres |
|-------|--------|------------------|---------------|
| **document_key** * | uuidv4 | Chave única de identificação do documento do **Termo de Abertura de Conta** ou **Contrato de Conta Escrow**. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36 |
| **signatures** * | list | Dados de assinatura do documento enviado. Cada item da lista, corresponde a um assinante do documento. | [Objeto signatures](#objeto-signatures) |
### Objeto signatures
| Campo | Tipo | Descrição | Caracteres |
|-------|------------|-------------------|-------------------|
| **authenticity** * | object | Conjunto de dados que evidenciam a assinatura eletrônica realizada pelo assinante. | [Objeto authenticity](#objeto-authenticity) |
| **signer** * | object | Objeto contendo os dados de um dos assinantes do documento. | [Objeto signer](#objeto-signer)|
| **authentication_type** * | enumerator | Tipo de assinatura. Sempre será "**opt-in**"| "**opt-in**" |
### Objeto authenticity
| Campo | Tipo | Descrição | Caracteres |
|-------|--------|-------------------------|------------|
| **timestamp** * | string | Data e hora do momento da assinatura do documento. | 27 |
| **facial_recognition_key** | uuidv4 | Chave única de identificação da foto da selfie do titular da conta. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36 |
| **lang** | string | Coordenada de longitude da geolocalização do assinante capturada no momento da assinatura. | - |
| **lat** | string | Coordenada de latitude da geolocalização do assinante capturada no momento da assinatura. | - |
| **ip_address** | string | Endereço IP do dispositivo do assinante. | - |
| **session_id** | string | ID da seção do assinante no momento da assinatura. | - |
### Objeto signer
| Campo | Tipo | Descrição | Caracteres |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| **name** * | string | Nome do assinante. | - |
| **email** * | string | Email do assinante. | - |
| **phone** * | object | Objeto com dados do telefone do assinante | **[Objeto phone](#objeto-phone)** |
| **document_number** * | string | CPF do assinante. | 11 |
### Objeto phone
| Campo | Descrição | Exemplo | Máx. Caracteres |
| --- | --- | --- | --- |
|`country_code` *| string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 |
| `area_code` *| string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2 |
| `number` *| string |Número de telefone (apenas números) | 10 |
### Enumeradores person_type
| Enum | Description |
|-------------|-------------------|
| **natural** | Pessoa física |
| **legal** | Pessoa jurídica |
### Enumeradores document_identification_type
| Enum | Description |
|---------|----------------------------------------|
| **rg** | RG - Registro Geral |
| **cnh** | CNH - Carteira Nacional de Habilitação |
### Enumeradores company_type
| Enum | Description |
|----------------------------|--------------------------------------------------------------------------|
| **ltda** | Limitada |
| **sa** | Sociedade Anônima |
| **micro_enterprise** | Micro Empresa |
| **freelancer** | Freelancer |
| **sa_opened** | Sociedade Anônima de Capital Aberto |
| **sa_closed** | Sociedade Anônima de Capital Fechado |
| **se_ltda** | Sociedade Empresária Limitada |
| **se_cn** | Sociedade Empresária em Nome Coletivo |
| **se_cs** | Sociedade Empresária em Comandita Simples |
| **se_ca** | Sociedade Empresária em Comandita por Ações |
| **scp** | Sociedade em Conta de Participação |
| **ei** | Empresário Individual |
| **ese** | Estabelecimento, no Brasil, de Sociedade Estrangeira |
| **eeab** | Estabelecimento, no Brasil, de Empresa Binacional Argentino-Brasileira |
| **ssp** | Sociedade Simples Pura |
| **ss_ltda** | Sociedade Simples Limitada |
| **ss_cn** | Sociedade Simples em Nome Coletivo |
| **ss_cs** | Sociedade Simples em Comandita Simples |
| **eireli_ne** | Empresa Individual de Responsabilidade Limitada (de Natureza Empresária) |
| **eireli_ns** | Empresa Individual de Responsabilidade Limitada (de Natureza Simples) |
| **eireli** | Empresa de Responsabilidade Individual |
| **mei** | Micro Empreendedor Individual |
| **me** | Micro Empresa |
| **cop** | Cooperativa |
| **private_association** | Sociedade Privada |
### Enumeradores marital_status
| Enum | Description |
|--------------|---------------|
| **single** | Solteiro(a) |
| **married** | Casado(a) |
| **widower** | Viúvo(a) |
| **divorced** | Divorciado(a) |
| **separated** | Separado(a) |
## Response
STATUS 201
Response Body
```json
{
"account_info": {
"account_branch": "0001",
"account_digit": "0",
"account_number": "1693580"
},
"account_request_key": "f230f1b5-07af-4737-b0e3-8a472304f5e7",
"account_request_status": "pending_kyc_analysis"
}
```
:::warning Atenção
O campo `account_request_key` deve ser armazenado e será utilizado para a confirmação da abertura da conta.
:::
### Response Body Params
| Campo | Tipo | Descrição | Caracteres|
|---|---| ---|---|
| `account_info` * | object | Objeto contendo as informações do Titular da Conta |**[Objeto account_info](#objeto-account_info)** | - |
| `account_request_key` * | string | Chave de identificação da requisição de criação | - | - |
| `account_request_status` * | string | Status de KYC | - | - |
### Objeto account_info
| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| --- |
| `account_branch` * | string | Número da Agência | 4 |
| `account_digit` * | string | Email | 11 |
| `account_number` * | string | Nome Completo do Titular da Conta | 50 |
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição(ptbr)
`translation`|
|---| --- | --- | --- | --- |
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema|
| 404 | QIT000404 | Not Found | Resource could not be found | Recurso não encontrado|
---
# Solicitar reserva de conta
URL: /documentation/baas/account/account_draft_checking
## Request
ENDPOINT /account_request/draft_checking
MÉTODO POST
## Abertura da Conta
Request Body
```json
{
"account_owner":{
"address":{
"street":"Av. Brigadeiro Faria Lima",
"state":"SP",
"city":"São Paulo",
"neighborhood":"Jardim Paulistano",
"number":"2391",
"postal_code":"01452905",
"complement":"Complemento"
},
"birth_date":"1990-05-06",
"email":"teste@gmail.com",
"individual_document_number":"99999999999",
"is_pep":false,
"mother_name":"Dona Maria Mariane",
"name":"Nome do Titular da Conta",
"nationality":"nationality",
"person_type":"natural",
"phone":{
"country_code":"055",
"area_code":"11",
"number":"999999999"
},
"monthly_income":1000
}
}
```
### Abertura da Conta
### Request Body Params
| Campo | Tipo | Descrição |
|------------------|--------|----------------------------------------------------------------------------|
| `account_owner`* | object | Detalhes do titular da conta, incluindo endereço e informações pessoais. |
### Objeto account_owner
| Campo | Tipo | Descrição |
|-------------------------------|---------|----------------------------------------------------------------|
| `address`* | object | Endereço do titular da conta. |
| `birth_date`* | string | Data de nascimento do titular (formato "AAAA-MM-DD"). |
| `email`* | string | Email do titular da conta. |
| `individual_document_number`* | string | CPF do titular (apenas números). |
| `is_pep`* | boolean | Declaração se a pessoa é PEP. |
| `mother_name`* | string | Nome da mãe do titular. |
| `name`* | string | Nome completo do titular. |
| `nationality` | string | Nacionalidade do titular. |
| `person_type`* | enum | Tipo de pessoa, deve ser sempre "natural" para pessoa física. |
| `phone`* | object | Telefone do titular. |
| `monthly_income` | number | Renda mensal do titular. |
### Objeto address
| Campo | Tipo | Descrição | Caracteres |
|-----------------|--------|------------------------|------------|
| `street`* | string | Rua do endereço | - |
| `state`* | enum | Estado do endereço | 2 |
| `city`* | string | Cidade do endereço | - |
| `neighborhood`* | string | Bairro do endereço | - |
| `number`* | string | Número da rua | - |
| `postal_code`* | string | CEP do endereço | - |
| `complement` | string | Complemento do endereço| - |
### Objeto phone
| Campo | Tipo | Descrição |
|------------------|--------|--------------------------|
| `country_code`* | string | Código DDI do telefone |
| `area_code`* | string | Código DDD do telefone |
| `number`* | string | Número de telefone |
### Enumeradores person_type
| Enum | Descrição |
|---------|--------------|
| `natural` | Pessoa física |
|`legal`| Pessoa Jurídica |
## Response
STATUS 201
Response Body
```json
{
"account_number": "1638634",
"reserved_account_status":"reserved",
"account_type": "checking",
"account_digit": "3",
"account_key": "b1690f7b-1e82-4f76-a8d3-c326a2b89b67",
"account_branch": "0001",
"account_name": "Nome do Proprietário",
"created_at": "2023-10-07T15:52:24"
}
```
:::warning Atenção
O campo `account_request_key` deve ser armazenado e será utilizado para a confirmação da abertura da conta.
:::
### Response Body Params
| Campo | Tipo | Descrição | Caracteres |
|---|---| ---|-------------------------------------------------|
| `account_key` * | string | Chave de única de identificação da conta| - | - |
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição(ptbr)
`translation`|
|---| --- | --- | --- | --- |
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema|
| 404 | QIT000404 | Not Found | Resource could not be found | Recurso não encontrado|
---
# Solicitar reserva de conta
URL: /documentation/baas/account/d4bf7f96-69b0-424b-a9d6-0a1bc79629cd
## Request
ENDPOINT /account_request/draft_checking
MÉTODO POST
## Abertura da Conta
Request Body
```json
{
"account_owner":{
"address":{
"street":"Av. Brigadeiro Faria Lima",
"state":"SP",
"city":"São Paulo",
"neighborhood":"Jardim Paulistano",
"number":"2391",
"postal_code":"01452905",
"complement":"Complemento"
},
"birth_date":"1990-05-06",
"email":"teste@gmail.com",
"individual_document_number":"99999999999",
"is_pep":false,
"mother_name":"Dona Maria Mariane",
"name":"Nome do Titular da Conta",
"nationality":"nationality",
"person_type":"natural",
"phone":{
"country_code":"055",
"area_code":"11",
"number":"999999999"
},
"monthly_income":1000
}
}
```
### Abertura da Conta
### Request Body Params
| Campo | Tipo | Descrição |
|------------------|--------|----------------------------------------------------------------------------|
| `account_owner`* | object | Detalhes do titular da conta, incluindo endereço e informações pessoais. |
### Objeto account_owner
| Campo | Tipo | Descrição |
|-------------------------------|---------|----------------------------------------------------------------|
| `address`* | object | Endereço do titular da conta. |
| `birth_date`* | string | Data de nascimento do titular (formato "AAAA-MM-DD"). |
| `email`* | string | Email do titular da conta. |
| `individual_document_number`* | string | CPF do titular (apenas números). |
| `is_pep`* | boolean | Declaração se a pessoa é PEP. |
| `mother_name`* | string | Nome da mãe do titular. |
| `name`* | string | Nome completo do titular. |
| `nationality` | string | Nacionalidade do titular. |
| `person_type`* | enum | Tipo de pessoa, deve ser sempre "natural" para pessoa física. |
| `phone`* | object | Telefone do titular. |
| `monthly_income` | number | Renda mensal do titular. |
### Objeto address
| Campo | Tipo | Descrição | Caracteres |
|-----------------|--------|------------------------|------------|
| `street`* | string | Rua do endereço | - |
| `state`* | enum | Estado do endereço | 2 |
| `city`* | string | Cidade do endereço | - |
| `neighborhood`* | string | Bairro do endereço | - |
| `number`* | string | Número da rua | - |
| `postal_code`* | string | CEP do endereço | - |
| `complement` | string | Complemento do endereço| - |
### Objeto phone
| Campo | Tipo | Descrição |
|------------------|--------|--------------------------|
| `country_code`* | string | Código DDI do telefone |
| `area_code`* | string | Código DDD do telefone |
| `number`* | string | Número de telefone |
### Enumeradores person_type
| Enum | Descrição |
|---------|--------------|
| `natural` | Pessoa física |
|`legal`| Pessoa Jurídica |
## Response
STATUS 201
Response Body
```json
{
"account_number": "1638634",
"reserved_account_status":"reserved",
"account_type": "checking",
"account_digit": "3",
"account_key": "b1690f7b-1e82-4f76-a8d3-c326a2b89b67",
"account_branch": "0001",
"account_name": "Nome do Proprietário",
"created_at": "2023-10-07T15:52:24"
}
```
:::warning Atenção
O campo `account_request_key` deve ser armazenado e será utilizado para a confirmação da abertura da conta.
:::
### Response Body Params
| Campo | Tipo | Descrição | Caracteres |
|---|---| ---|-------------------------------------------------|
| `account_key` * | string | Chave de única de identificação da conta| - | - |
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição(ptbr)
`translation`|
|---| --- | --- | --- | --- |
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema|
| 404 | QIT000404 | Not Found | Resource could not be found | Recurso não encontrado|
---
# Webhooks de abertura de conta
URL: /documentation/baas/escrow/webhooks
Após a chamada de solicitação de reserva de conta de conta é enviado um webhook do tipo account_request.status_change com o status pending_additional_data, esse evento é o gatilho para que seja enviada a requisição para confirmação da abertura de conta.
A resposta da solicitação de abertura de conta poderá retornar o status “pending_kyc_analysis” a depender da configuração de integração do parceiro.
Neste caso, a resposta sobre a aprovação ou reprovação da abertura da conta será retornada de forma assíncrona via webhook.
O número de conta será reservado no momento da solicitação de abertura, porém neste momento **a conta ainda não estará aberta**. Somente após a conclusão da análise de KYC da QI Tech a conta estará aberta.
## Webhook Pending KYC Analysis
Após a aprovação do Bacen Protege+, o status da solicitação de abertura de conta é atualizado para `pending_kyc_analysis` e um webhook é enviado para notificar o parceiro.
WEBHOOK_TYPE account_request.status_change
STATUS pending_kyc_analysis
Webhook Body
```json
{
"data": {
"account_info": {
"account_digit": "3",
"account_branch": "0001",
"account_number": "1638634"
},
"account_request_key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
"status": "pending_kyc_analysis"
},
"event_datetime": "2022-09-02 22:39:39",
"key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
"status": "pending_kyc_analysis",
"webhook_type": "account_request.status_change"
}
```
## Webhook aprovação KYC
Webhook Body
```json
{
"data": {
"account_info": {
"account_digit": "3",
"account_branch": "0001",
"account_number": "1638634"
},
"account_request_key": "dc575950-dcce-48e1-99a6-5fb0ada63d86"
},
"event_datetime": "2022-09-02 22:39:39",
"key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
"status": "pending_additional_data",
"webhook_type": "account_request.status_change"
}
```
### Enumeradores account_request_status
| Enum | Description |
|-----------------------------|---------------------------------|
| **pending_kyc_analysis** | Pendente aprovação KYC |
| **pending_additional_data** | Pendente informações adicionais |
| **rejected** | Abertura rejeitada |
## Contas de Pessoa Jurídica
# Account Rejected
WEBHOOK_TYPE account
STATUS account_rejected
Webhook Body
```json
{
"data": {
"account_info": {
"account_digit": "2",
"account_branch": "0001",
"account_number": "2359934",
"financial_institution_code": "329"
},
"allowed_user": {
"name": "Juliana Tereza Bernardes",
"document_number": "97564480084"
},
"account_owner": {
"name": "VOVO LUCIA CONVENIENCIA LTDA",
"document_number": "09080702000105"
}
},
"event_datetime": "2022-09-02 22:39:39",
"key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
"status": "account_rejected",
"webhook_type": "account"
}
```
## Contas de Pessoa Física
# Account Rejected
WEBHOOK_TYPE account
STATUS account_rejected
Webhook Body
```json
{
"key":"84864614-2860-4b78-bd44-77b961354014",
"data":{
"account_info":{
"account_key":"1435dbavf-2860-4b78-bd44-77b961354014",
"account_digit":"5",
"account_branch":"0001",
"account_number":"3998360",
"financial_institution_code":"329"
},
"account_owner":{
"name":"Pedro Pinho",
"document_number":"97634408077"
}
},
"status":"account_rejected",
"webhook_type":"account",
"event_datetime":"2024-01-09 14:35:46"
}
```
---
# Upload de arquivo remessa (CNAB)
URL: /documentation/baas/pagamento_em_lote/envio_de_remessa
:::caution Atenção!
A chamada deve ser autenticada seguindo o padrão descrito na seção de [**Upload de documentos**](/documentation/upload_de_documentos).
:::
## Request
ENDPOINT /payments/account/ ACCOUNT_KEY /remittance
MÉTODO POST
### Path parameters
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta, no formato uuid v4 | 36 |
## Request Body Params
Deverão ser enviados os seguintes dados, como form-data , no body da request:
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `file` * | file | Arquivo CNAB no padrão estipulado pela QI Tech | - |
## Response
STATUS 202
Response Body
```json
{
"cnab_remittance_key": "f14e9bac-94ed-4eb1-87b4-7fd7b7a2d280",
"cnab_remittance_status": "accepted"
}
```
### Response Body Params
| Campo | Tipo | Descrição | Caracteres |
|--------------------------------|---------|-----------------------------------------------------------------|----------------------------|
| `cnab_remittance_key` * | uuidv4 | Chave única de identificação do arquivo CNAB no formato uuid v4 | 36 |
| `cnab_remittance_status` * | string | Status do arquivo CNAB | **[Enumeradores cnab_remittance_status](#enumeradores-cnab_file_status)** |
### Enumeradores cnab_remittance_status
| Enumerador | Descrição |
|------------|---------------------------------------------------------------------------|
| uploaded | Upload feito com sucesso, mas arquivo ainda não começou a ser processado |
| processing | Arquivo sendo lido |
| accepted | Arquivo lido e aceito |
| rejected | Arquivo lido e rejeitado (todas as ocorrências do arquivo são rejeitadas) |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (ptbr)
`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 |
---
# Introdução a Transação em Lote CNAB240
URL: /documentation/baas/pagamento_em_lote/introducao
A QI Tech, através da API Payments, permite a realização de pagamentos utilizando o formato CNAB240, suportando diferentes tipos de transações, como boletos, PIX e TED, em uma única chamada. Esse sistema possibilita a execução de pagamentos em lote, garantindo maior eficiência para processos financeiros de alto volume.
Os pagamentos são processados de forma assíncrona, com validações rigorosas durante a submissão do arquivo CNAB240. Caso a solicitação inicial resulte em um HTTP status 4xx, nenhum pagamento será processado.
Após a submissão, o arquivo pode ser aprovado ou rejeitado. Caso seja rejeitado, a API retornará uma lista detalhada de erros relacionados à formatação do arquivo, permitindo que o integrador realize as correções necessárias antes de uma nova tentativa de envio. O arquivo será rejeitado caso seja encontrado qualquer erro sintático. No entanto, ele é lido integralmente, ou até que sejam encontrados um limite de 100 erros, para que todos os erros possam ser retornados e corrigidos de maneira mais prática e eficiente.
Enquanto o arquivo é lido, as ocorrências são adicionadas a uma fila, mas só serão processadas caso ele seja aceito. Ou seja, se o arquivo for rejeitado (status rejected), todas as suas ocorrências também serão descartadas. Por outro lado, no momento em que o arquivo é totalmente lido e aceito (status accepted), inicia-se o processamento dessas ocorrências, assegurando a continuidade das transações com base nos dados fornecidos.
---
# Criar recorrência de pagamento
URL: /documentation/baas/pix_automatico/movimentacoes/criar_recorrencia
## Request
ENDPOINT /account/ ACCOUNT_KEY /incoming_recurrence
MÉTODO POST
### Request Path Params
| Campo | Tipo | Descrição | Caracteres |
|-------------|--------|--------------------------------|------------|
| `account_key` * | uuid4 | Chave única de identificação da conta. | 36 |
### Request Body
Request Body: Criar recorrência de valor fixo
```json
{
"request_control_key": "01585acf-b0c3-4389-baf3-a58abbe92d58",
"end_to_end_id": "E73856642202309201429bZKfklNlbwu",
"periodicity": "monthly",
"journey_type": "journey_one",
"start_date": "2025-04-01",
"end_date": "2027-04-01",
"target_pix_key": "pix_key@test.bcb.com",
"pix_message": "Informação do pagamento",
"is_retry_allowed": true,
"transaction_amount": 150.04
}
```
Request Body: Criar recorrência de valor variável
```json
{
"request_control_key": "12385acf-b0c3-4389-baf3-a58abbe92d58",
"end_to_end_id": "E73856642202309201429bZKfklNlbwu",
"periodicity": "monthly",
"journey_type": "journey_one",
"start_date": "2025-07-01",
"end_date": null,
"target_pix_key": "pix_key@test.bcb.com",
"pix_message": "Pagamento da conta de energia elétrica",
"is_retry_allowed": true,
"minimum_transaction_amount": 50.00,
"maximum_transaction_amount": 300.00
}
```
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuid | Chave única de identificação da request utilizada pelo cliente no formato uuid4. | 36 |
| `periodicity` * | enumerator | Tipo da periodicidade associada ao pagamento | [Enumeradores periodicity](#enumeradores-periodicity) |
| `journey_type` * | enumerator | Tipo da jornada de solicitação | [Enumeradores journey_type](#enumeradores-journey_type) |
| `start_date` * | string | Data de ínicio da recorrência | - |
| `end_to_end_id` * | string | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo). Esta chave é retornada na consulta de chave Pix. | 32 |
| `target_pix_key` | string | Chave pix da conta a ser enviada a transação. | 100 |
| `target_account` | Object | Conta destino - Só deve ser enviada em transferências para transferência manuais. | [Objeto target_account](#objeto-target_account) | 10 |
| `transaction_amount` | number | Valor da transferência para ocorrência de valor fixo. | 10 |
| `minimum_transaction_amount` | number | Valor mínimo da transferência para ocorrência de valor variável. | 10 |
| `maximum_transaction_amount` | number | Valor máximo da transferência para ocorrência de valor valor variável. | 10 |
| `end_date` | string | Data de término da recorrência, para os casos de tempo indeterminado, enviar como null | - |
| `pix_message` | string | Mensagem a ser enviada junto à transferência Pix. | 140 |
| `is_retry_allowed` | boolean | Permissão para retentativa de transação Pix. | - |
### Enumeradores periodicity
| Enumerador | Descrição |
|------------------|--------------------|
| `weekly` | Recorrência semanal |
| `monthly` | Recorrência mensal |
| `quarterly` | Recorrência trimestral |
| `semiannual` | Recorrência semestral |
| `annual` | Recorrência anual |
### Enumeradores journey_type
| Enumerador | Descrição |
|------------------|--------------------|
| `journey_one` | Solicitação de autorização mediante uma notificação no aplicativo |
| `journey_two` | Solicitação de autorização mediante a leitura de um QR Code |
| `journey_three` | Autorização de recorrência por meio de um pix imediato mediante leitura de um QR Code |
| `journey_four` | Pagamento ou agendamento de um pix com uma solicitação de autorização da recorrência em sequência |
### Objeto target_account
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|------------|-----------------------------------------------------|---------------------------------------------------------|
| `account_branch` | string | Agência da conta. | 6 |
| `account_digit` | string | Dígito da conta. | 1 |
| `account_number` | string | Número da conta. | 20 |
| `owner_document_number` | string | CPF ou CNPJ (apenas números) do titular da conta. | 14 |
| `owner_name` | string | Nome do titular da conta. | 150 |
| `account_type` | enumerator | Tipo da conta. | [Enumerador account_type](#enumerador-account_type) |
| `ispb` | string | Base no CNPJ da instituição financeira (8 dígitos). | 8 |
:::info
Diferentes enumeradores podem significar o mesmo tipo de conta devido a informação retornada por diferentes
instituições.
:::
### Enumerador account_type
| Enumerador | Descrição |
|----------------------|---------------------|
| `checking_account` | Conta Corrente |
| `salary_account` | Conta Salário |
| `saving_account` | Conta Poupança |
| `payment_account` | Conta de Pagamentos |
## Response
STATUS 200
Response Body: Recorrência criada
```json
{
"incoming_recurrence_key": "cfa32109-a6dd-4304-94db-03a7b6d92a47",
"incoming_recurrence_status": "pending_confirmation",
"created_at": "2025-05-22T20:30:23.459Z",
}
```
| Campo | Tipo | Descrição | Max. Caracteres |
|--------------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `incoming_recurrence_key` | uuid | Chave única de identificação da autorização | 36 |
| `incoming_recurrence_status` | string |Identificador de status da recorrência | [Enumerador incoming_recurrence_status](#enumerador-incoming_recurrence_status) |
| `created_at` | string | Horário da criação da solicitação de recorrência | -
### Enumerador incoming_recurrence_status
| Enumerador | Descrição |
|----------------------|---------------------|
| **pending_confirmation** | Recorrência pendente de confirmação |
| **active** | Recorrência ativa |
| **cancelled** | Recorrência cancelada |
| **suspended** | Recorrência suspensa |
| **expired** | Recorrência expirada |
STATUS 4XX
Response Body
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo"
}
```
| Código HTTP | Código QI
`code` | Título
`title` | Descrição (eng)
`Description` | Descrição (ptbr)
`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: /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 |
---
# Tabela de Erros para Pix Transfer
URL: /documentation/baas/pix/erros_de_pix
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP Status Code | Error Code | Title | Description | Translation |
|------------------|------------|-------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 500 | QIT000500 | Internal Error | An internal error has occurred and its being investigated | Um erro interno aconteceu e está sendo investigado |
| 404 | QIT000404 | Bad Request | The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible | O recurso solicitado não pôde ser encontrado, mas pode estar disponível no futuro. Requests subsequentes do cliente são permitidos |
| 400 | QIT000400 | Bad Request | The server cannot or will not process the request due to an apparent client error (e.g., malformed request syntax, size too large, invalid request message framing, or deceptive request routing) | O servidor não pode ou não processará a requisição devido a um erro do cliente (por exemplo, sintaxe de requisição malformada, tamanho muito grande, enquadramento de mensagem de requisição inválida ou roteamento de requisição enganoso) |
| 753 | QIT000753 | Syntax Error | Malformed JSON. Could not decode the request body. The JSON was incorrect, empty or not encoded as UTF-8 | JSON malformado. Não foi possível decodificar o corpo da requisição. O JSON estava incorreto, vazio ou não foi codificado como UTF-8 |
| 400 | QIT000001 | Bad Request | (custom) | Payload Inválido |
| 403 | QIT000002 | Permission Validator Error | Request must be internal | Request deve ser interna |
| 403 | QIT000003 | Permission Validator Error | Request must be from a master user | Request deve ser de usuário master |
| 403 | PIT000001 | User is not allowed to do this transaction | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 400 | PIT000003 | Bad Request | Insufficient account balance for transfer and fee amount | Saldo de conta insuficiente para a transação e a taxa |
| 400 | PIT000004 | Bad Request | Transaction amount is over limit | O total da transação é superior ao limite |
| 404 | PIX000056 | Not Found | Pix key inquiry not found | Consulta de chave pix não encontrada |
| 400 | PXT000002 | Person is not Account Owner | Person \{person_key\} is not account owner | A pessoa \{person_key\} não é dona da conta |
| 400 | PXT000003 | Account is Closed | Account \{account_key\} is closed | Conta \{account_key\} está fechada |
| 404 | PXT000004 | Account not found | Account not found for: \{account_datum\} | Conta não encontrada para: \{account_datum\} |
| 404 | PXT000005 | Account not found | Account not found for pix key: \{pix_key\} | Conta não encontrada para chave pix: \{pix_key\} |
| 400 | PXT000006 | Account not found | Account was not provided for this query | Chave de identificação da conta não foi fornecida |
| 403 | PXT000008 | Invalid Permission | Person \{person_key\} does not have administration roles for account \{account_key\} | Pessoa \{person_key\} não tem permissões de administrador para a conta \{account_key\} |
| 404 | PXT000009 | Person Not Found | Person with document number \{person_document_number\} not found | Pessoa com número de documento \{person_document_number\} não encontrada |
| 400 | PXT000010 | Account is Blocked | Account \{account_key\} is blocked | Conta \{account_key\} está bloqueada |
| 400 | PXT000011 | Account Type Mismatch | Given account type does not match one registered | O tipo de conta fornecido não condiz com o registrado |
| 400 | PXT000012 | Invalid Document Number | Given \{document_number\} document number is invalid | CPF/CNPJ \{document_number\} fornecido não é válido |
| 400 | PXT000013 | Account Validation Failure | Account validation for received end_to_end_id is not valid | Validação da conta para o end_to_end_id recebido não é válida |
| 400 | PXT000014 | Target Account mismatch | Received target account data doesn't match validated account | Dados da conta de destino recebida não corresponde à conta validada |
| 400 | PXT000015 | Reversal date expired | Reversal original transaction is older than 90 days | A data de criação da transação original é mais antiga que 90 dias |
| 400 | PXT000016 | Reversal Account Flow Mismatch | Reversal account flow does not match original pix transfer's | O fluxo de contas de destino e de origem não correspondem ao da transação original |
| 400 | PXT000017 | Reversal Too Great | Reversal transfers sum amount surpasses that of original pix transfer | A soma das transações de devolução ultrapassam o valor da transação pix original |
| 404 | PXT000018 | Reversal Original Transfer not Found | Reversal original pix transfer not found | Transferência original da devolução não foi encontrada |
| 400 | PXT000019 | Chargeback Validation Failure | Previously done validation values do match with incoming chargeback | Os valores da atual devolução não correspondem com aqueles das validação |
| 404 | PXT000020 | Incoming PIX Validation Not Found | No previously done validation was found for given end to end id | Não se encontrou validação anterior para o id ponta-a-ponta provido |
| 400 | PXT000021 | Incoming Validation Already Done | There's an existing validation for end to end id \{end_to_end_id\} | A validação para o id ponta a ponta \{end_to_end_id\} já foi feita |
| 400 | PXT000022 | Wrong ISPB | ISPB is different from 32402502 | ISPB é diferente de 32402502 |
| 404 | PXT000023 | Outgoing PIX Transfer Not Found | Pix transfer key \{pix_transfer_key\} was not found | Transferência PIX de saída com chave \{pix_transfer_key\} não foi encontrada |
| 400 | PXT000024 | PIX Transfer Not Pending Confirmation | Pix transfer \{pix_transfer_key\} is not pending confirmation | Transferência PIX \{pix_transfer_key\} não está aguardando confirmação |
| 400 | PXT000025 | Invalid pix transfer key | Pix transfer \{pix_transfer_key\} is not pending confirmation or does not exist | Transferência PIX \{pix_transfer_key\} não está aguardando confirmação ou não existe |
| 400 | PXT000025 | Outgoing PIX Transfer Beyond of Transaction Limit | Pix transfer value R$ \{transfer_amount\} beyond of transaction limit R$ \{transaction_limit\} | Transferência PIX valor R$ \{transfer_amount\} além do limite R$ \{transaction_limit\} |
| 400 | PXT000026 | Search Params Error | Invalid integer value for page or size querystring parameters | Valor inválido para parâmetros de página ou tamanho de página |
| 403 | PXT000027 | Invalid Permission | Selected Person does not have administration roles | Pessoa selecionada não tem credencial de administrador |
| 400 | PXT000028 | Account Key can not be null when search for config fees | Account key can not be null when search for config fees | A chave de conta não pode ser nula quando buscar por configurações de tarifa |
| 400 | PXT000029 | Invalid Value for Enumerator Type | Invalid value \{value\} used for enumerator type \{enumerator\} | Valor inválido \{value\} para o tipo de enumerador \{enumerator\} |
| 400 | PXT000030 | To update or delete a fee configuration must be provided a valid fee ID | To update or delete a fee configuration must be provided a valid fee ID. ID provided: \{identification\} | Para atualizar ou remover uma configuração de tarifa deve ser fornecido um ID válido. ID fornecido: \{identification\} |
| 400 | PXT000031 | Fee configuration already exists | Fee configuration already exists for \{person_owner_type\} account with: purpose= \{purpose\} and \{transfer_type\}. Please use update | Configuração de tarifa já existe para conta \{person_owner_type\} com: finalidade= \{purpose\} e \{transfer_type\}. Por favor utilize o update |
| 400 | PXT000032 | Unable To Delete Default Configuration | Unable To Delete Default Configuration. Please use update | Não é permitido deletar uma configuração default. Por favor utilize o update |
| 400 | PXT000033 | Target Account Must Not Be Source Account | Target Account Must Not Be Source Account | A conta de destino não pode ser a conta de origem |
| 400 | PXT000034 | Account Key Must Not Be Null | You Need To Define An Account Key To Create A Fee Configuration | É necessário definir uma chave de conta para definir uma configuração de tarifa para a mesma |
| 400 | PXT000035 | Limit configuration already exists | Limit configuration already exists for \{account_key\} account for period(s) \{existing_limit_periods\}. Please use update | Configuração de limite já existe para conta \{account_key\} para o período(s) \{existing_limit_periods\}. Por favor utilize o update |
| 400 | PXT000036 | No limit configuration found. Please set default configurations | No limit configuration found. Please set default configurations for \{person_type\} person | Não foi possível encontrar configurações de limite, favor utilizar configurações padrões para \{person_type\} |
| 404 | PXT000037 | Person Not Found | Person with key \{person_key\} not found | Pessoa com chave \{person_key\} não encontrada |
| 400 | PXT000038 | Not enough balance | Not enough balance to pay for incoming pix fee | Saldo insuficiente para pagar por tarifa de pix de entrada |
| 400 | PXT000039 | Invalid Batch Limit Configuration | Received \{counter_config\} wrong configuration(s) for accounts: \{account_keys\}. Configurations must be None or positive float | Recebido \{counter_config\} configuração(ões) erradas para contas: \{account_keys\}. Configurações devem ser None ou float positivo |
| 400 | PXT000040 | Bad Request | Amount limit must be null, positive float or int. Sent \{limit\} | Limite deve ser nulo, positivo inteiro ou decimal. Sent \{limit\} |
| 404 | PXT000041 | Not Found | Qr Code not found | Qr Code não encontrado |
| 400 | PXT000042 | Bad Request | There is no ISPB number for this Bank Code | Não existe código ISPB para esse Bank Code |
| 400 | PXT000043 | Bad Request | Invalid decimal amount, sent \{number\} | Valor decimal inválido, enviado \{number\} |
| 404 | PXT000044 | Not Found | Pix Key \{pix_key\} is not activated | Chave PIX \{pix_key\} não está ativada |
| 404 | PXT000045 | Not Found | QR Code Payment is invalid for Receiver Conciliation ID \{receiver_conciliation_id\} | Pagamento via QR Code é inválido para Cliente Recebedor \{receiver_conciliation_id\} |
| 403 | PXT000046 | Invalid Permission | Only Master can change resource configuration | Apenas o Administrador pode alterar as configurações do recurso |
| 400 | PXT000047 | Bad Request | \{field_name\} could not be larger than \{max_length\} characters | \{field_name\} não pode ser maior que \{max_length\} caracteres |
| 400 | PXT000048 | Bad Request | Emoji not allowed in pix message | Emoji não é permitido na mensagem pix |
| 400 | PXT000049 | Bad Request | When paying QR Code end_to_end_id could not be none | Ao pagar um QR Code o end_to_end_id não pode ser nulo |
| 400 | PXT000050 | Bad Request | Could not read QR Code type, please try to read qr_code again | Não foi possível ler o tipo de QR Code. Favor tente ler o qr_code outra vez |
| 400 | PXT000051 | Invalid Requester Configuration Info | The configuration \{configuration\} format sent is not valid | O formato enviado da configuração \{configuration\} não é válido |
| 400 | PXT000052 | Bad Request | Only Master QI Tech can change default limits configurations | Apenas o Master QI Tech pode alterar as configurações de limites padrões |
| 400 | PXT000053 | Bad Request | QrCode already paid | Qr Code já Pago |
| 400 | PXT000054 | Bad Request | Invalid Pix Key, sent \{pix_key\} | Chave pix inválida, enviado \{pix_key\} |
| 400 | PXT000055 | Pix error | Invalid Limit Type Sent | Tipo inválido de limite enviado |
| 400 | PXT000056 | Bad Request | Only Master QI Tech can handle limit events | Apenas o Master QI Tech pode alterar eventos de limites |
| 400 | PXT000057 | Bad Request | Invalid request_key or no request found, request_key sent \{request_key\} | Requisição inválida ou requisição não encontrada, requisição enviada \{request_key\} |
| 400 | PXT000058 | Bad Request | When limit request is rejected, rejected reason could not be null | Quando uma requisição de limite é rejeitada, o motivo não pode ser nulo |
| 400 | PXT000059 | Bad Request | Target document number is not account owner document number | O documento informado não é o mesmo da conta de destino |
| 400 | PXT000060 | Bad Request | Nonexistent account in destination bank | Conta inexistente no banco de destino |
| 409 | PXT000061 | Conflict | End to end id invalid. A pix transfer with the end to end id \{end_to_end\} has already been registered! | End to end id inválido. Uma transação pix com o identificador único \{end_to_end\} já foi registrada! |
| 409 | PXT000062 | Conflict | Missing fields detected on jd connector response: \{response\} | Campos faltantes detectados em resposta do JD connector: \{response\} |
| 409 | PXT000063 | Conflict | Unexpected response: \{response\} | Resposta inesperada: \{response\} |
| 400 | PXT000064 | Bad Request | For Manual Pix Transfer Type a target account must be provided | Para transação pix do tipo manual, uma conta destino deve ser fornecida |
| 400 | PXT000065 | Bad Request | Pix transfer sent was already rejected. Rejection_reason: \{error_description\} | Pix transfer já rejeitada. Motivo da rejeição: \{error_description_translated\} |
| 404 | PXT000067 | Pix Key is Unregistered | Pix key \{pix_key\} is not currently used | A chave pix \{pix_key\} não está sendo utilizada |
| 422 | PXT000068 | Pix Key is Unregistered | Pix key inquiry timeout. Please try again | Consulta de chave pix excedeu o tempo limite. Por favor tente novamente |
| 400 | PXT000069 | Error in Qr Code Payload Request | An error occurred while requesting the qr code payload to the registry institution | Um erro ocorreu durante a requisição do payload do qr code para a instituição de registro |
| 400 | PXT000070 | Invalid Qr Code Format | The Qr Code format is invalid, please enter a valid Qr Code | O formato do Qr Code é inválido, por favor insira um Qr Code válido |
| 400 | PXT000071 | Invalid Qr Code Type | The Qr Code payload given did not provide a proper Qr Code type | O payload de QR Code fornecido não contêm um tipo de Qr Code Válido |
| 422 | PXT000072 | Pending Transfer | The transaction (\{end_to_end_id\}) could not be completed and is pending confirmation | Não foi possível concluir a transação (\{end_to_end_id\}) e ela está pendente de confirmação |
| 404 | PXT000073 | Outgoing PIX Transfer Not Found | Pix transfer end to end id \{end_to_end_id\} was not found | Transferência PIX de saída com identificador único \{end_to_end_id\} não foi encontrada |
| 400 | PXT000074 | Invalid Transaction Status | Unable to update transaction status. The status \{status\} is invalid | Não foi possível atualizar o status da transação. O status \{status\} é invalido |
| 400 | PXT000075 | Pix Transfer Key or End To End Not Provided | No pix transfer key or end to end id provided | Não foram fornecidos uma pix transfer key ou end to end id |
| 404 | PXT000076 | Incoming PIX Transfer Not Found | Pix transfer key \{pix_transfer_key\} was not found | Transferência PIX de entrada com chave \{pix_transfer_key\} não foi encontrada |
| 400 | PXT000077 | Pix Transfer Receipt not allowed | Pix Transfer Receipt cannot be generated for rejected transfers | Recibo de transação pix não pode ser gerado para transações rejeitadas |
| 400 | PXT000078 | Pix Transfer Receipt not available | Receipt not available due to pix transfer currently being processed. Wait a few minutes and try again | Comprovante não disponível pois transação Pix está em processamento. Por favor, aguarde alguns minutos e tente novamente |
| 400 | PXT000079 | Bad Request | Insufficient billing account balance for fee | Saldo de conta de cobrança insuficiente para a taxa |
| 400 | PXT000080 | Bad Request | Could not complete the transaction and the transaction was rejected | Não foi possível concluir a transação e a transferência foi rejeitada |
| 400 | PXT000081 | Bad Request | Pix key not sent | Chave PIX não enviada |
| 400 | PXT000082 | Bad Request | The sent PIX key \{pix_key\} does not match the decoded PIX key | A chave PIX enviada \{pix_key\} não coincide com a chave PIX decodificada |
| 400 | PXT000083 | Bad Request | Pix rejected. | Pix rejeitado. |
| 404 | PXT000084 | Original Pix Transfer Was Not Found | Original Pix Transfer Was Not Found | A transação PIX original não foi encontrada |
| 403 | PXT000085 | Invalid Permission | User do not has sufficient permissions | Usuário não tem permissões suficientes |
| 400 | PXT000086 | Update Default Failed | To update default requester configuration send default as requester_key in url | Para alterar a configuracao de requester padrao, envie default como requester_key na url |
| 400 | PXT000087 | Amount limit not approved try a lower value | Amount limit for \{person_type\} person not approved, please try a lower value | Limite total não aprovado para pessoa \{person_type\}, por favor tente um menor |
| 400 | PXT000088 | Bad Request | Invalid account information when translating to account DTO | Informações da conta inválidas na tradução do DTO |
| 409 | PXT000089 | Incoming Pix not pending | Incoming Pix with pix transfer key \{pix_transfer_key\} is not pending | Transferência de Entrada PIX \{pix_transfer_key\} não está pendente |
| 503 | PXT000090 | Service Unavailable | Pix transfer is not available right now. Please wait or use TED service | Transferência Pix não esta disponível no momento. Favor aguardar ou utilizar TED |
| 400 | PXT000091 | Bad Request | System account has no limits. Account key \{account_key\} is system account | Contas de sistema não possuem limite. Chave de conta \{account_key\} é conta de sistema |
| 422 | PXT000092 | Invalid Account Type | Pix is not yet implemented for non-checking or non-escrow account types | Transações Pix não estão implementadas para conta que não sejam escrow ou livres |
| 400 | PXT000093 | Bad Request | Fee must be either fixed_amount or percentage | Tarifas fixas e percentuais são mutuamente exclusivas |
| 400 | PXT000094 | Bad Request | Failed to fetch transactions by origin key | Falha ao obter transações por origin key |
| 400 | PXT000095 | Unforeseen Error Scenario on Reprocess | Scenario: pix_transfer_key: \{pix_transfer_key\}, pix_status: \{pix_status\}, bacen_status: \{bacen_status\}, internal_tx: \{internal_tx\}, reverse_tx: \{reverse_tx\}, external_tx: \{external_tx\} | Cenário: pix_transfer_key: \{pix_transfer_key\}, pix_status: \{pix_status\}, bacen_status: \{bacen_status\}, internal_tx: \{internal_tx\}, reverse_tx: \{reverse_tx\}, external_tx: \{external_tx\} |
| 417 | PXT000096 | Expectation Failed | Unexpected error trying to reprocess external transaction for outgoing Pix \{pix_transfer_key\} | Erro inesperado ao tentar refazer transação externa de saída Pix \{pix_transfer_key\} |
| 417 | PXT000097 | Expectation Failed | Unexpected error trying to reprocess reverse transaction for outgoing Pix \{pix_transfer_key\} | Erro inesperado ao tentar refazer transação reversa de saída Pix \{pix_transfer_key\} |
| 400 | PXT000098 | Expectation Failed | Unexpected subtype encountered: \{subtype\} | Subtipo inesperado encontrado: \{subtype\} |
| 400 | PXT000099 | Error retrieving account data | Error while retrieving data for account_key \{account_key\} | Erro ao recolher informações da conta \{account_key\} |
| 400 | PXT000100 | Rejected by external analysis | The transaction was rejected by external analysis | A transação foi rejeitada pela análise externa |
| 400 | PXT000101 | Bad Request | It is not allowed to set a maximum or a minumum value to a fixed amount fee | Não é permitido inserir valores de mínimo e máximo para tarifas de valor fixo |
| 404 | PXT000101 | Requester Configuration not found | There is no Requester Configuration attributed to requester_key given | Não há Requester Configuration para a requester_key enviada |
| 400 | PXT000102 | Invalid caas_client_key | There caas_client_key is not valid | A caas_client_key enviada não é válida |
| 406 | PXT000103 | \{key\} must be a valid uuid v4 string | \{key\} was not accepted for not being a valid uuid v4 string | \{key\} não foi aceito por não ser uma string uuid v4 válida |
| 400 | PXT000104 | Invalid key format | The key \{key\} is invalid | A chave \{key\} é inválida |
| 400 | PXT000105 | Invalid Key Type | Invalid Key Type: \{key_type\} | Tipo de chave inválido: \{key_type\} |
| 400 | PXT000106 | Bad Request | The key sent does not match the given key type | A chave enviada não corresponde ao tipo de chave fornecido |
| 400 | PXT000107 | Invalid UUID | The UUID \{uuid\} is invalid | O UUID \{uuid\} é inválido |
| 404 | PXT000108 | Invoice not found | The invoice with \{invoice_id\} was not found | A fatura com o id \{invoice_id\} não foi encontrada |
| 404 | PXT000109 | Payment Method not found | The payment method with \{payment_method_id\} was not found | O método de pagamento com o id \{payment_method_id\} não foi encontrado |
| 404 | PXT000110 | Payment not found | The payment with \{payment_id\} was not found | O pagamento com o id \{payment_id\} não foi encontrado |
| 400 | PXT000111 | Bad Request | Invalid pix transfer type sent | Tipo de transação pix inválida |
| 400 | PXT000112 | Bad Request | Receiver Conciliation id sent does not match expected | Número de conciliação do recebedor não atende ao esperado |
| 400 | PXT000113 | Bad Request | It has been identified by request_control_key or end_to_end_id that this request is already being processed | Foi identificado por request_control_key ou end_to_end_id que está requisição está sendo processada |
| 400 | PXT000114 | Bad Request | Requester Configuration already exists for \{requester_key\} | Requester Configuration já existe para o \{requester_key\} |
| 400 | PXT000115 | Bad Request | Insufficient account balance for transfer and fee amount | Saldo de conta insuficiente para a transação e a taxa |
| 400 | PXT000117 | Pix Transfer Pending | An error occurred while sending pix_transfer \{pix_transfer_key\} to SPI | Um erro ocorreu ao enviar a pix_transfer \{pix_transfer_key\} ao SPI |
| 400 | PXT000118 | Requester is not Pix Participant | The requester sent an alias key but is not a indirect pix participant | O requisitante enviou uma alias key no entanto não é um participante do pix indireto |
| 400 | PXT000119 | Requester is not account Owner | The requester is not the owner for the account sent | O requisitante não é dono da conta enviada |
| 404 | PXT000120 | Alias sent not found | Alias key attached to this account not found | Alias key vinculada à conta não encontrada |
| 400 | PXT000121 | Pix Transfer Direction Invalid | Pix transfer direction must be either outgoing or incoming | Pix transfer direction deve ser outgoing ou incoming |
| 400 | PXT000122 | Pix Transfer key or Request Control Key needed | A pix_transfer_key or a request_control_key must be provided | Uma pix_transfer_key ou uma request_control_key deve ser fornecida |
| 400 | PXT000123 | Invalid Timestamp Format sent | Given parameter is not in the correct format \{timestamp_format\} | Parametro enviado não está no formato correto \{timestamp_format\} |
| 404 | PXT000124 | Outgoing Pix Transfer not found | Given parameters returned no results found | Parâmetros enviados não retornaram resultados |
| 404 | PXT000125 | Incoming Pix Transfer not found | Given parameters returned no results found | Parâmetros enviados não retornaram resultados |
| 400 | PXT000126 | Error on qr code decode | There was an error on decode qr code | Houve um erro ao decodificar o qr code |
| 400 | PXT000127 | Invalid Reversal Reason | Reversal reason \{reversal_reason\} is not valid | Razão de reversão \{reversal_reason\} não é válida |
| 400 | PXT000128 | Bad Request | Pix key \{pix_key\} sent does match inquiry pix key. Verify if end_to_end_id sent is correct | Chave Pix \{pix_key\} enviada não condiz com consulta. Verifique se end_to_end_id enviado está correto |
| 400 | PXT000129 | SPI Error message | Message rejected by SPI-ICOM | Mensagem rejeitada pela SPI-ICOM |
| 408 | PXT000130 | SPI Timeout Control | SPI Timeout Control | Controle de timeout no SPI |
| 400 | PXT000131 | Receiver Internal Error | Cancelled transaction due to receiver's internal error | Transação interrompida devido a erro no PSP do Recebedor |
| 400 | PXT000132 | Invalid Target Account Number | Target account number is invalid | Número da conta de destino é inexistente ou inválido |
| 400 | PXT000133 | Blocked Target Account | Target account is blocked | A conta de destino encontra-se bloqueada |
| 400 | PXT000134 | Closed Target Account | Target account is closed | A conta de destino encontra-se encerrada |
| 400 | PXT000135 | Unsupported Transaction | Unsupported transaction for given target account | A conta de destino não suporta este tipo de transação |
| 400 | PXT000136 | Invalid Participant | SPI participant is not PSP settler agent of payer nor receiver | Participante direto do SPI não é liquidante do PSP do Pagador / Recebedor |
| 400 | PXT000137 | Zero Value Payment Order | Zero value payment order | Ordem de pagamento com valor zero |
| 400 | PXT000138 | Insufficient Funds | Insufficient funds in PI account from payer | Saldo insuficiente na conta PI do pagador |
| 400 | PXT000139 | Return Value Too Great | Return value greater than corresponding payment order | Valor de devolução acima do valor de pagamento correspondente |
| 400 | PXT000140 | Invalid Transactions Number | Invalid transactions number | Quantidade de transações inválida |
| 400 | PXT000141 | Unrelated Beneficiary Document Number | Beneficiary document number is not that of target account owner | CPF/CNPJ do usuário recebedor não é compatível com o titular da conta de destino |
| 400 | PXT000142 | Invalid Beneficiary Document Number | Invalid beneficiary document number | CPF/CNPJ da conta de destino está incorreto |
| 400 | PXT000143 | Incorrect Message Element | Incorrect message element | Elemento da mensagem incorreto |
| 400 | PXT000144 | Rejected Payment Order | Beneficiary's PSP has rejected payment order | Ordem de pagamento foi rejeitada pelo banco recebedor |
| 403 | PXT000145 | Unauthorized Payer | Signing participant is unauthorized to make a payment order for paying account | Participante que assinou a mensagem não é autorizado a realizar a operação na conta PI debitada |
| 400 | PXT000146 | Invalid Datetime | Invalid datetime for message delivery | Data e Hora do envio da mensagem inválida |
| 400 | PXT000147 | Generic Error | Error while processing payment (generic error) | Erro no processamento do pagamento (erro genérico) |
| 400 | PXT000148 | Bad Format Operation Identifier | Badly formatted operation's identifier | Identificador da operação mal formatado |
| 400 | PXT000149 | Invalid Payer ISPB | Invalid or non-existent payer's PSP ISPB number | Número ISPB do PSP do Pagador é inválido ou inexistente |
| 400 | PXT000150 | Invalid Beneficiary ISPB | Invalid or non-existent beneficiary's PSP ISPB number | Número ISPB do banco recebedor é inválido ou inexistente |
| 400 | PXT000151 | Incorrect Type | Incorrect type for target account | Tipo incorreto para a conta transacional especificada |
| 400 | PXT000152 | SPI Repeated E2E ID | The end_to_end_id was already used | O end_to_end_id já foi utilizado |
| 400 | PXT000153 | Invalid Target Account Type | The target account type can not receive PIX transactions | O tipo de conta destino não pode receber transações PIX |
| 400 | PXT000154 | Invalid ISPB | Invalid or non-existent ISPB number | Número ISPB é inválido ou inexistente |
| 400 | PXT000155 | Amount too Great | Amount too great for credited account | Valor de pagamento/devolução acima do permitido para a conta de destino creditada |
| 400 | PXT000156 | QR Code Rejected | QR Code rejected by beneficiary's PSP | QR Code rejeitado pelo PSP do usuário recebedor |
| 503 | PXT000157 | Bacen Service Unavailable | Could not send the message to ICOM after 3 retries | Não pode enviar a mensagem para a ICOM depois de 3 tentativas |
| 400 | PXT000158 | Invalid Amount | Paid amount diverges from expected amount of \{expected_amount\} | O valor do pagamento diverge do valor esperado de \{expected_amount\} |
| 400 | PXT000159 | QR code inactive | QR code is not active at the time of payment | QR code não está ativo no instante do pagamento |
| 400 | PXT000160 | QR Code Inactive | QR code is not active at the time of payment | QR code não está ativo no instante do pagamento |
| 400 | PXT000161 | Pix Key Is Not Active | Pix key is not active | Chave Pix não está ativa |
| 400 | PXT000162 | QR Code Not Found | QR code or Pix key is not valid | QR code ou Chave Pix não é válida |
| 400 | PXT000163 | QR Code Or Pix Key Is Not Valid | QR code or Pix key is not valid | QR code ou Chave Pix não é válida |
| 400 | PXT000164 | Unmapped Rejection Error Code | Settlement failed, unknown error reason code from receiver PSP | Código de recusa desconhecido do PSP recebedor |
| 400 | PXT000166 | Invalid Target | Account does not have permission to transfer to the given target account | A conta não possui permissão para realizar transferências para a conta enviada |
| 403 | PXT000167 | Requester not allowed to access this endpoint | Requester has no permission to perform pix transfers on this endpoint | Requester não possui permissão de realizar transações pix através deste endpoint |
| 403 | PXT000168 | No approver permission | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta |
| 400 | PXT000169 | tfa_info is required | Client must send object tfa_info | Cliente deve enviar objeto tfa_info |
| 400 | PXT000170 | Error occurred while sending token | An unexpected error occurred while sending token | Um erro inesperado ocorreu ao tentar enviar token |
| 400 | PXT000171 | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached | Número máximo de tentativas de validação de token atingido |
| 400 | PXT000172 | Token Expired | Token has expired. Resend token or recreate transfer | Token expirado. Reenvie token ou recrie a transferência |
| 400 | PXT000173 | Incorrect Token | Token sent does not match expected | Token enviado não condiz com o esperado |
| 400 | PXT000174 | Error Sending Token | An error occurred while sending token and its being investigated | Um erro ocorreu ao enviar token e está sendo investigado |
| 400 | PXT000175 | Invalid Status | Pix transfer not in pending_2fa_approval status | Pix transfer não está pendente de aprovação por autenticação de dois fatores |
| 400 | PXT000176 | Error Sending Token | An error occurred while resending token and its being investigated | Um erro ocorreu ao reenviar token e está sendo investigado |
| 400 | PXT000177 | Pix Transfer Batch key needed | A pix_transfer_batch_key must be provided | Uma pix_transfer_batch_key deve ser fornecida |
| 404 | PXT000178 | Pix Transfer Batch not found | A pix_transfer_batch not found | Uma pix_transfer_batch não encontrada |
| 400 | PXT000179 | Empty pix-transfer list received | A list of pix transfers must be provided | Uma lista de transferências pix deve ser fornecida |
| 400 | PXT000180 | Invalid Status | Pix transfer Batch not in pending_2fa_approval status | Pix transfer em lote não está pendente de aprovação por autenticação de dois fatores |
| 400 | PXT000181 | Target PSP Timeout | Beneficiary's PSP payment order timeout | Timeout do participante recebedor da ordem de pagamento |
| 400 | PXT000182 | Bad Request | The given Pix transfer is tied to a batch. It cannot be individually approved. Please approve batch | A Pix transfer enviada está ligada a um lote. Ela não pode ser individualmente aprovada. Por favor aprove o lote |
| 400 | PXT000183 | Invalid Person Type | Natural Person Cannot Pay for a PIX Fee | Pessoa Física não pode pagar tarifa de PIX |
| 404 | PXT000184 | Outgoing PIX Transfer must hold to be reprocessed | Pix transfer key \{pix_transfer_key\} must wait to be reprocessed | Transferência PIX de saída com chave \{pix_transfer_key\} deve aguardar para ser reprocessada |
---
# Introdução a Transação em Lote Ted
URL: /documentation/baas/ted/batch/introducao_a_transacao_em_lote_ted
A QI Tech oferece a possibilidade de realizar várias transações ted com uma única chamada. Nesse sistema, as transações
são realizadas de forma assíncrona. Caso na chamada inicial seja retornado um **http status 4xx**, nenhuma das
transações será realizada. Após a solicitação, o parceiro integrador receberá um webhook para cada transação informando
o status final da tentativa, podendo ser **rejected** ou **sent**.
## Autenticação de Dois Fatores
Assim como em transações ted, parceiros integradores com configuração de autenticação de dois fatores devem enviar o
objeto `tfa_info` com as informações de contato e envio de token.
---
# Tabela de Erros para Ted
URL: /documentation/baas/ted/erros_ted
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`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 |
---
# Aprovar o pagamento de um Boleto
URL: /documentation/boletos/2fa/realizar_pagamento_de_um_boleto
Para realizar o pagamento de um Boleto é necessário realizar duas chamadas:
1. Solicitação de token de validação de transferência: /baas/token_request
2. Aprovação da transferência: /baas/movement_validation
:::info
O Token enviado deve ser informado no momento da aprovação do pagamento do boleto, e o “***movement_payload***” deve ser o mesmo informado no momento da solicitação do Token.
:::
## Request
MÉTODO POST
ENDPOINT /baas/movement_validation
Request Body
```json
{
"token": "358192",
"movement_payload": {
"resource_account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"digitable_line": "32990001031000699926165000000201993810000003500"
}
}
```
## Body Params
| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `token` * | string | Token de autenticação | 6 |
| `agent_document_number` * | string | CPF do usuário que irá receber o token. (Apenas números) | 11 |
| `movement_payload` | Object | Payload contendo as informações da transferência | **[Objeto movement_payload](#objeto-movement_payload)** |
### Objeto movement_payload
| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `resource_account_key` * | uuuidv4 | Chave única de identificação da conta que irá realizar o pagamento | 36 |
| `digitable_line` * | float | Linha digitável do boleto | 47 |
## Response
STATUS 200
Response Body
```json
{
"movement_info": {
"origin": {
"account": "42863",
"branch": "0001",
"digit": "0",
"document": "73685224000239",
"name": "Empresa de Teste",
"financialInstitution": "QI Sociedade de Crédito Direto S.A."
},
"faceValue": "2185.0",
"amount": "2185.0",
"dueDate": "2024-04-18T03:00:00.000Z",
"type": "bank_slip_payment",
"digitableLine": "32990001031000699926165000000201993810000003500",
"barCode": "00191969000002185000000001120035240112154117",
"destination": {
"document": "05626796000106",
"guarantorName": null,
"name": "Beneficiário do Boleto",
"guarantorDocument": null,
"bank": "QI Sociedade de Crédito Direto S.A."
}
},
"account_key": "0000000-0000-0000-0000-000000000000",
"transaction_key": "0000000-0000-0000-0000-000000000000",
"movement_status": "approved",
"schedule_key": null,
"movement_amount": 2185,
"origin_key": null,
"transacted_at_br": "2024-04-18 09:50:38-03:00",
"requester_user_key": "0000000-0000-0000-0000-000000000000",
"requester_key": "0000000-0000-0000-0000-000000000000",
"movement_request_key": "0000000-0000-0000-0000-000000000000",
"movement_date": "2024-04-18",
"approval_feedback": true,
"movement_type": "bank_slip_payment",
"movement_data": {
"transaction_key": "0000000-0000-0000-0000-000000000000",
"resource_account_key": "0000000-0000-0000-0000-000000000000",
"digitable_line": "32990001031000699926165000000201993810000003500"
},
"transacted_at": "2024-04-18 12:50:38"
}
```
---
# Solicitar token para pagamento de um Boleto
URL: /documentation/boletos/2fa/solicitar_token_para_pagamento
Para realizar o pagamento de um Boleto é necessário realizar duas chamadas:
1. Solicitação de token de validação de transferência: /baas/token_request
2. Aprovação da transferência: /baas/movement_validation
## Request
- MÉTODO POST
- ENDPOINT /baas/token_request
Request Body
```json
{
"contact_type": "email",
"agent_document_number": "97564480084",
"movement_payload": {
"resource_account_key": "6d3089b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"digitable_line": "32990001031000699926165000000201993810000003500"
}
}
```
## Body Params
| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `contact_type` * | string | Forma de envio do token de autenticação, podendo ser via E-mail (“email”) ou SMS (“sms”)| 10 |
| `agent_document_number` * | string | CPF do usuário que irá receber o token. (Apenas números) | 11 |
| `movement_payload` | Object | Payload contendo as informações da transferência | **[Objeto movement_payload](#objeto-movement_payload)** |
### Objeto movement_payload
| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `resource_account_key` * | uuuidv4 | Chave única de identificação da conta que irá realizar o pagamento | 36 |
| `digitable_line` * | float | Linha digitável do boleto | 47 |
## Response
STATUS 200
Response Body
```json
{}
```
---
# Consulta de carteiras de cobrança
URL: /documentation/boletos/consultar_v1/consulta_de_carteira
## Request
ENDPOINT /bank_slip/requester_profiles
MÉTODO GET
## Response
STATUS 200
Response Body
```json
{
"requester_profile_codes": [
"329-09-0001-1467576",
"329-09-0001-5747500",
"329-09-0001-2730579",
"329-09-0001-2359934"
]
}
```
---
# Consultar arquivo retorno
URL: /documentation/boletos/consultar_v1/consultar_arquivo_retorno
:::info Aviso
Para garantir que o arquivo retorno para o dia corrente estará com as informações atualizadas verifique se as
informações do dia foram conciliadas através de pooling como apresentado em [Rotina de conciliação de arquivo retorno](/documentation/boletos/consultar/rotina_de_conciliacao_de_arquivo_retorno)
:::
## Request
ENDPOINT /bank_slip/requester_profile/ REQUESTER_PROFILE_CODE /cnab_files
MÉTODO GET
### Path params
| Campo | Tipo | Descrição | Caracteres |
|----------------------------|--------|---------------------------------|------------|
| `requester_profile_code` * | string | Código da carteira de cobrança. | 10 |
### Query params
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|------------------------------------|---------------------------------------------|
| `cnab_type` * | enum | Tipo de Arquivo | **[Enumeradores](#enumeradores-cnab_type)** |
| `from` * | string | Início do período a ser analisado. | 10 |
| `to` * | string | Fim do período a ser analisado. | 10 |
### Enumeradores cnab_type
| Campo | Descrição |
|---------------------|--------------------|
| requester_discharge | Arquivo de retorno |
## Response
STATUS 200
Response Body
```json
{
"data": [
{
"cnab_key": "47361262-0853-4c51-9c2a-5284e0d8a5e1",
"company_code": null,
"created_at": "2020-05-06T11:04:25",
"downloads": [],
"file_size": "None",
"filename": "CNAB.RET",
"line_length": "400",
"remitter_key": "ab871cc8-8369-4b72-95f1-b074b30c7208",
"requester_profile_code": "329-01-0001-0000002",
"type": {
"created_at": "2019-03-12T12:59:32",
"enumerator": "requester_discharge",
"translation_path": "bank_slip.CNABFileType.requester_discharge"
},
"url": "https://linkparadownload.com/CNAB.RET",
"version": "11"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"rows_per_page": 100,
"total_pages": 1,
"total_rows": 1
}
}
```
STATUS 400
Response Body
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
---
# Consultar boleto
URL: /documentation/boletos/consultar_v1/consultar_boleto
## Request
ENDPOINT /bank_slip/ BANK_SLIP_KEY
MÉTODO GET
### Path params
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `bank_slip_key` *| string | Chave de identificação do boleto | chave uuid |
## Response
STATUS 200
Response Body
```json
{
"amount": 3,
"asset_type": {
"created_at": "2019-02-01T16:44:11",
"enumerator": "invoice",
"translation_path": "bank_slip.AssetType.invoice"
},
"automatic_bankruptcy_protest": true,
"automatic_protest": false,
"automatic_write_off": false,
"bank_slip_file": [],
"bank_slip_key": "96b32f1a-c2bd-41a4-b4b1-a169235be68b",
"bank_slip_status": {
"created_at": "2019-02-01T16:44:07",
"enumerator": "registered",
"translation_path": "bank_slip.BankSlipStatus.registered"
},
"bank_teller_instructions": "Não aceitar após vencimento",
"barcode": "32991918600000900000001090000000000457475000",
"beneficiary_account_branch": "0001",
"beneficiary_account_digit": "5",
"beneficiary_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
"beneficiary_account_number": "5747500",
"beneficiary_document_number": "12345678905",
"beneficiary_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"beneficiary_name": "Greg Brown",
"billing_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
"business_date_expiration": "2020-06-01",
"created_at": "2020-05-15T21:00:25",
"days_before_fine": null,
"days_before_interest": null,
"days_to_bankruptcy_protest": 1,
"days_to_protest": null,
"days_to_write_off": null,
"digitable_line": "32990001039000000000104574750008191860000090000",
"discount_limit_date": null,
"discount_value": null,
"discounts": [],
"document_number": "123456/01",
"expenses": [
{
"amount": 3.9,
"created_at": "2022-11-19T10:42:47",
"expense_key": "6f21f308-f6c6-4198-a8bc-bc0e853bb8b5",
"paid": true,
"reason": {
"created_at": "2019-02-14T17:30:50",
"reason_code": "Tarifa de registro",
"translation_en_us": "Registration Fee",
"translation_pt_br": "Tarifa de registro"
},
"subject": {
"created_at": "2019-02-14T17:30:43",
"enumerator": "requester",
"translation_path": "bank_slip.AssetType.requester"
},
"subject_account_key": "9223d7ae-320a-411c-8ff4-861e054da4d4",
"updated_at": "2022-11-19T10:46:31"
}
],
"expiration": "2020-06-01",
"fine_percentage": 0.1,
"guarantor_address": null,
"guarantor_city": null,
"guarantor_document": null,
"guarantor_name": null,
"guarantor_person_type": null,
"guarantor_postal_code": "00000000",
"guarantor_state": null,
"has_protest_pending_feedback": false,
"historical_our_number": 2,
"institution_registration_date": null,
"interest_daily_value": 0.34,
"lock_origin_type": null,
"max_payment_days": 180,
"nfe_key": null,
"nfe_url": null,
"notary_office_number": null,
"notary_office_protocol": null,
"notification": [],
"occurrences": [
{
"agent_type": "integration",
"automatic_bankruptcy_protest": null,
"automatic_protest": null,
"automatic_write_off": null,
"created_at": "2020-05-15T21:00:25",
"discount_amount": null,
"discounts": [],
"fine_percentage": 2,
"interest_daily_value": 0.34,
"iof_amount": null,
"new_bank_slip_status": {
"created_at": "2019-02-14T17:30:39",
"enumerator": "registered",
"translation_path": "bank_slip.BankSlipStatus.registered"
},
"new_due_date": "2020-06-01",
"new_protest_status": {
"created_at": "2019-02-01T16:44:08",
"enumerator": "not_protested",
"translation_path": "bank_slip.ProtestStatus.not_protested"
},
"notary_office_number": null,
"notary_office_protocol": null,
"notification": [],
"occurrence_expenses": null,
"occurrence_feedback": {
"created_at": "2019-02-14T17:30:46",
"enumerator": "confirmed",
"translation_path": "bank_slip.OccurrenceFeedback.confirmed"
},
"occurrence_key": "c3ab3e01-f198-4e7e-9e01-7a8091b8bd72",
"occurrence_reasons": [],
"occurrence_type": {
"created_at": "2019-02-01T16:44:14",
"enumerator": "registration",
"translation_path": "bank_slip.OccurrenceType.registration"
},
"old_bank_slip_status": {
"created_at": "2019-02-01T16:44:07",
"enumerator": "accepted",
"translation_path": "bank_slip.BankSlipStatus.accepted"
},
"old_due_date": null,
"old_protest_status": null,
"paid_amount": null,
"paid_fine_amount": null,
"paid_interest_amount": null,
"payer_address": null,
"payer_postal_code": null,
"payment_bank": null,
"payment_branch": null,
"payment_credit_date": null,
"payment_method": null,
"payment_origin": null,
"protest_confirmation": null,
"protest_distribution_cost": null,
"protest_electronic_cost": null,
"protest_emolument": null,
"protest_expenses": null,
"protest_other_expenses": null,
"protocol_date": null,
"protocol_region": null,
"rebate_amount": null,
"registration_institution_occurrence_date": "2020-05-15",
"registration_institution_occurrence_event": [
{
"cnab_file": {
"cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
"company_code": null,
"created_at": "2020-05-15T21:00:22",
"downloads": [],
"file_size": "None",
"filename": null,
"line_length": null,
"remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"requester_profile_code": null,
"type": {
"created_at": "2019-02-01T16:44:17",
"enumerator": "api_instruction",
"translation_path": "bank_slip.CNABFileType.api_instruction"
},
"url": null,
"version": null
},
"cnab_file_occurrence_order": 1,
"created_at": "2020-05-15T21:00:25",
"new_status": {
"created_at": "2019-02-01T16:44:15",
"enumerator": "waiting_submission",
"translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
},
"old_status": null
}
],
"registration_institution_occurrence_status": {
"created_at": "2019-02-01T16:44:15",
"enumerator": "waiting_submission",
"translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
},
"requester_occurrence_event": [
{
"cnab_file": {
"cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
"company_code": null,
"created_at": "2020-05-15T21:00:22",
"downloads": [],
"file_size": "None",
"filename": null,
"line_length": null,
"remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"requester_profile_code": null,
"type": {
"created_at": "2019-02-01T16:44:17",
"enumerator": "api_instruction",
"translation_path": "bank_slip.CNABFileType.api_instruction"
},
"url": null,
"version": null
},
"cnab_file_occurrence_order": 1,
"created_at": "2020-05-15T21:00:25",
"new_status": {
"created_at": "2019-02-01T16:44:16",
"enumerator": "confirmed",
"translation_path": "bank_slip.RequesterOccurrenceStatus.confirmed"
},
"old_status": {
"created_at": "2019-02-01T16:44:16",
"enumerator": "accepted",
"translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
}
}
],
"requester_occurrence_status": {
"created_at": "2019-02-01T16:44:16",
"enumerator": "confirmed",
"translation_path": "bank_slip.RequesterOccurrenceStatus.confirmed"
},
"selected_user_agent": null
}
],
"original_expiration": "2022-12-01",
"our_number": 2,
"paid_amount": null,
"paid_fine_amount": null,
"paid_interest_amount": null,
"participant_control_number": null,
"payer_account_digit": null,
"payer_account_number": null,
"payer_account_type": null,
"payer_address": "Rua Carlos Tampaio, 112",
"payer_bank": null,
"payer_branch_digit": null,
"payer_branch_number": null,
"payer_document": "45508922008",
"payer_name": "John Nobody",
"payer_person_type": {
"created_at": "2019-02-01T16:44:09",
"enumerator": "natural",
"translation_path": "bank_slip.PersonType.natural"
},
"payer_postal_code": "00000000",
"payment_date": null,
"printing_policy": {
"created_at": "2019-02-01T16:44:10",
"enumerator": "no_printing",
"translation_path": "bank_slip.PrintingPolicy.no_printing"
},
"protest_status": {
"created_at": "2019-02-01T16:44:08",
"enumerator": "not_protested",
"translation_path": "bank_slip.ProtestStatus.not_protested"
},
"protocol_date": null,
"protocol_region": null,
"qr_code": null,
"rebate_amount": null,
"reference_requester_profile_code": null,
"registration_institution": {
"created_at": "2020-03-26T19:36:16",
"enumerator": "qi_scd",
"febraban_code": "329",
"remittance_sequence": 72,
"settlement_resource_account_key": "3e46d266-4fdb-4fd2-b87a-3e3de366afd4"
},
"requester_profile": 1,
"requester_profile_code": "329-01-0001-0067049",
"requester_registration_date": "2020-05-15",
"settlement_account_key": "9223d7ae-320a-411c-8ff4-861e054da4d4",
"settlements": [],
"tags": null
}
```
STATUS 400
Response Body
```json
{
{"title": "Bad Request", "description": "Invalid request body.", "translation": "Corpo da requisição inválido.", "extra_fields": {}, "code": "LEG000069"}
}
```
---
# Emitir PDF
URL: /documentation/boletos/consultar_v1/emitir_pdf
## Request
ENDPOINT /bank_slip/2-way/ BANK_SLIP_KEY
MÉTODO GET
### Path params
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `BANK_SLIP_KEY` *| string | Chave de identificação do boleto. | 10 |
## Response
STATUS 200
Response Body
```json
[
{
"barcode": "32998827300000003000001010000000000200670490",
"created_at": "2020-05-19T18:46:41",
"digitable_line": "32990001031000000000902006704908882730000000300",
"url": "https://linkparadownload.com/arquivo.pdf"
}
]
```
STATUS 400
Response Body
```json
{ }
```
---
# Francesinha
URL: /documentation/boletos/consultar_v1/francesinha
## Request
- ENDPOINT /bank_slip/little_french
- MÉTODO GET
### Body params
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `requester_profile_code` *| string | Código da carteira. | 10 |
| `date` | date | Data para a geração do relatorio, caso nulo, a data do relatório será HOJE (Formato YYYY-MM-DD). | 10 |
## Response
status: 200
Body.json
O body de resposta da francesinha será um arquivo excel encodado em base64.
status: 400
Body.json
```json
{ }
```
---
# Listar boletos
URL: /documentation/boletos/consultar_v1/listar_boletos
## Request
ENDPOINT /bank_slip/person/ BENEFICIARY_KEY
MÉTODO GET
:::caution **Atenção**
Note que em ambos os exemplos a lista bank_slip_file é vazia. Isto significa que não existe um arquivo pdf para este boleto. Caso o cliente deseje uma via PDF do boleto explicaremos como fazê-lo nos próximos passos.
:::
### Path params
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `beneficiary_key` *| string | Chave de identificação do beneficiário | chave uuid |
### Query params
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `payer_document` | string | Número do documento do pagador | - |
| `bank_slip_status` | enum | Status do boleto. | **[Enumeradores](#enumeradores-bank_slip_status)** |
| `requester_profile` | string | Número da carteira de boletos| - |
| `protest_status` | enum | Status de protesto. | **[Enumeradores](#enumeradores-protest_status)** |
| `from` | date | Data inicial de criação do boleto. | 10 |
| `to` | date | Data final de criação do boleto. | 10 |
| `number_search` | string | Nosso número (our_number) ou numero do documento (document_number). | - |
| `page` | integer | Pagina a ser consultada >= 1. | - |
| `page_size` | integer | Número máximo de registros retornados \<\= 100. | - |
### Enumeradores bank_slip_status
| Campo | Descrição |
|---|---|
| accepted | Boleto na fila para registro |
| rejected | Boleto rejeitado |
| registered | Boleto registrado (disponível para pagamento) |
| payment_notice | Boleto pago - mas sem liquidação financeira |
| notary_office_payment_notice | rejected |
| paid | Boleto pago - baixado com liquidação financeira. |
| written_off | Boleto baixado sem liquidação financeira. |
### Enumeradores protest_status
| Campo | Descrição |
|---|---|
| accepted | Boleto na fila para registro |
## Response
STATUS 200
Response Body
```json
{
"data": [
{
"amount": 3,
"asset_type": {
"created_at": "2019-02-01T16:44:11",
"enumerator": "invoice",
"translation_path": "bank_slip.AssetType.invoice"
},
"automatic_bankruptcy_protest": true,
"automatic_protest": false,
"automatic_write_off": false,
"bank_slip_file": [],
"bank_slip_key": "96b32f1a-c2bd-41a4-b4b1-a169235be68b",
"bank_slip_status": {
"created_at": "2019-02-01T16:44:07",
"enumerator": "accepted",
"translation_path": "bank_slip.BankSlipStatus.accepted"
},
"bank_teller_instructions": "Não aceitar após vencimento",
"beneficiary_account_branch": "0001",
"beneficiary_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
"beneficiary_account_number": "67049",
"beneficiary_document_number": "12345678905",
"beneficiary_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"beneficiary_name": "Greg Brown",
"billing_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
"business_date_expiration": "2020-06-01",
"created_at": "2020-05-15T21:00:25",
"days_before_fine": null,
"days_before_interest": null,
"days_to_bankruptcy_protest": 1,
"days_to_protest": null,
"days_to_write_off": null,
"discount_limit_date": null,
"discount_value": null,
"document_number": "123456/01",
"expenses": [],
"expiration": "2020-06-01",
"fine_percentage": 0.1,
"guarantor_address": null,
"guarantor_city": null,
"guarantor_document": null,
"guarantor_name": null,
"guarantor_person_type": null,
"guarantor_postal_code": "00000000",
"guarantor_state": null,
"historical_our_number": 2,
"institution_registration_date": null,
"interest_daily_value": 0.34,
"lock_origin_type": null,
"nfe_key": null,
"nfe_url": null,
"occurrences": [
{
"created_at": "2020-05-15T21:00:25",
"discount_amount": null,
"discount_limit_date": null,
"iof_amount": null,
"new_bank_slip_status": null,
"new_due_date": "2020-06-01",
"new_protest_status": {
"created_at": "2019-02-01T16:44:08",
"enumerator": "not_protested",
"translation_path": "bank_slip.ProtestStatus.not_protested"
},
"notary_office_number": null,
"notary_office_protocol": null,
"occurrence_expenses": null,
"occurrence_feedback": null,
"occurrence_key": "c3ab3e01-f198-4e7e-9e01-7a8091b8bd72",
"occurrence_reasons": [],
"occurrence_type": {
"created_at": "2019-02-01T16:44:14",
"enumerator": "registration",
"translation_path": "bank_slip.OccurrenceType.registration"
},
"old_bank_slip_status": {
"created_at": "2019-02-01T16:44:07",
"enumerator": "accepted",
"translation_path": "bank_slip.BankSlipStatus.accepted"
},
"old_due_date": null,
"old_protest_status": null,
"paid_amount": null,
"paid_fine_amount": null,
"paid_interest_amount": null,
"payment_bank": null,
"payment_branch": null,
"payment_credit_date": null,
"payment_method": null,
"payment_origin": null,
"protest_confirmation": null,
"protest_expenses": null,
"rebate_amount": null,
"registration_institution_occurrence_date": "2020-05-15",
"registration_institution_occurrence_event": [
{
"cnab_file": {
"cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
"company_code": null,
"created_at": "2020-05-15T21:00:22",
"downloads": [],
"file_size": "None",
"filename": null,
"line_length": null,
"remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"requester_profile_code": null,
"type": {
"created_at": "2019-02-01T16:44:17",
"enumerator": "api_instruction",
"translation_path": "bank_slip.CNABFileType.api_instruction"
},
"url": null,
"version": null
},
"cnab_file_occurrence_order": 1,
"created_at": "2020-05-15T21:00:25",
"new_status": {
"created_at": "2019-02-01T16:44:15",
"enumerator": "waiting_submission",
"translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
},
"old_status": null
}
],
"registration_institution_occurrence_status": {
"created_at": "2019-02-01T16:44:15",
"enumerator": "waiting_submission",
"translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
},
"requester_occurrence_event": [
{
"cnab_file": {
"cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
"company_code": null,
"created_at": "2020-05-15T21:00:22",
"downloads": [],
"file_size": "None",
"filename": null,
"line_length": null,
"remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"requester_profile_code": null,
"type": {
"created_at": "2019-02-01T16:44:17",
"enumerator": "api_instruction",
"translation_path": "bank_slip.CNABFileType.api_instruction"
},
"url": null,
"version": null
},
"cnab_file_occurrence_order": 1,
"created_at": "2020-05-15T21:00:25",
"new_status": {
"created_at": "2019-02-01T16:44:16",
"enumerator": "accepted",
"translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
},
"old_status": null
}
],
"requester_occurrence_status": {
"created_at": "2019-02-01T16:44:16",
"enumerator": "accepted",
"translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
}
}
],
"our_number": 2,
"paid_amount": null,
"paid_fine_amount": null,
"paid_interest_amount": null,
"participant_control_number": null,
"payer_account_digit": null,
"payer_account_number": null,
"payer_account_type": null,
"payer_address": "Rua Carlos Tampaio, 112",
"payer_bank": null,
"payer_branch_digit": null,
"payer_branch_number": null,
"payer_document": "45508922008",
"payer_name": "John Nobody",
"payer_person_type": {
"created_at": "2019-02-01T16:44:09",
"enumerator": "natural",
"translation_path": "bank_slip.PersonType.natural"
},
"payer_postal_code": "00000000",
"payment_date": null,
"printing_policy": {
"created_at": "2019-02-01T16:44:10",
"enumerator": "no_printing",
"translation_path": "bank_slip.PrintingPolicy.no_printing"
},
"protest_status": {
"created_at": "2019-02-01T16:44:08",
"enumerator": "not_protested",
"translation_path": "bank_slip.ProtestStatus.not_protested"
},
"rebate_amount": null,
"registration_institution": {
"created_at": "2020-03-26T19:36:16",
"enumerator": "qi_scd",
"febraban_code": "329",
"remittance_sequence": 72,
"settlement_resource_account_key": "3e46d266-4fdb-4fd2-b87a-3e3de366afd4"
},
"requester_profile": 1,
"requester_profile_code": "329-01-0001-0067049",
"requester_registration_date": "2020-05-15"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"rows_per_page": 100,
},
"totals": {
"delayed_bank_slip_amount": 0,
"delayed_bank_slip_number": 0,
"due_bank_slip_amount": 3,
"due_bank_slip_number": 2,
"paid_bank_slip_amount": 0,
"paid_bank_slip_number": 0,
"total_bank_slip_amount": 3,
"total_bank_slip_number": 1,
"written_off_bank_slip_amount": 0,
"written_off_bank_slip_number": 0
}
}
```
STATUS 400
Response Body
```json
{
{"title": "Bad Request", "description": "Invalid request body.", "translation": "Corpo da requisição inválido.", "extra_fields": {}, "code": "LEG000069"}
}
```
:::danger Observações Gerais:
- O tamanho máximo da página (page_size) é 100.
- Caso o número de registros retornados na página corrente seja menor que o page_size o atributo next_page virá nulo.
:::
---
# Rotina de conciliação de arquivo retorno
URL: /documentation/boletos/consultar_v1/rotina_de_conciliacao_de_arquivo_retorno
Diariamente ocorre a conciliação de retornos para os boletos. Para garantir que os dados do dia estão atualizados,
utilize o endpoint especificado nesta página para verificar se os arquivos retorno estão disponíveis para
consulta. Recomendamos que o pooling seja feito a uma frequência não superior a uma requisição 2 minutos.
## Request
ENDPOINT /bank_slip/cnab_discharge_status
MÉTODO GET
## Response
STATUS 200
Response Body: Rotina concluída
```json
{
"discharge_ready": true
}
```
Response Body: Rotina pendente
```json
{
"discharge_ready": false
}
```
---
# Aprovar pagamento de boleto
URL: /documentation/boletos/pagamento/aprovar_pagamento
## Request
ENDPOINT /bank_slip/payment_approval
MÉTODO POST
**body.json**
```json
{
"operation_key": "0e241203-8c6b-4e0a-ac42-e0d2a2fc2d37",
"feedback": True
}
```
### Body params
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `operation_key` *| string | Chave entregue quando o pagamento foi criada (parâmetro key da resposta). | uuid |
| `feedback` | string | Booleano de aprovação ou rejeição da transferência: "true" ou "false". | - |
## Response
STATUS 200
Response Body
```json
{
"data": {
"error_list": [],
"successful_feedback_list": [
{
"account_key": "21af482f-b8ac-48dd-8f9a-ea23429d28be",
"approval_feedback": true,
"movement_amount": 10.0,
"movement_data": {
"digitable_line": "09990001029100010009895007444201283400000001000",
"resource_account_key": "21af482f-b8ac-48dd-8f9a-ea23429d28be"
},
"movement_date": "2020-08-06",
"movement_info": null,
"movement_request_key": "c154b5bf-66ac-4b37-b365-a4c05e68785b",
"movement_status": "approved",
"movement_type": "bank_slip_payment",
"requester_key": "ba99b7f1-3db6-4a63-a386-ba2c7f31e784"
}
]
},
"event_datetime": "2020-08-06 19:23:00",
"key": "9a1eedb3-da45-418c-89e9-28459d4c51ed",
"status": "ok",
"webhook_type": "bank_slip_payment_approval"
}
```
STATUS 400
Response Body
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
---
# Consultar linha digitável de boleto
URL: /documentation/boletos/pagamento/consulta_linha_digitavel
## Request
ENDPOINT /bank_slip/payment
MÉTODO GET
### Query params
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `digitable_line` *| string | Linha digitável do boleto. | 48 |
## Response
STATUS 200
Response Body
```json
{
"barcode": "31893833500000835480005050500512130021164946",
"beneficiary_bank_code": "318",
"beneficiary_document_number": "61902722000126",
"beneficiary_legal_name": "Sport Club Corinthians Paulista",
"beneficiary_person_type": "legal",
"calculated_internally": true,
"calculation_date": "2020-08-05",
"calculation_model": 1,
"digitable_line": "31890005025050051213700211649462383350000083548",
"discount_amount": "0",
"expiration_date": "2020-08-02",
"expired_as_of_payment_date": true,
"expired_as_of_today": true,
"factual_expiration_date": "2020-08-03",
"fine_amount": "16.71",
"guarantor_document": null,
"guarantor_name": null,
"interest_amount": "0",
"max_payment_date": "2020-08-08",
"nominal_amount": "835.48",
"payer_document_number": "15676407883",
"payer_legal_name": "LUCIANO RENATO MOREIRA",
"payer_person_type": "natural",
"payment_date": "2020-08-05",
"rebate_amount": "0.0",
"total_amount": "852.19",
"valid_payment_amount": true,
"valid_payment_calculation": true,
"valid_payment_time_frame": true
}
```
STATUS 400
Response Body
```json
{
"code": "BLP000142",
"title": "Bad Request",
"description": "This digitable line is out of minimum or maximum length.",
"translation": "Esta linha digitável está fora do comprimento mínimo ou máximo.",
"extra_fields": {}
}
```
STATUS 400
Response Body
```json
{
"code": "BLP000141",
"title": "Bad Request",
"http_status": 400,
"description": "The given digitable_line must have only numbers.",
"translation": "A linha digit\u00e1vel fornecida deve conter somente n\u00fameros.",
"extra_fields": {}
}
```
STATUS 400
Response Body
```json
{
"code": "BLP000012",
"title": "Bad Request",
"http_status": 400,
"description": "Missing mandatory parameter: digitable_line",
"translation": "Par\u00e2metro obrigat\u00f3rio ausente: digitable_line",
"extra_fields": {}
}
```
STATUS 422
Response Body
```json
{
"code": "IPP000014",
"title": "Invalid Barcode",
"http_status": 422,
"description": "Invalid barcode",
"translation": "O Código de barras é inválido",
"extra_fields": {}
}
```
STATUS 422
Response Body
```json
{
"code": "IPP000022",
"title": "Unprocessable Entity",
"http_status": 422,
"description": "Covenant not accepted",
"translation": "Convênio não aceito",
"extra_fields": {}
}
```
STATUS 422
Response Body
```json
{
"code": "IPP000023",
"title": "Unprocessable Entity",
"http_status": 422,
"description": "Max retries exceeded, while trying to complete payment.",
"translation": "Número máximo de tentativas excedido, ao tentar concluir o pagamento.",
"extra_fields": {}
}
```
STATUS 422
Response Body
```json
{
"code": "IPP000017",
"title": "Unprocessable Entity",
"http_status": 422,
"description": "The tax collection is overdue",
"translation": "A arrecadação está vencida",
"extra_fields": {}
}
```
### Response Params
| Campo | Tipo | Descrição | Caracteres |
| --- | -- |--------------------------------------------------------------------| --- |
|`barcode`| string | Código de barras do boleto. | 44 |
|`beneficiary_bank_code`| string | Código de bancário do banco que registrou o boleto. | 3 |
|`beneficiary_document_number`| string | CPF/CNPJ do beneficiário (recebedor) do boleto. Também é o CPF/CNPJ do titular da conta onde o boleto foi registrado. | 14 |
|`beneficiary_legal_name`| string | Nome do beneficiário (recebedor) do boleto. Também é o nome do titular da conta onde o boleto foi registrado. | - |
|`beneficiary_person_type`| enum | Natureza Jurídica do beneficiário (recebedor) do boleto. Também é a natureza jurídica do titular da conta onde o boleto foi registrado. | [Enumerador person_type](#enumeradores-person_type) |
|`calculated_internally`| boolean | Indica se o calculo foi realizado pela QI Tech ou não. | - |
|`calculation_date`| string | Data de referência do calculo de multa e juros do boleto. | 10 |
|`calculation_model`| int | Modelo de calculo utilizado no calculo de multa e juros do boleto. Este campo é informado pelo banco que registrou o boleto. | [Códigos calculation_model](#codigos-calculation_model) |
|`digitable_line`| uuid | Linha digitável do boleto. | 47 |
|`discount_amount`| string | Valor do desconto de pontualidade do boleto. | - |
|`expiration_date`| string | Data de vencimento do boleto. | 10 |
|`expired_as_of_payment_date`| boolean | Informa se o boleto estará vencido na data de agendamento do pagamento (Campo pode ser ignorado). | 10 |
|`expired_as_of_today`| string | Informa se o boleto esta vencido na data de hoje. | 10 |
|`factual_expiration_date`| string | Data de vencimento do boleto em dia útil. Por exemplo, se o boleto tiver vencimento em `2023-12-16` este campo terá o valor informado `2023-12-18`. | 10 |
|`fine_amount`| string | Valor calculado de multa do boleto. | - |
|`guarantor_document`| string | CPF/CNPJ do sacador avalista do boleto. | 14 |
|`guarantor_name`| string | Nome do sacador avalista do boleto. | - |
|`interest_amount`| string | Valor de juros calculado após o vencimento do boleto. | - |
|`max_payment_date`| string | Data limite de pagamento do boleto. | 10 |
|`nominal_amount`| string | Valor original do boleto. | - |
|`payer_document_number`| string | CPF/CNPJ do pagador do boleto. | 14 |
|`payer_legal_name`| string | Nome do pagador do boleto. | 14 |
|`payer_person_type`| enum | Natureza jurídcia do pagador do boleto. | [Enumerador person_type](#enumeradores-person_type) |
|`payment_date`| string | Data do pagamento do boleto. | 10 |
|`rebate_amount`| string | Valor de abatimento no boleto. | - |
|`total_amount`| string | Valor do total do boleto (com juros, multa, abatimento e desconto). | - |
|`valid_payment_amount`| boolean | Informa se o valor de pagamento é válido (será sempre `true`). | - |
|`valid_payment_calculation` | boolean | Informa se o valor calculado pelo banco registrador do boleto é válido (quando o `calculation_model` for `2` ou `3`). | - |
|`valid_payment_time_frame` | boolean | Informa se a data de agendamento do pagamento é menor que a data máxima para pagamento do boleto. | - |
### Enumeradores person_type
| Enumerador | Descrição |
| --- | -- |
| `natural` | Pessoa física |
| `legal` | Pessoa jurídica |
### Códigos calculation_model
| Enumerador | Descrição |
| --- | -- |
| 1 | Instituição pagadora do boleto calcula os valores de juros e multa do boleto (Caso seja informado no boleto consultado, o campo `calculated_internally` será retornado como `true`). |
| 2 | Instituição que registrou o boleto calcula os valores de juros e multa. Após a data de vencimento do boleto, a instituição atualiza os valores diariamente na base centralizada de boleto. |
| 3 | Instituição que registrou o boleto calcula o valor do boleto. A instituição atualiza o valor do boleto diariamente na base centralizada de boleto. |
## Ambiente de Sandbox
### Boletos de convênio/tributos
Os boletos de convênio/tributos são emitidos por órgãos governamentais, como prefeituras, governos estaduais ou federais, para a cobrança de impostos, taxas, contribuições sociais, multas, e outros valores devidos ao governo.
Em nosso ambiente de sandbox, disponibilizamos linhas digitáveis mockadas para a simulação de pagamentos bem-sucedidos e testes de cenários de erro.
### Cenários de sucesso
| Linha digitável |
|---|
| 828300000007411100972013905080001546763201900028 |
| 838000000009235700481007241345219112001474229880 |
| 848000000006308600802021201071261517689002201070 |
| 858200000015000000643025703477209504800448091020 |
### Cenários de erro
| Linha digitável | Código de erro |
|---|---|
| 858500000037350000643217212883260006147448091022 | IPP000014 |
### Boleto bancário
Um boleto bancário, também conhecido como boleto ou bloqueto, é um documento muito usado no Brasil para pagar por produtos ou serviços. Com um boleto, a pessoa ou empresa que o emite pode receber o dinheiro que está sendo cobrado do pagador.
Em nosso ambiente de sandbox, disponibilizamos linhas digitáveis mockadas para a simulação de pagamentos bem-sucedidos.
### Cenários de sucesso
| Linha digitável |
|---|
| 32990001039000210987502864982109595090000063958 |
| 32990001039000000006836762871105695090000010000 |
| 32990001031000699960099000000200195070000025527 |
| 32990001039000000000103194237800895060001000000 |
| 32990001031000699960095000000208497790000030990 |
---
# Realizar pagamento de boleto
URL: /documentation/boletos/pagamento/realizar_pagamento
### Request
ENDPOINT /bank_slip/payment
MÉTODO POST
Request Body
```json
{
"digitable_line": "42297034020000453753620034706323183380000005000",
"resource_account_key": "21af482f-b8ac-48dd-8f9a-ea23429d28be",
"payment_date": "2020-08-05"
}
```
#### Body params
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `digitable_line` *| string | Linha digitável do boleto. | 10 |
| `resource_account_key` *| string | Chave da conta que será utilizada. | 10 |
| `payment_date` | date | Data para a realização do pagamento. Se não enviada a data será hoje. | 10 |
:::info Informação
Para visualizar os convênios de pagamentos aceitos, [clique aqui](https://storage.googleapis.com/live-doc-api/public_samples/active_covenants.xlsx).
:::
### Response
STATUS 200
Response Body: Pagamento através de uma conta livre
```json
{
"data": {
"digitable_line": "09990001029100010009895007444201283400000001000",
"resource_account_key": "21af482f-b8ac-48dd-8f9a-ea23429d28be"
},
"event_datetime": "2020-08-06 19:22:06",
"key": "e7719f95-a31d-4171-ae83-2d8b3d419dc2",
"status": "success",
"webhook_type": "bank_slip_payment"
}
```
STATUS 200
Response Body: Pagamento através de uma conta escrow
```json
{
"data": {
"digitable_line": "09990001029100010009895007444201283400000001000",
"resource_account_key": "21af482f-b8ac-48dd-8f9a-ea23429d28be"
},
"event_datetime": "2020-08-06 19:22:06",
"key": "e7719f95-a31d-4171-ae83-2d8b3d419dc2",
"status": "waiting_approval",
"webhook_type": "bank_slip_payment"
}
```
STATUS 400
Response Body
```json
{
"code": "LEG000069"
"title": "Bad Request",
"description": "Invalid request body.",
"translation": "Corpo da requisição inválido.",
"extra_fields": {}
}
```
STATUS 423 - Pagamento fora do horário
Response Body
```json
{
"code": "BLP000024",
"title": "Locked",
"http_status": 423,
"description": "Operation window closed. System available from {OPENING_TIME} to {CLOSING_TIME}",
"translation": "Opera\u00e7\u00e3o encerrada. Sistema dispon\u00edvel de {OPENING_TIME} a {CLOSING_TIME}",
"extra_fields": {
"next_available_datetime": "2023-08-13T18:00:00.000Z"
}
}
```
STATUS 400
Response Body
```json
{
"code": "IPP000015",
"title": "Bad Request",
"http_status": 400,
"description": "Invalid amount",
"translation": "O valor inserido é inválido",
"extra_fields": {}
}
```
STATUS 422
Response Body
```json
{
"code": "IPP000013",
"title": "Incompatible Payment Value",
"http_status": 422,
"description": "The input amount does not match tax collection value",
"translation": "O valor do pagamento é diferente da arrecadação",
"extra_fields": {}
}
```
STATUS 422
Response Body
```json
{
"code": "IPP000012",
"title": "Tax Collection Already Paid",
"http_status": 422,
"description": "This tax collection is already paid",
"translation": "A arrecadação já foi paga",
"extra_fields": {}
}
```
STATUS 422
Response Body
```json
{
"code": "IPP000017",
"title": "Unprocessable Entity",
"http_status": 422,
"description": "The tax collection is overdue",
"translation": "A arrecadação está vencida",
"extra_fields": {}
}
```
STATUS 422
Response Body
```json
{
"code": "IPP000023",
"title": "Unprocessable Entity",
"http_status": 422,
"description": "Max retries exceeded, while trying to complete payment.",
"translation": "Número máximo de tentativas excedido, ao tentar concluir o pagamento.",
"extra_fields": {}
}
```
STATUS 422
Response Body
```json
{
"code": "IPP000024",
"title": "Unprocessable Entity",
"http_status": 422,
"description": "Error while processing payment output. Try again.",
"translation": "Erro ao processar a saída do pagamento. Tente novamente.",
"extra_fields": {}
}
```
STATUS 422
Response Body
```json
{
"code": "IPP000025",
"title": "Unprocessable Entity",
"http_status": 422,
"description": "Outside of covenant payment hours.",
"translation": "Fora do horário de pagamento do convênio.",
"extra_fields": {}
}
```
## Ambiente de Sandbox
### Boletos de convênio/tributos
Os boletos de convênio/tributos são emitidos por órgãos governamentais, como prefeituras, governos estaduais ou federais, para a cobrança de impostos, taxas, contribuições sociais, multas, e outros valores devidos ao governo.
Em nosso ambiente de sandbox, disponibilizamos linhas digitáveis mockadas para a simulação de pagamentos bem-sucedidos e testes de cenários de erro.
#### Cenários de sucesso
| Linha digitável |
|---|
| 828300000007411100972013905080001546763201900028 |
| 838000000009235700481007241345219112001474229880 |
| 848000000006308600802021201071261517689002201070 |
| 858200000015000000643025703477209504800448091020 |
#### Cenários de erro
| Linha digitável | Código de erro |
|---|---|
| 858900000034050002701002700011434710592720230733 | IPP000015 |
| 858400000000750002701007700011434710592720230733 | IPP000013 |
| 858800000040450004322322120716192390688090088931 | IPP000012 |
| 858900000000350004322326120716192390688090083760 | IPP000014 |
### Boleto bancário
Um boleto bancário, também conhecido como boleto ou bloqueto, é um documento muito usado no Brasil para pagar por produtos ou serviços. Com um boleto, a pessoa ou empresa que o emite pode receber o dinheiro que está sendo cobrado do pagador.
Em nosso ambiente de sandbox, disponibilizamos linhas digitáveis mockadas para a simulação de pagamentos bem-sucedidos.
#### Cenários de sucesso
| Linha digitável |
|---|
| 32990001039000210987502864982109595090000063958 |
| 32990001039000000006836762871105695090000010000 |
| 32990001031000699960099000000200195070000025527 |
| 32990001039000000000103194237800895060001000000 |
| 32990001031000699960095000000208497790000030990 |
---
# Redirecionamento da Conta de Liquidação de um Boleto
URL: /documentation/boletos/redirecionamento_de_conta_de_liquidacao
Esse endpoint será utilizado para alterar a conta de liquidação de um boleto registrado na QI Tech.
:::caution Atenção!
- O boleto permanece registrado na conta original, ela deve permanecer aberta enquanto houverem boletos resgistrados nela;
- Os webhooks permanecerão sendo enviados para o parceiro integrador da conta original;
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /settlement_account
MÉTODO PATCH
### Path parameters
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta em que o boleto foi emitido | 36 |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira| 36 |
| `bank_slip_key` | uuidv4 | Chave única de identificação do boleto | 36 |
Request Body
```json
{
"settlement_account_key": "614a451d-3b82-460e-bcc0-2caf3dde711f"
}
```
### Request Body Params
| Campo | Tipo | Descrição | Caracteres |
|------------------------------|---------|-------------------------------------------------------|------------|
| `settlement_account_key` * | uuidv4 | Chave única que identifica a nova conta de liquidação | 36 |
## Response
STATUS 204
Response Body
```json
{}
```
### Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (pt-br)
`translation` |
|--------------------------|----------------------|--------------------|----------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | BKS000025 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BKS000007 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. |
| 400 | BKS000008 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BKS000009 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 400 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). | |
| 400 | BKS000032 | Bad Request | Bank slip must be in 'registered' status. | O boleto deve possuir o status 'registered'. |
| 400 | BKS000052 | Bad Request | Invalid account status. | Status da conta inválido. |
---
# Emissão de um bolePix
URL: /documentation/boletos/v1/emissao/emissao_de_um_bolepix
:::caution Atenção
Antes de registrar um bolePix é necessário que a exista uma Chave Pix Aleatória ativa na conta onde o boleto será registrado.
:::
Na QI Tech, é possível realizar a emissão de um boleto vinculado a um QR Code Pix.
Desta forma, o sacado poderá realizar o pagamento do boleto através da linha digitável do boleto registrado ou então através da leitura do QR Code Pix vinculado a este boleto.
Nos casos em que o sacado realizar o pagamento através de leitura do QR Code Pix, a liquidação financeira do pagamento será instatânea, sendo que os retornos bancários, bem com os webhooks a respeito da liquidação deste boleto serão gerados da mesma forma que um boleto comum.
## Request
ENDPOINT /multibank_instruction
MÉTODO POST
Request Body
```json
{
"occurrences": [{
"amount": 1000,
"automatic_bankruptcy_protest": false,
"bank_teller_instructions": "Não pagar após vencimento.",
"beneficiary_account_key": "8a35e639-8420-4f6c-9647-c2515e5381ef",
"beneficiary_key": "3c866e34-23fe-46c2-a8b0-e39ca4348923",
"days_to_bankruptcy_protest": 0,
"document_number": "123456/01",
"expiration": "2020-06-01",
"fine_percentage": "3",
"interest_daily_value": "0.34",
"occurrence_type": "registration",
"payer_address": "Rua Carlos Sampaio, 123",
"payer_document": "41184562067",
"payer_name": "João Ninguem",
"payer_person_type": "natural",
"payer_postal_code_root": "15800",
"payer_postal_code_suffix": "020",
"printing_policy": "no_printing",
"registration_institution_enumerator": "qi_scd",
"requester_profile": "09",
"requester_profile_code": "329-09-0001-0000002",
"pix_key": "1684629c-d52a-4941-92f5-410907316129"
}]
}
```
### Query params
| Campo | Tipo | Descrição | Caracteres |
|---|---|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| `use_multi_process` | boolean | Indica se o processamento das ocorrências de registro serão enviados para processamento em fila ou se serão processados de forma sequencial. Caso seja este parâmetro seja informado como `true`, é obrigatório o envio do nosso número bancário `our_number` no payload da ocorrência de registro. | - |
### Body params
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `occurrences` * | array of objects | Lista de ocorrências a serem processadas. | **[Objeto occurrences](#objeto-occurrences)** |
### Objeto occurrences
| Campo | Tipo | Descrição | Caracteres |
|--------------------------------------|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------|
| `amount` * | double | Valor do boleto. | - |
| `automatic_bankruptcy_protest` | boolean | Configuração de protesto automático. | - |
| `bank_teller_instructions` | string | Instruções ao caixa (Mensagem/Observações do boleto). | - |
| `beneficiary_account_key` | string | Chave da conta do beneficiário. | - |
| `beneficiary_key` | string | Chave do beneficiário. | - |
| `days_to_bankruptcy_protest` | int | Número de dias para envio automático de protesto falimentar. | - |
| `document_number` | string | Numero do documento. | - |
| `expiration` * | string | Data de vencimento. | - |
| `fine_percentage` | string | Porcentagem de multa | - |
| `interest_daily_value` | string | Valor de juros por dia em reais | - |
| `occurrence_type` * | string | Tipo de ocorrência. | - |
| `payer_address` | string | Endereço do pagador. | - |
| `payer_document` * | string | Documento do pagador (CPF ou CNPJ). | - |
| `payer_name` * | string | Nome do pagador. | - |
| `payer_person_type` * | string | Tipo de pessoa pagante. | - |
| `payer_postal_code_root` | string | Os cinco primeiros digitos do CEP. | - |
| `payer_postal_code_suffix` | string | Os três últimos dígitos do CEP. | - |
| `printing_policy` | string | Política de impressão do boleto | - |
| `registration_institution_enumerator` * | string | Será sempre `qi_scd`. | `qi_scd` |
| `requester_profile` * | string | Número da carteira. | 02 |
| `requester_profile_code` * | string | Código da carteira composto da seguinte forma: "329-carteira-agencia-conta_com_7_digitos". OBS: a carteira de cobrança padrão QI Tech é de numero "09". | - |
| `notification` | object | Número da carteira. | **[Objeto notification](#objeto-notification)** |
| `discounts` | object | Lista de objetos com informações de desconto. | **[Objeto discounts](#objeto-discounts)** |
| `guarantor_name` | string | Nome do sacador avalista. | - |
| `guarantor_document_root` | string | Base do CNPJ do sacador avalista. | - |
| `guarantor_document_subsidiary` | string | Informação de CNPJ de matriz ou filial. | - |
| `guarantor_document_digit` | string | Dígito verificador do CNPJ. | - |
| `pix_key` * | string | Chave Pix onde o QR Code Pix vinculado ao bolepix será registrado. | 100 |
:::info Campo “***pix_key***”
A “***pix_key***” pode ser um **CPF**, **CNPJ**, **E-mail**, **Celular** ou uma **Chave Aleatória** (UUID), seguindo as seguintes formatações:
**CPF:** Número inteiro com 11 dígitos.
**CNPJ:** Número inteiro com 14 dígitos.
**E-mail:** Texto contendo ao menos um “@”.
**Celular:** Texto contendo os seguintes valores: “+55” + “DDD do celular“ + “Número Inteiro do Celular com no mínimo 8 e no máximo 9 dígitos”. Ex: “+5511987654321“.
**Chave Aleatória:** UUID.
:::
### Objeto notification
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `document_number` * | string | Numero de documento do usuario que vai receber a notificação. | - |
| `email` * | string | Email do usuario que vai receber a notificação. | - |
| `name` * | string | Nome do usuario que vai receber a notificação.| - |
| `phone` * | object | Objeto contento informações do telefone do usuario que vai receber a notificação. | **[Objeto phone](#objeto-phone)** |
| `send_2_way` * | booleano | Enviar notificações de emissão de segunda via. | true/false |
| `send_after_due_date` * | boolean | Enviar notificações após a data de vencimento do boleto. | true/false |
| `send_before_due_date` * | boolean | Enviar notificações antes da data de vencimento do boleto. | true/false |
| `send_on_protest` * | boolean | Enviar notificações de protesto. | true/false|
### Objeto phone
| Campo | Descrição | Exemplo | Máx. Caracteres |
| --- | --- | --- | --- |
|`country_code` | string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 |
| `area_code` | string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2 |
| `number` | string |Número de telefone (apenas números) | 10 |
### Objeto discounts
| Campo | Descrição | Exemplo | Máx. Caracteres |
| --- | --- | --- | --- |
|`discount_value` | float | Valor do desconto.| 3 |
| `discount_number` | int32 | Ordem que o desconto deve ser aplicado. | 2 |
| `discount_limit_date` | date | Data limite do desconto. | 10 |
## Response
STATUS 200
Response Body
```json
{
"bank_slips": [
{
"amount": "649.73",
"bank_slip_key": "4bc636d0-1e41-4ce6-801c-475814bf4dcf",
"bank_slip_status": "accepted",
"barcode": "32991916500000649730001090000699935200347340",
"beneficiary_account_key": "1c977186-9167-4ef1-b27d-08483429f74c",
"beneficiary_key": "f01d4877-b1cc-4f4a-a8f9-952c2cef9ca8",
"digitable_line": "32990001039000069993552003473403191650000064973",
"expiration": "2022-11-10",
"nfe_key": null,
"nfe_url": null,
"our_number": 6999352,
"participant_control_number": null,
"payer_postal_code": "38050000",
"protest_status": "not_protested",
"qr_code": {
"pix_key": "9de04466-0b02-4263-9c28-9cdc0fb638bb",
"qr_code_key": "881979cb-1c15-4dea-a05e-316caae22f5e",
"qr_code_url": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/881979cb-1c15-4dea-a05e-316caae22f5e5204000053039865802BR5925LOTEAMENTO RESIDENCIAL PO6014PORTO NACIONAL61087750000062070503***630414B8"
}
}
],
"file_info": {
"beneficiary_code": null,
"beneficiary_name": null,
"file_sequence_id": null,
"file_type_identifier": null,
"file_type_literal": null,
"service_code": null,
"service_literal": null,
"wrote_at": null
},
"occurrence_stats": {
"bank_slip_edit": 0,
"bankruptcy_protest_request": 0,
"cancel_rebate": 0,
"extension": 0,
"notary_office_entry": 0,
"notary_office_exit": 0,
"notary_office_payment": 0,
"notification": 0,
"payment": 0,
"payment_notice": 0,
"payment_write_off": 0,
"protest_cancel_and_write_off_request": 0,
"protest_cancel_request": 0,
"protest_remove_request": 0,
"protest_request": 0,
"rebate": 0,
"registration": 1,
"write_off": 0
},
"semantic_errors": []
}
```
STATUS 400
Response Body
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
### Response Params
| Campo | Tipo | Descrição | Caracteres |
| --- | -- |--------------------------------------------------------------------| --- |
|`bank_slips` | list | Lista com a informações dos boletos registrados caso o parâmetro `use_multi_process` seja informado com o valor `false`. | [Objeto Bank Slip](#objeto-bank_slip) |
| `file_info` | list | Informações do arquivo, . | [Objeto File Info](#objeto-file-info) |
| `occurrence_stats` | object | Informações do arquivo, . | [Objeto File Info](#objeto-file-info) |
| `semantic_errors` | list | Lista de erros no processamento de cada boleto. Será retornado caso exista algum erro no processamento e caso o parâmetro `use_multi_process` seja informado com o valor `false`. | [Objeto Semantic Error](#objeto-semantic-error) |
### Objeto bank_slip
| Campo | Tipo | Descrição | Caracteres |
| --- | -- |--------------------------------------------------------------------| --- |
|`amount` | float | Valor do boleto. | - |
|`bank_slip_key` | uuid | Chave unica de identificação do boleto na QI Tech. | 36 |
|`bank_slip_status` | enum | Chave unica de identificação do boleto na QI Tech. | [Enumeradores bank_slip_status](#enumeradores-bank_slip_status) |
|`barcode` | string | Código de barras do boleto. | 44 |
|`beneficiary_account_key` | uuid | Chave unica de identificação da conta em que o boleto foi registrado. | 36 |
|`beneficiary_key` | uuid | Chave unica de identificação do titular da conta em que o boleto foi registrado. | 36 |
|`digitable_line` | uuid | Linha digitável do boleto. | 47 |
|`expiration` | string | Data de vencimento do boleto. | 10 |
|`nfe_key` | string | Chave unica de identificação da nota fiscal eletrônica. | - |
|`nfe_url` | string | URL da nota fiscal eletrônica. | - |
|`our_number` | int | Nosso número bancário. É um número sequencial de identificação deste boleto em relação a conta (carteira de cobrança) em que ele foi registrado. Seu valor pode ser informado na requisição de registro do boleto. Caso não seja informado, a QI Tech gerará um valor deste campo (sendo este um valor incremental, ex: 1º boleto registrado na conta terá o `our_number` de valor 1, o 16º boleto registrado na conta terá o `our_number` de valor 16). | -
|`participant_control_number` | string | Número de controle do participante. | 10 |
|`payer_postal_code` | string | CEP do pagador do boleto. | 8 |
|`protest_status` | string | Situação do protesto do boleto, caso o protesto tenha sido solicitado. | [Enumeradores protest_status](#enumeradores-protest_status) |
|`qr_code` | object | Objeto com as informações do QR Code Pix vinculado ao boleto. | [Objeto qr_code](#objeto-qr_code) |
### Objeto qr_code
| Campo | Tipo | Descrição | Caracteres |
| --- | -- |--------------------------------------------------------------------| --- |
|`pix_key` | string | Chave pix onde o QR Code Pix vinculado ao boleto foi registrado. | 100 |
|`qr_code_key` | uuid | Chave única de identificação do QR Code Pix vinculado ao boleto . | 36 |
|`qr_code_url` | uuid | URL do Pix Copia e Cola do QR Code Pix vinculado ao boleto. | 36 |
### Enumeradores bank_slip_status
| Enumerador | Descrição |
| --- | -- |
| `accepted` | Boleto aceito para processamento |
| `registered` | Registro do boleto foi concluído na câmara de registro de boletos |
| `paid` | Valor do pagamento do boleto foi creditado na conta do beneficiário do boleto |
| `written_off` | Boleto baixado (boleto não é mais pagável) |
| `rejected` | Registro de boleto rejeitado pela câmara de registro de boletos |
| `payment_notice` | Aviso de que o pagamento do boleto foi processado no banco pagador (porém a liquidação na conta do beneficiário ainda não ocorreu) |
| `notary_office_payment_notice` | Aviso de que o pagamento de um boleto protestado foi processado no banco pagador (porém o cartório ainda não realizou o repasse do pagamento e a liquidação na conta do beneficiário ainda não ocorreu) |
### Enumeradores protest_status
| Enumerador | Descrição |
| --- | -- |
| `not_protested` | Boleto não possui solicitação de protesto. |
| `protest_requested` | Boleto com solicitação de protesto em processamento pela QI Tech. |
| `notary_office_entry` | Solicitação de protesto de boleto foi aceita pelo cartório. |
| `protest_cancel_requested` | Solicitação de cancelamento de protesto em processamento pela QI Tech. |
| `notary_office_exit` | Protesto do boleto foi retirado do cartório. |
| `protested` | Protesto foi confirmado pelo cartório e o boleto se encontrada protestado. |
| `paid_at_notary_office` | Cartório identificou o pagamento do protesto do boleto e esta processando o repasse do pagamento para a QI Tech. |
| `judicially_suspended` | Protesto suspenso judicialmente. |
| `protest_remove_requested` | Solicitação de retirada de protesto foi aceita pelo cartório. |
---
# Emissão de boleto via CNAB
URL: /documentation/boletos/v1/emissao/emissao_via_cnab
## Request
ENDPOINT /multibank_cnab
MÉTODO POST
:::caution Atenção!
A chamada deve ser autenticada seguindo o padrão descrito na seção AUTENTICAÇÃO E SEGURANÇA. Com as seguintes ressalvas:
**1 -** O valor da variável ContentMD5 deverá ser a Hash MD5 do binário arquivo a ser enviado;
**2 -** O binário do arquivo deve ser enviado no corpo da request como um FormData utilizando como chave a string "file" e no valor o arquivo a ser enviado. (Este conteúdo não é encriptado);
:::
:::info
O arquivo transmitido nesta chamada deve seguir o padrão de Layout de Arquivo de Cobrança com 400 posições da QI Tech.
Segue link para download do manual: [Layout de Cobrança - QI Tech versão 2.1.](https://storage.googleapis.com/live-doc-api/public_samples/Layout%20de%20Cobran%C3%A7a%20-%20QI%20Tech%20v2.1.pdf)
:::
STATUS 200
Response Body
```json
{
"cnab_file": {
"cnab_key": "52ff2ea1-a17f-4476-8eb8-617ddd16a81e",
"company_code": null,
"created_at": "2020-04-17T21:41:09",
"downloads": [
{
"cnab_file_id": 0,
"created_at": "2020-04-17T21:41:09",
"document_number": "41184562067",
"name": "João Ninguem",
"person_key": "string"
}
],
"file_size": "None",
"filename": "1905200807.REM",
"line_length": 400,
"remitter_key": "329",
"requester_profile_code": "329-01-0001-0000002",
"type": "requester_remittance",
"url": "https://google.com",
"version": "1"
},
"file_info": {
"bank_warning_number": 244,
"beneficiary_code": "1234567",
"beneficiary_name": "QI SOCIEDADE DE CREDITO DIRETO",
"credit_date": 190520,
"file_type_identifier": 1,
"file_type_literal": "REMESSA",
"service_code": 1,
"service_literal": "COBRANCA",
"wrote_at": 180520
},
"occurrence_list": [
{
"amount": "1399.67",
"asset_type": "invoice",
"automatic_bankruptcy_protest": true,
"automatic_protest": false,
"automatic_write_off": false,
"bank_teller_instructions": "SOMAR OS ENCARGOS PERTINENTES",
"beneficiary_account_branch": 1,
"beneficiary_account_number": 1273,
"beneficiary_account_number_digit": "1",
"cnab_file_occurrence_order": 1,
"days_before_fine": 0,
"days_before_interest": 0,
"days_to_bankruptcy_protest": 10,
"days_to_protest": 0,
"days_to_write_off": 0,
"discount_limit_date": "2020-05-14 00:00:00",
"discount_value": "0.00",
"document_number": "0198874/01",
"expiration": "2020-06-18 00:00:00",
"fine_percentage": "2.00",
"guarantor_address": "AVENIDA DAS AMERICAS, 1321",
"guarantor_city": "FAZENDA RIO GRANDE",
"guarantor_document_digit": 86,
"guarantor_document_root": 80550452,
"guarantor_document_subsidiary": 1,
"guarantor_name": "PLASTILIT PRODUTOS PLASTICOS DO PARANA S.A.",
"guarantor_postal_code_root": 83820,
"guarantor_postal_code_suffix": 23,
"guarantor_state": "PR",
"interest_daily_value": "4.67",
"messages": [
{"SOMAR OS ENCARGOS PERTINENTES"}
]
"occurrence_cnab_line": 2,
"occurrence_feedback": null,
"occurrence_sequence": "0",
"occurrence_type": "registration",
"origin_type": "remittance",
"our_number": 109001065,
"our_number_digit": "1",
"participant_control_number": "700000004167313",
"payer_address": "AVENIDA 7 DE SETEMBRO, N. 1043",
"payer_document": "77900454000143",
"payer_name": "ARLINDO RAGAZZON ME",
"payer_person_type": "legal",
"payer_postal_code_root": 89874,
"payer_postal_code_suffix": 0,
"printing_policy": "no_printing",
"rebate_amount": "0.00",
"registration_institution_enumerator": "bradesco",
"registration_institution_febraban_code": "237",
"requester_key": "64d3bafa-2205-43ca-b6a7-2827aefe3ebc",
"requester_profile": 19,
"requester_profile_code": "237-19-0001-0001273",
"requester_registration_date": "2020-05-18 00:00:00",
}
]
}
```
STATUS 400
Response Body
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
---
# Emissão de boleto via JSON
URL: /documentation/boletos/v1/emissao/emissao_via_json
## Request
ENDPOINT /multibank_instruction
MÉTODO POST
Request Body
```json
{
"occurrences": [
{
"amount": 1000,
"automatic_bankruptcy_protest": false,
"bank_teller_instructions": "Não pagar após vencimento.",
"beneficiary_account_key": "8a35e639-8420-4f6c-9647-c2515e5381ef",
"beneficiary_key": "3c866e34-23fe-46c2-a8b0-e39ca4348923",
"days_to_bankruptcy_protest": 0,
"document_number": "123456/01",
"expiration": "2020-06-01",
"fine_percentage": "3",
"interest_daily_value": "0.34",
"occurrence_type": "registration",
"payer_address": "Rua Carlos Sampaio, 123",
"payer_document": "41184562067",
"payer_name": "João Ninguem",
"payer_person_type": "natural",
"payer_postal_code_root": "15800",
"payer_postal_code_suffix": "020",
"printing_policy": "no_printing",
"registration_institution_enumerator": "qi_scd",
"requester_profile": "09",
"requester_profile_code": "329-09-0001-0000002"
}
]
}
```
:::danger Atenção!
Caso os dados de endereço do pagador do boleto não sejam informados, não será possível realizar o protesto do boleto em caso de não pagamento.
:::
### Query params
| Campo | Tipo | Descrição | Caracteres |
|---|---|-------------------------------------------------------------------------------------------|---------------|
| `use_multi_process` | boolean | Indica se o processamento das ocorrências de registro serão enviados para processamento em fila ou se serão processados de forma sequencial. Caso seja este parâmetro seja informado como `true`, é obrigatório o envio do nosso número bancário `our_number` no payload da ocorrência de registro. | - |
### Body params
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `occurrences` * | array of objects | Lista de ocorrências a serem processadas. | **[Objeto occurrences](#objeto-occurrences)** |
### Objeto occurrences
| Campo | Tipo | Descrição | Caracteres |
|--------------------------------------|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------|
| `amount` * | double | Valor do boleto. | - |
| `automatic_bankruptcy_protest` | boolean | Configuração de protesto automático. | - |
| `bank_teller_instructions` | string | Instruções ao caixa (Mensagem/Observações do boleto). | - |
| `beneficiary_account_key` | string | Chave da conta do beneficiário. | - |
| `beneficiary_key` | string | Chave do beneficiário. | - |
| `days_to_bankruptcy_protest` | int | Número de dias para envio automático de protesto falimentar. | - |
| `document_number` | string | Numero do documento. | - |
| `expiration` * | string | Data de vencimento. | - |
| `fine_percentage` | string | Porcentagem de multa | - |
| `interest_daily_value` | string | Valor de juros por dia em reais | - |
| `occurrence_type` * | string | Tipo de ocorrência. | - |
| `payer_address` | string | Endereço do pagador. | - |
| `payer_document` * | string | Documento do pagador (CPF ou CNPJ). | - |
| `payer_name` * | string | Nome do pagador. | - |
| `payer_person_type` * | string | Tipo de pessoa pagante. | - |
| `payer_postal_code_root` | string | Os cinco primeiros digitos do CEP. | - |
| `payer_postal_code_suffix` | string | Os três últimos dígitos do CEP. | - |
| `printing_policy` | string | Política de impressão do boleto | - |
| `registration_institution_enumerator` * | string | Será sempre `qi_scd`. | `qi_scd` |
| `requester_profile` * | string | Número da carteira. | 02 |
| `requester_profile_code` * | string | Código da carteira composto da seguinte forma: "329-carteira-agencia-conta_com_7_digitos". OBS: a carteira de cobrança padrão QI Tech é de numero "09". | - |
| `notification` | object | Número da carteira. | **[Objeto notification](#objeto-notification)** |
| `discounts` | object | Lista de objetos com informações de desconto. | **[Objeto discounts](#objeto-discounts)** |
| `guarantor_name` | string | Nome do sacador avalista. | - |
| `guarantor_document_root` | string | Base do CNPJ do sacador avalista. | - |
| `guarantor_document_subsidiary` | string | Informação de CNPJ de matriz ou filial. | - |
| `guarantor_document_digit` | string | Dígito verificador do CNPJ. | - |
### Objeto notification
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `document_number` * | string | Numero de documento do usuario que vai receber a notificação. | - |
| `email` * | string | Email do usuario que vai receber a notificação. | - |
| `name` * | string | Nome do usuario que vai receber a notificação.| - |
| `phone` * | object | Objeto contento informações do telefone do usuario que vai receber a notificação. | **[Objeto phone](#objeto-phone)** |
| `send_2_way` * | booleano | Enviar notificações de emissão de segunda via. | true/false |
| `send_after_due_date` * | boolean | Enviar notificações após a data de vencimento do boleto. | true/false |
| `send_before_due_date` * | boolean | Enviar notificações antes da data de vencimento do boleto. | true/false |
| `send_on_protest` * | boolean | Enviar notificações de protesto. | true/false|
### Objeto phone
| Campo | Tipo | Descrição | Caracteres |
| --- | --- | --- | --- |
|`country_code` | string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 |
| `area_code` | string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2 |
| `number` | string |Número de telefone (apenas números) | 10 |
### Objeto discounts
| Campo | Tipo | Descrição | Caracteres |
| --- | --- |-----------------------------------------|------------|
|`discount_value` | float | Valor do desconto. | - |
| `discount_number` | int | Ordem que o desconto deve ser aplicado. | - |
| `discount_limit_date` | date | Data limite do aplicação do desconto. | 10 |
## Response
STATUS 200
Response Body
```json
{
"bank_slips": [
{
"amount": "649.73",
"bank_slip_key": "4bc636d0-1e41-4ce6-801c-475814bf4dcf",
"bank_slip_status": "accepted",
"barcode": "32991916500000649730001090000699935200347340",
"beneficiary_account_key": "1c977186-9167-4ef1-b27d-08483429f74c",
"beneficiary_key": "f01d4877-b1cc-4f4a-a8f9-952c2cef9ca8",
"digitable_line": "32990001039000069993552003473403191650000064973",
"expiration": "2022-11-10",
"nfe_key": null,
"nfe_url": null,
"our_number": 6999352,
"participant_control_number": null,
"payer_postal_code": "38050000",
"protest_status": "not_protested"
}
],
"file_info": {
"beneficiary_code": null,
"beneficiary_name": null,
"file_sequence_id": null,
"file_type_identifier": null,
"file_type_literal": null,
"service_code": null,
"service_literal": null,
"wrote_at": null
},
"occurrence_stats": {
"bank_slip_edit": 0,
"bankruptcy_protest_request": 0,
"cancel_rebate": 0,
"extension": 0,
"notary_office_entry": 0,
"notary_office_exit": 0,
"notary_office_payment": 0,
"notification": 0,
"payment": 0,
"payment_notice": 0,
"payment_write_off": 0,
"protest_cancel_and_write_off_request": 0,
"protest_cancel_request": 0,
"protest_remove_request": 0,
"protest_request": 0,
"rebate": 0,
"registration": 1,
"write_off": 0
},
"semantic_errors": []
}
```
STATUS 400
Response Body
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}",
"title": "Bad Request",
"description": "Invalid request body.",
"translation": "Corpo da requisição inválido.",
"extra_fields": {},
"code": "LEG000069"
}
```
### Response Params
| Campo | Tipo | Descrição | Caracteres |
| --- | -- |--------------------------------------------------------------------| --- |
|`bank_slips` | list | Lista com a informações dos boletos registrados caso o parâmetro `use_multi_process` seja informado com o valor `false`. | [Objeto Bank Slip](#objeto-bank_slip) |
| `file_info` | list | Informações do arquivo, . | [Objeto File Info](#objeto-file-info) |
| `occurrence_stats` | object | Informações do arquivo, . | [Objeto File Info](#objeto-file-info) |
| `semantic_errors` | list | Lista de erros no processamento de cada boleto. Será retornado caso exista algum erro no processamento e caso o parâmetro `use_multi_process` seja informado com o valor `false`. | [Objeto Semantic Error](#objeto-semantic-error) |
### Objeto bank_slip
| Campo | Tipo | Descrição | Caracteres |
| --- | -- |--------------------------------------------------------------------| --- |
|`amount` | float | Valor do boleto. | - |
|`bank_slip_key` | uuid | Chave unica de identificação do boleto na QI Tech. | 36 |
|`bank_slip_status` | enum | Chave unica de identificação do boleto na QI Tech. | [Enumeradores bank_slip_status](#enumeradores-bank_slip_status) |
|`barcode` | string | Código de barras do boleto. | 44 |
|`beneficiary_account_key` | uuid | Chave unica de identificação da conta em que o boleto foi registrado. | 36 |
|`beneficiary_key` | uuid | Chave unica de identificação do titular da conta em que o boleto foi registrado. | 36 |
|`digitable_line` | uuid | Linha digitável do boleto. | 47 |
|`expiration` | string | Data de vencimento do boleto. | 10 |
|`nfe_key` | string | Chave unica de identificação da nota fiscal eletrônica. | - |
|`nfe_url` | string | URL da nota fiscal eletrônica. | - |
|`our_number` | int | Nosso número bancário. É um número sequencial de identificação deste boleto em relação a conta (carteira de cobrança) em que ele foi registrado. Seu valor pode ser informado na requisição de registro do boleto. Caso não seja informado, a QI Tech gerará um valor deste campo (sendo este um valor incremental, ex: 1º boleto registrado na conta terá o `our_number` de valor 1, o 16º boleto registrado na conta terá o `our_number` de valor 16). | -
|`participant_control_number` | string | Número de controle do participante. | 10 |
|`payer_postal_code` | string | CEP do pagador do boleto. | 8 |
|`protest_status` | string | Situação do protesto do boleto, caso o protesto tenha sido solicitado. | [Enumeradores protest_status](#enumeradores-protest_status) |
### Enumeradores bank_slip_status
| Enumerador | Descrição |
| --- | -- |
| `accepted` | Boleto aceito para processamento |
| `registered` | Registro do boleto foi concluído na câmara de registro de boletos |
| `paid` | Valor do pagamento do boleto foi creditado na conta do beneficiário do boleto |
| `written_off` | Boleto baixado (boleto não é mais pagável) |
| `rejected` | Registro de boleto rejeitado pela câmara de registro de boletos |
| `payment_notice` | Aviso de que o pagamento do boleto foi processado no banco pagador (porém a liquidação na conta do beneficiário ainda não ocorreu) |
| `notary_office_payment_notice` | Aviso de que o pagamento de um boleto protestado foi processado no banco pagador (porém o cartório ainda não realizou o repasse do pagamento e a liquidação na conta do beneficiário ainda não ocorreu) |
### Enumeradores protest_status
| Enumerador | Descrição |
| --- | -- |
| `not_protested` | Boleto não possui solicitação de protesto. |
| `protest_requested` | Boleto com solicitação de protesto em processamento pela QI Tech. |
| `notary_office_entry` | Solicitação de protesto de boleto foi aceita pelo cartório. |
| `protest_cancel_requested` | Solicitação de cancelamento de protesto em processamento pela QI Tech. |
| `notary_office_exit` | Protesto do boleto foi retirado do cartório. |
| `protested` | Protesto foi confirmado pelo cartório e o boleto se encontrada protestado. |
| `paid_at_notary_office` | Cartório identificou o pagamento do protesto do boleto e esta processando o repasse do pagamento para a QI Tech. |
| `judicially_suspended` | Protesto suspenso judicialmente. |
| `protest_remove_requested` | Solicitação de retirada de protesto foi aceita pelo cartório. |
---
# Enviar instrução de boleto
URL: /documentation/boletos/v1/enviar_instrucao_de_boleto
## Enviar instrução de Boleto
Para solicitar uma instrução de boleto, basta fazer a requisição de emissão com o "occurrence_type" conforme abaixo:
| Valor | Descrição |
|---|---|
| `registration` | Registrar um novo boleto. |
| `bank_slip_edit` | Editar informações do pagador de um boleto existente. |
| `extension` | Prorrogação da data de vencimento de um boleto existente. |
| `write_off` | Baixa sem financeiro de um boleto. |
| `rebate` | Abatimento do pagamento. |
| `cancel_rebate` | Cancelar abatimento do pagamento. |
| `bank_slip_edit` | Edição de um boleto existente (Desconto, Endereço, Multa/juros). |
| `protest_request` | Protestar boleto. |
| `bankruptcy_protest_request` | Protesto Falimentar. |
| `protest_remove_request` | Cancelar Protesto. |
| `protest_cancel_request` | Sustar Protesto sem Baixa. |
| `protest_cancel_and_write_off_request` | Sustar Protesto com Baixa. |
**Exemplos de request**
### Prorrogação
Para solicitar essa instrução, o boleto precisa estar registrado, e deve estar pagável.
Request Body
```json
{
"occurrences": [
{
"occurrence_type": "extension",
"requester_profile_code": "329-01-0001-0000001",
"our_number": 1000000,
"expiration": "2022-06-15"
}
]
}
```
### Baixa
Para solicitar essa instrução, o boleto precisa estar registrado.
Request Body
```json
{
"occurrences": [
{
"occurrence_type": "write_off",
"requester_profile_code": "329-01-0001-0000001",
"our_number": 1000000
}
]
}
```
### Abatimento
Para solicitar essa instrução, o boleto não pode estar vencido.
Request Body
```json
{
"occurrences": [
{
"occurrence_type": "rebate",
"our_number": 1000000,
"rebate_amount": 10,
"requester_profile_code": "329-01-0001-0000001"
}
]
}
```
### Cancelar abatimento
Para solicitar essa instrução, o boleto deve conter um abatimento ativo, e não pode estar vencido.
Request Body
```json
{
"occurrences": [
{
"our_number": 1000000008,
"occurrence_type": "cancel_rebate",
"requester_profile_code": "329-01-0001-0000001",
"bank_slip_key": "ce9b6834-4c6c-423a-a337-b9815a462ae5"
}
]
}
```
### Desconto
Para solicitar essa instrução, o boleto não pode estar vencido/baixado.
Request Body
```json
{
"occurrences": [
{
"our_number": 1000000008,
"occurrence_type": "bank_slip_edit",
"requester_profile_code": "329-01-0001-0000001",
"registration_institution_enumerator": "qi_scd",
"discounts": [
{
"discount_number": 1,
"discount_limit_date": "2022-06-14",
"discount_value": 10
}
]
}
]
}
```
### Adicionar/Editar Endereço
Para solicitar essa instrução, o boleto deve estar registrado, e ser pagável.
Request Body
```json
{
"occurrences": [
{
"our_number": 1000000008,
"occurrence_type": "bank_slip_edit",
"requester_profile_code": "329-01-0001-0000001",
"payer_address": "Rua dos Alfeneiros, 4, Little Whinging - Surrey, City, SP",
"payer_postal_code_root": "17057",
"payer_postal_code_suffix": "770"
}
]
}
```
### Editar Multa/Juros
Para solicitar essa instrução, o boleto deve estar registrado, e ser pagável.
Request Body
```json
{
"occurrences": [
{
"our_number": 1000000008,
"occurrence_type": "bank_slip_edit",
"requester_profile_code": "329-01-0001-0000001",
"fine_percentage": 1,
"interest_daily_value": 0.33
}
]
}
```
### Protesto
Para solicitar essa instrução, o boleto precisa estar vencido, e precisa ter os dados de endereço do pagador.
Request Body
```json
{
"occurrences": [
{
"our_number": 1000000002,
"occurrence_type": "protest_request",
"requester_profile_code": "329-01-0001-0000001"
}
]
}
```
### Protesto Falimentar
Para solicitar essa instrução, o boleto precisa estar vencido, e precisa ter os dados de endereço do pagador.
Request Body
```json
{
"occurrences": [
{
"our_number": 1000000002,
"occurrence_type": "bankruptcy_protest_request",
"requester_profile_code": "329-01-0001-0000001"
}
]
}
```
### Cancelar protesto
Para solicitar essa instrução, o boleto precisa estar protestado.
Request Body
```json
{
"occurrences": [
{
"our_number": 1000000002,
"occurrence_type": "protest_remove_request",
"requester_profile_code": "329-01-0001-0000001"
}
]
}
```
### Cancelar protesto automático
Para solicitar essa instrução, o boleto precisa ser registrado com essa opção ativa.
Request Body
```json
{
"occurrences": [
{
"our_number": 1000000002,
"occurrence_type": "bank_slip_edit",
"requester_profile_code": "329-01-0001-0000001",
"automatic_bankruptcy_protest": false,
"automatic_protest": false
}
]
}
```
### Sustar protesto sem baixa
Para solicitar essa instrução, o boleto precisa ser estar protestado.
Request Body
```json
{
"occurrences": [
{
"our_number": 1000000002,
"occurrence_type": "protest_cancel_request",
"requester_profile_code": "329-01-0001-0000001"
}
]
}
```
### Cancelar protesto automático
Para solicitar essa instrução, o boleto precisa ser estar protestado.
Request Body
```json
{
"occurrences": [
{
"our_number": 1000000002,
"occurrence_type": "protest_cancel_and_write_off_request",
"requester_profile_code": "329-01-0001-0000001"
}
]
}
```
## Exemplo de response
A resposta varia de cada tipo de instrução, geralmente resultando na mudança dos campos de occurrence_stats, na chave de cada instrução.
Já no campo semantic_errors, é devolvido uma lista com objetos de cada ocorrência com seus respectivos erros (exemplo abaixo).
Request Body
```json
{
"file_info": {
"beneficiary_code": null,
"beneficiary_name": null,
"file_sequence_id": null,
"file_type_identifier": null,
"file_type_literal": null,
"service_code": null,
"service_literal": null,
"wrote_at": null
},
"occurrence_stats": {
"bank_slip_edit": 0,
"bankruptcy_protest_request": 0,
"cancel_rebate": 0,
"extension": 0,
"notary_office_entry": 0,
"notary_office_exit": 0,
"notary_office_payment": 0,
"notification": 0,
"payment": 0,
"payment_notice": 0,
"payment_write_off": 0,
"protest_cancel_and_write_off_request": 0,
"protest_cancel_request": 0,
"protest_remove_request": 0,
"protest_request": 0,
"rebate": 0,
"registration": 0,
"write_off": 1
},
"semantic_errors": [
{
"0": {
"errors": [
{
"created_at": "2019-03-12T12:59:32",
"reason_code": "CEP Inválido",
"translation_en_us": "Invalid Postal Code",
"translation_pt_br": "CEP Inválido"
}
],
"our_number": 1000000000,
"participant_control_number": null
}
}
]
}
```
---
# Introdução
URL: /documentation/boletos/v1/introducao
Carteira de cobrança é o serviço que permite a emissão de boletos bancários. Existem diversos tipos de carteiras e cada uma define como serão gerados seus boletos, os custos, taxa de liquidação, conta a ser creditada e diversas configurações que permitirão ao banco fazer a cobrança correta. Durante a abertura de conta na QI Tech, fica disponível automaticamente para o cliente uma carteira dentro da QI e uma carteira no Bradesco, com as configurações globais de cobrança da QI Tech.
Além disso, se o cliente tiver interesse no cadastro ou alteração de uma carteira, com configurações diferentes da configuração global, ele poderá solicitar o serviço à nossa equipe.
## Como funciona a emissão de boletos?
As APIs da QI Tech permitem a abstração do ciclo de vida de um boleto através de uma maquina de estados, onde temos os seguintes status:
## Solicitação de registro
- accepted: Solicitação de emissão de boleto entrou para fila de registro;
- rejected : Solicitação de emissão de boleto rejeitada, quando a solicitação de registro do boleto contem erro de semântica que impede o registro.
## Registro efetivado
registered: Boleto registrado e disponível para pagamento.
## Notificação de pagamento
- payment_notice : Aviso de pagamento do boleto, essa notificação é enviada no momento que o boleto é pago, mas ainda não existe a liquidação financeira.
- notary_office_payment_notice : Aviso de pagamento do boleto, essa notificação é enviada no momento que o boleto é pago em cartório, mas ainda não existe a liquidação financeira.
## Liquidação
- paid : Boleto pago - baixado com liquidação financeira.
- written_off : Boleto baixado sem liquidação financeira.
---
# authentication
URL: /documentation/caas/banking/authentication
## Autenticação
> Para autenticar uma chamada, utilize o código seguinte:
```shell
# No shell, você somente precisa adicionar o header adequado em cada requisição
curl "api_endpoint_here"
-H "Authorization: EXAMPLE_API_KEY"
```
> Substitua a API key 'EXAMPLE_API_KEY' com a sua chave adquirida com o nosso suporte.
Utilizamos uma API Key para permitir acesso a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso você ainda não tenha recebido a sua chave, envie um e-mail para suporte.caas@qitech.com.br .
Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo:
`Authorization: EXAMPLE_API_KEY`
:::info **Atenção**
Você deve substituir EXAMPLE_API_KEY com a API Key recebida do suporte.
:::
---
# authentication
URL: /documentation/caas/card_issuance/authentication
## Autenticação
> Para autenticar uma chamada, utilize o código seguinte:
```shell
# No shell, você somente precisa adicionar o header adequado em cada requisição
curl "api_endpoint_here"
-H "Authorization: EXAMPLE_API_KEY"
```
> Substitua a API key 'EXAMPLE_API_KEY' com a sua chave adquirida com o nosso suporte.
Utilizamos uma API Key para permitir acesso a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso você ainda não tenha recebido a sua chave, envie um e-mail para suporte.caas@qitech.com.br .
Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo:
`Authorization: EXAMPLE_API_KEY`
:::info **Atenção**
Você deve substituir EXAMPLE_API_KEY com a API Key recebida do suporte.
:::
---
# authentication
URL: /documentation/caas/card_order/authentication
## Autenticação
> Para autenticar uma chamada, utilize o código seguinte:
```shell
# No shell, você somente precisa adicionar o header adequado em cada requisição
curl "api_endpoint_here"
-H "Authorization: EXAMPLE_API_KEY"
```
> Substitua a API key 'EXAMPLE_API_KEY' com a sua chave adquirida com o nosso suporte.
Utilizamos uma API Key para permitir acesso a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso você ainda não tenha recebido a sua chave, envie um e-mail para suporte.caas@qitech.com.br .
Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo:
`Authorization: EXAMPLE_API_KEY`
:::info **Atenção**
Você deve substituir EXAMPLE_API_KEY com a API Key recebida do suporte.
:::
---
# authentication
URL: /documentation/caas/credit_analysis/authentication
## Autenticação
> Para autenticar uma chamada, utilize o código seguinte:
```shell
# No shell, você somente precisa adicionar o header adequado em cada requisição
curl "api_endpoint_here"
-H "Authorization: EXAMPLE-OF-API-KEY"
```
> Substitua a API key 'EXAMPLE-OF-API-KEY' com a sua chave adquirida com o nosso suporte.
Utilizamos uma API Key para permitir acesso a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso você ainda não tenha recebido a sua chave, envie um e-mail para suporte.caas@qitech.com.br .
Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo:
`Authorization: EXAMPLE-OF-API-KEY`
:::info **Atenção**
Você deve substituir EXAMPLE-OF-API-KEY com a API Key recebida do suporte.
:::
---
# Imagens
URL: /documentation/caas/credit_analysis/image
Em várias situações é necessário enviar imagens para a nossa API, a fim de realizar operações de OCR, FaceMatch e validação de documentos. Para tanto, é preciso inicialmente realizar o upload da imagem para depois enviá-la para análise.
Ao enviar uma imagem utilizando o endpoint /image uma GUID (Globally Unique Identifier) é retornada. Este valor deverá ser utilizado nas chamadas subsequentes para referenciar esta imagem.
O tamanho máximo de uma imagem aceita é de 10MB.
Neste momento, somente imagens com formato jpeg são aceitas.
## Envio
> Exemplo de envio utilizando o cUrl
```shell
curl -F "data=@path/to/local/file" \
-H "Authorization: EXAMPLE-OF-API-KEY" \
"https://api.caas.qitech.app/image?type=face"
```
Response Body
```json
{
"image_id": "f4b5337a-7b50-406e-8c8e-7d0e77b5aa02",
"image_size": "134232",
"image_dimensions": "630x230"
}
```
Para enviar uma imagem, basta realizar o envio da imagem no formato .jpeg em `multipart/form-data` com uma requisição POST no endpoint:
`https://api.caas.qitech.app/api/image?type=$type`
Onde $type é a classificação da imagem e deve ser enviado conforme um dos seguintes enumeradores (Caso a imagem sendo enviada não se enquadre em nenhuma das classificações, entrar em contato com o [suporte](mailto:suporte.caas@qitech.com.br) para que providenciem a adição):
* face
* driver_license
* id
* contract
Após o envio, será retornado um objeto JSON com a GUID que aponta para a imagem que foi enviada.
## Recuperação dos Arquivos
> Leitura de imagem
```shell
curl "https://api.caas.qitech.app/api/image/f4b5337a-7b50-406e-8c8e-7d0e77b5aa02/file" \
-H "Authorization: EXAMPLE-OF-API-KEY"
```
Após o envio de uma imagem para a API, é possível recuperá-la por meio de uma requisição GET adequadamente autenticada no endpoint:
`https://api.caas.qitech.app/api/image/{image_key}/file`
Onde image_key é o valor retornado durante o envio da imagem.
## Recuperação dos meta-dados do arquivo
> Leitura de meta dados
```shell
curl "https://api.caas.qitech.app/api/image/f4b5337a-7b50-406e-8c8e-7d0e77b5aa02" \
-H "Authorization: EXAMPLE-OF-API-KEY"
```
Após o envio de uma imagem para a API, é possível recuperar os meta-dados da imagem utilizando o endpoint:
`https://api.caas.qitech.app/api/image/{image_key}`
Onde image_key é o valor retornado durante o envio da imagem.
---
# Compatibilidade da Biblioteca
URL: /documentation/caas/device_scan/android/compatibility
| Configuração | Versão mínima |
|------------|--------------|
|minSdkVersion|21|
---
# builder
URL: /documentation/caas/face_recognition/android/builder
## FaceRecognition.Builder
| Parâmetro | Função | Obrigatório |
| --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---- |
| mobileToken | Chave do cliente que identifica que os dados coletados são provenientes do seu aplicativo. Caso ainda não tenha recebido o seu mobile-token, entre em contato com o suporte. | Sim. |
| .setSandboxEnvironment() | Caso este parâmetro seja utilizado no construtor, a biblioteca será configurada para enviar os dados ao ambiente de sandbox. Caso ausente, as requisições são enviadas para o ambiente production. | Não. |
| .showIntroductionScreens(Boolean showIntroductionScreens) | Quando "false" desativa as telas de introdução à coleta da foto que aparecem para o usuário. | Não. O padrão é "true". |
| .setShowSuccessScreen(Boolean showSuccessScreen) | Quando "false" desativa a tela de sucesso após a coleta da foto. | Não. O padrão é "true". |
| .setBackgroundColor(String backgroundColor) | Permite a configuração da cor de background das activities do SDK. | Não. O padrão é "#ffffff". |
| .setFontColor(String fontColor) | Permite a configuração da cor da fonte e dos ícones das activities do SDK. | Não. O padrão é "#000000". |
| .setFontFamily(FontFamily fontFamily) | Permite a configuração da fonte das activities do SDK. | Não. Caso não seja informada o padrão é FontFamily.open_sans. Fontes disponíveis: FontFamily.open_sans, FontFamily.futura, FontFamily.verdana, FontFamily.roboto, FontFamily.poppins e FontFamily.helvetica. | Não. |
| .activeFaceLiveness(Boolean activeFaceLiveness) | Indica se o SDK deve realizar um procedimento de captura de selfie do usuário ou de prova de vida ativa. | Não. O padrão é _false_. |
| .audioConfiguration(AudioConfiguration audioConfiguration) | Configura o guiamento por voz do SDK, que narra as instruções de captura em tempo real. As configurações aceitas são _AudioConfiguration.enable_, que exibe o botão de ligar/desligar áudio com a narração iniciando desligada; _AudioConfiguration.disable_, que desativa a narração e oculta o botão; e _AudioConfiguration.accessibility_, que exibe o botão com a narração iniciando ligada quando o dispositivo possui recursos de acessibilidade ativos. Com o TalkBack ativo, as instruções completas são entregues pelo próprio leitor de telas. | Não. O padrão é _AudioConfiguration.disable_. |
| .setVisualConfiguration([VisualConfiguration](https://docs.zaig.com.br/android_facerecon/#o-objeto-visualconfiguration). visualConfiguration) | Utilizado para customizar as imagens mostradas para o usuário ao longo da execução do SDK. | Não. |
| .setTextConfiguration([TextConfiguration](https://docs.zaig.com.br/android_facerecon/#o-objeto-textconfiguration). textConfiguration) | Utilizado para customizar os textos da tela introdutória de onboarding mostradas para o usuário ao longo da execução do SDK. | Não. |
| .setSessionId(String sessionId) | Utilizado para definir a chave que identifica a sessão iniciada no SDK. É usada para rastrear todo fluxo percorrido pelo usuário na execução da FaceRecon através de logs. Este campo aceita até 255 caracteres. | Não. |
| .setLogLevel(FaceRecognition.LogLevel logLevel) | Utilizado para customizar o nível de verbosidade dos logs do SDK. Níveis disponíveis: LogLevel.debug, LogLevel.info, LogLevel.warn, LogLevel.error e LogLevel.trace. O padrão é LogLevel.debug. | Não. |
| .setDocumentNumber(String documentNumber) | Utilizado para definir o número do documento do usuário. Este campo aceita 14 caracteres do CPF formatado da seguinte maneira 000.000.000-00 | Sim em todas as chamadas caso use a validação 1:1 em algum momento. |
| .setValidation(Boolean validation) | Utilizado para definir se o SDK deve ou não realizar a validação 1:1 com a selfie do usuário. Na primeira sessão do usuário esta flag deve estar, **obrigatoriamente false**. Esta função depende necessita do método setDocumentNumber preenchido. | Não. O padrão é _false_. |
## O Objeto VisualConfiguration
| Parâmetro | Função | Obrigatório |
| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| .setOnboardingDrawable(int onboarding_drawable, int onboarding_width) | Utilizado para configurar a imagem mostrada para o usuário na tela de onboarding do SDK. O parâmetro _onboarding_drawable_ deve referenciar o id da imagem a ser mostrada e _onboarding_width_ é o tamanho desejado de exibição desta imagem. | Não. |
| .setButtonBorderSize(int border_size) | Utilizado para configurar a largura de borda dos botões do SDK. | Não. O padrão é _1_. |
| .setButtonShadow(boolean button_shadow) | Quando setado para _false_ remove o efeito de sombra, padrão no android, utilizado pelos botões do SDK. | Não. O padrão é _true_. |
## O Objeto TextConfiguration
| Parâmetro | Função | Obrigatório |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------- | ----------- |
| .setCustomText(CustomLabel label, String text) | Utilizado para configurar os textos mostrados para o usuário na tela de onboarding do SDK | Não. |
```
```
---
# Validação 1:1 - Face Match
URL: /documentation/caas/face_recognition/android/face_match
Para utilizar a funcionalidade de Validação 1:1 (Face Match) é necessário que o parâmetro _validation_ seja setado como _true_ no construtor do SDK, isso pode ser feito chamando o metodo `setValidation()`. Além disso, é necessário que o parâmetro _documentNumber_ seja preenchido com o CPF do usuário. Conforme exemplo abaixo:
```java
FaceRecognition faceRecognition = new FaceRecognition.Builder("YOUR_MOBILE_TOKEN_SENT_BY_QITECH")
// ... Outras configurações
.setDocumentNumber("000.000.000-00")
.setValidation(true)
// ...
.build();
```
> **ATENÇÃO:** A validação 1:1 só pode ser utilizada a partir da segunda sessão do usuário, ou seja, após a primeira sessão, quando o parâmetro _documentNumber_ for preenchido com CPF do usuário e o parâmetro _validation_ com `false`, havendo um registro para ser validado.
---
# using_sdk
URL: /documentation/caas/face_recognition/android/using_sdk
## Iniciando o SDK
Para incorporar o SDK ao seu aplicativo você deve realizar a configuração do seu aplicativo de captura personalizado através de um componente Builder e submetê-lo como parâmetro via Intent Extra para a FaceReconActivity.
```java
Intent intent = new Intent(getApplicationContext(), FaceReconActivity.class);
VisualConfiguration visualConfiguration = new VisualConfiguration()
.setOnboardingDrawable(R.drawable.introscreen,500);
TextConfiguration textConfiguration = new TextConfiguration()
.setCustomText(TextConfiguration.CustomLabel.onboardingTitle, "Para tirar uma boa foto:")
.setCustomText(TextConfiguration.CustomLabel.onboardingFirstLabel, "- Vá para um local iluminado")
.setCustomText(TextConfiguration.CustomLabel.onboardingSecondLabel, "- Retire adereços e mostre bem o rosto")
.setCustomText(TextConfiguration.CustomLabel.onboardingThirdLabel, "- Insira seu rosto na moldura, aguardando que fique verde para realizar a captura");
FaceRecognition mFaceRecognition = new FaceRecognition.Builder("YOUR_MOBILE_TOKEN_SENT_BY_QITECH")
.showIntroductionScreens(true)
.setVisualConfiguration(visualConfiguration)
.setTextConfiguration(textConfiguration)
.setBackgroundColor("#000000")
.setFontColor("#FFFFFF")
.setFontFamily(FaceRecognition.FontFamily.futura)
.setSessionId("SESSION_ID")
.setLogLevel(FaceRecognition.LogLevel.debug)
.setShowSuccessScreen(false)
.build();
intent.putExtra("settings", mFaceRecognition);
startActivityForResult(intent, REQUEST_CODE);
```
Utilizamos um Mobile Token para permitir o acesso autenticado do seu aplicativo a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso ainda não tenha recebido o seu token, envie um e-mail para suporte.caas@qitech.com.br .
Nossa API espera receber o Mobile Token em todas as requisições ao nosso servidor vindas do SDK, portanto, este deve ser obrigatoriamente incluído como parâmetro de configuração através do método mencionado anteriormente.
:::info **Atenção**
Você deve substituir "YOUR_MOBILE_TOKEN_SENT_BY_QITECH" com o Mobile Token recebido do suporte.
:::
---
# Registration
URL: /documentation/caas/face_recognition/api/registration
Antes da utilização do recurso de Validação Facial da API é necessário que seja feito o cadastro do cliente. Esta ação gerará uma entrada inicial no banco de dados que fornecerá uma imagem para ser usada como base durante a validação.
## Definição de Objeto
Request Body
```json
{
"registration_key": "ee37510e-4dfe-4b9c-b1f4-667288de2190",
"document_number": "123.456.789-00",
"image": {
"image_key": "f1c0d2e1-f950-4360-896d-36588e443fc9",
"file_size": 47407,
"width_px": 0,
"height_px": 0,
"created_at": "2020-07-29T18:40:57Z",
},
"status": "indeterminate",
"registration_status_events": [],
"registration_date": "2020-07-29T18:40:57Z"
}
```
Ao cadastrar um cliente, nossa API gerará um objeto JSON contendo todas as informações relacionadas a este cadastro. Esse objeto será utilizado como referência ao realizar o reconhecimento facial deste cliente antes de uma transação.
nome | tipo | descrição
:----: | :----: | ---------
registration_key | string | Chave do objeto Registration
document_number | string | CPF do cliente
image | image | Objeto que carrega as propriedades da imagem enviada no cadastro
status | string | Situação do cadastro do cliente
registration_status_events | registration_status_events | Objeto que carrega o histórico de modificação de status do cadastro
registration_date | datetime | Data de realização do cadastro em UTC
## Dinâmica dos Status - **status**
Uma vez feito o cadastro de um cliente, será retornado sob a flag **status** a situação deste cadastro. Os resultados possíveis são:
Resultado | Descrição
--------- | ---------
authentic | Este cadastro possui histórico de transações concluídas com sucesso
undefined | Este cadastro não possui histórico de fraudes nem histórico de transações concluído com sucesso
fraud | Este cadastro possui histórico de fraudes associado
## Criação de um Registration
Request Body: Envio simultâneo de imagem (Base64)
```json
{
"document_number": "123.456.789-00",
"image": "base_64_image_code",
}
```
Request Body: Envio antecipado da imagem
```json
{
"document_number": "123.456.789-00",
"image_key": "f1c0d2e1-f950-4360-896d-36588e443fc9",
}
```
Para efetuar o cadastro de um cliente, basta realizar o envio de um objeto JSON de cadastro com uma requisição **POST** no endpoint:
`https://api.caas.qitech.app/face_recognition/registration`
São suportados dois tipos objetos JSON de cadastro. Um em caso de envio prévio da imagem através do endpoint `/image`, e outro em caso de envio da imagem simultâneamente à requisição de cadastro.
nome | tipo | descrição
:----: | :----: | ---------
document_number | String | CPF do cliente
image | String | Base64 da imagem sem cabeçalhos ou informações adicionais
image_key | String | UUID4 retornado durante o envio da imagem pelo endpoint /image
Após o envio, será retornado um objeto Registration contendo os dados de cadastro do usuário.
**Atenção -** Ao efetuar o envio simultâneo da imagem com a realização do cadastro, esta será submetida aos mesmos testes de qualidade executados quando a imagem é enviada pelo endpoint `/image`. Assim, a imagem enviada está sujeita as mesmas regras descritas na sessão **Imagem** desta documentação.
## Atualização dos Status - **status**
Request Body
```json
{
"registration_status": "fraud",
"incident": "misappropriation",
"event_date": "2029-08-25T13:34:12-03:00"
}
```
Para garantir a retroalimentação do banco de dados de fraudadores, é necessário informar ao sistema caso um cliente cometa qualquer tipo de fraude ou caso o cliente complete a sua primeira transação com sucesso.
Para isso, a atualização do status de cadastro de um cliente como fraudador deverá sem enviada uma requisição do tipo **PUT** para o endpoint:
`https://api.caas.qitech.app/face_recognition/registration/{registration_key}/status`
Os seguintes valores podem ser utilizados no campo **incident**, que indica o tipo de fraude cometida pelo cliente:
Enumerador | Descrição
--------- | ---------
misappropriation | Indivíduo realizou apropriação indébita sobre algum produto
misrepresentation | Indivíduo cadastrado sob documentos falsos ou de terceiros
successfull_transaction | Indivíduo completou uma transação com sucesso
status_restoration | Enumerador usado em casos que se deseja restaurar o status para **undefined**
## Recuperação de objeto
Response Body
```json
{
"registration_key": "ee37510e-4dfe-4b9c-b1f4-667288de2190",
"document_number": "123.456.789-00",
"image": {
"image_key": "f1c0d2e1-f950-4360-896d-36588e443fc9",
"file_size": 47407,
"width_px": 0,
"height_px": 0,
"created_at": "2020-07-29T18:40:57Z",
},
"status": "fraud",
"registration_status_events": [
{
"registration_status": "fraud",
"incident": "misappropriation",
"event_date": "2020-08-25T13:34:12Z"
}
],
"registration_date": "2020-07-29T18:40:57Z"
}
```
Em qualquer momento os dados de registro de um cliente poderão ser recuperados através de uma requisição **GET** ao endpoint:
`https://api.caas.qitech.app/face_recognition/registration/{registration_key}`
---
# Validation
URL: /documentation/caas/face_recognition/api/validation
Para a execução da validação por reconhecimento facial de um cliente é necessário enviar uma foto de rosto junto do CPF de um cliente cadastrado.
A partir dai, o registro desse usuário será buscado no sistema para, então, realizar uma validação 1:1 entre uma foto do cliente guardada no banco de dados e a imagem enviada.
## Definição do Objeto
Request Body
```json
{
"validation_key": "ee37510e-4dfe-4b9c-b1f4-667288de2190",
"document_number": "123.456.789-00",
"image": {
"image_key": "f1c0d2e1-f950-4360-896d-36588e443fc9",
"file_size": 47407,
"width_px": 0,
"height_px": 0,
"created_at": "2020-07-29T18:40:57Z",
},
"registration": {
"registration_key": "903dcb34-2970-4ddf-add5-87463ba51d99",
"registration_status": "authentic",
"registration_date": "2020-07-29T18:40:57Z"
},
"similarity_ratio": "99",
"validation_result": "pass",
"validation_date": "2020-07-29T18:40:57Z"
}
```
Todas as validações de cliente através de reconhecimento facial gerarão um objeto Validation. Caso desejado, este objeto poderá ser recuperado futuramente através do endpoint apropriado.
nome | tipo | descrição
:----: | :----: | ---------
validation_key | string | Chave do objeto Validation
document_number | string | CPF do cliente
image | image | Objeto que carrega as propriedades da imagem enviada na validação
registration | registration | Objeto que carrega as propriedades do registro que está sendo usado como referência na validação
similarity_ratio | integer | Razão de similaridade entre a imagem cadastrada e a imagem enviada
validation_result | string | Resultado da análise 1:1 realizada
validation_date | datetime | Data de realização da validação por reconhecimento facial em UTC
## Criação de Validation
Request Body: Envio simultâneo de imagem (Base64)
```json
{
"document_number": "123.456.789-00",
"image": "base_64_image_code",
}
```
Request Body: Envio antecipado da imagem
```json
{
"document_number": "123.456.789-00",
"image_key": "f1c0d2e1-f950-4360-896d-36588e443fc9",
}
```
Assim como no cadastro, também são aceitos dois formatos de JSON, um contendo o Base64 da imagem e outro contendo a **image_key** recebida no momento do envio da imagem pelo endpoint `/image`.
`https://api.caas.qitech.app/face_recognition/validation`
Após o envio, será retornado um objeto JSON contendo o resultado da análise juntamente da UUID que aponta para a imagem que foi enviada.
**Atenção -** Ao efetuar o envio simultâneo da imagem com a realização da validação por reconhecimento facial, esta será submetida aos mesmos testes de qualidade executados quando a imagem é enviada pelo endpoint `/image`. Assim, a imagem enviada está sujeita as mesmas regras descritas na sessão **Imagem** desta documentação.
## Dinamica dos Status - **validation_result**
Após executada a análise será enviada o resultado da análise sob a flag **validation_result**. Os resultados possíveis são:
Resultado | Descrição
--------- | ---------
match | Foto enviada corresponde ao usuário cadastrado
mismatch | Foto enviada não corresponde ao usuário cadastrado
## Recuperação de objeto
Response Body
```json
{
"validation_key": "ee37510e-4dfe-4b9c-b1f4-667288de2190",
"document_number": "123.456.789-00",
"validation_image": {
"image_key": "f1c0d2e1-f950-4360-896d-36588e443fc9",
"file_size": 47407,
"width_px": 0,
"height_px": 0,
"created_at": "2020-07-29T18:40:57Z",
},
"registration": {
"registration_key": "903dcb34-2970-4ddf-add5-87463ba51d99",
"registration_status": "authentic",
"registration_date": "2020-07-29T18:40:57Z"
},
"similarity_ratio": "99",
"validation_result": "pass",
"validation_date": "2020-07-29T18:40:57Z"
}
```
Em qualquer momento os dados de uma validação poderão ser recuperados através de uma requisição **GET** ao endpoint:
`https://api.caas.qitech.app/face_recognition/validation/{validation_key}`
---
# necessary_permissions
URL: /documentation/caas/face_recognition/ios/necessary_permissions
## Permissões Necessárias
Para que o SDK possa acessar os recursos do dispositivo para coletar a selfie do usuário, é necessário que sejam solicitadas permissões ao usuário.
No arquivo **info.plist**, adicione as permissões abaixo:
| Permissão | Motivo |
| ---------------------------------- | -------------------------------------------------- |
| Privacy - Camera Usage Description | Acesso à câmera para capturar a selfie do usuário. |
---
# using_sdk
URL: /documentation/caas/face_recognition/ios/using_sdk
## Iniciando o SDK
```swift
import QITechIosFaceRecognition
class ViewController: UIViewController, QITechIosFaceRecognitionControllerDelegate {
var qitechFaceRecognitionConfiguration : QITechIosFaceRecognitionConfiguration?
override func viewDidLoad() {
super.viewDidLoad()
self.setupFaceRecognition()
}
func setupFaceRecognition() -> Void {
// The environment can be 'Sandbox' ou 'Production'
let environment = QITechIosFaceRecognitionEnvironment.Sandbox
// MobileToken is the key sent to you by QI Tech. Each environment requires a different MobileToken.
let mobileToken = "YOUR_MOBILE_TOKEN_SENT_BY_QITECH"
self.faceRecognitionConfig = QITechIosFaceRecognitionConfiguration(environment: environment,
mobileToken: mobileToken,
sessionId: "UNIQUE_SESSION_ID",
backgroundColor: "#000000",
fontColor: "#FFFFFF",
fontFamily: .open_sans,
showIntroductionScreens: true,
activeFaceLiveness: true,
audioConfiguration: AudioConfiguration.Enable,
logLevel: .debug
)
}
// Event where you intend to call QI Tech FaceRecognition View Controller - on this example, when the user press 'next' button
@IBAction func pressNext(_ sender: Any) {
let qitechFaceRecognitionController = QITechIosFaceRecognitionController(faceRecognitionConfiguration: self.faceRecognitionConfig)
qitechFaceRecognitionViewController.delegate = self
let qitechFaceRecognitionViewController = qitechFaceRecognitionController.getViewController()
present(qitechFaceRecognitionViewController, animated: true, completion: nil)
}
// Do something if QI Tech FaceRecognition's SDK successfully collected document picture
func qitechIosFaceRecognitionController(_ faceRecognitionViewController: QITechIosFaceRecognitionController, didFinishWithResults results: QITechIosFaceRecognitionControllerResponse) {
}
// Do something if QI Tech FaceRecognition's SDK found any error when collecting document picture
func qitechIosFaceRecognitionController(_ faceRecognitionViewController: QITechIosFaceRecognitionController, didFailWithError error: QITechIosFaceRecognitionControllerError) {
}
// Do something if the user canceled the picture collection on any steps
func qitechIosFaceRecognitionControllerDidCancel(_ faceRecognitionViewController: QITechIosFaceRecognitionController) {
}
}
```
Para incorporar o SDK ao seu aplicativo você deve realizar a configuração do seu aplicativo de captura personalizado através da classe **QITechIosFaceRecognitionConfiguration** e depois instanciar o **ViewController QITechIosFaceRecognitionController** passando como argumento as configurações personalizadas.
Para iniciar o processo de análise de face, basta chamar a função _present_ para chamar o ViewController da QI Tech que realizará a coleta da selfie.
Importante implementar o _Delegate_ responsável por receber os retornos em caso de sucesso, erro ou no caso de o usuário interromper a jornada em qualquer etapa da validação.
Ao lado temos um exemplo completo da implementação.
## Mobile Token
Utilizamos um Mobile Token para permitir o acesso autenticado do seu aplicativo a nossa API. Ele provavelmente já foi enviado por e-mail para você. Caso ainda não tenha recebido o seu token, envie um e-mail para suporte.caas@qitech.com.br .
Nossa API espera receber o Mobile Token em todas as requisições ao nosso servidor vindas do SDK, portanto, este deve ser obrigatoriamente incluído como parâmetro de configuração através do método mencionado anteriormente.
:::info **Atenção**
Você deve substituir "YOUR_MOBILE_TOKEN_SENT_BY_QITECH" com o Mobile Token recebido do suporte.
:::
---
# authentication
URL: /documentation/caas/limits/authentication
## Autenticação
> Para autenticar uma chamada, utilize o código seguinte:
```shell
# No shell, você somente precisa adicionar o header adequado em cada requisição
curl "api_endpoint_here"
-H "Authorization: EXAMPLE_API_KEY"
```
> Substitua a API key 'EXAMPLE_API_KEY' com a sua chave adquirida com o nosso suporte.
Utilizamos uma API Key para permitir acesso a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso você ainda não tenha recebido a sua chave, envie um e-mail para suporte.caas@qitech.com.br .
Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo:
`Authorization: EXAMPLE_API_KEY`
:::info **Atenção**
Você deve substituir EXAMPLE_API_KEY com a API Key recebida do suporte.
:::
---
# builder
URL: /documentation/caas/ocr/android/builder
## DocumentRecognition.Builder
| Parâmetro | Função | Obrigatório |
|------------|--------------|--------------|
|mobileToken |Chave do cliente que identifica que os dados coletados são provenientes do seu aplicativo. Caso ainda não tenha recebido o seu mobile-token, entre em contato com o suporte.|Sim.|
|.setDocumentSteps(DocumentRecognitionStep[] documentSteps)|Define o fluxo de captura de documentos realizado pelo usuário. Mais informações [aqui](https://docs.zaig.com.br/android_ocr/#documentdetectorstep)|Sim.|
|.setSandboxEnvironment()|Caso este parâmetro seja utilizado no construtor, a biblioteca será configurada para enviar os dados ao ambiente de sandbox. Caso ausente, as requisições são enviadas para o ambiente production.|Não.|
|.showIntroductionScreens(Boolean showIntroductionScreens)|Quando "false" desativa as telas de introdução à coleta de foto do documento que aparecem para o usuário.|Não. O padrão é "true".|
|.setShowSuccessScreen(Boolean showSuccessScreen)|Quando "false" desativa a tela de sucesso após a coleta da foto.|Não. O padrão é "true".|
|.setBackgroundColor(String backgroundColor)|Permite a configuração da cor de background das activities do SDK.|Não. O padrão é "#ffffff".|
|.setFontColor(String fontColor)|Permite a configuração da cor da fonte e dos ícones das activities do SDK.|Não. O padrão é "#000000".|
| .setFontFamily(FontFamily fontFamily)| Permite a configuração da fonte das activities do SDK.| Não. Caso não seja informada o padrão é FontFamily.open_sans. Fontes disponíveis: FontFamily.open_sans, FontFamily.futura, FontFamily.verdana, FontFamily.roboto, FontFamily.poppins e FontFamily.helvetica.|Não.|
|.setVisualConfiguration([VisualConfiguration](https://docs.zaig.com.br/android_ocr/#o-objeto-visualconfiguration). visualConfiguration)| Utilizado para customizar as imagens mostradas para o usuário ao longo da execução do SDK.|Não.|
|.setTextConfiguration([TextConfiguration](https://docs.zaig.com.br/android_ocr/#o-objeto-textconfiguration). textConfiguration) | Utilizado para customizar os textos da tela introdutória de onboarding mostradas para o usuário ao longo da execução do SDK.|Não.|
|.setSessionId(String sessionId)| Utilizado para definir a chave que identifica a sessão iniciada no SDK. É usada para rastrear todo fluxo percorrido pelo usuário na execução da FaceRecon através de logs. Este campo aceita até 255 caracteres. |Não.|
|.setLogLevel(DocumentRecognition.LogLevel logLevel)| Utilizado para customizar o nível de verbosidade dos logs do SDK. Níveis disponíveis: LogLevel.debug, LogLevel.info, LogLevel.warn, LogLevel.error e LogLevel.trace. O padrão é LogLevel.debug. |Não.|
|.setAudioConfiguration(AudioConfiguration audioConfiguration)|Configura o guiamento por voz do SDK, que narra as instruções de captura em tempo real. As configurações aceitas são _AudioConfiguration.enable_, que exibe o botão de ligar/desligar áudio com a narração iniciando desligada; _AudioConfiguration.disable_, que desativa a narração e oculta o botão; e _AudioConfiguration.accessibility_, que exibe o botão com a narração iniciando ligada quando o dispositivo possui recursos de acessibilidade ativos. Com o TalkBack ativo, as instruções completas são entregues pelo próprio leitor de telas.|Não. O padrão é _AudioConfiguration.disable_.|
## O Objeto VisualConfiguration
| Parâmetro | Função | Obrigatório |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| .setOnboardingDrawable(int onboarding_drawable, int onboarding_width) | Utilizado para configurar a imagem mostrada para o usuário na tela de onboarding do SDK. O parâmetro _onboarding_drawable_ deve referenciar o id da imagem a ser mostrada e _onboarding_width_ é o tamanho desejado de exibição desta imagem. | Não. |
| .setDocumentFullDrawable(int documentfull_drawable, int documentfull_width) | Utilizado para configurar a imagem mostrada para o usuário na tela de captura de CNH inteira do SDK. O parâmetro _documentfull_drawable_ deve referenciar o id da imagem a ser mostrada e _documentfull_width_ é o tamanho desejado de exibição desta imagem. | Não. |
| .setDocumentFrontDrawable(int documentfront_drawable, int documentfront_width) | Utilizado para configurar a imagem mostrada para o usuário na tela de captura de CNH e RG frente do SDK. O parâmetro _documentfront_drawable_ deve referenciar o id da imagem a ser mostrada e _documentfront_width_ é o tamanho desejado de exibição desta imagem. | Não. |
| .setDocumentBackDrawable(int documentback_drawable, int documentback_width) | Utilizado para configurar a imagem mostrada para o usuário na tela de captura de CNH e RG verso do SDK. O parâmetro _documentback_drawable_ deve referenciar o id da imagem a ser mostrada e _documentback_width_ é o tamanho desejado de exibição desta imagem. | Não. |
| .setButtonBorderSize(int border_size) | Utilizado para configurar a largura de borda dos botões do SDK. | Não. O padrão é _1_. |
| .setButtonShadow(boolean button_shadow) | Quando setado para _false_ remove o efeito de sombra, padrão no android, utilizado pelos botões do SDK. | Não. O padrão é _true_. |
## O Objeto TextConfiguration
| Parâmetro | Função | Obrigatório |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| .setCustomText(CustomLabel label, String text) | Utilizado para configurar os textos mostrados para o usuário na tela de onboarding do SDK| Não.|
---
# DocumentDetectorStep
URL: /documentation/caas/ocr/android/implementation_demo
O código a seguir é um exemplo de referência para a implementação correta do SDK em uma _activity_:
```java
import com.qitech.documentrecognition.Document;
import com.qitech.documentrecognition.DocumentRecognition;
import com.qitech.documentrecognition.DocumentRecognitionResponse;
import com.qitech.documentrecognition.DocumentRecognitionStep;
import com.qitech.documentrecognition.DocumentRecognitionActivity;
import java.util.ArrayList;
public class MainActivity extends AppCompatActivity implements View.OnClickListener {
ConstraintLayout constraintLayout;
ImageView backVector, iconVector;
TextView textViewBack, textViewTitle, textViewDescription;
Button buttonCNHfull, buttonCNH, buttonRG;
DocumentRecognitionStep[] DocumentSteps;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_onboarding1);
constraintLayout = findViewById(R.id.constraintLayout);
backVector = findViewById(R.id.backVector);
iconVector = findViewById(R.id.iconVector);
textViewBack = findViewById(R.id.textViewBack);
textViewTitle = findViewById(R.id.textViewTitle);
textViewDescription = findViewById(R.id.textViewDescription);
buttonCNH = findViewById(R.id.buttonCNH);
buttonRG = findViewById(R.id.buttonRG);
buttonCNHfull = findViewById(R.id.buttonCNHfull);
constraintLayout.setBackgroundColor(Color.parseColor("#000000"));
backVector.setColorFilter(Color.parseColor("#FFFFFF"));
iconVector.setColorFilter(Color.parseColor("#FFFFFF"));
textViewBack.setTextColor(Color.parseColor("#FFFFFF"));
textViewTitle.setTextColor(Color.parseColor("#FFFFFF"));
textViewDescription.setTextColor(Color.parseColor("#FFFFFF"));
backVector.setOnClickListener(this);
textViewBack.setOnClickListener(this);
buttonCNH.setOnClickListener(this);
buttonRG.setOnClickListener(this);
}
@Override
public void onClick(View view) {
if (view.getId() == R.id.textViewBack || view.getId() == R.id.backVector) {
finish();
}
else if (view.getId() == R.id.buttonCNH) {
Log.i("OnboardingActivity1Tag", "CNH document was chosen");
DocumentSteps = new DocumentRecognitionStep[]{
new DocumentRecognitionStep(Document.cnh_front),
new DocumentRecognitionStep(Document.cnh_back)};
} else if (view.getId() == R.id.buttonRG) {
Log.i("OnboardingActivity1Tag", "RG document was chosen");
DocumentSteps = new DocumentRecognitionStep[]{
new DocumentRecognitionStep(Document.rg_front),
new DocumentRecognitionStep(Document.rg_back)};
} else if (view.getId() == R.id.buttonCNHfull) {
Log.i("OnboardingActivity1Tag", "CNH full document was chosen");
DocumentSteps = new DocumentRecognitionStep[]{
new DocumentRecognitionStep(Document.cnh)};
}
Intent intent = new Intent(getApplicationContext(), DocumentRecognitionActivity.class);
DocumentRecognition mDocumentRecognition = new DocumentRecognition.Builder("d782a5be-2f96-452b-bf21-4d1bbfd0d710")
.setDocumentSteps(DocumentSteps)
.setBackgroundColor("#000000")
.setFontColor("#FFFFFF")
.setFontFamily(DocumentRecognition.FontFamily.open_sans)
.setSessionId(String.valueOf(UUID.randomUUID()))
.setLogLevel(FaceRecognition.LogLevel.debug)
.build();
intent.putExtra("settings", mDocumentRecognition);
startActivityForResult(intent, 1);
}
@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
if (requestCode == 1){
if (resultCode == RESULT_OK && data != null){
Intent resultIntent = new Intent();
setResult(RESULT_OK, resultIntent);
ArrayList mDocumentRecognitionResponse = data.getParcelableArrayListExtra("DocumentRecognitionResponse");
resultIntent.putParcelableArrayListExtra("DocumentRecognitionResponse", mDocumentRecognitionResponse);
finish();
} else {
// o usuário fechou a activity
}
}
super.onActivityResult(requestCode, resultCode, data);
}
}
```
---
# using_sdk
URL: /documentation/caas/ocr/android/using_sdk
## Iniciando o SDK
Para incorporar o SDK ao seu aplicativo você deve realizar a configuração do seu aplicativo de captura personalizado através de um componente Builder e submetê-lo como parâmetro via Intent Extra para a DocumentRecognitionActivity.
```java
Intent intent = new Intent(context, DocumentRecognitionActivity.class);
VisualConfiguration visualConfiguration = new VisualConfiguration()
.setOnboardingDrawable(R.drawable.introscreen,500)
.setDocumentFrontDrawable(R.drawable.documentfront, 500)
.setDocumentBackDrawable(R.drawable.documentback, 500);
TextConfiguration textConfiguration = new TextConfiguration()
.setCustomText(TextConfiguration.CustomLabel.onboardingTitle, "Vamos começar!")
.setCustomText(TextConfiguration.CustomLabel.onboardingFirstLabel, "- Vá para um local iluminado")
.setCustomText(TextConfiguration.CustomLabel.onboardingSecondLabel, "- Retire o documento do plástico")
.setCustomText(TextConfiguration.CustomLabel.onboardingThirdLabel, "- Insira seu documento na moldura, aguardando que fique verde para realizar a captura.");
DocumentRecognition mDocumentRecognition = new DocumentRecognition.Builder("YOUR_MOBILE_TOKEN_SENT_BY_QITECH")
.setDocumentSteps(DocumentSteps)
.setVisualConfiguration(visualConfiguration)
.setTextConfiguration(textConfiguration)
.showIntroductionScreens(true)
.setShowSuccessScreen(false)
.setBackgroundColor("#000000")
.setFontColor("#FFFFFF")
.setFontFamily(DocumentRecognition.FontFamily.open_sans)
.setSessionId("SESSION_ID")
.setLogLevel(FaceRecognition.LogLevel.debug)
.build();
intent.putExtra("settings", mDocumentRecognition);
startActivityForResult(intent, REQUEST_CODE);
```
Utilizamos um Mobile Token para permitir o acesso autenticado do seu aplicativo a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso ainda não tenha recebido o seu token, envie um e-mail para suporte.caas@qitech.com.br .
Nossa API espera receber o Mobile Token em todas as requisições ao nosso servidor vindas do SDK, portanto, este deve ser obrigatoriamente incluido como parâmetro de configuração através do método mencionado anteriormente.
:::info **Atenção**
Você deve substituir "YOUR_MOBILE_TOKEN_SENT_BY_QITECH" com o Mobile Token recebido do suporte.
:::
---
# authentication
URL: /documentation/caas/ocr/api/authentication
## Autenticação
> Para autenticar uma chamada, utilize o código seguinte:
```shell
# No shell, você somente precisa adicionar o header adequado em cada requisição
curl "api_endpoint_here"
-H "Authorization: EXAMPLE_API_KEY"
```
> Substitua a API key 'EXAMPLE_API_KEY' com a sua chave adquirida com o nosso suporte.
Utilizamos uma API Key para permitir acesso a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso ainda não tenha recebido a sua chave, envie um e-mail para suporte.caas@qitech.com.br .
Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo:
`Authorization: EXAMPLE_API_KEY`
:::info **Atenção**
Você deve substituir EXAMPLE_API_KEY com a API Key recebida do suporte.
:::
---
# quality
URL: /documentation/caas/ocr/api/quality
## Validação de qualidade da imagem
Request Body: Caso de imagem inválida
```json
{
"title": "document_quality",
"description": "A imagem enviada não pode ser processada com êxito."
}
```
Ao realizar um post no endpoint de imagem, caso a imagem não seja suficiente para validação, um HTTP Status Code 400 será retornado, como pode ser visto no exemplo ao lado. O Status Code 400 também é retornado quando o documento não atende aos requisitos de imagem, citados anteriormente.
**Atenção -** Existem outros motivos pelos quais retornamos 400 (Todos relacionados a dados inválidos). Somente os retornos com o title "document_quality" são resultantes de uma validação de má qualidade da imagem e portanto devem ser repassados ao usuário.
---
# necessary_permissions
URL: /documentation/caas/ocr/ios/necessary_permissions
## Permissões Necessárias
Para que o SDK possa acessar os recursos do dispositivo para coletar a foto, é necessário que sejam solicitadas permissões ao usuário.
No arquivo **info.plist**, adicione as permissões abaixo:
| Permissão | Motivo |
| ---------------------------------- | ---------------------------------------------------- |
| Privacy - Camera Usage Description | Acesso à câmera para capturar as fotos do documento. |
---
# Importando o SDK
URL: /documentation/caas/ocr/ios/using_sdk
## Remotamente
> Iniciando a instalação
```shell
pod init
```
Nosso SDK pode ser importado utilizando CocoaPods.
| SDK | Versão atual |
| ---------- | ------------------------------ |
| QITechIosOCR | `pod 'QITechIosOCR', '~> 8.2.0'` |
Para iniciar a instalação, execute o comando ao lado na pasta raiz do seu projeto.
> Adicionando a source no podfile
```ruby
source 'https://github.com/QITechSDKs/iOS.git'
```
O próximo passo é adicionar no arquivo `podfile` o source da QI Tech.
> Adicionando o pod no podfile
```ruby
pod 'QITechIosOCR', '~> '
```
Por fim, basta adicionar o nome do `pod` de acordo com o formato ao lado.
> Exemplo de podfile
```ruby
source 'https://github.com/QITechSDKs/iOS.git'
source 'https://cdn.cocoapods.org/'
target 'ExampleApp' do
use_frameworks!
pod 'QITechIosOCR', '~> 8.2.0'
end
post_install do |installer|
installer.pods_project.targets.each do |target|
if ['DatadogCore', 'DatadogInternal', 'DatadogCrashReporting', 'DatadogLogs'].include?(target.name)
target.build_configurations.each do |config|
config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '12.0'
config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
end
end
end
end
```
:::warning Atenção
Ao integrar dependências no iOS, pode surgir a necessidade de usar linkagem estática para algumas bibliotecas e dinâmica para outras. Essa configuração é relevante para garantir compatibilidade, evitar erros de build e otimizar o desempenho do projeto.
:::
### Linkagem Híbrida de Dependências (caso necessário)
A necessidade de linkagem híbrida surge porque algumas bibliotecas têm requisitos específicos, sendo que algumas precisam de linkagem estática para evitar conflitos internos e duplicação de símbolos e outras dependências podem precisar linkagem dinâmica, pois são projetadas para modularidade e compartilhamento entre projetos.
Diferenças Entre Linkagem Estática e Dinâmica
* Estática (static_framework): O código da biblioteca é incorporado diretamente no binário final, reduzindo o tempo de carregamento em runtime e eliminando dependências externas durante a execução.
* Dinâmica (dynamic_framework): A biblioteca é carregada em tempo de execução como um arquivo separado. Isso reduz o tamanho do binário final e facilita atualizações/modificações independentes.
> Configurando linkagem híbrida no Podfile
```ruby
...
use_frameworks! :linkage => :dynamic # CONFIGURANDO O MODO PADRÃO DE LINKAGEM PARA DINÂMICO
...
static_frameworks = ['framework_1', 'framework_2', ...] # INCLUIR TODAS AS DEPENDÊNCIAS QUE PRECISAM SER LINKADAS DE MODO ESTÁTICO
pre_install do |installer|
installer.pod_targets.each do |pod|
if static_frameworks.include?(pod.name)
def pod.static_framework?;
true
end
def pod.build_type;
Pod::BuildType.static_framework
end
end
end
end
```
> Instalando as dependências
```shell
pod install
```
Por fim, execute o comando `pod install` para baixar e instalar as dependências.
## Permissões Necessárias
Para que o SDK possa acessar os recursos do dispositivo para coletar a foto, é necessário que sejam solicitadas permissões ao usuário.
No arquivo **info.plist**, adicione as permissões abaixo:
| Permissão | Motivo |
| ---------------------------------- | ---------------------------------------------------- |
| Privacy - Camera Usage Description | Acesso à câmera para capturar as fotos do documento. |
## Iniciando o SDK
```swift
import QITechIosOcr
class ViewController: UIViewController, QITechIosOcrControllerDelegate {
var qitechOcrConfiguration : QITechIosOcrConfiguration?
override func viewDidLoad() {
super.viewDidLoad()
self.setupOcr()
}
func setupOcr() -> Void
{
// The environment can be 'Sandbox' ou 'Production'
let environment = QITechIosOcrEnvironment.Sandbox
// MobileToken is the key sent to you by QI Tech. Each environment requires a different MobileToken.
let mobileToken = "YOUR_MOBILE_TOKEN_SENT_BY_QITECH"
// The documentFlow can be 'CnhFull', 'CnhFrontAndBack', 'RgFrontAndBack' ou 'RgCinDigital'
let documentFlow = QITechIosOcrDocumentFlow.CnhFrontAndBack
self.ocrConfig = QITechIosOcrConfiguration(environment: environment,
mobileToken: mobileToken,
sessionId: "UNIQUE_SESSION_ID",
documentFlow: documentFlow,
backgroundColor: "#000000",
fontColor: "#FFFFFF",
fontFamily: .open_sans,
showIntroductionScreens: true,
logLevel: .debug
)
}
// Event where you intend to call QI Tech OCR View Controller - on this example, when the user press 'next' button
@IBAction func pressNext(_ sender: Any) {
let qitechOcrController = QITechIosOcrController(ocrConfiguration: self.ocrConfig)
qitechOcrViewController.delegate = self
let qitechOcrViewController = qitechOcrController.getViewController()
present(qitechOcrViewController, animated: true, completion: nil)
}
// Do something if QI Tech OCR's SDK succesfully collected document picture
func qitechIosOcrController(_ ocrViewController: QITechIosOcrController, didFinishWithResults results: QITechIosOcrControllerResponse) {
}
// Do something if QI Tech OCR's SDK found any error when collecting document picture
func qitechIosOcrController(_ ocrViewController: QITechIosOcrController, didFailWithError error: QITechIosOcrControllerError) {
}
// Do something if the user canceled the picture collection on any steps
func qitechIosOcrControllerDidCancel(_ ocrViewController: QITechIosOcrController) {
}
}
```
Para incorporar o SDK ao seu aplicativo você deve realizar a configuração do seu aplicativo de captura personalizado através da classe **QITechIosOcrConfiguration** e depois instanciar o **ViewController QITechIosOcrController** passando como argumento as configurações personalizadas.
Para iniciar o processo de análise de documento, basta chamar a função _present_ para chamar o ViewController da QI Tech que realizará a coleta das imagens.
Importante implementar o _Delegate_ responsável por receber os retornos em caso de sucesso, erro ou no caso de o usuário interromper a jornada em qualquer etapa da validação.
Ao lado temos um exemplo completo da implementação.
:::info **Atenção**
Habilite o suporte as orientações _Portrait_ e _Landscape Right_ em sua aplicação para um funcionamento correto do SDK.
:::
## Mobile Token
Utilizamos um Mobile Token para permitir o acesso autenticado do seu aplicativo a nossa API. Ele provavelmente já foi enviado por e-mail para você. Caso ainda não tenha recebido o seu token, envie um e-mail para suporte.caas@qitech.com.br .
Nossa API espera receber o Mobile Token em todas as requisições ao nosso servidor vindas do SDK, portanto, este deve ser obrigatoriamente incluido como parâmetro de configuração através do método mencionado anteriormente.
:::info **Atenção**
Você deve substituir "YOUR_MOBILE_TOKEN_SENT_BY_QITECH" com o Mobile Token recebido do suporte.
:::
---
# Transações na QI Conta
URL: /documentation/cards/autorizacao/balance_transaction
---
No contexto de cartão pré-pago, as situações de débito ou crédito possuem um reflexo na QI Conta do portador do cartão. Essas transações são representadas pela entidade `Balance Transaction`. Essas transações devem obrigatoriamente ser executadas na QI Conta do portador mesmo que tardiamente. Sendo assim, caso um débito não possa ser efetuado por algum motivo, a `Balance Transaction` ficará pendente e será retentada automaticamente pelo sistema da QI até que todo o valor seja debitado.
É importante que essas transações sejam acompanhadas e caso alguma `Balance Transaction` persista em pendência o cliente deve entrar em contato com o portador do cartão para assegurar que a QI Conta esteja apta e com o saldo necessário para cobrir essa pendência.
Sempre que uma `Balance Transaction` for criada, um webhook de `Balance Transaction Event` será enviado.
Webhook de evento de transação na QI Conta
```json
{
"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
"data": {
"balance_transaction_key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
"transaction_key": "b64c1ca5-095d-4005-a4ed-3be09d7b111f",
"amount": 25.32,
"transacted_at": "2023-07-24T12:00:00.000Z",
"balance_transaction_status": "transacted"
},
"webhook_type": "prepaid_card.balance_transaction_event",
"event_datetime": "2023-07-24T12:00:00.000Z"
}
```
#### Details
| Campo | Tipo | Descrição |
|---|---| ---|
| `balance_transaction_key` | string | Identificador único da Requisição de Autorização |
| `transaction_key` | string | Identificador único da entidade Autorização relacionada com esta requisição |
| `amount` | string | O valor transacionado na QI Conta neste evento |
| `transacted_at` | string | O horário que a transação foi executada |
| `balance_transaction_status` | string | O estado da `Balance Transaction` após este evento |
O `balance_transaction_status` descreve se a transação foi executada na QI Conta do portador do cartão, podendo estar pendente (`pending_transaction_execution`), parcialmente transacionada (`partially_transacted`) ou transacionada (`transacted`)
:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita.
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::
:::info Reenvio de webhooks!
A consulta e reenvio de webhooks pode ser feito conforme documentação: [Reenvio de webhooks](/documentation/notificacoes/reenvio_de_notificacoes)
:::
---
# Manual BaaS - Conta Digital
URL: /documentation/casos_de_uso/manual_baas
:::warning Aviso
Antes de iniciar o processo de abertura de conta, é de responsabilidade do parceiro realizar as análises de KYC e Prevenção a Fraude.
:::
:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita.
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::
:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::
Para isso, deve ser utilizado o endpoint de análise descrito em /onboarding.
## 1 - Criando uma Conta
### 1.1. Upload de documentos
Antes da abertura da conta deve ser realizado o upload dos documentos da empresa. Seguem listas de documentos exigidos para cada tipo de empresa:
Para S.A.'s:
- Estatuto Social.
- Ata de Eleição dos Representantes Legais da empresa.
- Procuração (caso aplicável).
- Documento com foto de cada representante legal ou procurador.
Para os demais casos:
- Contrato social.
- Procuração (caso aplicável).
- Documento com foto de cada representante legal ou procurador.Os documentos devem ser compactados em um arquivo “.zip” e enviados através do endpoint de upload de documentos ().
#### **Response**
ENDPOINT /upload
MÉTODO POST
Response Body
```json
{
"document_key": "cd639c4a-2279-468a-a047-59865b8159ed",
"document_md5": "8f5bef84cb07dc047017c0d304dbb6b8",
"url": "https://storage.googleapis.com/sandbox-doc-api/documents/cd639c4a-2279-468a-a047-59865b8159ed/identificacao_teste.pdf"
}
```
:::caution IMPORTANTE
Guarde essa **_“document_key”_**, pois ela será necessária na etapa da criação da conta.
:::
### 1.2. Criação da conta PJ
#### **Request**
ENDPOINT /account
MÉTODO POST
Request Body
```json
{
"account_owner": {
"annual_revenue_amount": 180000,
"address": {
"city": "Limeira",
"complement": "complemento",
"neighborhood": "Vila Cidade Jardim",
"number": "662",
"postal_code": "13480290",
"state": "SP",
"street": "Avenida Campinas"
},
"cnae_code": "4721-1/02",
"company_statute": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
"company_document_number": "09080702000105",
"company_type": "ltda",
"email": "padaria@vovolucia.com.br",
"foundation_date": "1950-08-21",
"annual_revenue_amount": "1000000.00",
"name": "VOVO LUCIA CONVENIENCIA LTDA",
"person_type": "legal",
"phone": {
"area_code": "19",
"country_code": "55",
"number": "988888888"
},
"trading_name": "Empadaria Vovo Lucia",
"company_representatives": [{
"address": {
"city": "Recife",
"complement": null,
"neighborhood": "Fundão",
"number": "137",
"postal_code": "52221110",
"state": "PE",
"street": "Rua Camapuã"
},
"birth_date": "1972-02-02",
"document_identification_number": "339122924",
"document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
"email": "marcos.alves@yopmail.com",
"individual_document_number": "08531309069",
"is_pep": false,
"final_beneficiary": true,
"marital_status": "single",
"mother_name": "Sueli Isadora Alves",
"name": "Marcos Felipe Henrique Alves",
"nationality": "Brasileira",
"person_type": "natural",
"phone": {
"area_code": "88",
"country_code": "55",
"number": "995924634"
}
},
{
"person_type": "natural",
"name": "Juliana Tereza Bernardes",
"mother_name": "Maria Mariane",
"birth_date": "1990-05-06",
"profession": "Deputada",
"nationality": "Brasileira",
"marital_status": "single",
"is_pep": false,
"final_beneficiary": true,
"individual_document_number": "97564480084",
"document_identification_number": "232479719",
"document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
"email": "juliana.tereza@yopmail.com",
"phone": {
"country_code": "55",
"area_code": "11",
"number": "912821359"
},
"address": {
"street": "Passagem Mariana",
"state": "PA",
"city": "Ananindeua",
"neighborhood": "Águas Lindas",
"number": "660",
"postal_code": "67118003",
"complement": "complemento"
}
}
]
},
"allowed_user": {
"email": "juliana.tereza@yopmail.com",
"individual_document_number": "97564480084",
"name": "Juliana Tereza Bernardes",
"person_type": "natural",
"phone": {
"country_code": "55",
"area_code": "11",
"number": "912828135"
}
},
"signed_contract": {
"document_key": "4d7f4e29-4b58-4905-9a69-b1f9215263f5",
"signatures": [
{
"authenticity": {
"timestamp": "1970-01-01T00:00:01.080100Z",
"facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb",
"lang": "-35.8916627",
"lat": "-7.2226067",
"ip_address": "177.51.1.000",
"session_id": "jdifj329842"
},
"signer": {
"name": "IVANILDO DE SENA LIMA",
"email": "teste@gmail.com",
"phone": {
"country_code": "055",
"area_code": "11",
"number": "999999999"
},
"document_number": "99999999999"
},
"authentication_type": "opt-in"
}
]
}
}
```
**“account_owner”:** Os dados da empresa devem ser enviados neste objeto.
“***account_owner.company_statute***”: A “***document_key***” retornada no endpoint de upload de documentos, no momento do upload do “.zip” dos documentos societários da empresa, deve ser enviada neste campo.
“***account_owner.company_representatives***”: A lista com os dados dos representantes legais da empresa deve ser enviada neste objeto. Deve ser enviado, no mínimo, os representantes legais, suficientes para representar legalmente a empresa conforme seu respectivo estatuto/contrato social. A validação dos poderes de cada representante legal enviado fica a cargo do parceiro.
“***account_owner.company_representatives.document_identification***”: A “***document_key***” retornada no endpoint de upload de documentos, no momento do upload do “.zip” do documento com foto do representante, deve ser enviada neste campo.
“***allowed_user***”: Neste campo devem ser enviados os dados de um dos representantes legais da empresa enviado no objeto “***account_owner.company_representatives***”. Este usuário será o usuário administrador da conta e possuirá poderes de movimentação sobre a conta e também poderes para adicionar novos usuários administradores. O SMS/e-mail de confirmação tanto para movimentação quanto adição de novos usuários será enviado para essa pessoa.
:::info
O usuário com permissão de administrador possui plenos poderes sobre a conta (mediante autenticação de 2 fatores, via SMS ou e-mail). Sendo assim, este usuário deve possuir permissão legal para movimentá-la segundo o contrato/estatuto social da empresa. A validação dos poderes de um usuário administrador fica a cargo do parceiro.
:::
### 1.2.1 Assinatura do Termo de Abertura de Conta
No payload de abertura de conta deverá ser enviado o campo `signature_contract` que deverá conter as informações de device scan do momento em que o usuário (Titular da conta ou usuário master) realiza o aceite do termo de abertura de cont
### Objeto signed_contract
| Campo | Tipo | Descrição | Caracteres |
|-------|--------|------------------|---------------|
| **document_key** * | uuidv4 | Chave única de identificação do documento do **Termo de Abertura de Conta** ou **Contrato de Conta Escrow**. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36 |
| **signatures** * | list | Dados de assinatura do documento enviado. Cada item da lista, corresponde a um assinante do documento. | [Objeto signatures](#objeto-signatures) |
### Objeto signatures
| Campo | Tipo | Descrição | Caracteres |
|-------|------------|-------------------|-------------------|
| **authenticity** * | object | Conjunto de dados que evidenciam a assinatura eletrônica realizada pelo assinante. | [Objeto authenticity](#objeto-authenticity) |
| **signer** * | object | Objeto contendo os dados de um dos assinantes do documento. | [Objeto signer](#objeto-signer)|
| **authentication_type** * | enumerator | Tipo de assinatura. Sempre será "**opt-in**"| "**opt-in**" |
### Objeto authenticity
| Campo | Tipo | Descrição | Caracteres |
|-------|--------|-------------------------|------------|
| **timestamp** * | string | Data e hora do momento da assinatura do documento. | 27 |
| **facial_recognition_key** | uuidv4 | Chave única de identificação da foto da selfie do titular da conta. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36 |
| **lang** | string | Coordenada de longitude da geolocalização do assinante capturada no momento da assinatura. | - |
| **lat** | string | Coordenada de latitude da geolocalização do assinante capturada no momento da assinatura. | - |
| **ip_address** | string | Endereço IP do dispositivo do assinante. | - |
| **session_id** | string | ID da seção do assinante no momento da assinatura. | - |
### Objeto signer
| Campo | Tipo | Descrição | Caracteres |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| **name** * | string | Nome do assinante. | - |
| **email** * | string | Email do assinante. | - |
| **phone** * | object | Objeto com dados do telefone do assinante | **[Objeto phone](#objeto-phone)** |
| **document_number** * | string | CPF do assinante. | 11 |
### Objeto phone
| Campo | Descrição | Exemplo | Máx. Caracteres |
| --- | --- | --- | --- |
|`country_code` *| string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 |
| `area_code` *| string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2 |
| `number` *| string |Número de telefone (apenas números) | 10 |
**Response**
- MÉTODO POST
- ENDPOINT /account
Response Body
```json
{
"data": {
"account_info": {
"account_branch": "0001",
"account_digit": "2",
"account_number": "2359934",
"financial_institution_code": "329"
},
"account_owner": {
"document_number": "09080702000105",
"name": "VOVO LUCIA CONVENIENCIA LTDA"
},
"allowed_user": {
"document_number": "97564480084",
"name": "Juliana Tereza Bernardes"
}
},
"event_datetime": "2022-09-02 22:39:10",
"key": "\",
"status": "pending_kyc_analysis",
"webhook_type": "account"
}
```
:::info IMPORTANTE
IMPORTANTE: a “***key***” retornada nesta resposta é a PROPOSAL-KEY do pedido de abertura da conta. Ela deve ser armazenada para leitura do webhook de abertura da conta.
:::
A resposta da solicitação de abertura de conta sempre retornará o status “***pending_kyc_analysis***”.
Um número de conta será reservado para esse cliente, porém a conta ainda estará pendente de análise de KYC por parte da QI Tech. Neste momento, a conta não estará aberta e não poderá receber ou enviar recursos.
### 1.3. Criação da conta PF
**Request**
- ENDPOINT /account
- MÉTODO POST
Request Body
```json
{
"account_owner": {
"address": {
"street": "Avenida Sargento Geraldo Sant'Ana",
"number": "1100",
"neighborhood": "Jardim Taquaral",
"city": "São Paulo",
"state": "SP",
"postal_code": "04674225"
},
"phone": {
"country_code": "55",
"number": "912828135",
"area_code": "11"
},
"email": "juliana.tereza@yopmail.com",
"name": "Juliana Tereza Bernardes",
"person_type": "natural",
"nationality": "Brasil",
"birth_date": "1993-08-02",
"mother_name": "Patricia Monica Diaz Bascur Tieppo",
"is_pep": false,
"individual_document_number": "97564480084",
"document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
"document_identification_type": "cnh",
"revenue_amount": 1000,
"profession": "autonomo"
},
"signed_contract": {
"document_key": "4d7f4e29-4b58-4905-9a69-b1f9215263f5",
"signatures": [
{
"authenticity": {
"timestamp": "1970-01-01T00:00:01.080100Z",
"facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb",
"lang": "-35.8916627",
"lat": "-7.2226067",
"ip_address": "177.51.1.000",
"session_id": "jdifj329842"
},
"signer": {
"name": "IVANILDO DE SENA LIMA",
"email": "teste@gmail.com",
"phone": {
"country_code": "055",
"area_code": "11",
"number": "999999999"
},
"document_number": "99999999999"
},
"authentication_type": "opt-in"
}
]
}
}
```
**“account_owner”:** Os dados da pessoa física titular da conta devem ser enviados neste objeto.
**“account_owner.document_identification”:** A “document_key” retornada no endpoint de upload de documentos.
#### 1.3.1. Forma de envio do documento de identificação
Na abertura da conta PF, podem ser enviados dois tipos de documento (***document_identification_type***): **cnh** ou **rg**.
O documento de identificação pode ser enviado nos formatos “**.pdf**”, “**.png**” e “**.jpeg**”.
##### 1.3.1.1. Envio de documento de identificação do tipo CNH
Caso o documento seja enviado em 2 arquivos, sendo que, a frente do documento consta em um arquivo e o verso em outro, os seguintes campos devem ser infomado no objeto ***account_owner*** do endpoint ***/account*** (**1.2.2.**):
Request Body
```json
"document_identification": "\",
"document_identification_back": "\",
"document_identification_type": "cnh",
```
Caso o documento seja enviado em 1 arquivo, contendo a frente e verso do documento no mesmo arquivo (**foto do documento ou cnh digital**), os seguintes campos devem ser infomado no objeto account_owner do endpoint ***/account*** (**1.2.2.**):
Request Body
```json
"document_identification": "\",
"document_identification_type": "cnh",
```
##### 1.3.1.2. Envio de documento de identificação do tipo RG
Para o tipo de documento RG, sempre devem ser enviados 2 arquivos, um contendo a frente do documento e outro com o verso do documento. Para este caso os seguintes campos devem ser infomados no objeto account_owner do endpoint /account (1.2.2.):
Request Body
```json
"document_identification": "\",
"document_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 IMPORTANTE
**IMPORTANTE:** a “***key***” retornada nesta resposta é a **PROPOSAL-KEY** do pedido de abertura da conta. Ela deve ser armazenada para leitura do webhook de abertura da conta.
:::
A resposta da solicitação de abertura de conta sempre retornará o status “***pending_kyc_analysis***”.
Um número de conta será reservado para esse cliente, porém a conta ainda estará pendente de análise de KYC por parte da QI Tech. Neste momento, a conta não estará aberta e não poderá receber ou enviar recursos.
:::info
Para simular situações de aprovação, reprovação e analise manual pode ser utilizado o primeiro digito do CPF/CNPJ do owner da conta:
- 0 à 7 -> Análise Manual
- 8 -> Reprovação Automática
- 9 -> Aprovação Automática
:::
Após a conclusão da análise de KYC/PLD pela QI Tech, será enviado um webhook de abertura da conta, conforme abaixo:
**Webhook**
- WEBHOOK_TYPE account
- STATUS Account Opened
Response Body
```json
{
"data": {
"account_info": {
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"account_digit": "2",
"account_branch": "0001",
"account_number": "2359934",
"financial_institution_code": "329"
},
"allowed_user": {
"name": "Juliana Tereza Bernardes",
"document_number": "97564480084"
},
"account_owner": {
"name": "VOVO LUCIA CONVENIENCIA LTDA",
"document_number": "09080702000105"
}
},
"event_datetime": "2022-09-02 22:39:39",
"key": "\",
"status": "account_opened",
"webhook_type": "account"
}
```
Neste momento será retornada “account_key” da conta e ela estará pronta para utilização.
Caso a conta não passe no processo de KYC/PLD, será enviado um webhook de conta rejeitada:
**Webhook**
- WEBHOOK_TYPE account
- STATUS Account Rejected
Response Body
```json
{
"data": {
"account_info": {
"account_digit": "2",
"account_branch": "0001",
"account_number": "2359934",
"financial_institution_code": "329"
},
"allowed_user": {
"name": "Juliana Tereza Bernardes",
"document_number": "97564480084"
},
"account_owner": {
"name": "VOVO LUCIA CONVENIENCIA LTDA",
"document_number": "09080702000105"
}
},
"event_datetime": "2022-09-02 22:39:39",
"key": "\",
"status": "account_rejected",
"webhook_type": "account"
}
```
:::caution Atenção
A propriedade **allowed_user** retornada apenas nos webhooks de abertura de conta de PJ, em caso de PF temos apenas a propriedade de **account_info** e **account_owner** sendo retornadas dentro do objeto de **data**.
:::
#### 1.3.2 Assinatura do Termo de Abertura de Conta
No payload de abertura de conta deverá ser enviado o campo `signature_contract` que deverá conter as informações de device scan do momento em que o usuário (Titular da conta ou usuário master) realiza o aceite do termo de abertura de cont
### Objeto signed_contract
| Campo | Tipo | Descrição | Caracteres |
|-------|--------|------------------|---------------|
| **document_key** * | uuidv4 | Chave única de identificação do documento do **Termo de Abertura de Conta** ou **Contrato de Conta Escrow**. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36 |
| **signatures** * | list | Dados de assinatura do documento enviado. Cada item da lista, corresponde a um assinante do documento. | [Objeto signatures](#objeto-signatures) |
### Objeto signatures
| Campo | Tipo | Descrição | Caracteres |
|-------|------------|-------------------|-------------------|
| **authenticity** * | object | Conjunto de dados que evidenciam a assinatura eletrônica realizada pelo assinante. | [Objeto authenticity](#objeto-authenticity) |
| **signer** * | object | Objeto contendo os dados de um dos assinantes do documento. | [Objeto signer](#objeto-signer)|
| **authentication_type** * | enumerator | Tipo de assinatura. Sempre será "**opt-in**"| "**opt-in**" |
### Objeto authenticity
| Campo | Tipo | Descrição | Caracteres |
|-------|--------|-------------------------|------------|
| **timestamp** * | string | Data e hora do momento da assinatura do documento. | 27 |
| **facial_recognition_key** | uuidv4 | Chave única de identificação da foto da selfie do titular da conta. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36 |
| **lang** | string | Coordenada de longitude da geolocalização do assinante capturada no momento da assinatura. | - |
| **lat** | string | Coordenada de latitude da geolocalização do assinante capturada no momento da assinatura. | - |
| **ip_address** | string | Endereço IP do dispositivo do assinante. | - |
| **session_id** | string | ID da seção do assinante no momento da assinatura. | - |
### Objeto signer
| Campo | Tipo | Descrição | Caracteres |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| **name** * | string | Nome do assinante. | - |
| **email** * | string | Email do assinante. | - |
| **phone** * | object | Objeto com dados do telefone do assinante | **[Objeto phone](#objeto-phone)** |
| **document_number** * | string | CPF do assinante. | 11 |
### Objeto phone
| Campo | Descrição | Exemplo | Máx. Caracteres |
| --- | --- | --- | --- |
|`country_code` *| string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 |
| `area_code` *| string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2 |
| `number` *| string |Número de telefone (apenas números) | 10 |
### 1.4. Recuperando dados da conta
**Request**
- ENDPOINT /account
- MÉTODO GET
- PARAMETERS account_type[checking], owner_name, account_number, owner_document_number, account_status[opened, closed, blocked], page, page_size
***Response:***
Response Body
```json
{
"data": [
{
"account_block_reason": null,
"account_branch": "0001",
"account_credentials": [{
"account_id": 3395,
"created_at": "2022-09-02T22:39:39",
"credential_type": {
"created_at": "2019-06-18T13:19:30",
"enumerator": "observer",
"id": 3,
"translation_path": "account.CredentialType.observer"
},
"credential_type_id": 3,
"id": 3244,
"is_active": true,
"person_key": "bffded45-5fcf-4d13-9d2a-566a0af338cc",
"updated_at": null
},
{
"account_id": 3395,
"created_at": "2022-09-02T22:39:39",
"credential_type": {
"created_at": "2019-06-18T13:19:30",
"enumerator": "requester",
"id": 2,
"translation_path": "account.CredentialType.requester"
},
"credential_type_id": 2,
"id": 3245,
"is_active": true,
"person_key": "ef48fbe4-267b-45c1-9049-75345c075486",
"updated_at": null
}
],
"account_digit": "2",
"account_documents": [],
"account_events": [{
"account_id": 3395,
"created_at": "2022-09-02T22:39:39",
"id": 5132,
"new_account_status": {
"created_at": "2019-10-11T18:58:31",
"enumerator": "opened",
"id": 1,
"translation_path": "account.AccountStatus.opened"
},
"new_account_status_id": 1,
"old_account_status": null,
"old_account_status_id": null
}],
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"account_name": "Default",
"account_number": "2359934",
"account_status": {
"created_at": "2019-10-11T18:58:31",
"enumerator": "opened",
"translation_path": "account.AccountStatus.opened"
},
"account_type": {
"created_at": "2019-03-15T13:09:15",
"enumerator": "checking",
"translation_path": "account.AccountType.checking"
},
"automatic_transfer_management_status": {
"created_at": "2022-10-27T13:48:18",
"enumerator": "master"
},
"automatic_transfers": [],
"balance": 0,
"blocked_balance": 0,
"blocked_balance_events": [],
"created_at": "2022-09-02T22:39:39",
"destinations": [],
"fee": 0,
"internal_webhooks": [],
"investment_available_amount": 0,
"investment_configuration": null,
"is_system_account": false,
"owner_document_number": "09080702000105",
"owner_name": "VOVO LUCIA CONVENIENCIA LTDA",
"owner_person_key": "bffded45-5fcf-4d13-9d2a-566a0af338cc",
"permitted_person_keys": [
"bffded45-5fcf-4d13-9d2a-566a0af338cc",
"bffded45-5fcf-4d13-9d2a-566a0af338cc",
"ef48fbe4-267b-45c1-9049-75345c075486"
],
"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
"requester_name": "Requester Name Sandbox",
"setup_fee": null,
"transactional_limit": null,
"webhook_enabled": true
}, ...
],
"pagination": {
"current_page": 1,
"next_page": null,
"rows_per_page": 100,
"total_pages": 1,
"total_rows": 8
}
}
```
:::info
Os campos mais pertinentes da resposta da consulta dos dados da conta são: **account_branch**, **account_digit**, **account_key**, **account_number**, **balance**, **owner_document_number**, **owner_name**, **owner_person_key**.
:::
## 2 - Transferência PIX
### 2.1. Realizar Transferência PIX
Para realizar um PIX é necessário realizar três chamadas:
1. Criação do pedido de transferência: /baas/pix_transfer
2. Solicitação de token de validação de transferência: /baas/token_request
3. Aprovação da transferência: /baas/movement_validation
:::info
Uma transferência PIX pode ser realizada utilizando dois payloads distintos: **chave PIX** ou **dados bancários**.
:::
### **2.1.1. Criação do pedido de transferência**
### Transferência utilizando uma chave PIX (CPF, CNPJ, E-mail, Celular ou chave aleatória)
- ENDPOINT /baas/pix_transfer
- MÉTODO POST
Request Body
```json
{
"pix_transfer_type": "key",
"source_account": {
"account_branch": "0001",
"account_digit": "2",
"account_number": "2359934",
"owner_document_number": "09080702000105"
},
"pix_key": "65322181032",
"transaction_amount": 45,
"requester_document_identification": "09080702000105"
}
```
:::info
A “**pix_key**” pode ser um **CPF**, **CNPJ**, **E-mail**, **Celular** ou uma **Chave Aleatória (UUID)**, seguindo as seguintes formatações:
**CPF:** Número inteiro com 11 dígitos.
**CNPJ:** Número inteiro com 14 dígitos.
**E-mail:** Texto contendo ao menos um “@”.
**Celular:** Texto contendo os seguintes valores: “+55” + “DDD do celular“ + “Número Inteiro do Celular com no mínimo 8 e no máximo 9 dígitos”. Ex: “+5511987654321“.
**Chave Aleatória:** UUID.
:::
### Transferência utilizando dados da Conta Bancária (PIX Manual)
- ENDPOINT /baas/pix_transfer
- MÉTODO POST
Request Body
```json
{
"pix_transfer_type": "manual",
"source_account": {
"account_branch": "0001",
"account_digit": "2",
"account_number": "2359934",
"owner_document_number": "09080702000105"
},
"target_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "12345678",
"owner_document_number": "32402502000135",
"owner_name": "Qi Tech",
"account_type": "checking_account",
"ispb": "32402502"
},
"transaction_amount": 45
}
```
Utilizando o PIX Manual é necessário informar o ISPB da instituição destino. Este dado é utilizado, pois existem instituições de pagamento que recebem PIX, porém não possuem código de banco. O ISPB é a base do CNPJ da instituição. Para ter acesso à lista completa de ISPB’s de cada instituição participante do PIX, basta utilizar o endpoint de consulta em nossa documentação: https://docs.qitech.com.br/reference/161-consulta-de-institui%C3%A7%C3%B5es-financeiras
Response Body
```json
{
"data": {
"end_to_end_id": "E3240250220221120012039U3OKZZMW8",
"fee_amount": 1,
"pix_message": null,
"pix_transfer_key": "cea836b5-b02e-4f94-b1e2-4d575671c33d",
"source_account": {
"account_brach": "0001",
"account_digit": "2",
"account_number": "2359934",
"account_type": "checking",
"owner_document_number": "09080702000105",
"owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
},
"target_account": {
"document_number": "***.221.81*-**",
"financial_institution": "BANCO ORIGINAL S.A."
},
"transaction_amount": 45,
"transfer_purpose": "transfer"
},
"event_datetime": "2022-09-02 22:20:47",
"operation_key": "86d80cf4-430b-4e16-910a-41798810ddcf",
"status": "pending_approval"
}
```
:::info Possíveis status da solicitação de transferência/pagamento via PIX:
**pending_approval:** transferência pendente de aprovação pelo usuário administrador da conta (“***allowed_user***”)
**sent:** transferência enviada
:::
:::caution Atenção
O campo **end_to_end_id** retornado deve ser amarzenado e enviado no momento da aprovação da transação. É ELE QUEM GARANTE
:::
Após realizar a primeira chamada de “***/baas/pix_transfer***”, é necessário solicitar o token para aprovar a transação. Para aprovar a transferência PIX, é necessário utilizar a “***pix_transfer_key***” retornada na solicitação de transferência e solicitar a geração de um token que será enviado ao usuário administrador da conta para aprovação (“**allowed_user**”).
### **2.1.2. Solicitação de token de validação de transferência:**
- ENDPOINT /baas/token_request
- MÉTODO POST
Request Body
```json
{
"contact_type": "sms",
"agent_document_number": "97564480084",
"movement_payload": {
"pix_transfer_key": "cea836b5-b02e-4f94-b1e2-4d575671c33d",
"approver_document_number": "97564480084"
}
}
```
:::info
**contact_type:** é o método de autenticação de dois fatores que será utilizado no momento da aprovação da transferência, podendo ser via E-mail (“email”) ou SMS (“sms”).
:::
:::info
**approver_document_number:** Deve ser informado o CPF do usuário administrador que realizará a aprovação da transferência PIX.
:::
:::info
**agent_document_number:** neste campo pode ser informado o CPF do usuário master que receberá o token para aprovação de 2 fatores da transação.
:::
A última chamada para concluir a transferência será a do “**/baas/movement_validation**” e o Token enviado deve ser informado no momento da aprovação da transferência PIX. A validade do Token é de **2 minutos**.
O usuário administrador deve inserir na aplicação do parceiro o token recebido via E-mail ou SMS.
### **2.1.3. Aprovação da transferência:**
- ENDPOINT /baas/movement_validation
- MÉTODO POST
Request Body
```json
{
"token": "248358",
"movement_payload": {
"pix_transfer_key": "cea836b5-b02e-4f94-b1e2-4d575671c33d",
"approver_document_number": "97564480084"
}
}
```
Reponse Body
```json
{
"authentication_code": "287c4478a1adcd6e820e654ac1b1edf2",
"event_datetime": "2022-09-02 23:00:07",
"operation_key": "05283f8e-b9c0-47ff-a06f-9626be710f69",
"pix_transaction": {
"end_to_end_id": "E3240250220221120012039U3OKZZMW8",
"fee_amount": 1,
"pix_message": null,
"pix_transfer_key": "cea836b5-b02e-4f94-b1e2-4d575671c33d",
"pix_transfer_status": "sent",
"pix_transfer_type": "key",
"source_account": {
"account_branch": "0001",
"account_digit": "2",
"account_number": "2359934"
},
"target_account": {
"document_number": "***.221.81*-**",
"financial_institution": "BANCO ORIGINAL S.A."
},
"transaction_key": "d2ba3817-26d7-4957-ab82-24f78d910a8a",
"transfer_amount": 45
},
"status": "sent"
}
```
STATUS 422
Response Body
```json
{
"data": "{\"title\": \"Pending Transfer\", \"description\": \"The transaction () 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
Caso seja retornado **http error 422**, a solicitação de Pix **não deve ser retentada**. É preciso checar o status da solicitação de transferência Pix através de um GET na rota [/baas/pix/pix_transfer](/documentation/pix/pesquisar_por_transferencia_pix_de_saida).
:::
### 2.2. Webhook de Efetivação de um PIX
#### **Webhook**
- WEBHOOK_TYPE account_transaction
- SOURCE_SUB_TYPE pix_withdrawal
Response Body
```json
{
"key": "508ebbba-0b1d-41f6-b9a2-975a4c2e925e",
"data": {
"amount": -45,
"origin": {
"name": "PIX",
"branch": "0001",
"document": "32402502000135",
"account_key": "3d0e7d50-e898-49f3-b23b-05353c8a3c72",
"account_digit": "3",
"account_number": "00003"
},
"timestamp": "2023-01-05T18:16:03.395863",
"description": "237 0001 1017372-2 ***.221.81*-** BANCO BRADESCO S.A.",
"destination": {
"name": "Default",
"branch": "0001",
"document": "23426525852",
"account_key": "508ebbba-0b1d-41f6-b9a2-975a4c2e925e",
"account_digit": "0",
"account_number": "7058818"
},
"reference_key": "aafbf4bc-58eb-45fd-899c-af44f68dfd60",
"reference_type": "pix_outgoing",
"account_balance": 99359.15,
"source_sub_type": "pix_withdrawal",
"transaction_key": "3e37a0a9-d6d2-4474-8bff-5448e446c225",
"source_sub_type_str": "Transferência de PIX"
},
"datetime": "2023-01-05T18:16:03.395863",
"webhook_type": "account_transaction"
}
```
### 2.3. Webhook de Cobrança de fee de PIX
**Webhook**
- WEBHOOK_TYPE account_transaction
- SOURCE_SUB_TYPE pix_fee
Response Body
```json
{
"key": "508ebbba-0b1d-41f6-b9a2-975a4c2e925e",
"data": {
"amount": -0.85,
"origin": {
"name": "Fee Account",
"branch": "0001",
"document": "32402502000135",
"account_key": "3679ffd0-d52e-4492-b11c-b11c655047d3",
"account_digit": "8",
"account_number": "00005"
},
"timestamp": "2023-01-05T18:16:03.554624",
"description": "237 0001 1017372-2 ***.221.81*-** BANCO BRADESCO S.A.",
"destination": {
"name": "Default",
"branch": "0001",
"document": "23426525852",
"account_key": "508ebbba-0b1d-41f6-b9a2-975a4c2e925e",
"account_digit": "0",
"account_number": "7058818"
},
"reference_key": "aafbf4bc-58eb-45fd-899c-af44f68dfd60",
"reference_type": "pix_outgoing",
"account_balance": 99358.3,
"source_sub_type": "pix_fee",
"transaction_key": "53c7421b-1340-4625-b383-b94d350ff9b2",
"source_sub_type_str": "Tarifa de PIX"
},
"datetime": "2023-01-05T18:16:03.554624",
"webhook_type": "account_transaction"
}
```
### 2.4. Chargeback Pix
Um Chargeback Pix (Estorno) é realizado em 3 etapas:
- 1 - Iniciação do Chargeback Pix: /baas/pix_transfer
- 2 - Solicitação do token de autorização do Chargeback Pix: /baas/token_request
- 3 - Aprovação do Chargeback Pix: /baas/movement_validation
#### 2.4.1. Iniciando Chargeback Pix
##### Request
ENDPOINT /baas/pix_transfer
MÉTODO POST
Request Body
```json
{
"is_chargeback": true,
"pix_transfer_key": "a180f2fb-0c7e-4708-b6a0-8d231770132e",
"chargeback_amount": 100.46,
"chargeback_message": "Mensagem de devolução"
}
```
:::info
A _**pix_transfer_key**_ é a chave do Pix que creditou a conta na QI, retornada via Webhook de _**account_transaction**_.
O _**chargeback_amount**_ deve ser menor ou igual ao valor do Pix que creditou a conta na QI.
:::
##### Response
ENDPOINT /baas/pix_transfer
MÉTODO POST
Response Body
```json
{
"data": {
"pix_transfer_key": "7a71e1f7-d8d1-4cf0-9243-c0b3837a3d26",
"pix_transfer_status": "pending_approval",
"pix_transfer_type": "chargeback",
"target_account": {
"document_number": "***45762***",
"financial_institution": "ITAÚ UNIBANCO S.A."
},
"transfer_amount": 100.46
},
"event_datetime": "2023-04-28 18:19:30",
"operation_key": "ab895342-988d-4d20-ba71-f82a7b9aad1b",
"status": "pending_approval"
}
```
:::info
A _**pix_transfer_key**_ retornada na chamada é a chave de referência do Chargeback Pix que deverá ser aprovado.
:::
#### 2.4.2. Solicitação do token de autorização do Chargeback Pix
ENDPOINT /bass/token_request
MÉTODO POST
Request Body
```json
{
"contact_type": "email",
"movement_payload": {
"pix_transfer_key": "7a71e1f7-d8d1-4cf0-9243-c0b3837a3d26",
"approver_document_number": "97564480084"
}
}
```
#### 2.4.3. Aprovação do Chargeback Pix
ENDPOINT /bass/movement_validation
MÉTODO POST
Request Body
```json
{
"contact_type": "email",
"movement_payload": {
"pix_transfer_key": "7a71e1f7-d8d1-4cf0-9243-c0b3837a3d26",
"approver_document_number": "97564480084"
}
}
```
## 3 - Transferência TED
:::info
As transferências TED só podem ser realizadas em dias úteis das **7:00** às **17:00**.
:::
### 3.1. Realizar Transferência TED
Para realizar uma transferência via TED é necessário realizar a seguinte chamada:
1. Solicitação de token de validação de transferência: /baas/token_request
2. Aprovação da transferência: /baas/movement_validation
**Request**
- ENDPOINT /baas/token_request
- MÉTODO POST
Request Body
```json
{
"contact_type": "sms",
"agent_document_number": "97564480084",
"movement_payload": {
"source_account": {
"account_branch": "0001",
"account_number": "9477323",
"account_digit": "0",
"owner_document_number": "38299588000107"
},
"target_account": {
"financial_institution_code": "341",
"account_branch": "0001",
"account_number": "4311337",
"account_digit": "1",
"owner_document_number": "21669721019",
"owner_name": "Nome do Titular da Conta Destino"
},
"transaction_amount": 8.86
}
}
```
O Token enviado deve ser informado no momento da aprovação da transferência TED, e o “***movement_payload***” deve ser o mesmo informado no momento da solicitação do Token.
**Request**
- ENDPOINT /baas/movement_validation
- MÉTODO POST
Request Body
```json
{
"token": "329329",
"agent_document_number": "99999999999",
"movement_payload": {
"source_account": {
"account_branch": "0001",
"account_number": "0000000",
"account_digit": "0",
"owner_document_number": "99999999000107"
},
"target_account": {
"financial_institution_code": "341",
"account_branch": "0001",
"account_number": "0000000",
"account_digit": "1",
"owner_document_number": "999999999",
"owner_name": "Nome do Titular da Conta Destino"
},
"transaction_amount": 8.86,
"approver_document_number": "999999999"
}
}
```
**Response**
- MÉTODO POST
- ENDPOINT /baas/movement_validation
Response Body
```json
{
"authentication_code": "e8f0fffaeb4ebad2df0417194fe6a9e5",
"origin_key": "d07f77f9-f157-4c35-a26b-567cba59e385",
"pdf_encoded_string": "\",
"source_account": {
"account_branch": "0001",
"account_digit": "2",
"account_number": "2359934",
"financial_institution_compe_number": 329,
"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
"owner_document_number": "09080702000105",
"owner_document_number_formatted": "09.080.702/0001-05",
"owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
},
"source_subtype": "withdrawal",
"source_subtype_translation_ptbr": "Transferência",
"target_account": {
"account_branch": "0001",
"account_digit": "1",
"account_number": "81156",
"account_type": "checking_account",
"account_type_str": "Conta Corrente",
"financial_institution_compe_number": "001",
"financial_institution_name": "Banco do Brasil S.A.",
"owner_document_number": "10932327656",
"owner_document_number_formatted": "109.323.276-56",
"owner_name": "Lucas de Jesus Clarim"
},
"transacted_at": "2022-09-02 14:39:56",
"transacted_at_br": "2022-09-02 11:39:56",
"transacted_at_br_formatted": "21/11/2022, 11:39:56",
"transacted_at_formatted": "21/11/2022, 14:39:56",
"transaction_amount": 550,
"transaction_amount_formatted": "R$ 550,00",
"transaction_key": "32ac0781-f292-4172-b58f-3310102e6fb9"
}
```
:::info
O campo de “***transacted_at***“ estão em formato UTC.
:::
:::info
A “***transaction_key***“ será utilizada posteriormente para solicitação do comprovante de transferência.
:::
### 3.2. Efetivação de uma TED
**Webhook**
- WEBHOOK_TYPE account_transaction
- SOURCE_SUB_TYPE withdrawal
Response Body
```json
{
"key": "508ebbba-0b1d-41f6-b9a2-975a4c2e925e",
"data": {
"amount": -550,
"origin": {
"name": "TED",
"branch": "0001",
"document": "32402502000135",
"account_key": "23a4a2c8-9d82-4ebe-a90d-44fe8d839ec0",
"account_digit": "7",
"account_number": "00001"
},
"timestamp": "2023-01-05T07:35:37.127502",
"description": "001 0001 81156-1 32.402.502/0001-35 - QI Tech",
"destination": {
"name": "Default",
"branch": "0001",
"document": "23426525852",
"account_key": "508ebbba-0b1d-41f6-b9a2-975a4c2e925e",
"account_digit": "0",
"account_number": "7058818"
},
"reference_key": "58729e67-f490-4607-aafd-2fc7945d3d77",
"reference_type": "ted_outgoing",
"account_balance": 99404.15,
"source_sub_type": "withdrawal",
"transaction_key": "4ac9e80b-22d9-4097-8676-e19f84c89543",
"source_sub_type_str": "Transferência"
},
"datetime": "2023-01-05T07:35:37.127502",
"webhook_type": "account_transaction"
}
```
### 3.3. Estorno de uma TED
**Webhook**
- WEBHOOK_TYPE account_transaction
- SOURCE_SUB_TYPE withdrawal_reversal
Response Body
```json
{
"key": "508ebbba-0b1d-41f6-b9a2-975a4c2e925e",
"data": {
"amount": 550,
"origin": {
"name": "TED",
"branch": "0001",
"document": "32402502000135",
"account_key": "23a4a2c8-9d82-4ebe-a90d-44fe8d839ec0",
"account_digit": "7",
"account_number": "00001"
},
"timestamp": "2023-01-05T07:42:26.631137",
"description": "001 0001 81156-1 32.402.502/0001-35 - QI Tech",
"destination": {
"name": "Default",
"branch": "0001",
"document": "23426525852",
"account_key": "508ebbba-0b1d-41f6-b9a2-975a4c2e925e",
"account_digit": "0",
"account_number": "7058818"
},
"reference_key": "58729e67-f490-4607-aafd-2fc7945d3d77",
"reference_type": "ted_outgoing",
"account_balance": 99954.15,
"source_sub_type": "withdrawal_reversal",
"transaction_key": "53268774-6891-42a4-a658-42e21cef867c",
"source_sub_type_str": "Estorno de Transferência"
},
"datetime": "2023-01-05T07:42:26.631137",
"webhook_type": "account_transaction"
}
```
## 4 - Pagamento QR Code PIX
### 4.1. Pagando um QR Code PIX Estático
Para realizar o pagamento de um QR Code PIX Estático, é necessário realizar quatro chamadas:
1. Decodificar o QR Code PIX: /baas/pix/qrcode
2. Criação do pedido de transferência: /baas/pix_transfer
3. Solicitação de token de validação de transferência: /baas/token_request
4. Aprovação da transferência: /baas/movement_validation
A informação que deve ser utilizada para decodificação do QR Code PIX Estático é a URI do PIX Copia e Cola vinculada ao QR Code.
:::info
**Exemplo de URI PIX Copia e Cola:** 00020126580014br.gov.bcb.pix01360598e5d1-2cfc-4857-abf8-12d495aa0a6d52040000530398654040.225802BR5925VOVO LUCIA CONVENIENCIA L6009sao paulo610912345-78062070503***63043A5A
:::
**Request**
- ENDPOINT /baas/pix/qrcode
- MÉTODO POST
Reponse Body
```json
{
"qr_code_payload": "\"
}
```
**Response**
- MÉTODO POST
- ENDPOINT /baas/pix/qrcode
Response Body
```json
{
"end_to_end_id": "E3240250220221120030008388062101",
"qr_code_data": {
"additional_data": null,
"amount": 30,
"ispb_number": "32402502",
"receiver_conciliation_id": "***",
"target_account_branch": "0001",
"target_account_digit": "5",
"target_account_number": "2",
"target_account_type": "checking",
"target_bank_code": 329,
"target_bank_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
"target_document_number": "32402502000135",
"target_name": "QI SOCIEDADE DE CREDITO DIRETO S.A.",
"target_person_type": "legal",
"target_pix_key": "316bd44f-2202-4c33-9dc0-096192acd427"
},
"qr_code_key": "1608e022-e42d-49d8-bacf-da5844570635",
"qr_code_payload": "00020126580014br.gov.bcb.pix0136316bd44f-2202-4c33-9dc0-096192acd427520400005303986540530.005802BR5925QI SOCIEDADE DE CREDITO D6009sao paulo610912345-78062070503***63048698",
"qr_code_type": "static"
}
```
:::caution Atenção
A requisição para pagar um PIX QR Code Estático é a mesma utilizada na transferência PIX com a as seguintes alterações:
**1** - Adição de um novo campo “***end_to_end_id***”. Deve ser informado o mesmo valor retornado da decodificação do QR Code Estático;
**2** - Informar no campo “***transaction_amount***“ o mesmo valor retornado no campo “qr_code_data.amount” da decodificação do QR Code Estático;
**3** - Alterar o campo “***pix_transfer_type***” para “***static***“, para solicitação do pagamento via “***/baas/pix_transfer***”.
:::
**Request**
- MÉTODO POST
- ENDPOINT /baas/pix_transfer
Request Body
```json
{
"pix_transfer_type": "static",
"source_account": {
"account_branch": "0001",
"account_digit": "2",
"account_number": "2359934",
"owner_document_number": "09080702000105"
},
"end_to_end_id": "E3240250220221118200949955075000",
"transaction_amount": 30,
"pix_key": "316bd44f-2202-4c33-9dc0-096192acd427",
"requester_document_identification": "09080702000105"
}
```
**Response**
- MÉTODO POST
- ENDPOINT /baas/pix_transfer
Response Body
```json
{
"data": {
"end_to_end_id": "E3240250220221118200949955075000",
"fee_amount": 1,
"pix_message": null,
"pix_transfer_key": "59a0da26-3223-4679-aa2c-020d46e923c1",
"source_account": {
"account_brach": "0001",
"account_digit": "2",
"account_number": "2359934",
"account_type": "checking",
"owner_document_number": "09080702000105",
"owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
},
"target_account": {
"document_number": "32402502000135",
"financial_institution": "QI SOCIEDADE DE CRÉDITO DIRETO S.A."
},
"transaction_amount": 30,
"transfer_purpose": "transfer"
},
"event_datetime": "2022-09-02 23:00:07",
"operation_key": "527f60a4-0118-4b90-adf8-d33f895c9f8f",
"status": "pending_approval"
}
```
Após realizar a segunda chamada no endpoint “**/baas/pix_transfer**”, é necessário solicitar o Token para aprovar a transação. Para aprovar a transferência PIX, é necessário utilizar a “**pix_transfer_key**” retornada na solicitação de transferência e solicitar a geração de um token que será enviado ao usuário administrador da conta para aprovação (“***allowed_user***”).
**Request**
- MÉTODO POST
- ENDPOINT /baas/token_request
Request Body
```json
{
"contact_type": "sms",
"agent_document_number": "97564480084",
"movement_payload": {
"pix_transfer_key": "59a0da26-3223-4679-aa2c-020d46e923c1",
"approver_document_number": "97564480084"
}
}
```
A última chamada para concluir o pagamento será a do “**/baas/movement_validation**” e o Token enviado deve ser informado no momento da aprovação da transferência PIX. A validade do Token é de 2 minutos.
O usuário administrador deve inserir na aplicação do parceiro o token recebido via E-mail ou SMS.
**Request**
- MÉTODO POST
- ENDPOINT /baas/movement_validation
Request Body
```json
{
"token": "957219",
"movement_payload": {
"pix_transfer_key": "59a0da26-3223-4679-aa2c-020d46e923c1",
"approver_document_number": "97564480084"
}
}
```
**Response**
- MÉTODO POST
- ENDPOINT /baas/movement_validation
Response Body
```json
{
"authentication_code": "4c579663bd3f369c4f5f5cd89d8e1a24",
"event_datetime": "2022-09-02 23:00:07",
"operation_key": "527f60a4-0118-4b90-adf8-d33f895c9f8f",
"pix_transaction": {
"end_to_end_id": "E3240250220221118200949955075000",
"fee_amount": 1,
"pix_message": null,
"pix_transfer_key": "59a0da26-3223-4679-aa2c-020d46e923c1",
"pix_transfer_status": "sent",
"pix_transfer_type": "static",
"source_account": {
"account_branch": "0001",
"account_digit": "2",
"account_number": "2359934"
},
"target_account": {
"document_number": "***.221.81*-**",
"financial_institution": "BANCO ORIGINAL S.A."
},
"transaction_key": "d5134c23-18d2-4279-bc99-459312b64bfc",
"transfer_amount": 30
},
"status": "sent"
}
```
:::info
A única diferença desta Response em relação a Response de Aprovação de Transferência PIX, é o valor do campo “***pix_transfer_type***“, que é retornado como sendo “***static***”.
:::
### 4.2. Pagando um QR Code PIX Dinâmico
Para realizar o pagamento de um QR Code PIX Dinâmico, é necessário realizar quatro chamadas:
1. Decodificar o QR Code PIX: /baas/pix/qrcode
2. Criação do pedido de transferência: /baas/pix_transfer
3. Solicitação de token de validação de transferência: /baas/token_request
4. Aprovação da transferência: /baas/movement_validation. A informação que deve ser utilizada para decodificação do QR Code PIX Dinâmico é a URI do PIX Copia e Cola vinculada
:::info
A única alteração no “***/baas/pix/qrcode***“ entre é QR Code PIX Estático e o QR Code PIX Dinâmico, é a resposta do endpoint.
:::
**Response**
- MÉTODO POST
- ENDPOINT /baas/pix/qrcode
Response Body
```json
{
"end_to_end_id": "E3240250220221120162904592385040",
"qr_code_data": {
"account_type": "checking",
"additional_data": [],
"address": "Avenida Brigadeiro Faria Lima",
"amount": 35,
"category_code": "0000",
"city": "Sao Paulo",
"created_at": "2022-09-01T20:20:11",
"days_after_due_accepted": 180,
"discount_amount": null,
"due_date": "2022-11-30",
"fee_amount": null,
"fine_amount": null,
"ispb_number": "32402502",
"original_amount": null,
"payer_document_number": "10932327656",
"payer_name": "Payer Name",
"payer_person_type": "natural",
"postal_code": "01452000",
"presented_at": "2022-09-01T16:29:04",
"question_to_payer": "QR Code Payment",
"receiver_conciliation_id": "a6c3f35b342047e58ac105a0ae0c0c6f",
"receiver_url": null,
"reduction_amount": null,
"reusable_qrcode": "yes",
"revision": 1,
"state": "SP",
"status": "active",
"target_account_branch": "0001",
"target_account_digit": "5",
"target_account_number": "2",
"target_bank_code": 329,
"target_bank_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
"target_document_number": "32402502000135",
"target_name": "QI SOCIEDADE DE CREDITO DIRETO S.A.",
"target_person_type": "legal",
"target_pix_key": "316bd44f-2202-4c33-9dc0-096192acd427",
"target_trading_name": null
},
"qr_code_key": "a1bcf9be-918d-431e-ae79-a75f78337423",
"qr_code_payload": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/a6c3f35b-3420-47e5-8ac1-05a0ae0c0c6f5204000053039865802BR5902QI6009Sao Paulo61080145200062070503***6304AFEE",
"qr_code_type": "dynamic_term"
}
```
:::caution Atenção
A requisição para pagar um PIX QR Code Dinâmico é a mesma utilizada na transferência PIX com a as seguintes alterações:
1 - Adição de um novo campo “end_to_end_id”. Deve ser informado o mesmo valor retornado da decodificação do QR Code Dinâmico.
2 - Informar no campo “transaction_amount“ o mesmo valor retornado no campo “qr_code_data.amount” da decodificação do QR Code Dinâmico;
3 - Alterar o campo “pix_transfer_type” para “dynamic_term“, para solicitação do pagamento via “/baas/pix_trasnfer”.
4 - Adição de um novo campo “receiver_conciliation_id”. Deve ser informado o mesmo valor retornado da decodificação do QR Code Dinâmico.
:::
**Request**
- MÉTODO POST
- ENDPOINT /baas/pix_transfer
Response Body
```json
{
"pix_transfer_type": "dynamic_term",
"source_account": {
"account_branch": "0001",
"account_digit": "2",
"account_number": "2359934",
"owner_document_number": "09080702000105"
},
"end_to_end_id": "E3240250220221120162904592385040",
"receiver_conciliation_id": "a6c3f35b342047e58ac105a0ae0c0c6f",
"transaction_amount": 35,
"requester_document_identification": "09080702000105"
}
```
**Response**
- MÉTODO POST
- ENDPOINT /baas/pix_transfer
Response Body
```json
{
"data": {
"end_to_end_id": "E3240250220221120162904592385040",
"fee_amount": 0,
"pix_message": null,
"pix_transfer_key": "8ddd3bce-5130-4b5b-b7f1-40f17547a413",
"source_account": {
"account_brach": "0001",
"account_digit": "2",
"account_number": "2359934",
"account_type": "checking",
"owner_document_number": "09080702000105",
"owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
},
"target_account": {
"document_number": "32402502000135",
"financial_institution": "QI SOCIEDADE DE CRÉDITO DIRETO S.A."
},
"transaction_amount": 35,
"transfer_purpose": "transfer"
},
"event_datetime": "2022-09-02 13:45:44",
"operation_key": "c697d8d8-4520-4285-b5ec-d573fb6c1eb3",
"status": "pending_approval"
}
```
Após realizar a segunda chamada no endpoint “***/baas/pix_transfer***”, é necessário solicitar o Token para aprovar a transação. Para aprovar a transferência PIX, é necessário utilizar a “***pix_transfer_key***” retornada na solicitação de transferência e solicitar a geração de um token que será enviado ao usuário administrador da conta para aprovação (“***allowed_user***”).
**Request**
- MÉTODO POST
- ENDPOINT /baas/token_request
Response Body
```json
{
"contact_type": "sms",
"agent_document_number": "97564480084",
"movement_payload": {
"pix_transfer_key": "8ddd3bce-5130-4b5b-b7f1-40f17547a413",
"approver_document_number": "97564480084"
}
}
```
A última chamada para concluir o pagamento será a do “***/baas/movement_validation***” e o Token enviado deve ser informado no momento da aprovação da transferência PIX. A validade do Token é de 2 minutos.
O usuário administrador deve inserir na aplicação do parceiro o token recebido via E-mail ou SMS.
**Request**
- MÉTODO POST
- ENDPOINT /baas/movement_validation
Response Body
```json
{
"token": "231564",
"movement_payload": {
"pix_transfer_key": "8ddd3bce-5130-4b5b-b7f1-40f17547a413",
"approver_document_number": "97564480084"
}
}
```
**Response**
- MÉTODO POST
- ENDPOINT /baas/movement_validation
Response Body
```json
{
"authentication_code": "936c01a20ebf73c6d474a14bc32553b0",
"event_datetime": "2022-09-02 23:00:07",
"operation_key": "c697d8d8-4520-4285-b5ec-d573fb6c1eb3",
"pix_transaction": {
"end_to_end_id": "E3240250220221120162904592385040",
"fee_amount": 1,
"pix_message": null,
"pix_transfer_key": "8ddd3bce-5130-4b5b-b7f1-40f17547a413",
"pix_transfer_status": "sent",
"pix_transfer_type": "dynamic_term",
"source_account": {
"account_branch": "0001",
"account_digit": "2",
"account_number": "2359934"
},
"target_account": {
"document_number": "***.221.81*-**",
"financial_institution": "BANCO ORIGINAL S.A."
},
"transaction_key": "96e063f4-b1fb-4f93-ae30-906029764a0a",
"transfer_amount": 35
},
"status": "sent"
}
```
:::info
A única diferença desta Response em relação a Response de Aprovação de Transferência PIX, é o valor do campo “***pix_transfer_type***“, que é retornado como sendo “***dynamic_term***”.
:::
## 5 - Gerenciar Chaves PIX
:::info
A “***pix_key***” pode ser um **CPF**, **CNPJ**, **E-mail**, **Celular** ou uma **Chave Aleatória** (UUID), seguindo as seguintes formatações:
**CPF:** Número inteiro com 11 dígitos.
**CNPJ:** Número inteiro com 14 dígitos.
**E-mail:** Texto contendo ao menos um “@”.
**Celular:** Texto contendo os seguintes valores: “+55” + “DDD do celular“ + “Número Inteiro do Celular com no mínimo 8 e no máximo 9 dígitos”. Ex: “+5511987654321“.
**Chave Aleatória:** UUID.
:::
### 5.1. Criar Chave PIX CPF, CNPJ ou Aleatória
Para criar uma chave PIX CNPJ ou Chave Aleatória, basta acionar o endpoint “***/baas/pix/keys***“, alterando apenas o “***pix_key_type***“ para “**cnpj**”, “**cpf**” ou “**random_key**”.
**Request**
- MÉTODO POST
- ENDPOINT /baas/pix/keys
Request Body
```json
{
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"pix_key_type": "random_key"
}
```
ou
Request Body
```json
{
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"pix_key_type": "cnpj",
"pix_key": "09080702000105"
}
```
ou
**payload.json**
```json
{
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"pix_key_type": "cpf",
"pix_key": "03882617038"
}
```
**Response**
- MÉTODO POST
- ENDPOINT /baas/pix/keys
Response Body
```json
{
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"created_at": "2022-09-02T18:20:52",
"pix_key": {
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"created_at": "2022-09-02T18:20:51",
"pix_key": "09080702000105",
"pix_key_status": "pending_confirmation",
"pix_key_type": "cnpj",
"updated_at": "2022-09-02T18:20:51"
},
"pix_key_request_key": "d60abf67-ad9c-42ee-9089-d26c8fc855b9",
"request_data": {
"account_created_at": "2022-09-02T22:44:36",
"account_digit": "2",
"account_number": "2359934",
"account_type": "checking",
"branch_number": "0001",
"key": "09080702000105",
"owner_document_number": "09080702000105",
"owner_name": "VOVO LUCIA CONVENIENCIA LTDA",
"owner_person_type": "legal",
"trading_name": "VOVO LUCIA"
},
"request_failure_reason": null,
"request_status": "pending",
"request_type": "inclusion",
"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
"updated_at": "2022-09-02T18:20:52"
}
```
:::caution Atenção
No caso da Response de criação de uma Chave PIX **Aleatória**, o campo “***pix_key***“ retornará um valor nulo, já que se trata de um
processo assíncrono onde a chave é gerada pelo Banco Central. Para recuperar o valor da chave aleatória gerada, é necessária realizar uma consulta à lista de chaves cadastradas em uma conta, conforme descrito no item “**Consultar Chaves PIX cadastradas em uma conta**, ou aguardar o webhook de inclusão.“.
:::
:::info
Como se trata de um processo assíncrono para verificar se as chave PIX **CNPJ** ou **CPF** estão ativas, é necessário realizar uma consulta à lista de chaves cadastradas em um conta, conforme descrito no item “**Consultar Chaves PIX cadastradas em uma conta**", ou aguardar o webhook de inclusão.
:::
**Webhook**
- WEBHOOK_TYPE key_inclusion
Response Body
```json
{
"pix_key": "c232142c-ddbf-41d6-a54f-3b90c28b97dc",
"account_key": "94945886-7a6f-43e6-a307-e36c959e4903",
"webhook_type": "key_inclusion",
"pix_key_status": "active",
"pix_key_request_key": "e274eb13-40b3-4902-978e-8e5fa267af53",
"pix_key_request_type": "inclusion",
"pix_key_request_status": "approved"
}
```
### 5.2. Criar Chave PIX E-mail e Celular
Para criar uma chave PIX **E-mail** ou **Celular** deve-se acionar dois endpoints:
**1 - Para criação da chave:** POST no endpoint “**/baas/pix/keys**“, alterando o campo “***pix_key_type***“ para “email” ou “phone_number”. Neste momento, será enviado um Token para o E-mail ou Celular informado no campo “***pix_key***“.
**2 - Para aprovação da chave:** PATCH no endpoint “**/baas/pix/keys/\ **“, informando o Token recebido na etapa anterior.
**Request**
- MÉTODO POST
- ENDPOINT /baas/pix/keys
Request Body
```json
{
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"pix_key_type": "email",
"pix_key": "vovo.lucia@gmail.com.br"
}
```
ou
Request Body
```json
{
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"pix_key_type": "phone_number",
"pix_key": "+5511987654321"
}
```
**Response**
- MÉTODO POST
- ENDPOINT /baas/pix/keys
Response Body
```json
{
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"created_at": "2022-09-02T17:41:55",
"pix_key": {
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"created_at": "2022-09-02T17:41:54",
"pix_key": "pedro.pinho@qitech.com.br",
"pix_key_status": "pending_confirmation",
"pix_key_type": "email",
"updated_at": "2022-09-02T17:41:54"
},
"pix_key_request_key": "f6209b7e-82da-44a8-9cfa-6ad0a689adb2",
"request_data": {
"account_created_at": "2022-09-02T22:44:36",
"account_digit": "2",
"account_number": "2359934",
"account_type": "checking",
"branch_number": "0001",
"key": "pedro.pinho@qitech.com.br",
"owner_document_number": "09080702000105",
"owner_name": "VOVO LUCIA CONVENIENCIA LTDA",
"owner_person_type": "legal",
"trading_name": "VOVO LUCIA"
},
"request_failure_reason": null,
"request_status": "pending",
"request_type": "inclusion",
"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
"updated_at": "2022-09-02T17:41:55"
}
```
**IMPORTANTE:** O valor retornado no campo “pix_key_request_key“ deve ser utilizado na URL da requisição para aprovação da criação da Chave PIX.
### 5.3. Aprovação da Chave PIX E-mail ou Celular solicitada
**Request**
- MÉTODO PATCH
- ENDPOINT /baas/pix/keys/ PIX_KEY_REQUEST_KEY /twofa_validation
Request Body
```json
{
"verification_code": "756816"
}
```
### 5.4. Reenviar o código de verificação
**Request**
- MÉTODO PATCH
- ENDPOINT /baas/pix/keys/ PIX_KEY_REQUEST_KEY /resend_twofa
**payload.json**
```json
{}
```
### 5.5. Consultar Chaves PIX cadastradas em uma conta
**Request**
- MÉTODO GET
- ENDPOINT /baas/pix/keys
- PARAMETERS account_key
***Response***
Response Body
```json
{
"data": [
{
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"created_at": "2022-09-02T17:17:31",
"pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
"pix_key_status": "active",
"pix_key_type": "random_key",
"updated_at": "2022-09-02T17:17:31"
},
{
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"created_at": "2022-09-02T18:20:51",
"pix_key": "09080702000105",
"pix_key_status": "active",
"pix_key_type": "cnpj",
"updated_at": "2022-09-02T18:20:51"
}
]
}
```
### 5.6. Exclusão de Chaves PIX
**Request**
- MÉTODO DELETE
- ENDPOINT /baas/pix/keys/PIX-KEY
Payload: { }
**Response**
Response Body
```json
{
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"created_at": "2022-09-02T20:00:36",
"pix_key": {
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"created_at": "2022-09-02T18:20:51",
"pix_key": "09080702000105",
"pix_key_status": "inactivated",
"pix_key_type": "cnpj",
"updated_at": "2022-09-02T20:00:36"
},
"pix_key_request_key": "dced4317-c1e7-4da4-a75a-42f855c7598e",
"request_data": {},
"request_failure_reason": null,
"request_status": "approved",
"request_type": "deletion",
"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
"updated_at": "2022-09-02T20:00:36"
}
```
## 6 - Gerar QR Code PIX
### 6.1. Gerando QR Code PIX Estático
O QR Code é criado a partir de uma Chave PIX ativa cadastrada em uma conta. Após a geração do QR Code, serão retornados tanto a URI do PIX Copia e Cola vinculada ao QR Code, como também o base64 da imagem do QR Code (caso solicitado).
A imagem do QR Code pode ser gerada pelo próprio parceiro a partir da URI do PIX Copia e Cola.
Para gerar um QR Code PIX Estático será usada apenas uma requisição:
**Request**
- MÉTODO POST
- ENDPOINT /baas/qrcode/static
Request Body
```json
{
"pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
"amount": 35.00,
"receiver_name": "Tywin Lannister",
"qr_code_format": "both"
}
```
:::info
No campo **qr_code_format** poderá ser informado os valores “***image***”, “***payload***“ e “***both***”.
- “***image***”: será retornado o campo com o base64 da imagem do QR Code PIX.
- “***payload***”: será retornado o campo com o base64 da URI do PIX Copia e Cola do QR Code PIX.
- “***both***”: serão retornados os dois campos.
:::
**Response**
- MÉTODO POST
- ENDPOINT /baas/qrcode/static
Response Body
```json
{
"external_reference_key": null,
"image": "\",
"payload": "MDAwMjAxMjY0NzAwMTRici5nb3YuYmNiLnBpeDAxMjVwZWRyby5waW5ob0BxaXRlY2guY29tLmJyNTIwNDAwMDA1MzAzOTg2NTQwNTM1LjAwNTgwMkJSNTkxNVR5d2luIExhbm5pc3RlcjYwMDlzYW8gcGF1bG82MTA5MTIzNDUtNzgwNjIwNzA1MDMqKio2MzA0M0QzMA",
"revision": null
}
```
### 6.2. Gerando QR Code PIX Dinâmico
Existem dois tipos de QR Code Dinâmico. O QR Code Dinâmico com Pagamento Instantâneo e o QR Code Dinâmico com Vencimento.
#### 6.2.1. Gerando QR Code PIX Dinâmico com Vencimento
É um tipo de QR Code PIX que funciona de forma muito semelhante a um boleto bancário, podendo possuir informação de vencimento, multa, juros por atraso e desconto por pagamento antecipado. Para gerar ester tipo de QR Code PIX é necessário apenas uma requisição no Endpoint “***/baas/qrcode/dynamic***“.
**Request**
- MÉTODO POST
- ENDPOINT /baas/qrcode/dynamic
Request Body
```json
{
"amount": 100,
"qr_code_type": "dynamic_term",
"occurrence_type": "registration",
"max_payment_days": 180,
"expiration_date": "2025-09-24",
"pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
"payer_name": "QI Tech",
"payer_document_number": "98765432100",
"payer_person_type": "natural",
"payer_request": "O que voce achou da experiencia",
"rebate_amount": 0,
"interest_amount": 1,
"fine_amount": 2,
"discounts": [{
"limit_date": "2023-02-24",
"amount": 20,
"discount_type": "absolute"
}],
"additional_data": [{
"\": "\"
}]
}
```
:::info
**occurrence_type:** neste campo é informada a ação pretendida. Podem ser: registration, edit, write_off
- **registration:** Para criar um novo QR Code
- **edit:** Para editar um QR Code já existente (Conforme descrito no item abaixo).
- **write_off:** para baixar um QR Code ativo.
**interest_amount:** valor em reais (R$) de juros cobrados por dia de atraso.
**fine_amount:** valor da multa por atraso, em reais (R$).
**discounts:** informação do desconto por pagamento antecipado. Caso não seja aplicável, enviar uma lista vazia ([]).
**additional_data:** são metatags customizáveis que podem ser apresentadas para o pagador no momento do pagamento. Seguem o seguinte padrão: ”\ ”: “\ “.
**tag_name** possui uma limitação de 100 caracteres e **tag_value** possui uma limitação de 320 caracteres.
:::
**Response**
- MÉTODO POST
- ENDPOINT /baas/qrcode/dynamic
Response Body
```json
{
"qr_code_type": "dynamic_term",
"amount": 100,
"expiration_seconds": null,
"max_payment_days": 180,
"receiver_conciliation_id": "3bd19ada234141bf9f1fc5ce0b216723",
"payer_name": "QI Tech",
"payer_document_number": "98765432100",
"payer_person_type": "natural",
"payer_request": "O que voce achou da experiencia",
"pix_message": null,
"modality_alteration": false,
"expiration_date": "2025-09-24",
"rebate_amount": 10,
"interest_amount": 10,
"fine_amount": 10,
"paid_amount": null,
"discounts": [{
"discount_type": "absolute",
"limit_date": "2023-02-24",
"amount": 20
}],
"additional_data": [{
"\": "\"
}],
"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
O campo “**base_64**“ é a URI do PIX Copia e Cola vinculado a este QR Code PIX Dinâmico.
:::
#### 6.2.2. Gerando QR Code PIX Dinâmico com Pagamento Instantâneo
É um tipo de QR Code PIX semelhante ao Estático, porém facilita a conciliação por parte do recebedor do pagamento e pode ter vencimento intradia (podendo durar apenas 5 minutos, por exemplo).
Para gerar este tipo de QR Code PIX é necessário apenas uma requisição no Endpoint ***“/baas/qrcode/dynamic”***.
**Request**
- MÉTODO POST
- ENDPOINT /baas/qrcode/dynamic
Request Body
```json
{
"amount": 100,
"occurrence_type": "registration",
"qr_code_type": "dynamic_instant",
"pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
"expiration_seconds": 360,
"payer_name": "QI Tech",
"payer_document_number": "98765432100",
"payer_person_type": "natural",
"payer_request": "Valor referente a compra 1234",
"additional_data": [{
"\": "\"
}]
}
```
**Response**
- MÉTODO POST
- ENDPOINT /baas/qrcode/dynamic
Response Body
```json
{
"qr_code_type": "dynamic_instant",
"amount": 100,
"expiration_seconds": 360,
"max_payment_days": null,
"receiver_conciliation_id": "8e5af204fa5844eca9707c4facc5e5f5",
"payer_name": "QI Tech",
"payer_document_number": "98765432100",
"payer_person_type": "natural",
"payer_request": "Valor referente a compra 1234",
"pix_message": null,
"modality_alteration": false,
"expiration_date": null,
"rebate_amount": null,
"interest_amount": null,
"fine_amount": null,
"paid_amount": null,
"discounts": [],
"additional_data": [{
"\": "\"
}],
"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. Editar dados de QR Code PIX Dinâmico
Para editar os dados de um QR Code PIX Dinâmico, é necessário informar a “***qr_code_key***“ do QR Code PIX e “***occurrence_type***” igual a “***edit***”. Nesse caso, é preciso reenviar todos os dados novamente.
**Request**
- MÉTODO POST
- ENDPOINT /baas/qrcode/dynamic
Request Body
```json
{
"qr_code_key": "3bd19ada-2341-41bf-9f1f-c5ce0b216723",
"amount": 200,
"qr_code_type": "dynamic_term",
"occurrence_type": "edit",
"max_payment_days": 180,
"expiration_date": "2025-09-24",
"pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
"payer_name": "QI Tech",
"payer_document_number": "98765432100",
"payer_person_type": "natural",
"payer_request": "O que voce achou da experiencia",
"rebate_amount": 0,
"interest_amount": 1,
"fine_amount": 2,
"discounts": [{
"limit_date": "2023-02-24",
"amount": 20,
"discount_type": "absolute"
}],
"additional_data": [{
"\": "\"
}]
}
```
**Request**
- MÉTODO POST
- ENDPOINT /baas/qrcode/dynamic
Response Body
```json
{
"qr_code_type": "dynamic_term",
"amount": 200,
"expiration_seconds": null,
"max_payment_days": 180,
"receiver_conciliation_id": "3bd19ada234141bf9f1fc5ce0b216723",
"payer_name": "QI Tech",
"payer_document_number": "98765432100",
"payer_person_type": "natural",
"payer_request": "O que voce achou da experiencia",
"pix_message": null,
"modality_alteration": false,
"expiration_date": "2025-09-24",
"rebate_amount": 10,
"interest_amount": 10,
"fine_amount": 10,
"paid_amount": null,
"discounts": [{
"discount_type": "absolute",
"limit_date": "2023-02-24",
"amount": 20
}],
"additional_data": [{
"\": "\"
}],
"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. Baixar QR Code PIX Dinâmico
Para baixar um QR Code PIX Dinâmico, é necessário informar a “***qr_code_key***“ do QR Code PIX e “***occurrence_type***” igual a “***write_off***”.
**Request**
- MÉTODO POST
- ENDPOINT /baas/qrcode/dynamic
Request Body
```json
{
"qr_code_key": "3bd19ada-2341-41bf-9f1f-c5ce0b216723",
"occurrence_type": "write_off"
}
```
**Response**
- MÉTODO POST
- ENDPOINT /baas/qrcode/dynamic
Response Body
```json
{
"qr_code_type": "dynamic_term",
"amount": null,
"expiration_seconds": 86400,
"max_payment_days": null,
"receiver_conciliation_id": "3bd19ada234141bf9f1fc5ce0b216723",
"payer_name": null,
"payer_document_number": null,
"payer_person_type": "natural",
"payer_request": null,
"pix_message": null,
"modality_alteration": false,
"expiration_date": null,
"rebate_amount": null,
"interest_amount": null,
"fine_amount": null,
"paid_amount": null,
"discounts": [],
"additional_data": [],
"origin": "system",
"origin_key": null,
"pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
"qr_code_key": "3bd19ada-2341-41bf-9f1f-c5ce0b216723",
"occurrence_type": "write_off",
"end_to_end_id": null,
"base_64": null,
"image": null,
"source_account_branch": null,
"source_account_financial_institution": null,
"source_account_ispb": null,
"source_account_number": null,
"source_account_digit": null,
"qr_code_occurrence_key": "46001adf-ffe2-4534-b60e-f6c16b9af56e"
}
```
## 7 - Registrar, Alterar e Pagar boletos bancários
### 7.1. Consulta de Carteiras de Cobrança
Para registrar, alterar e pagar boletos, é preciso, primeiramente, possuir o Código da Carteira de Cobrança (Requester Profile Code) vinculada a uma conta. Toda conta já nasce com uma Carteira de Cobrança vinculada.
O Código da Carteira de Cobrança segue o seguinte padrão:
”No. do banco” + “código da carteira” + “No. agência da conta” + “No. da Conta com 7 caracteres e sem dígito“.
Por padrão, na QI Tech, os números do banco, do código da carteira e agência sempre serão “329”, “09” e “0001”, respectivamente.
ex: “**329-09-0001-2359934**”.
Caso seja necessário recuperar a lista de Códigos de Carteira de Cobrança de cada conta, deve ser utilizado o seguinte endpoint:
**Request**
- MÉTODO GET
- ENDPOINT /bank_slip/requester_profiles
***Response***
Response Body
```json
{
"requester_profile_codes": [
"329-09-0001-1467576",
"329-09-0001-5747500",
"329-09-0001-2730579",
"329-09-0001-2359934"
]
}
```
:::tip NOTA
O registro, alteração e baixa de boletos, funciona através da dinâmica de ocorrências. Cada ocorrência é enviada para a QI Tech e encaminhada para a base centralizadora de boletos.
As ocorrências podem ser aceitas ou rejeitadas pelo base centralizadora de boletos.
A resposta a respeito da aceitação ou rejeição das ocorrências é enviada via webhook ao parceiro
:::
### 7.2. Registrar Boleto
Para realizar o registro de um boleto, é necessário enviar uma ocorrência de registro, conforme descrito no endpoint abaixo:
**Request**
- MÉTODO POST
- ENDPOINT /multibank_instruction?use_multi_process=true
Request Body
```json
{
"occurrences": [
{
"amount": 800,
"our_number": 1,
"automatic_bankruptcy_protest": false,
"bank_teller_instructions": "Não aceitar após vencimento",
"days_to_bankruptcy_protest": 0,
"document_number": "123456/01",
"expiration": "2022-12-01",
"fine_percentage": "2",
"interest_daily_value": "0.34",
"occurrence_type": "registration",
"payer_address": "Rua Carlos Sampaio, 123",
"payer_document": "41184562067",
"payer_name": "João Ninguem",
"payer_person_type": "natural",
"payer_postal_code_root": "15800",
"payer_postal_code_suffix": "020",
"registration_institution_enumerator": "qi_scd",
"requester_profile": 9,
"requester_profile_code": "329-09-0001-2359934"
}
]
}
```
:::info
O nosso número bancário (“***our_number***”) é o ID do boleto dentro da carteira de cobrança. Ele deve ser um ID incremental.
O nosso número bancário (“***our_number”) deve ser gerado pelo parceiro e informado no momento do registro do boleto.
**IMPORTANTE:** O boleto deve ser localizado através da chave: nosso número bancário (“***our_number***”) + Código da Carteira de Cobrança (“***requester_profile_code***“).
:::
**Response**
- MÉTODO POST
- ENDPOINT /multibank_instruction?use_multi_process=true
Response Body
```json
{
"file_info": {
"beneficiary_code": null,
"beneficiary_name": null,
"file_sequence_id": null,
"file_type_identifier": null,
"file_type_literal": null,
"service_code": null,
"service_literal": null,
"wrote_at": null
},
"occurrence_stats": {
"bank_slip_edit": 0,
"bankruptcy_protest_request": 0,
"cancel_rebate": 0,
"extension": 0,
"notary_office_entry": 0,
"notary_office_exit": 0,
"notary_office_payment": 0,
"notification": 0,
"payment": 0,
"payment_notice": 0,
"payment_write_off": 0,
"protest_cancel_and_write_off_request": 0,
"protest_cancel_request": 0,
"protest_remove_request": 0,
"protest_request": 0,
"rebate": 0,
"registration": 1,
"write_off": 0
},
"semantic_errors": []
}
```
A resposta sobre a aceitação ou rejeição do registro do boleto será informada através do seguinte webhook.
**Webhook**
- WEBHOOK_TYPE bank_slip.status_change
- STATUS registered
Response Body
```json
{
"key": "41927fa9-f9ed-4797-b48a-6ac68e58dc17",
"data": {
"expiration": "2022-12-01",
"our_number": 1,
"bank_slip_key": "41927fa9-f9ed-4797-b48a-6ac68e58dc17",
"rebate_amount": 0,
"occurrence_type": "registration",
"occurrence_feedback": "confirmed",
"occurrence_sequence": 0,
"requester_profile_code": "329-09-0001-2359934",
"glados_occurrence_reasons": null,
"cnab_file_occurrence_order": 1,
"registration_institution_occurrence_date": "2022-11-21"
},
"status": "registered",
"webhook_type": "bank_slip.status_change",
"event_datetime": "2022-11-22 00:41:32"
}
```
Para vincular o webhook enviado a um boleto, deve-se utilizar o nosso número bancário (“***our_number***”) e o Código da Carteira de Cobrança (“requester_profile_code“).
Assim que o registro do boleto é aceito pela base centralizadora, é retornado no webhook a chave UUID do boleto (“***bank_slip_key***“). Guarde essa chave pois através dela será possível recuperar as informações do boleto.
### 7.2. Alterar Dados do Boleto
Para alterar os dados de um boleto, é necessário enviar uma ocorrência. Cada possível alteração possui sua ocorrência correspondente. A lista de ocorrências para alteração dos dados de um boleto pode ser verificada em nossa documentação Enviar instrução de Boleto[LINK]).
### 7.3. Solicitação de 2ª via de boleto
Após o registro do boleto, pode ser solicitada a geração de um arquivo “.pdf” do boleto, contendo os dados para pagamento.
**Request**
- MÉTODO POST
- ENDPOINT /bank_slip/2-way/BANKSLIP-KEY
Payload: { }
**Response**
Response Body
```json
{
...
"bank_slip_file": [{
"barcode": "32991918600000800000001090000000000123599340",
"created_at": "2022-11-21T23:29:45",
"digitable_line": "32990001039000000000101235993407191860000080000",
"url": "https://storage.googleapis.com/sandbox-bank-slip-api/bank-slip-pdf/41927fa9-f9ed-4797-b48a-6ac68e58dc17_1.pdf"
}],
...
}
```
:::info
Serão retornados todos os dados do boleto e o link para download do “.pdf” será informado no objeto “bank_slip_file.url“.
:::
### 7.4. Consultar dados de um Boleto
Os dados de um boleto podem ser consultados de duas formas diferentes.
#### 7.4.1. Consulta através da linha digitável
A linha digitável de um boleto é uma série numérica que traz em si as informações do boleto. Esta série numérica é digitada pelo usuário pagador do boleto no internet-banking do banco pagador.
:::info
Exemplo de linha digitável: 32990001031000000000902000000204685640000100000
:::
Através da linha digitável, podem ser consultados os dados do boleto:
**Request**
- MÉTODO GET
- ENDPOINT /bank_slip/payment
- PARAMETERS digitable_line
**Response**
Response Body
```json
{
"barcode": "32991918600000800000001090000000000123599340",
"beneficiary_bank_code": "329",
"beneficiary_document_number": "09080702000105",
"beneficiary_legal_name": "VOVO LUCIA CONVENIENCIA LTDA",
"beneficiary_person_type": "legal",
"calculated_internally": true,
"calculation_date": "2022-11-21",
"calculation_model": 1,
"digitable_line": "32990001039000000000101235993407191860000080000",
"discount_amount": "0",
"expiration_date": "2022-12-01",
"expired_as_of_payment_date": false,
"expired_as_of_today": false,
"factual_expiration_date": "2022-12-01",
"fine_amount": "0",
"guarantor_document": null,
"guarantor_name": null,
"interest_amount": "0",
"max_payment_date": "2023-05-30",
"nominal_amount": "800.00",
"payer_document_number": "41184562067",
"payer_legal_name": "Jo_o Ninguem",
"payer_person_type": "natural",
"payment_date": "2022-11-21",
"rebate_amount": "0.0",
"total_amount": "800.0",
"valid_payment_amount": true,
"valid_payment_calculation": true,
"valid_payment_time_frame": true
}
```
#### 7.4.2. Consulta através da Chave do Boleto
Assim que o registro do boleto é aceito pela base centralizadora, é retornado no webhook a chave UUID do boleto (“***bank_slip_key***“). Através dessa chave é possível recuperar as informações do boleto:
**Request**
- MÉTODO GET
- ENDPOINT /bank_slip/BANKSLIP-KEY
Request Body
```json
{
"barcode": "32991918600000800000001090000000000123599340",
"beneficiary_bank_code": "329",
"beneficiary_document_number": "09080702000105",
"beneficiary_legal_name": "VOVO LUCIA CONVENIENCIA LTDA",
"beneficiary_person_type": "legal",
"calculated_internally": true,
"calculation_date": "2022-11-21",
"calculation_model": 1,
"digitable_line": "32990001039000000000101235993407191860000080000",
"discount_amount": "0",
"expiration_date": "2022-12-01",
"expired_as_of_payment_date": false,
"expired_as_of_today": false,
"factual_expiration_date": "2022-12-01",
"fine_amount": "0",
"guarantor_document": null,
"guarantor_name": null,
"interest_amount": "0",
"max_payment_date": "2023-05-30",
"nominal_amount": "800.00",
"payer_document_number": "41184562067",
"payer_legal_name": "Jo_o Ninguem",
"payer_person_type": "natural",
"payment_date": "2022-11-21",
"rebate_amount": "0.0",
"total_amount": "800.0",
"valid_payment_amount": true,
"valid_payment_calculation": true,
"valid_payment_time_frame": true
}
```
### 7.5. Pagar Boleto
Para realizar o pagamento de um Boleto é necessário realizar duas chamadas:
1. Solicitação de token de validação de transferência: /baas/token_request
2. Aprovação da transferência: /baas/movement_validation
**Request**
- MÉTODO POST
- ENDPOINT /baas/token_request
Request Body
```json
{
"contact_type": "email",
"agent_document_number": "97564480084",
"movement_payload": {
"resource_account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"digitable_line": "32990001031000699926165000000201993810000003500"
}
}
```
:::info
O Token enviado deve ser informado no momento da aprovação do pagamento do boleto, e o “***movement_payload***” deve ser o mesmo informado no momento da solicitação do Token.
:::
**Request**
- MÉTODO POST
- ENDPOINT /baas/movement_validation
Request Body
```json
{
"token": "358192",
"movement_payload": {
"resource_account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"digitable_line": "32990001031000699926165000000201993810000003500"
}
}
```
**Response**
- MÉTODO POST
- ENDPOINT /baas/movement_validation
Response Body
```json
{
"authentication_code": "7bf20f1721ecc043d2a16a20ae668b01",
"bank_slip": {
"beneficiary": {
"document_number": "32402502000135",
"document_number_formatted": "32.402.502/0001-35",
"name": "QI SCD"
},
"digitable_line": "32990001031000699926165000000201993810000003500",
"expiration_date": "2023-06-14",
"expiration_date_formatted": "14/06/2023",
"financial_institution_compe_number": "329",
"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
"payer": {
"document_number": "10932327656",
"document_number_formatted": "109.323.276-56",
"name": "Lucas Clarim"
},
"payment_date": "2022-11-22",
"payment_date_formatted": "22/11/2022",
"payment_key": "13b35108-0fdc-44ab-b86d-5dda12dc8dce"
},
"origin_key": "13b35108-0fdc-44ab-b86d-5dda12dc8dce",
"pdf_encoded_string": "\",
"source_account": {
"account_branch": "0001",
"account_digit": "2",
"account_number": "2359934",
"financial_institution_compe_number": 329,
"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
"owner_document_number": "09080702000105",
"owner_document_number_formatted": "09.080.702/0001-05",
"owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
},
"source_subtype": "bank_slip_payment",
"source_subtype_translation_ptbr": "Pagamento de Boleto",
"transacted_at": "2022-11-22 12:26:21",
"transacted_at_br": "2022-11-22 09:26:21",
"transacted_at_br_formatted": "22/11/2022, 09:26:21",
"transacted_at_formatted": "22/11/2022, 12:26:21",
"transaction_amount": 35,
"transaction_amount_formatted": "R$ 35,00",
"transaction_key": "eee862b9-7f2e-4eea-b04a-fa0e89442618"
}
```
### 7.6. Notificação de aviso de recebimento de um Boleto
No momento em que um boleto é pago em outro banco, é enviado um aviso de que este boleto foi pago em tempo real. A Liquidação financeira do pagamento ocorrerá no próximo dia útil.
**Webhook**
- WEBHOOK_TYPE bank_slip.status_change
- STATUS payment_notice
Response Body
```json
{
"key": "945e191d-1a78-4a28-8669-000b7e4a3522",
"data": {
"our_number": 1,
"paid_amount": 800,
"payment_bank": 341,
"bank_slip_key": "41927fa9-f9ed-4797-b48a-6ac68e58dc17",
"payment_method": 2,
"payment_origin": 3,
"occurrence_type": "payment_notice",
"occurrence_feedback": "confirmed",
"occurrence_sequence": 0,
"requester_profile_code": "329-09-0001-2359934",
"registration_institution": "qi_scd",
"cnab_file_occurrence_order": 1,
"registration_institution_occurrence_date": "2022-11-02"
},
"status": "payment_notice",
"webhook_type": "bank_slip.status_change",
"event_datetime": "2022-11-21 23:02:02"
}
```
:::info
**payment_method:** é o meio de pagamento do boleto, podendo ser:
**“credit_card”:** cartão de crédito
**”cash”:** dinheiro
**”account_debit”:** débito em conta
**”check”:** cheque
:::
:::info
**payment_origin:** é a origem do local do pagamento do boleto, podendo ser:
**“internet”:** Internet Banking
**”phisical_cashier”:** Caixa do Banco (“boca do caixa”)
**”taa”:** Terminal de auto-atendimento
**”eletronic_file”:** CNAB de liquidação
**”call_center”:** Call Center
**”dda”:** DDA (Débito Direto Autorizado)
**”corban”:** Lotérica - Correspondente Bancário
:::
:::caution Atenção
A informação de Método de Pagamento (“***payment_method***“) e Origem do Pagamento (“***payment_origin***“), são dados informados no momento do pagamento do boleto, sua consistência e veracidade fica a cargo da instituição que processou tal pagamento.
:::
## 8 - Movimentações, Comprovantes e Extratos
:::info
Esse manual contém a estrutura/informações dos nossos produtos de Banking as a Service, porém também cabe a utilização como forma documentação de nossos endpoints.
:::
### 8.1. Movimentações
Para toda e qualquer movimentação será enviado um webhook de “***account_transaction***“.
Cada transação possui um tipo de classificação (**Source Sub Type**). Essa classificação é utilizada para categorizar cada movimentação na conta. A lista de Source Sub Types pode ser vista no **Anexo I** deste manual.
Os créditos em conta resultarão em um webhook com “***data.amount***” positivo, “***data.origin***“ sendo a conta de origem dos recursos e a “***data.destination***“ sendo a conta de destino dos recursos:
**Webhook**
- WEBHOOK_TYPE account_transaction
Response Body: Pix
```json
{
"key": "\",
"data": {
"amount": 1000000,
"origin": {
"name": "Treasury Account",
"branch": "0001",
"document": "32402502000135",
"account_key": "5d068423-6094-49e4-b15b-7740038295a8",
"account_digit": "5",
"account_number": "00002"
},
"timestamp": "2022-09-02T21:36:33.446120",
"description": "329 0001 00002-5 32.402.502/0001-35 - QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
"destination": {
"name": "Default",
"branch": "0001",
"document": "09080702000105",
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"account_digit": "2",
"account_number": "2359934"
},
"reference_key": "983b4a28-7de6-4e71-97ef-60fb50c7b013",
"reference_type": "movement_request",
"account_balance": 1000000,
"source_sub_type": "internal_funds_transfer",
"transaction_key": "67a62397-2c32-4768-8485-ec9129a46654",
"source_sub_type_str": "Transferência Interna",
"transaction_details": {
"payer_name": "0001",
"receiver_name": "Default",
"payer_account_digit": "5",
"payer_account_branch": "",
"payer_account_number": "1111111",
"payer_document_number": "66681638999999",
"receiver_account_digit": "6",
"receiver_account_branch": "0000",
"receiver_account_number": "34256449809",
"receiver_conciliation_id": null,
"receiver_document_number": "00809641658"
}
},
"datetime": "2022-09-02T21:36:33.446120",
"webhook_type": "account_transaction"
}
```
Response Body: Outras transações
```json
{
"key": "\",
"data": {
"amount": 1000000,
"origin": {
"name": "Treasury Account",
"branch": "0001",
"document": "32402502000135",
"account_key": "5d068423-6094-49e4-b15b-7740038295a8",
"account_digit": "5",
"account_number": "00002"
},
"timestamp": "2022-09-02T21:36:33.446120",
"description": "329 0001 00002-5 32.402.502/0001-35 - QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
"destination": {
"name": "Default",
"branch": "0001",
"document": "09080702000105",
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"account_digit": "2",
"account_number": "2359934"
},
"reference_key": "983b4a28-7de6-4e71-97ef-60fb50c7b013",
"reference_type": "movement_request",
"account_balance": 1000000,
"source_sub_type": "internal_funds_transfer",
"transaction_key": "67a62397-2c32-4768-8485-ec9129a46654",
"source_sub_type_str": "Transferência Interna",
},
"datetime": "2022-09-02T21:36:33.446120",
"webhook_type": "account_transaction"
}
```
Os débitos em conta resultarão em um webhook com “***data.amount***” negativo, “***data.origin***“ sendo a conta destinatária dos recursos e a “***data.destination***“ sendo a conta de origem dos recursos:
**Webhook**
- WEBHOOK_TYPE account_transaction
Response Body
```json
{
"key": "\",
"data": {
"amount": -45,
"origin": {
"name": "PIX",
"branch": "0001",
"document": "32402502000135",
"account_key": "3d0e7d50-e898-49f3-b23b-05353c8a3c72",
"account_digit": "3",
"account_number": "00003"
},
"timestamp": "2022-09-02T23:00:05.326738",
"description": "212 0001 1017372-2 ***.221.81*-** BANCO ORIGINAL S.A.",
"destination": {
"name": "Default",
"branch": "0001",
"document": "09080702000105",
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"account_digit": "2",
"account_number": "2359934"
},
"reference_key": "cea836b5-b02e-4f94-b1e2-4d575671c33d",
"reference_type": "pix_outgoing",
"account_balance": 999955,
"source_sub_type": "pix_withdrawal",
"transaction_key": "d2ba3817-26d7-4957-ab82-24f78d910a8a",
"source_sub_type_str": "Transferência de PIX"
},
"datetime": "2022-09-02T23:00:05.326738",
"webhook_type": "account_transaction"
}
```
**Lista de source_sub_types’s:**
| Enum | Descrição |
|-----------------------------------------|-------------------------------------------------|
| operation_disbursement | Desembolso da Operação |
| protest_expense | Despesas de Protesto |
| automatic_integrated_payment | Pagamento Automático Integrado |
| tax | Impostos |
| electronic_funds_fee | Tarifa de TED |
| credit_operation_fee | Tarifa de Abertura de Crédito |
| internal_funds_transfer | Transferência Interna |
| incoming_funds_transfer | Transferência de Entrada |
| outgoing_funds_transfer | TED |
| deposit | Depósito |
| withdrawal | Transferência |
| withdrawal_reversal | Estorno de Transferência |
| trade_funds_transfer | Transferência de Pagamento de Cessão |
| settlement_funds_transfer | Transferência para Liquidação |
| bank_slip_fee | Tarifa de Boleto |
| bank_slip_settlement | Liquidação de Boleto |
| outgoing_funds_transfer_reversal | Estorno de TED |
| incoming_funds_transfer_refusal | Transferência Negada |
| electronic_funds_fee_reversal | Estorno de Tarifa de TED |
| monthly_account_fee_reversal | Estorno de Tarifa de Manutenção de Conta |
| bank_slip_fee_reversal | Estorno de Tarifa de Boleto |
| correspondent_bank_transfer | Repasse de Correspondente Bancário |
| credit_analysis_fee | Tarifa de Análise de Crédito |
| credit_operation_fee_reversal | Estorno de Tarifa de Abertura de Crédito |
| financial_investments_income | Renda de Aplicação Financeira |
| bank_slip_settlement_reversal | Estorno de Liquidação de Boleto |
| bank_slip_settlement_expense_reversal | Estorno de Tarifa de liquidação de Boleto |
| bank_slip_settlement_incoming_reversal | Estorno de Recebimento de Liquidação de Boleto |
| correspondent_bank_transfer_reversal | Estrono de Repasse de Correspondente Bancário |
| credit_analysis_fee_reversal | Estorno de Tarifa de Análise de Crédito |
| doc_expense_reversal | Estorno de Tarifa de DOC |
| incoming_doc_reversal | Estorno de Entrada de DOC |
| operation_disbursement_reversal | Estorno de Desembolso da Operação |
| operation_settling_reversal | Estorno de Pagamento de Operação |
| outgoing_doc_reversal | Estorno de Saída de DOC |
| rebate_reversal | Estorno de Rebate |
| settlement_funds_transfer_reversal | Estorno de Transferência para Liquidação |
| tax_reversal | Estorno de Impostos |
| trade_funds_transfer_reversal | Estorno de Transferência de Pagamento de Cessão |
| bank_slip_permanency_fee | Tarifa de Permanência do Título |
| bank_slip_cancel_protest_fee | Tarifa de Permanência do Título |
| bank_slip_protest_fee | Tarifa de Pedido de Protesto |
| bank_slip_notary_office_fee | Custas de Protesto |
| bank_slip_registration_fee | Tarifa de Registro |
| bank_slip_extension_fee | Tarifa de Prorrogação |
| bank_slip_rebate_fee | Tarifa de Abatimento |
| bank_slip_discount_fee | Tarifa de Desconto |
| bank_slip_settlement_fee | Tarifa de Liquidação |
| bank_slip_write_off_term_fee | Tarifa de Baixa por Decurso de Prazo |
| bank_slip_write_off_fee | Tarifa de Baixa |
| bank_slip_cancel_protest_write_off_fee | Tarifa de Sustação de Protesto com Baixa |
| bank_slip_notary_office_settlement_fee | Tarifa de Liquidação em Cartório |
| rebate_tax_free | Repasse por Conta e Ordem |
| rebate_tax_free_reversal | Estorno de Repasse por Conta e Ordem |
| incoming_funds_transfer_reversal | Estorno de Transferência Interna |
| bank_slip_payment | Pagamento de Boleto |
| bank_slip_payment_reversal | Estorno de Pagamento de Boleto |
| warranty_analysis_fee | Tarifa de Análise de Garantia |
| bank_slip_settlement_deposit | Liquidação de Boleto |
| bank_slip_payment_withdrawal | Pagamento de Boleto |
| account_setup_fee | Tarifa de Abertura de Conta |
| account_setup_fee_reversal | Estorno de Tarifa de Abertura de Conta |
| bank_slip_payment_withdrawal_reversal | Estorno de Pagamento de Boleto |
| incoming_anticipation_of_receivable | - |
| incoming_credit_card_settlement | Liquidação de cartão de crédito |
| incoming_debit_card_settlement | Liquidação de cartão de débito |
| assignment_automatic_transfer | Débito de Cessão Automática |
| assignment_automatic_transfer_reversal | Estorno de Débito de Cessão Automática |
| pix_fee | Tarifa de PIX |
| incoming_pix_transfer | Entrada de PIX |
| outgoing_pix_transfer | Saída de PIX |
| pix_fee_reversal | Estorno de Tarifa de PIX |
| incoming_pix_transfer_reversal | Estorno de entrada de PIX |
| outgoing_pix_transfer_reversal | Estorno de saída de PIX |
| pix_deposit | Depósito de PIX |
| pix_withdrawal | Transferência de PIX |
| pix_withdrawal_reversal | Estorno de transferência de PIX |
| pix_chargeback_withdrawal | Envio de devolução PIX |
| outgoing_pix_chargeback | Saída de PIX por devolução |
| incoming_pix_chargeback | Recebimento de devolução PIX |
| pix_chargeback_deposit | Entrada de PIX por devolução |
| pix_chargeback_withdrawal_reversal | Estorno de envio de devolução PIX |
| outgoing_pix_chargeback_reversal | Estorno de saída de PIX por devolução |
| incoming_pix_chargeback_reversal | Estorno de recebimento de devolução PIX |
| operation_pix_disbursement | Desembolso PIX da Operação |
| operation_pix_disbursement_reversal | Estorno de Desembolso PIX da Operação |
| receivables_inquiry_fee | Tarifa de Consulta de Agenda de Recebíveis |
| pix_deposit_reversal | Estorno de Depósito de PIX |
| internal_pix_transfer | Transferência de PIX |
| automatic_integrated_payment_reversal | Estorno de Pagamento Automático Integrado |
| operation_dibursement_reversal | Estorno de Desembolso da Operação |
| available_yield | Depósito de Investimento Liquido |
### 8.2. Comprovantes
O comprovante de uma transferência/pagamento pode ter seus dados recuperados através da “**transaction_key** ”.
**Request**
- MÉTODO GET
- ENDPOINT /transaction_receipt/TRANSACTION-KEY
**Response** - Para transferências/pagamentos PIX
Response Body
```json
{
"chargeback_reason": null,
"chargeback_returned_amount": null,
"chargeback_unexpected_reason": null,
"end_to_end_id": "E3240250220221120012039U3OKZZMW8",
"origin_key": "cea836b5-b02e-4f94-b1e2-4d575671c33d",
"original_transfer_data": null,
"pix_message": null,
"pix_transfer_type": "key",
"receiver_conciliation_id": null,
"source_account": {
"account_branch": "0001",
"account_digit": "2",
"account_number": "2359934",
"financial_institution_compe_number": 329,
"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
"owner_document_number": "09080702000105",
"owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
},
"source_subtype": "pix_withdrawal",
"source_subtype_translation_ptbr": "Transferência de PIX",
"target_account": {
"account_branch": "0001",
"account_digit": "2",
"account_number": "1017372",
"financial_institution_compe_number": 212,
"financial_institution_name": "BANCO ORIGINAL S.A.",
"is_internal": false,
"ispb_number": "92894922",
"owner_document_number": "***22181***",
"owner_name": "Vivo Test",
"target_pix_key": "65322181032"
},
"transacted_at": "2022-11-20 02:00:05",
"transacted_at_br": "2022-11-19 23:00:05",
"transaction_amount": 45,
"transaction_key": "d2ba3817-26d7-4957-ab82-24f78d910a8a",
"translated_chargeback_reason": null
}
```
**Response** - Para transferências Internas ou Pagamento de TED
Response Body
```json
{
"origin_key": "983b4a28-7de6-4e71-97ef-60fb50c7b013",
"source_account": {
"account_branch": "0001",
"account_digit": "5",
"account_number": "00002",
"financial_institution_compe_number": 329,
"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
"owner_document_number": "32402502000135",
"owner_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A."
},
"source_subtype": "internal_funds_transfer",
"source_subtype_translation_ptbr": "Transferência Interna",
"target_account": {
"account_branch": "0001",
"account_digit": "2",
"account_number": "2359934",
"financial_institution_compe_number": 329,
"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
"owner_document_number": "09080702000105",
"owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
},
"transacted_at": "2022-11-20 00:36:33",
"transacted_at_br": "2022-11-19 21:36:33",
"transaction_amount": 1000000,
"transaction_key": "67a62397-2c32-4768-8485-ec9129a46654"
}
```
**Response** - Para Pagamentos de Boletos
Response Body
```json
{
"bank_slip": {
"beneficiary": {
"document_number": "32402502000135",
"name": "QI SCD"
},
"digitable_line": "32990001031000699926165000000201993810000003500",
"expiration_date": "2023-06-14",
"financial_institution_compe_number": "329",
"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
"payer": {
"document_number": "10932327656",
"name": "Lucas Clarim"
},
"payment_date": "2022-11-22",
"payment_key": "13b35108-0fdc-44ab-b86d-5dda12dc8dce"
},
"origin_key": "13b35108-0fdc-44ab-b86d-5dda12dc8dce",
"source_account": {
"account_branch": "0001",
"account_digit": "2",
"account_number": "2359934",
"financial_institution_compe_number": 329,
"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
"owner_document_number": "09080702000105",
"owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
},
"source_subtype": "bank_slip_payment",
"source_subtype_translation_ptbr": "Pagamento de Boleto",
"transacted_at": "2022-11-22 12:26:21",
"transacted_at_br": "2022-11-22 09:26:21",
"transaction_amount": 35,
"transaction_key": "eee862b9-7f2e-4eea-b04a-fa0e89442618"
}
```
### 8.3. Extratos
O extrato de uma conta pode ser recuperado através do seguinte endpoint:
**Request**
- MÉTODO GET
- ENDPOINT /account_statement
- PARAMETERS account_key, document_number, date_from, date_to, page, page_size
**Response**
Response Body
```json
{
"data": {
"account_info": {
"account_block_reason": null,
"account_branch": "0001",
"account_credentials": [{
"account_id": 3395,
"credential_type": "observer",
"credential_type_id": 3,
"document_number": "09080702000105",
"id": 3244,
"is_active": true,
"name": "VOVO LUCIA CONVENIENCIA LTDA",
"updated_at": null
},
{
"account_id": 3395,
"credential_type": "requester",
"credential_type_id": 2,
"document_number": "94310345000195",
"id": 3245,
"is_active": true,
"name": "Parceiro Sandbox",
"updated_at": null
}
],
"account_digit": "2",
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"account_name": "Default",
"account_number": "2359934",
"account_status": "opened",
"account_type": "checking",
"automatic_transfer_management_status": {
"created_at": "2022-10-27T13:48:18",
"enumerator": "master"
},
"automatic_transfers": [],
"balance": 999359,
"blocked_balance": 0,
"destinations": [],
"fee": 0,
"internal_webhooks": [],
"investment_available_amount": 0,
"investment_configuration": null,
"owner_document_number": "09080702000105",
"owner_name": "VOVO LUCIA CONVENIENCIA LTDA",
"owner_person_key": "d2fddd2c-3436-41d5-97e0-5721ee871a3a",
"permitted_person_keys": [
"bffded45-5fcf-4d13-9d2a-566a0af338cc",
"ef48fbe4-267b-45c1-9049-75345c075486"
],
"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
"requester_name": "Parceiro Sandbox",
"setup_fee": null,
"transactional_limit": null,
"webhook_enabled": true
},
"transaction_list": [
{
"account_balance": 999359,
"description": "001 0001 81156-1 109.323.276-56 - Lucas de Jesus Clarim",
"source_subtype": "withdrawal",
"transacted_at": "2022-11-21 14:39:56",
"transaction_amount": -551,
"transaction_key": "32ac0781-f292-4172-b58f-3310102e6fb9"
},
{
"account_balance": 999910,
"description": "329 0001 00002-5 32.402.502/0001-35 - QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
"source_subtype": "internal_funds_transfer",
"transacted_at": "2022-11-20 02:27:38",
"transaction_amount": -45,
"transaction_key": "9cee2272-b280-47ed-b9ec-00674f25db1b"
},
{
"account_balance": 999955,
"description": "212 0001 1017372-2 ***.221.81*-** BANCO ORIGINAL S.A.",
"source_subtype": "pix_withdrawal",
"transacted_at": "2022-11-20 02:00:05",
"transaction_amount": -45,
"transaction_key": "d2ba3817-26d7-4957-ab82-24f78d910a8a"
},
{
"account_balance": 1000000,
"description": "329 0001 00002-5 32.402.502/0001-35 - QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
"source_subtype": "internal_funds_transfer",
"transacted_at": "2022-11-20 00:36:33",
"transaction_amount": 1000000,
"transaction_key": "67a62397-2c32-4768-8485-ec9129a46654"
}
]
},
"event_datetime": "2022-11-22 12:57:44",
"key": "d96fb39c-e80b-447b-aad8-191c9bd2eb17",
"status": "success",
"webhook_type": "account_statement"
}
```
## 9 - Gestão de Usuários
É possível realizar a inclusão e edição dos usuários administradores de uma conta aberta aberta. As inclusões sempre demanda autenticação de 2 fatores para os usuários que estão sendo adicionados.
### 9.1. Incluíndo um novo usuário a uma conta aberta
#### 9.1.1. Criação
Primeiro é necessário criar o usuário. No momento da criação a QI enviará um token para o usuário criado, por sms ou email.
**Request**
- MÉTODO POST
- ENDPOINT /baas/token_request
Request Body
```json
{
"contact_type": "sms",
"agent_document_number": "97564480084",
"person_creation": {
"person": {
"date_of_birth": "1987-01-11",
"spouse_name": "sample spouse name",
"birth_place": "sample birth place",
"phone_number": {
"country_code": "55",
"area_code": "88",
"number": "988887777"
},
"representative": null,
"father_name": "sample father name",
"address": {
"street": "Rua Sample Avenue",
"complement": "Apto 123",
"state": "MG",
"number": "1234",
"neighborhood": "Cabral",
"postal_code": "38300000",
"city": "Ituiutaba"
},
"nationality": "Brasil",
"document_identification_number": "890537823",
"mother_name": "Sample Mama",
"person_type": "natural",
"name": "Sample Name Natural",
"profession": "sample profession",
"gender": null,
"email": "sample@gmail.com",
"document_number": "68346734500",
"marital_status": null
}
}
}
```
A Autenticação de 2 fatores para criação/atualização de novos usuários só pode ser realizada via “sms”.
#### 9.1.2. Confirmação da criação
É necessário informar o token enviado para finalizar a criação do novo usuário:
**Request**
- MÉTODO POST
- ENDPOINT /baas/movement_validation
Request Body
```json
{
"token": "456785",
"person_creation": {
"person": {
"date_of_birth": "1987-01-11",
"spouse_name": "sample spouse name",
"birth_place": "sample birth place",
"phone_number": {
"country_code": "55",
"area_code": "88",
"number": "988887777"
},
"representative": null,
"father_name": "sample father name",
"address": {
"street": "Rua Sample Avenue",
"complement": "Apto 123",
"state": "MG",
"number": "1234",
"neighborhood": "Cabral",
"postal_code": "38300000",
"city": "Ituiutaba"
},
"nationality": "Brasil",
"document_identification_number": "890537823",
"mother_name": "Sample Mama",
"person_type": "natural",
"name": "Sample Name Natural",
"profession": "sample profession",
"gender": null,
"email": "sample@gmail.com",
"document_number": "68346734500",
"marital_status": null
}
}
}
```
**Response**
- MÉTODO POST
- ENDPOINT /baas/movement_validation
Response Body
```json
{
"hash": "1ab3754bbe74e16c1bebfadd9b8fb9e3",
"return_response": {
"birth_place": null,
"created_at": null,
"date_of_birth": "1987-01-11T00:00:00",
"document_identification_number": null,
"email": "sample@gmail.com",
"father_name": null,
"gender": null,
"is_pep": false,
"kc_key": null,
"marital_status": null,
"mother_name": "Sample Mama",
"nationality": "Brasil",
"natural_revenue_range": {
"average_amount": null,
"created_at": "2021-03-12T13:26:08",
"description": "Unavailable",
"description_ptbr": "Indisponível",
"enumerator": "0",
"more_than_amount": null,
"up_to_amount": null
},
"person": {
"address": {
"city": "Ituiutaba",
"complement": "Apto 123",
"created_at": null,
"neighborhood": "Cabral",
"number": "1234",
"postal_code": "38300000",
"state": "MG",
"street": "Rua Sample Avenue"
},
"category": null,
"category_nick": null,
"created_at": null,
"document_number": "44236096307",
"domain": {
"created_at": "2022-07-14T15:42:45",
"domain_key": "7aa7e064-f06b-4e09-ae19-7c27694f545b",
"domain_name": "Koin Soluções Domain Updated",
"owner_person_key": "997d1b30-e40a-42a0-b87a-4191a5165494"
},
"internal_contact": null,
"internal_contact_person_key": null,
"name": "Sample Name Natural",
"person_category": null,
"person_code": 1564,
"person_key": "9021859f-9860-41e6-af19-559a2599859c",
"person_status": {
"created_at": "2019-02-15T18:28:09",
"enumerator": "pending",
"translation_path": "onboarding.PersonStatus.pending"
},
"person_type": {
"created_at": "2019-02-15T18:28:08",
"enumerator": "natural",
"translation_path": "onboarding.PersonType.natural"
},
"phone": [{
"area_code": "16",
"country_code": "55",
"created_at": null,
"number": "997239044",
"phone_key": "b1c3f2d1-2433-4305-9d58-4dd83c30b7aa",
"phone_type": null
}],
"professional_data": [],
"qualifications": [],
"registration_date": "2022-08-22",
"risk": null,
"special_attention": false,
"terms_acknowledgement": false,
"valid_cip_beneficiary": false
},
"profession": null,
"revenue_amount": null,
"spouse_name": null
},
"validation": true
}
```
#### 9.1.3. Criar vínculo profissional
Após a criação do usuário, é necessário vinculá-lo a uma empresa titular de uma conta aberta:
**Request**
- MÉTODO POST
- ENDPOINT /baas/token_request
Request Body
```json
{
"contact_type": "sms",
"agent_document_number": "97564480084",
"professional_data_creation": {
"natural_person": "3ea7f034-f06b-4e28-ae19-7c23694f546b",
"legal_person": "8bc83ae4-68e4-7bc9-8c84-077131ba2c93",
"natural_person_roles": [{
"product_type": "account",
"role_type": "requester"
},
{
"product_type": "escrow",
"role_type": "requester"
}
],
"post_type": "ceo"
}
}
```
#### 9.1.4. Aprovar vínculo profissional
Para aprovar a inclusão do vínculo, é necessário enviar o token recebido pelo usuário administrador.
**Request**
- MÉTODO POST
- ENDPOINT /baas/movement_validation
***Payload***
Response Body
```json
{
"token": "076244",
"professional_data_creation": {
"natural_person": "3ea7f034-f06b-4e28-ae19-7c23694f546b",
"legal_person": "8bc83ae4-68e4-7bc9-8c84-077131ba2c93",
"natural_person_roles": [{
"product_type": "account",
"role_type": "requester"
},
{
"product_type": "escrow",
"role_type": "requester"
}
],
"post_type": "ceo"
}
}
```
**Response**
- MÉTODO POST
- ENDPOINT /baas/movement_validation
***Body***
Response Body
```json
{
"hash": "53d62e42d5299fca0d261ff1eae4bffc",
"return_response": {
"admission_date": "2022-08-22",
"created_at": "2022-08-22T21:51:29",
"email": null,
"final_beneficiary": null,
"is_active": true,
"legal_person_key": "9bc89ea4-64e4-4bd9-8d84-077135ba2c93",
"natural_person_key": "9021859f-9860-41e6-af19-559a2599859c",
"natural_person_roles": [{
"created_at": "2022-08-22T21:51:29",
"natural_person_roles_events": [],
"product_type": {
"created_at": "2021-02-26T14:16:35",
"enumerator": "account"
},
"role_type": {
"created_at": "2021-02-26T14:14:52",
"enumerator": "requester"
},
"updated_at": "2022-08-22T21:51:29"
},
{
"created_at": "2022-08-22T21:51:29",
"natural_person_roles_events": [],
"product_type": {
"created_at": "2022-04-08T14:51:34",
"enumerator": "escrow"
},
"role_type": {
"created_at": "2021-02-26T14:14:52",
"enumerator": "requester"
},
"updated_at": "2022-08-22T21:51:29"
}
],
"phone": null,
"post_type": {
"created_at": "2019-02-15T18:28:12",
"enumerator": "ceo",
"translation_path": "onboarding.PostType.ceo"
},
"profession_data_key": "bfe8bc59-533a-4c6a-be3a-af5137794c70",
"updated_at": "2022-08-22T21:51:29"
},
"validation": true
}
```
### 9.2. Atualizando Dados de um Usuário Existente
Os dados de um usuário são sempre atualizados no nível do vínculo deste usuário com uma determinada empresa. Sendo assim, para realizar qualquer update, são sempre necessária a chave de identificação do usuário (“***natural_person***“) e a chave do vínculo deste usuário com a empresa (“***professional_data_key***“).
#### 9.2.1. Solicitar alteração
Primeiramente é necessário solicitar a atualização dos dados de um usuário em relação a uma determinada empresa.
**Request**
- MÉTODO POST
- ENDPOINT /baas/token_request
Response Body
```json
{
"contact_type": "sms",
"agent_document_number": "97564480084",
"professional_data_contact_update": {
"professional_data_key": "4ba8ff34-e07b-4ea8-ae59-8c23994f546b",
"natural_person": "3ea7f034-f06b-4e28-ae19-7c23694f546b",
"email": "sample@gmail.com",
"phone_number": {
"country_code": "55",
"area_code": "888",
"number": "988887777"
}
}
}
```
#### 9.2.2. Aprovar solicitação de alteração
Para aprovar a alteração dos dados do usuário, é necessário enviar o token enviado ao usuário alvo da alteração:
**Request**
- MÉTODO POST
- ENDPOINT /baas/movement_validation
Response Body
```json
{
"token": "076244",
"professional_data_contact_update": {
"professional_data_key": "4ba8ff34-e07b-4ea8-ae59-8c23994f546b",
"natural_person": "3ea7f034-f06b-4e28-ae19-7c23694f546b",
"email": "sample@gmail.com",
"phone_number": {
"country_code": "55",
"area_code": "888",
"number": "988887777"
}
}
}
```
**Response**
- MÉTODO POST
- ENDPOINT /baas/movement_validation
Response Body
```json
{
"hash": "a355aade311f93ec87637e321f11386d",
"return_response": {
"admission_date": "2022-08-22",
"created_at": "2022-08-22T21:51:29",
"email": "contacto_info@fakemail.com",
"final_beneficiary": null,
"is_active": true,
"legal_person_key": "9bc89ea4-64e4-4bd9-8d84-077135ba2c93",
"natural_person_key": "9021859f-9860-41e6-af19-559a2599859c",
"natural_person_roles": [{
"created_at": "2022-08-22T21:51:29",
"natural_person_roles_events": [],
"product_type": {
"created_at": "2021-02-26T14:16:35",
"enumerator": "account"
},
"role_type": {
"created_at": "2021-02-26T14:14:52",
"enumerator": "requester"
},
"updated_at": "2022-08-22T21:51:29"
},
{
"created_at": "2022-08-22T21:51:29",
"natural_person_roles_events": [],
"product_type": {
"created_at": "2022-04-08T14:51:34",
"enumerator": "escrow"
},
"role_type": {
"created_at": "2021-02-26T14:14:52",
"enumerator": "requester"
},
"updated_at": "2022-08-22T21:51:29"
}
],
"phone": {
"area_code": "16",
"country_code": "55",
"number": "997239044",
"phone_type": "commercial"
},
"post_type": {
"created_at": "2019-02-15T18:28:12",
"enumerator": "ceo",
"translation_path": "onboarding.PostType.ceo"
},
"profession_data_key": "bfe8bc59-533a-4c6a-be3a-af5137794c70",
"updated_at": "2022-08-22T21:51:29"
},
"validation": true
}
```
---
# Manual BaaS - Serviço
URL: /documentation/casos_de_uso/manual_baas_servico
:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita.
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::
:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::
:::caution Atenção
Antes de iniciar o processo de abertura de conta, é de responsabilidade do parceiro realizar as análises de KYC e Prevenção a Fraude.
Para isso, deve ser utilizado o endpoint de análise descrito em [/onboarding](https://docs.zaig.com.br/onboarding/#introducao).
:::
### 1 - Criando uma Conta
**1.1. Upload de documentos:** Antes da abertura da conta deve ser realizado o upload dos documentos da empresa. Seguem listas de documentos exigidos para cada tipo de empresa:
Para S.A.'s:
- Estatuto Social.
- Ata de Eleição dos Representantes Legais da empresa.
- Procuração (caso aplicável).
- Documento com foto de cada representante legal ou procurador.
Para os demais casos:
- Contrato social.
- Procuração (caso aplicável).
- Documento com foto de cada representante legal ou procurador.
Os documentos devem ser compactados em um arquivo “.zip” e enviados através do endpoint de [upload de documentos](/documentation/upload_de_documentos/).
**Response**
ENDPOINT /upload
MÉTODO POST
Response Body
```json
{
"document_key": "cd639c4a-2279-468a-a047-59865b8159ed",
"document_md5": "8f5bef84cb07dc047017c0d304dbb6b8",
"url": "https://storage.googleapis.com/sandbox-doc-api/documents/cd639c4a-2279-468a-a047-59865b8159ed/identificacao_teste.pdf"
}
```
:::info
**IMPORTANTE:** guarde essa “**document_key**”, pois ela será necessária na etapa da criação da conta.
:::
**1.2.1. Criação da conta PJ:**
**Request**
ENDPOINT /account
MÉTODO POST
Request Body
```json
{
"account_owner": {
"address": {
"city": "Limeira",
"complement": "complemento",
"neighborhood": "Vila Cidade Jardim",
"number": "662",
"postal_code": "13480290",
"state": "SP",
"street": "Avenida Campinas"
},
"cnae_code": "4721-1/02",
"company_statute": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
"company_document_number": "09080702000105",
"company_type": "ltda",
"email": "padaria@vovolucia.com.br",
"foundation_date": "1950-08-21",
"annual_revenue_amount": "1000000.00",
"name": "VOVO LUCIA CONVENIENCIA LTDA",
"person_type": "legal",
"phone": {
"area_code": "19",
"country_code": "055",
"number": "988888888"
},
"trading_name": "Empadaria Vovo Lucia",
"company_representatives": [{
"address": {
"city": "Recife",
"complement": null,
"neighborhood": "Fundão",
"number": "137",
"postal_code": "52221110",
"state": "PE",
"street": "Rua Camapuã"
},
"birth_date": "1972-02-02",
"document_identification_number": "339122924",
"document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
"email": "marcos.alves@yopmail.com",
"individual_document_number": "08531309069",
"is_pep": false,
"final_beneficiary": true,
"marital_status": "single",
"mother_name": "Sueli Isadora Alves",
"name": "Marcos Felipe Henrique Alves",
"nationality": "Brasileira",
"person_type": "natural",
"phone": {
"area_code": "88",
"country_code": "055",
"number": "995924634"
}
},
{
"person_type": "natural",
"name": "Juliana Tereza Bernardes",
"mother_name": "Maria Mariane",
"birth_date": "1990-05-06",
"profession": "Deputada",
"nationality": "Brasileira",
"marital_status": "single",
"is_pep": false,
"final_beneficiary": true,
"individual_document_number": "97564480084",
"document_identification_number": "232479719",
"document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
"email": "juliana.tereza@yopmail.com",
"phone": {
"country_code": "055",
"area_code": "11",
"number": "912821359"
},
"address": {
"street": "Passagem Mariana",
"state": "PA",
"city": "Ananindeua",
"neighborhood": "Águas Lindas",
"number": "660",
"postal_code": "67118003",
"complement": "complemento"
}
}
]
}
}
```
“***account_owner***”: Os dados da empresa devem ser enviados neste objeto.
“***account_owner.company_statute***”: A “***document_key***” retornada no endpoint de upload de documentos, no momento do upload do “.zip” dos documentos societários da empresa, deve ser enviada neste campo.
“***account_owner.company_representatives***”: A lista com os dados dos representantes legais da empresa deve ser enviada neste objeto. Deve ser enviado, no mínimo, os representantes legais, suficientes para representar legalmente a empresa conforme seu respectivo estatuto/contrato social. A validação dos poderes de cada representante legal enviado fica a cargo do parceiro.
“***account_owner.company_representatives.document_identification***”: A “***document_key***” retornada no endpoint de upload de documentos, no momento do upload do “.zip” do documento com foto do representante, deve ser enviada neste campo.
**Response**
ENDPOINT /account
MÉTODO POST
Response Body
```json
{
"data": {
"account_info": {
"account_branch": "0001",
"account_digit": "2",
"account_number": "2359934",
"financial_institution_code": "329"
},
"account_owner": {
"document_number": "09080702000105",
"name": "VOVO LUCIA CONVENIENCIA LTDA"
}
},
"event_datetime": "2022-09-02 22:39:10",
"key": "\",
"status": "pending_kyc_analysis",
"webhook_type": "account"
}
```
:::info
**IMPORTANTE:** a “***key***” retornada nesta resposta é a **PROPOSAL-KEY** do pedido de abertura da conta. Ela deve ser armazenada para leitura do webhook de abertura da conta.
:::
A resposta da solicitação de abertura de conta sempre retornará o status “***pending_kyc_analysis***”.
Um número de conta será reservado para esse cliente, porém a conta ainda estará pendente de análise de KYC por parte da QI Tech. Neste momento, a conta não estará aberta e não poderá receber ou enviar recursos.
**1.2.2. Criação da conta PF:**
**Request**
ENDPOINT /account
MÉTODO POST
Request Body
```json
{
"account_owner": {
"address": {
"street": "Avenida Sargento Geraldo Sant'Ana",
"number": "1100",
"neighborhood": "Jardim Taquaral",
"city": "São Paulo",
"state": "SP",
"postal_code": "04674225"
},
"phone": {
"country_code": "055",
"number": "912828135",
"area_code": "11"
},
"email": "juliana.tereza@yopmail.com",
"name": "Juliana Tereza Bernardes",
"person_type": "natural",
"nationality": "Brasil",
"birth_date": "1993-08-02",
"mother_name": "Patricia Monica Diaz Bascur Tieppo",
"is_pep": false,
"individual_document_number": "97564480084",
"document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
"document_identification_type": "cnh",
"revenue_amount": 1000,
"profession": "autonomo"
}
}
```
“***account_owner***”: Os dados da pessoa física titular da conta devem ser enviados neste objeto.
“***account_owner.document_identification***”: A “***document_key***” retornada no endpoint de upload de documentos.
**1.2.2.1. Forma de envio do documento de identificação:** Na abertura da conta PF, podem ser enviados dois tipos de documento (***document_identification_type***): cnh ou rg.
O documento de identificação pode ser enviado nos formatos “.pdf”, “.png” e “.jpeg”.
**1.2.2.1.1. Envio de documento de identificação do tipo CNH:**
Caso o documento seja enviado em 2 arquivos, sendo que, a frente do documento consta em um arquivo e o verso em outro, os seguintes campos devem ser infomado no objeto ***account_owner*** do endpoint **/account (1.2.2.)**:
"document_identification": "\ ",
"document_identification_back": "\ ",
"document_identification_type": "cnh",
Caso o documento seja enviado em 1 arquivo, contendo a frente e verso do documento no mesmo arquivo (**foto do documento ou cnh digital**), os seguintes campos devem ser infomado no objeto ***account_owner*** do endpoint ***/account*** (**1.2.2.**):
"document_identification": "\ ",
"document_identification_type": "cnh",
**1.2.2.1.2. Envio de documento de identificação do tipo RG:**
Para o tipo de documento RG, sempre devem ser enviados 2 arquivos, um contendo a frente do documento e outro com o verso do documento. Para este caso os seguintes campos devem ser infomados no objeto ***account_owner*** do endpoint ***/account*** (**1.2.2.**):
"document_identification": "\ ",
"document_identification_back": "\ ",
"document_identification_type": "rg",
**Response**
ENDPOINT /account
MÉTODO POST
Response Body
```json
{
"data": {
"account_info": {
"account_branch": "0001",
"account_digit": "2",
"account_number": "2359934",
"financial_institution_code": "329"
},
"account_owner": {
"document_number": "97564480084",
"name": "Juliana Tereza Bernardes"
}
},
"event_datetime": "2022-09-02 22:39:10",
"key": "\",
"status": "pending_kyc_analysis",
"webhook_type": "account"
}
```
:::info
**IMPORTANTE:** a “**key**” retornada nesta resposta é a **PROPOSAL-KEY** do pedido de abertura da conta. Ela deve ser armazenada para leitura do webhook de abertura da conta.
:::
A resposta da solicitação de abertura de conta sempre retornará o status “***pending_kyc_analysis***”.
Um número de conta será reservado para esse cliente, porém a conta ainda estará pendente de análise de KYC por parte da QI Tech. Neste momento, a conta não estará aberta e não poderá receber ou enviar recursos.
:::info
Para simular situações de aprovação, reprovação e analise manual pode ser utilizado o primeiro digito do CPF/CNPJ do owner da conta:
- 0 à 7 -> Aprovação Automática
- 8 -> Reprovação Automática
- 9 -> Análise Manual
:::
**1.2.3.** Após a conclusão da análise de KYC/PLD pela QI Tech, será enviado um webhook de abertura da conta, conforme abaixo:
**Webhook**
WEBHOOK_TYPE account
SOURCE_SUB_TYPE Account Opened
Body
```json
{
"data": {
"account_info": {
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"account_digit": "2",
"account_branch": "0001",
"account_number": "2359934",
"financial_institution_code": "329"
},
"account_owner": {
"name": "VOVO LUCIA CONVENIENCIA LTDA",
"document_number": "09080702000105"
}
},
"event_datetime": "2022-09-02 22:39:39",
"key": "\",
"status": "account_opened",
"webhook_type": "account"
}
```
:::info
Neste momento será retornada “***account_key***” da conta e ela estará pronta para utilização.
:::
**1.2.4.** Caso a conta não passe no processo de KYC/PLD, será enviado um webhook de conta rejeitada:
**Webhook**
WEBHOOK_TYPE available_balance
STATUS Success
Body
```json
{
"data": {
"account_info": {
"account_digit": "2",
"account_branch": "0001",
"account_number": "2359934",
"financial_institution_code": "329"
},
"account_owner": {
"name": "VOVO LUCIA CONVENIENCIA LTDA",
"document_number": "09080702000105"
}
},
"event_datetime": "2022-09-02 22:39:39",
"key": "\",
"status": "account_rejected",
"webhook_type": "account"
}
```
**1.3. Recuperando dados da conta:**
**Request**
ENDPOINT /account
MÉTODO POST
PARAMETERS account_type[checking], owner_name, account_number, owner_document_number, account_status[opened, closed, blocked], page, page_size
Request Body
```json
{
"data": [
{
"account_block_reason": null,
"account_branch": "0001",
"account_credentials": [{
"account_id": 3395,
"created_at": "2022-09-02T22:39:39",
"credential_type": {
"created_at": "2019-06-18T13:19:30",
"enumerator": "observer",
"id": 3,
"translation_path": "account.CredentialType.observer"
},
"credential_type_id": 3,
"id": 3244,
"is_active": true,
"person_key": "bffded45-5fcf-4d13-9d2a-566a0af338cc",
"updated_at": null
},
{
"account_id": 3395,
"created_at": "2022-09-02T22:39:39",
"credential_type": {
"created_at": "2019-06-18T13:19:30",
"enumerator": "requester",
"id": 2,
"translation_path": "account.CredentialType.requester"
},
"credential_type_id": 2,
"id": 3245,
"is_active": true,
"person_key": "ef48fbe4-267b-45c1-9049-75345c075486",
"updated_at": null
}
],
"account_digit": "2",
"account_documents": [],
"account_events": [{
"account_id": 3395,
"created_at": "2022-09-02T22:39:39",
"id": 5132,
"new_account_status": {
"created_at": "2019-10-11T18:58:31",
"enumerator": "opened",
"id": 1,
"translation_path": "account.AccountStatus.opened"
},
"new_account_status_id": 1,
"old_account_status": null,
"old_account_status_id": null
}],
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"account_name": "Default",
"account_number": "2359934",
"account_status": {
"created_at": "2019-10-11T18:58:31",
"enumerator": "opened",
"translation_path": "account.AccountStatus.opened"
},
"account_type": {
"created_at": "2019-03-15T13:09:15",
"enumerator": "checking",
"translation_path": "account.AccountType.checking"
},
"automatic_transfer_management_status": {
"created_at": "2022-10-27T13:48:18",
"enumerator": "master"
},
"automatic_transfers": [],
"balance": 0,
"blocked_balance": 0,
"blocked_balance_events": [],
"created_at": "2022-09-02T22:39:39",
"destinations": [],
"fee": 0,
"internal_webhooks": [],
"investment_available_amount": 0,
"investment_configuration": null,
"is_system_account": false,
"owner_document_number": "09080702000105",
"owner_name": "VOVO LUCIA CONVENIENCIA LTDA",
"owner_person_key": "bffded45-5fcf-4d13-9d2a-566a0af338cc",
"permitted_person_keys": [
"bffded45-5fcf-4d13-9d2a-566a0af338cc",
"bffded45-5fcf-4d13-9d2a-566a0af338cc",
"ef48fbe4-267b-45c1-9049-75345c075486"
],
"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
"requester_name": "Requester Name Sandbox",
"setup_fee": null,
"transactional_limit": null,
"webhook_enabled": true
}, ...
],
"pagination": {
"current_page": 1,
"next_page": null,
"rows_per_page": 100,
"total_pages": 1,
"total_rows": 8
}
}
```
:::info
Os campos mais pertinentes da resposta da consulta dos dados da conta são:
**account_branch**, **account_digit**, **account_key**,**account_number**, **balance**, **owner_document_number**, **owner_name**, **owner_person_key**.
:::
---
### 2 - Transferência PIX
**2.1. Realizar Transferência PIX:** para realizar um PIX é necessário realizar três chamadas:
1. Criação do pedido de transferência: **/baas/pix_transfer**
2. Aprovação da transferência: **/baas/pix_transfer_approval**
:::info
Uma transferência PIX pode ser realizada utilizando dois payloads distintos: **chave PIX** ou **dados bancários**.
:::
**2.2. Transferência utilizando uma chave PIX (CPF, CNPJ, E-mail, Celular ou chave aleatória):**
**Request**
ENDPOINT /baas/pix_transfer
MÉTODO POST
Request Body
```json
{
"pix_transfer_type": "key",
"source_account": {
"account_branch": "0001",
"account_digit": "2",
"account_number": "2359934",
"owner_document_number": "09080702000105"
},
"pix_key": "65322181032",
"transaction_amount": 45,
"requester_document_identification": "09080702000105"
}
```
:::info
A “***pix_key***” pode ser um **CPF**, **CNPJ**, **E-mail**, **Celular** ou uma **Chave Aleatória** (UUID), seguindo as seguintes formatações:
**CPF:** Número inteiro com 11 dígitos.
**CNPJ:** Número inteiro com 14 dígitos.
**E-mail:** Texto contendo ao menos um “@”.
**Celular:** Texto contendo os seguintes valores: “+55” + “[DDD do celular]“ + “[Número Inteiro do Celular com no mínimo 8 e no máximo 9 dígitos]”. Ex: “+5511987654321“.
**Chave Aleatória:** UUID.
:::
**2.3. Transferência utilizando dados da Conta Bancária (PIX Manual):**
**Request**
ENDPOINT /baas/pix_transfer
MÉTODO POST
Request Body
```json
{
"pix_transfer_type": "manual",
"source_account": {
"account_branch": "0001",
"account_digit": "2",
"account_number": "2359934",
"owner_document_number": "09080702000105"
},
"target_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "12345678",
"owner_document_number": "32402502000135",
"owner_name": "Qi Tech",
"account_type": "checking_account",
"ispb": "32402502"
},
"transaction_amount": 45
}
```
Utilizando o PIX Manual é necessário informar o ISPB da instituição destino. Este dado é utilizado, pois existem instituições de pagamento que recebem PIX, porém não possuem código de banco. O ISPB é a base do CNPJ da instituição. Para ter acesso à lista completa de ISPB’s de cada instituição participante do PIX, basta utilizar o endpoint de consulta em nossa documentação: /documentation/lista_de_instituicoes_financeiras/consulta_de_instituicoes_financeiras
**Response**
ENDPOINT /baas/pix_transfer
MÉTODO POST
Response Body
```json
{
"data": {
"end_to_end_id": "E3240250220221120012039U3OKZZMW8",
"fee_amount": 1,
"pix_message": null,
"pix_transfer_key": "cea836b5-b02e-4f94-b1e2-4d575671c33d",
"source_account": {
"account_brach": "0001",
"account_digit": "2",
"account_number": "2359934",
"account_type": "checking",
"owner_document_number": "09080702000105",
"owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
},
"target_account": {
"document_number": "***.221.81*-**",
"financial_institution": "BANCO ORIGINAL S.A."
},
"transaction_amount": 45,
"transfer_purpose": "transfer"
},
"event_datetime": "2022-09-02 22:20:47",
"operation_key": "86d80cf4-430b-4e16-910a-41798810ddcf",
"status": "pending_approval"
}
```
:::info
Possíveis status da solicitação de transferência/pagamento via PIX:
**pending_approval:** transferência pendente de aprovação pelo solicitante
**sent:** transferência enviada
:::
Para aprovar a transferência PIX, é necessário utilizar a “***pix_transfer_key***” retornada na solicitação de transferência (***/baas/pix_transfer***):
**Request**
ENDPOINT /baas/pix_transfer_approval
MÉTODO POST
Request Body
```json
{
"pix_transfer_key": "cea836b5-b02e-4f94-b1e2-4d575671c33d",
"approver_document_number": "97564480084"
}
```
**Response**
ENDPOINT /baas/pix_transfer_approval
MÉTODO POST
Response Body
```json
{
"data": {
"end_to_end_id": "E3240250220221120012039U3OKZZMW8",
"fee_amount": 1,
"pix_message": null,
"pix_transfer_key": "cea836b5-b02e-4f94-b1e2-4d575671c33d",
"source_account": {
"account_brach": "0001",
"account_digit": "2",
"account_number": "2359934",
"account_type": "checking",
"owner_document_number": "09080702000105",
"owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
},
"target_account": {
"document_number": "***.221.81*-**",
"financial_institution": "BANCO ORIGINAL S.A."
},
"transaction_amount": 45,
"transfer_purpose": "transfer"
},
"event_datetime": "2022-09-02 22:20:47",
"operation_key": "86d80cf4-430b-4e16-910a-41798810ddcf",
"status": "sent"
}
```
STATUS 422
Response Body
```json
{
"data": "{\"title\": \"Pending Transfer\", \"description\": \"The transaction () 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
Caso seja retornado **http error 422**, a solicitação de Pix **não deve ser retentada**. É preciso checar o status da solicitação de transferência Pix através de um GET na rota [/baas/pix/pix_transfer](/documentation/pix/pesquisar_por_transferencia_pix_de_saida).
:::
---
### 3 - Movimentações, Comprovantes e Extratos
**3.1. Movimentações:**
Para toda e qualquer movimentação será enviado um webhook de “***account_transaction***“.
Cada transação possui um tipo de classificação (**Source Sub Type**). Essa classificação é utilizada para categorizar cada movimentação na conta. A lista de Source Sub Types pode ser vista no **Anexo I** deste manual.
**3.1.1.** Os créditos em conta resultarão em um webhook com “***data.amount***” positivo, “***data.origin***“ sendo a conta de origem dos recursos e a “***data.destination***“ sendo a conta de destino dos recursos:
**Webhook**
WEBHOOK_TYPE account_transaction
Body: Pix
```json
{
"key": "\",
"data": {
"amount": 1000000,
"origin": {
"name": "Treasury Account",
"branch": "0001",
"document": "32402502000135",
"account_key": "5d068423-6094-49e4-b15b-7740038295a8",
"account_digit": "5",
"account_number": "00002"
},
"timestamp": "2022-09-02T21:36:33.446120",
"description": "329 0001 00002-5 32.402.502/0001-35 - QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
"destination": {
"name": "Default",
"branch": "0001",
"document": "09080702000105",
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"account_digit": "2",
"account_number": "2359934"
},
"reference_key": "983b4a28-7de6-4e71-97ef-60fb50c7b013",
"reference_type": "movement_request",
"account_balance": 1000000,
"source_sub_type": "internal_funds_transfer",
"transaction_key": "67a62397-2c32-4768-8485-ec9129a46654",
"source_sub_type_str": "Transferência Interna",
"transaction_details": {
"payer_name": "0001",
"receiver_name": "Default",
"payer_account_digit": "5",
"payer_account_branch": "",
"payer_account_number": "1111111",
"payer_document_number": "66681638999999",
"receiver_account_digit": "6",
"receiver_account_branch": "0000",
"receiver_account_number": "34256449809",
"receiver_conciliation_id": null,
"receiver_document_number": "00809641658"
}
},
"datetime": "2022-09-02T21:36:33.446120",
"webhook_type": "account_transaction"
}
```
Body: Outras transações
```json
{
"key": "\",
"data": {
"amount": 1000000,
"origin": {
"name": "Treasury Account",
"branch": "0001",
"document": "32402502000135",
"account_key": "5d068423-6094-49e4-b15b-7740038295a8",
"account_digit": "5",
"account_number": "00002"
},
"timestamp": "2022-09-02T21:36:33.446120",
"description": "329 0001 00002-5 32.402.502/0001-35 - QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
"destination": {
"name": "Default",
"branch": "0001",
"document": "09080702000105",
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"account_digit": "2",
"account_number": "2359934"
},
"reference_key": "983b4a28-7de6-4e71-97ef-60fb50c7b013",
"reference_type": "movement_request",
"account_balance": 1000000,
"source_sub_type": "internal_funds_transfer",
"transaction_key": "67a62397-2c32-4768-8485-ec9129a46654",
"source_sub_type_str": "Transferência Interna"
},
"datetime": "2022-09-02T21:36:33.446120",
"webhook_type": "account_transaction"
}
```
**3.1.2.** Os débitos em conta resultarão em um webhook com “data.amount” negativo, “***data.origin***“ sendo a conta destinatária dos recursos e a “***data.destination***“ sendo a conta de origem dos recursos:
**Webhook**
WEBHOOK_TYPE account_transaction
Body
```json
{
"key": "\",
"data": {
"amount": -45,
"origin": {
"name": "PIX",
"branch": "0001",
"document": "32402502000135",
"account_key": "3d0e7d50-e898-49f3-b23b-05353c8a3c72",
"account_digit": "3",
"account_number": "00003"
},
"timestamp": "2022-09-02T23:00:05.326738",
"description": "212 0001 1017372-2 ***.221.81*-** BANCO ORIGINAL S.A.",
"destination": {
"name": "Default",
"branch": "0001",
"document": "09080702000105",
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"account_digit": "2",
"account_number": "2359934"
},
"reference_key": "cea836b5-b02e-4f94-b1e2-4d575671c33d",
"reference_type": "pix_outgoing",
"account_balance": 999955,
"source_sub_type": "pix_withdrawal",
"transaction_key": "d2ba3817-26d7-4957-ab82-24f78d910a8a",
"source_sub_type_str": "Transferência de PIX"
},
"datetime": "2022-09-02T23:00:05.326738",
"webhook_type": "account_transaction"
}
```
**Lista de source_sub_types’s:**
|Enum|Descrição|
|--|--|
|operation_disbursement| Desembolso da Operação|
|protest_expense| Despesas de Protesto|
|automatic_integrated_payment| Pagamento Automático Integrado|
|tax | Impostos|
|electronic_funds_fee| Tarifa de TED|
|credit_operation_fee| Tarifa de Abertura de Crédito|
|internal_funds_transfer| Transferência Interna|
|incoming_funds_transfer| Transferência de Entrada|
|outgoing_funds_transfer| TED|
|deposit| Depósito|
|withdrawal | Transferência|
|withdrawal_reversal | Estorno de Transferência|
|trade_funds_transfer| Transferência de Pagamento de Cessão|
|settlement_funds_transfer| Transferência para Liquidação|
|bank_slip_fee | Tarifa de Boleto|
|bank_slip_settlement| Liquidação de Boleto|
|outgoing_funds_transfer_reversal| Estorno de TED|
|incoming_funds_transfer_refusal | Transferência Negada|
|electronic_funds_fee_reversal| Estorno de Tarifa de TED|
|monthly_account_fee_reversal| Estorno de Tarifa de Manutenção de Conta|
|bank_slip_fee_reversal |Estorno de Tarifa de Boleto|
|correspondent_bank_transfer| Repasse de Correspondente Bancário|
|credit_analysis_fee |Tarifa de Análise de Crédito|
|credit_operation_fee_reversal| Estorno de Tarifa de Abertura de Crédito|
|financial_investments_income| Renda de Aplicação Financeira|
|bank_slip_settlement_reversal| Estorno de Liquidação de Boleto|
|bank_slip_settlement_expense_reversal| Estorno de Tarifa de liquidação de Boleto|
|bank_slip_settlement_incoming_reversal| Estorno de Recebimento de Liquidação de Boleto|
|correspondent_bank_transfer_reversal| Estrono de Repasse de Correspondente Bancário|
|credit_analysis_fee_reversal| Estorno de Tarifa de Análise de Crédito|
|doc_expense_reversal| Estorno de Tarifa de DOC|
|incoming_doc_reversal| Estorno de Entrada de DOC|
|operation_disbursement_reversal| Estorno de Desembolso da Operação|
|operation_settling_reversal| Estorno de Pagamento de Operação|
|outgoing_doc_reversal| Estorno de Saída de DOC|
|rebate_reversal |Estorno de Rebate|
|settlement_funds_transfer_reversal| Estorno de Transferência para Liquidação|
|tax_reversal| Estorno de Impostos|
|trade_funds_transfer_reversal| Estorno de Transferência de Pagamento de Cessão|
|bank_slip_permanency_fee |Tarifa de Permanência do Título|
|bank_slip_cancel_protest_fee |Tarifa de Permanência do Título|
|bank_slip_protest_fee| Tarifa de Pedido de Protesto|
|bank_slip_notary_office_fee| Custas de Protesto|
|bank_slip_registration_fee| Tarifa de Registro|
|bank_slip_extension_fee| Tarifa de Prorrogação|
|bank_slip_rebate_fee |Tarifa de Abatimento|
|bank_slip_discount_fee| Tarifa de Desconto|
|bank_slip_settlement_fee| Tarifa de Liquidação|
|bank_slip_write_off_term_fee| Tarifa de Baixa por Decurso de Prazo|
|bank_slip_write_off_fee |Tarifa de Baixa|
|bank_slip_cancel_protest_write_off_fee| Tarifa de Sustação de Protesto com Baixa|
|bank_slip_notary_office_settlement_fee| Tarifa de Liquidação em Cartório|
|rebate_tax_free |Repasse por Conta e Ordem|
|rebate_tax_free_reversal| Estorno de Repasse por Conta e Ordem|
|incoming_funds_transfer_reversal| Estorno de Transferência Interna|
|bank_slip_payment| Pagamento de Boleto|
|bank_slip_payment_reversal| Estorno de Pagamento de Boleto|
|warranty_analysis_fee |Tarifa de Análise de Garantia|
|bank_slip_settlement_deposit| Liquidação de Boleto|
|bank_slip_payment_withdrawal |Pagamento de Boleto|
|account_setup_fee |Tarifa de Abertura de Conta|
|account_setup_fee_reversal| Estorno de Tarifa de Abertura de Conta|
|bank_slip_payment_withdrawal_reversal| Estorno de Pagamento de Boleto|
|incoming_anticipation_of_receivable| -|
|incoming_credit_card_settlement| Liquidação de cartão de crédito|
|incoming_debit_card_settlement| Liquidação de cartão de débito|
|assignment_automatic_transfer |Débito de Cessão Automática|
|assignment_automatic_transfer_reversal |Estorno de Débito de Cessão Automática|
|pix_fee| Tarifa de PIX|
|incoming_pix_transfer| Entrada de PIX|
|outgoing_pix_transfer| Saída de PIX|
|pix_fee_reversal| Estorno de Tarifa de PIX|
|incoming_pix_transfer_reversal| Estorno de entrada de PIX|
|outgoing_pix_transfer_reversal| Estorno de saída de PIX|
|pix_deposit| Depósito de PIX|
|pix_withdrawal| Transferência de PIX|
|pix_withdrawal_reversal |Estorno de transferência de PIX|
|pix_chargeback_withdrawal| Envio de devolução PIX|
|outgoing_pix_chargeback |Saída de PIX por devolução|
|incoming_pix_chargeback| Recebimento de devolução PIX|
|pix_chargeback_deposit| Entrada de PIX por devolução|
|pix_chargeback_withdrawal_reversal |Estorno de envio de devolução PIX|
|outgoing_pix_chargeback_reversal |Estorno de saída de PIX por devolução|
|incoming_pix_chargeback_reversal |Estorno de recebimento de devolução PIX|
|operation_pix_disbursement| Desembolso PIX da Operação|
|operation_pix_disbursement_reversal| Estorno de Desembolso PIX da Operação|
|receivables_inquiry_fee |Tarifa de Consulta de Agenda de Recebíveis|
|pix_deposit_reversal |Estorno de Depósito de PIX|
|internal_pix_transfer |Transferência de PIX|
|automatic_integrated_payment_reversal |Estorno de Pagamento Automático Integrado|
|operation_dibursement_reversal| Estorno de Desembolso da Operação|
|available_yield| Depósito de Investimento Liquido|
**3.2. Comprovantes:** O comprovante de uma transferência/pagamento pode ter seus dados recuperados através da “***transaction_key***”.
**Request**
ENDPOINT /transaction_receipt/[TRANSACTION-KEY]
MÉTODO GET
Response Body - Para transferências/pagamentos PIX
```json
{
"chargeback_reason": null,
"chargeback_returned_amount": null,
"chargeback_unexpected_reason": null,
"end_to_end_id": "E3240250220221120012039U3OKZZMW8",
"origin_key": "cea836b5-b02e-4f94-b1e2-4d575671c33d",
"original_transfer_data": null,
"pix_message": null,
"pix_transfer_type": "key",
"receiver_conciliation_id": null,
"source_account": {
"account_branch": "0001",
"account_digit": "2",
"account_number": "2359934",
"financial_institution_compe_number": 329,
"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
"owner_document_number": "09080702000105",
"owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
},
"source_subtype": "pix_withdrawal",
"source_subtype_translation_ptbr": "Transferência de PIX",
"target_account": {
"account_branch": "0001",
"account_digit": "2",
"account_number": "1017372",
"financial_institution_compe_number": 212,
"financial_institution_name": "BANCO ORIGINAL S.A.",
"is_internal": false,
"ispb_number": "92894922",
"owner_document_number": "***22181***",
"owner_name": "Vivo Test",
"target_pix_key": "65322181032"
},
"transacted_at": "2022-11-20 02:00:05",
"transacted_at_br": "2022-11-19 23:00:05",
"transaction_amount": 45,
"transaction_key": "d2ba3817-26d7-4957-ab82-24f78d910a8a",
"translated_chargeback_reason": null
}
```
Response Body - Para transferências Internas ou Pagamento de TED
```json
{
"origin_key": "983b4a28-7de6-4e71-97ef-60fb50c7b013",
"source_account": {
"account_branch": "0001",
"account_digit": "5",
"account_number": "00002",
"financial_institution_compe_number": 329,
"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
"owner_document_number": "32402502000135",
"owner_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A."
},
"source_subtype": "internal_funds_transfer",
"source_subtype_translation_ptbr": "Transferência Interna",
"target_account": {
"account_branch": "0001",
"account_digit": "2",
"account_number": "2359934",
"financial_institution_compe_number": 329,
"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
"owner_document_number": "09080702000105",
"owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
},
"transacted_at": "2022-11-20 00:36:33",
"transacted_at_br": "2022-11-19 21:36:33",
"transaction_amount": 1000000,
"transaction_key": "67a62397-2c32-4768-8485-ec9129a46654"
}
```
Response Body - Para Pagamentos de Boletos
```json
{
"bank_slip": {
"beneficiary": {
"document_number": "32402502000135",
"name": "QI SCD"
},
"digitable_line": "32990001031000699926165000000201993810000003500",
"expiration_date": "2023-06-14",
"financial_institution_compe_number": "329",
"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
"payer": {
"document_number": "10932327656",
"name": "Lucas Clarim"
},
"payment_date": "2022-11-22",
"payment_key": "13b35108-0fdc-44ab-b86d-5dda12dc8dce"
},
"origin_key": "13b35108-0fdc-44ab-b86d-5dda12dc8dce",
"source_account": {
"account_branch": "0001",
"account_digit": "2",
"account_number": "2359934",
"financial_institution_compe_number": 329,
"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
"owner_document_number": "09080702000105",
"owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
},
"source_subtype": "bank_slip_payment",
"source_subtype_translation_ptbr": "Pagamento de Boleto",
"transacted_at": "2022-11-22 12:26:21",
"transacted_at_br": "2022-11-22 09:26:21",
"transaction_amount": 35,
"transaction_key": "eee862b9-7f2e-4eea-b04a-fa0e89442618"
}
```
**3.3. Extratos:** O extrato de uma conta pode ser recuperado através do seguinte endpoint:
**Request**
ENDPOINT /account_statement
MÉTODO GET
PARAMETERS account_key, document_number, date_from, date_to, page, page_size
Response Body
```json
{
"data": {
"account_info": {
"account_block_reason": null,
"account_branch": "0001",
"account_credentials": [{
"account_id": 3395,
"credential_type": "observer",
"credential_type_id": 3,
"document_number": "09080702000105",
"id": 3244,
"is_active": true,
"name": "VOVO LUCIA CONVENIENCIA LTDA",
"updated_at": null
},
{
"account_id": 3395,
"credential_type": "requester",
"credential_type_id": 2,
"document_number": "94310345000195",
"id": 3245,
"is_active": true,
"name": "Parceiro Sandbox",
"updated_at": null
}
],
"account_digit": "2",
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"account_name": "Default",
"account_number": "2359934",
"account_status": "opened",
"account_type": "checking",
"automatic_transfer_management_status": {
"created_at": "2022-10-27T13:48:18",
"enumerator": "master"
},
"automatic_transfers": [],
"balance": 999359,
"blocked_balance": 0,
"destinations": [],
"fee": 0,
"internal_webhooks": [],
"investment_available_amount": 0,
"investment_configuration": null,
"owner_document_number": "09080702000105",
"owner_name": "VOVO LUCIA CONVENIENCIA LTDA",
"owner_person_key": "d2fddd2c-3436-41d5-97e0-5721ee871a3a",
"permitted_person_keys": [
"bffded45-5fcf-4d13-9d2a-566a0af338cc",
"ef48fbe4-267b-45c1-9049-75345c075486"
],
"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
"requester_name": "Parceiro Sandbox",
"setup_fee": null,
"transactional_limit": null,
"webhook_enabled": true
},
"transaction_list": [
{
"account_balance": 999359,
"description": "001 0001 81156-1 109.323.276-56 - Lucas de Jesus Clarim",
"source_subtype": "withdrawal",
"transacted_at": "2022-11-21 14:39:56",
"transaction_amount": -551,
"transaction_key": "32ac0781-f292-4172-b58f-3310102e6fb9"
},
{
"account_balance": 999910,
"description": "329 0001 00002-5 32.402.502/0001-35 - QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
"source_subtype": "internal_funds_transfer",
"transacted_at": "2022-11-20 02:27:38",
"transaction_amount": -45,
"transaction_key": "9cee2272-b280-47ed-b9ec-00674f25db1b"
},
{
"account_balance": 999955,
"description": "212 0001 1017372-2 ***.221.81*-** BANCO ORIGINAL S.A.",
"source_subtype": "pix_withdrawal",
"transacted_at": "2022-11-20 02:00:05",
"transaction_amount": -45,
"transaction_key": "d2ba3817-26d7-4957-ab82-24f78d910a8a"
},
{
"account_balance": 1000000,
"description": "329 0001 00002-5 32.402.502/0001-35 - QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
"source_subtype": "internal_funds_transfer",
"transacted_at": "2022-11-20 00:36:33",
"transaction_amount": 1000000,
"transaction_key": "67a62397-2c32-4768-8485-ec9129a46654"
}
]
},
"event_datetime": "2022-11-22 12:57:44",
"key": "d96fb39c-e80b-447b-aad8-191c9bd2eb17",
"status": "success",
"webhook_type": "account_statement"
}
```
---
### 4 - Transferência TED
:::info
As transferências TED só podem ser realizadas em dias úteis das **7:00** às **17:00**.
:::
**4.1. Realizar Transferência TED:**
Para realizar uma transferência via TED é necessário realizar a seguinte chamada:
**Request**
ENDPOINT /wire_transfer
MÉTODO POST
Response Body
```json
{
"source_account": {
"account_branch": "0001",
"account_number": "9477323",
"account_digit": "0",
"owner_document_number": "38299588000107"
},
"target_account": {
"financial_institution_code": "341",
"account_branch": "0001",
"account_number": "4311337",
"account_digit": "1",
"owner_document_number": "21669721019",
"owner_name": "Nome do Titular da Conta Destino"
},
"transaction_amount": 8.86
}
```
**Response**
ENDPOINT /wire_transfer
MÉTODO POST
Response Body
```json
{
"data": {
"source_account": {
"account_branch": "0001",
"account_digit": "0",
"account_number": "9477323",
"owner_document_number": "38299588000107"
},
"target_account": {
"account_branch": "0001",
"account_digit": "1",
"account_number": "4311337",
"financial_institution_code": "341",
"owner_document_number": "21669721019",
"owner_name": "Nome do Titular da Conta Destino"
},
"transaction_amount": 8.86,
"transaction_key": "076b76b9-6177-4cd6-b164-da55df678df6"
},
"event_datetime": "2023-02-14 23:05:53",
"key": "d09c5533-a8d7-4ac2-bd3b-dd4433263d80",
"status": "success",
"webhook_type": "wire_transfer"
}
```
O campo de “event_datetime“ esta em formato UTC.
:::info
A “***transaction_key***“ é a chave única de identificação da transferência e poderá ser utilizada posteriormente para solicitação do comprovante de transferência.
:::
**4.2. Estorno de uma TED:** Caso a instituição destinatária devolva a TED, será disparado o seguinte webhook:
**Webhook**
WEBHOOK_TYPE account_transaction
SOURCE_SUB_TYPE withdrawal_reversal
Body
```json
{
"key": "508ebbba-0b1d-41f6-b9a2-975a4c2e925e",
"data": {
"amount": 550,
"origin": {
"name": "TED",
"branch": "0001",
"document": "32402502000135",
"account_key": "23a4a2c8-9d82-4ebe-a90d-44fe8d839ec0",
"account_digit": "7",
"account_number": "00001"
},
"timestamp": "2023-01-05T07:42:26.631137",
"description": "001 0001 81156-1 32.402.502/0001-35 - QI Tech",
"destination": {
"name": "Default",
"branch": "0001",
"document": "23426525852",
"account_key": "508ebbba-0b1d-41f6-b9a2-975a4c2e925e",
"account_digit": "0",
"account_number": "7058818"
},
"reference_key": "58729e67-f490-4607-aafd-2fc7945d3d77",
"reference_type": "ted_outgoing",
"account_balance": 99954.15,
"source_sub_type": "withdrawal_reversal",
"transaction_key": "53268774-6891-42a4-a658-42e21cef867c",
"source_sub_type_str": "Estorno de Transferência"
},
"datetime": "2023-01-05T07:42:26.631137",
"webhook_type": "account_transaction"
}
```
---
### 5 - Registrar e Alterar boletos bancários
**5.1. Consulta de Carteiras de Cobrança:** Para registrar, alterar e pagar boletos, é preciso, primeiramente, possuir o Código da Carteira de Cobrança (Requester Profile Code) vinculada a uma conta. Toda conta já nasce com uma Carteira de Cobrança vinculada.
O Código da Carteira de Cobrança segue o seguinte padrão:
”No. do banco” + “código da carteira” + “No. agência da conta” + “No. da Conta com 7 caracteres e sem dígito“.
Por padrão, na QI Tech, os números do banco, do código da carteira e agência sempre serão “329”, “09” e “0001”, respectivamente.
ex: “**329-09-0001-2359934**”.
Caso seja necessário recuperar a lista de Códigos de Carteira de Cobrança de cada conta, deve ser utilizado o seguinte endpoint:
**Request**
ENDPOINT /bank_slip/requester_profiles
MÉTODO GET
Response Body
```json
{
"requester_profile_codes": [
"329-09-0001-1467576",
"329-09-0001-5747500",
"329-09-0001-2730579",
"329-09-0001-2359934"
]
}
```
:::tip Dica
O registro, alteração e baixa de boletos, funciona através da dinâmica de ocorrências. Cada ocorrência é enviada para a QI Tech e encaminhada para a base centralizadora de boletos.
As ocorrências podem ser aceitas ou rejeitadas pelo base centralizadora de boletos.
A resposta a respeito da aceitação ou rejeição das ocorrências é enviada via webhook ao parceiro.
:::
**5.2. Registrar Boleto:** Para realizar o registro de um boleto, é necessário enviar uma ocorrência de registro, conforme descrito no endpoint abaixo:
**Request**
ENDPOINT /multibank_instruction?use_multi_process=true
MÉTODO POST
Request Body
```json
{
"occurrences": [
{
"amount": 800,
"our_number": 1,
"automatic_bankruptcy_protest": false,
"bank_teller_instructions": "Não aceitar após vencimento",
"days_to_bankruptcy_protest": 0,
"document_number": "123456/01",
"expiration": "2022-12-01",
"fine_percentage": "2",
"interest_daily_value": "0.34",
"occurrence_type": "registration",
"payer_address": "Rua Carlos Sampaio, 123",
"payer_document": "41184562067",
"payer_name": "João Ninguem",
"payer_person_type": "natural",
"payer_postal_code_root": "15800",
"payer_postal_code_suffix": "020",
"registration_institution_enumerator": "qi_scd",
"requester_profile": 9,
"requester_profile_code": "329-09-0001-2359934"
}
]
}
```
:::info
O nosso número bancário (“***our_number***”) é o ID do boleto dentro da carteira de cobrança. Ele deve ser um ID incremental.
O nosso número bancário (“***our_number***”) deve ser gerado pelo parceiro e informado no momento do registro do boleto.
**IMPORTANTE:** O boleto deve ser localizado através da chave: nosso número bancário (“***our_number***”) + Código da Carteira de Cobrança (“***requester_profile_code***).
:::
**Response**
ENDPOINT /multibank_instruction?use_multi_process=true
MÉTODO POST
Response Body
```json
{
"file_info": {
"beneficiary_code": null,
"beneficiary_name": null,
"file_sequence_id": null,
"file_type_identifier": null,
"file_type_literal": null,
"service_code": null,
"service_literal": null,
"wrote_at": null
},
"occurrence_stats": {
"bank_slip_edit": 0,
"bankruptcy_protest_request": 0,
"cancel_rebate": 0,
"extension": 0,
"notary_office_entry": 0,
"notary_office_exit": 0,
"notary_office_payment": 0,
"notification": 0,
"payment": 0,
"payment_notice": 0,
"payment_write_off": 0,
"protest_cancel_and_write_off_request": 0,
"protest_cancel_request": 0,
"protest_remove_request": 0,
"protest_request": 0,
"rebate": 0,
"registration": 1,
"write_off": 0
},
"semantic_errors": []
}
```
**5.3.** A resposta sobre a aceitação ou rejeição do registro do boleto será informada através do seguinte webhook.
**Webhook**
WEBHOOK_TYPE bank_slip.status_change
STATUS registered
Body
```json
{
"key": "41927fa9-f9ed-4797-b48a-6ac68e58dc17",
"data": {
"expiration": "2022-12-01",
"our_number": 1,
"bank_slip_key": "41927fa9-f9ed-4797-b48a-6ac68e58dc17",
"rebate_amount": 0,
"occurrence_type": "registration",
"occurrence_feedback": "confirmed",
"occurrence_sequence": 0,
"requester_profile_code": "329-09-0001-2359934",
"glados_occurrence_reasons": null,
"cnab_file_occurrence_order": 1,
"registration_institution_occurrence_date": "2022-11-21"
},
"status": "registered",
"webhook_type": "bank_slip.status_change",
"event_datetime": "2022-11-22 00:41:32"
}
```
Para vincular o webhook enviado a um boleto, deve-se utilizar o nosso número bancário (“***our_number***”) e o Código da Carteira de Cobrança (“***requester_profile_code***“).
Assim que o registro do boleto é aceito pela base centralizadora, é retornado no webhook a chave UUID do boleto (“***bank_slip_key***“). Guarde essa chave pois através dela será possível recuperar as informações do boleto.
**5.4. Alterar Dados do Boleto:** Para alterar os dados de um boleto, é necessário enviar uma ocorrência. Cada possível alteração possui sua ocorrência correspondente. A lista de ocorrências para alteração dos dados de um boleto pode ser verificada em nossa documentação (/documentation/emissao_de_boleto/enviar_instrucao_de_boleto).
**5.5. Solicitação de 2ª via de boleto:** Após o registro do boleto, pode ser solicitada a geração de um arquivo “.pdf” do boleto, contendo os dados para pagamento.
**Request**
ENDPOINT /bank_slip/2-way/[BANKSLIP-KEY]
MÉTODO POST
Request Body
```json
{}
```
Response Body
```json
{
"bank_slip_file": [{
"barcode": "32991918600000800000001090000000000123599340",
"created_at": "2022-11-21T23:29:45",
"digitable_line": "32990001039000000000101235993407191860000080000",
"url": "https://storage.googleapis.com/sandbox-bank-slip-api/bank-slip-pdf/41927fa9-f9ed-4797-b48a-6ac68e58dc17_1.pdf"
}],
}
```
:::info
Serão retornados todos os dados do boleto e o link para download do “.pdf” será informado no objeto “***bank_slip_file.url***“.
:::
**5.5. Consultar dados de um Boleto:** Os dados de um boleto podem ser consultados de duas formas diferentes.
**5.5.1. Consulta através da linha digitável:** A linha digitável de um boleto é uma série numérica que traz em si as informações do boleto. Esta série numérica é digitada pelo usuário pagador do boleto no internet-banking do banco pagador.
:::info
Exemplo de linha digitável: 32990001031000000000902000000204685640000100000
:::
Através da linha digitável, podem ser consultados os dados do boleto:
**Request**
ENDPOINT /bank_slip/payment
MÉTODO GET
PARAMETERS digitable_line
Response Body
```json
{
"barcode": "32991918600000800000001090000000000123599340",
"beneficiary_bank_code": "329",
"beneficiary_document_number": "09080702000105",
"beneficiary_legal_name": "VOVO LUCIA CONVENIENCIA LTDA",
"beneficiary_person_type": "legal",
"calculated_internally": true,
"calculation_date": "2022-11-21",
"calculation_model": 1,
"digitable_line": "32990001039000000000101235993407191860000080000",
"discount_amount": "0",
"expiration_date": "2022-12-01",
"expired_as_of_payment_date": false,
"expired_as_of_today": false,
"factual_expiration_date": "2022-12-01",
"fine_amount": "0",
"guarantor_document": null,
"guarantor_name": null,
"interest_amount": "0",
"max_payment_date": "2023-05-30",
"nominal_amount": "800.00",
"payer_document_number": "41184562067",
"payer_legal_name": "Jo_o Ninguem",
"payer_person_type": "natural",
"payment_date": "2022-11-21",
"rebate_amount": "0.0",
"total_amount": "800.0",
"valid_payment_amount": true,
"valid_payment_calculation": true,
"valid_payment_time_frame": true
}
```
**5.5.2. Consulta através da Chave do Boleto:** Assim que o registro do boleto é aceito pela base centralizadora, é retornado no webhook a chave UUID do boleto (“***bank_slip_key***“). Através dessa chave é possível recuperar as informações do boleto:
**Request**
ENDPOINT /bank_slip/[BANKSLIP-KEY]
MÉTODO GET
Response Body
```json
{
"barcode": "32991918600000800000001090000000000123599340",
"beneficiary_bank_code": "329",
"beneficiary_document_number": "09080702000105",
"beneficiary_legal_name": "VOVO LUCIA CONVENIENCIA LTDA",
"beneficiary_person_type": "legal",
"calculated_internally": true,
"calculation_date": "2022-11-21",
"calculation_model": 1,
"digitable_line": "32990001039000000000101235993407191860000080000",
"discount_amount": "0",
"expiration_date": "2022-12-01",
"expired_as_of_payment_date": false,
"expired_as_of_today": false,
"factual_expiration_date": "2022-12-01",
"fine_amount": "0",
"guarantor_document": null,
"guarantor_name": null,
"interest_amount": "0",
"max_payment_date": "2023-05-30",
"nominal_amount": "800.00",
"payer_document_number": "41184562067",
"payer_legal_name": "Jo_o Ninguem",
"payer_person_type": "natural",
"payment_date": "2022-11-21",
"rebate_amount": "0.0",
"total_amount": "800.0",
"valid_payment_amount": true,
"valid_payment_calculation": true,
"valid_payment_time_frame": true
}
```
**5.6. Notificação de aviso de recebimento de um Boleto:** No momento em que um boleto é pago em outro banco, é enviado um aviso de que este boleto foi pago em tempo real. A Liquidação financeira do pagamento ocorrerá no próximo dia útil.
**Webhook**
WEBHOOK_TYPE bank_slip.status_change
STATUS payment_notice
Body
```json
{
"key": "945e191d-1a78-4a28-8669-000b7e4a3522",
"data": {
"our_number": 1,
"paid_amount": 800,
"payment_bank": 341,
"bank_slip_key": "41927fa9-f9ed-4797-b48a-6ac68e58dc17",
"payment_method": 2,
"payment_origin": 3,
"occurrence_type": "payment_notice",
"occurrence_feedback": "confirmed",
"occurrence_sequence": 0,
"requester_profile_code": "329-09-0001-2359934",
"registration_institution": "qi_scd",
"cnab_file_occurrence_order": 1,
"registration_institution_occurrence_date": "2022-11-02"
},
"status": "payment_notice",
"webhook_type": "bank_slip.status_change",
"event_datetime": "2022-11-21 23:02:02"
}
```
:::info
“**payment_method:**“ é o meio de pagamento do boleto, podendo ser:
“**credit_card**”: cartão de crédito
”**cash**”: dinheiro
”**account_debit**”: débito em conta
”**check**”: cheque
:::
:::info
payment_origin: é a origem do local do pagamento do boleto, podendo ser:
“**internet**”: Internet Banking
”**phisical_cashier**”: Caixa do Banco (“boca do caixa”)
”**taa**”: Terminal de auto-atendimento
”**eletronic_file**”: CNAB de liquidação
”**call_center**”: Call Center
”**dda**”: DDA (Débito Direto Autorizado)
”**corban**”: Lotérica - Correspondente Bancário
:::
:::caution Atenção
A informação de Método de Pagamento (“***payment_method***“) e Origem do Pagamento (“***payment_origin***“), são dados informados no momento do pagamento do boleto, sua consistência e veracidade fica a cargo da instituição que processou tal pagamento.
:::
---
### 6 - Gerar QR Code PIX
**6.1. Gerando QR Code PIX Estático:** O QR Code é criado a partir de uma Chave PIX ativa cadastrada em uma conta. Após a geração do QR Code, serão retornados tanto a URI do PIX Copia e Cola vinculada ao QR Code, como também o base64 da imagem do QR Code (caso solicitado).
A imagem do QR Code pode ser gerada pelo próprio parceiro a partir da URI do PIX Copia e Cola.
Para gerar um QR Code PIX Estático será usada apenas uma requisição:
**Request**
ENDPOINT /baas/qrcode/static
MÉTODO POST
Request Body
```json
{
"pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
"amount": 35.00,
"receiver_name": "Tywin Lannister",
"qr_code_format": "both"
}
```
:::info
No campo **qr_code_format** poderá ser informado os valores “**image**”, “**payload**“ e “**both**”.
“**image**”: será retornado o campo com o base64 da imagem do QR Code PIX.
“**payload**”: será retornado o campo com o base64 da URI do PIX Copia e Cola do QR Code PIX.
“**both**”: serão retornados os dois campos.
:::
**Response**
ENDPOINT /baas/qrcode/static
MÉTODO POST
Response Body
```json
{
"external_reference_key": null,
"image": "\",
"payload": "\",
"revision": null
}
```
**6.2. Gerando QR Code PIX Dinâmico:** Existem dois tipos de QR Code Dinâmico. O QR Code Dinâmico com Pagamento Instantâneo e o QR Code Dinâmico com Vencimento.
**6.2.1. Gerando QR Code PIX Dinâmico com Vencimento:** É um tipo de QR Code PIX que funciona de forma muito semelhante a um boleto bancário, podendo possuir informação de vencimento, multa, juros por atraso e desconto por pagamento antecipado. Para gerar ester tipo de QR Code PIX é necessário apenas uma requisição no Endpoint “/baas/qrcode/dynamic“.
**Request**
ENDPOINT /baas/qrcode/dynamic
MÉTODO POST
Request Body
```json
{
"amount": 100,
"qr_code_type": "dynamic_term",
"occurrence_type": "registration",
"max_payment_days": 180,
"expiration_date": "2025-09-24",
"pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
"payer_name": "QI Tech",
"payer_document_number": "98765432100",
"payer_person_type": "natural",
"payer_request": "O que voce achou da experiencia",
"rebate_amount": 0,
"interest_amount": 1,
"fine_amount": 2,
"discounts": [{
"limit_date": "2023-02-24",
"amount": 20,
"discount_type": "absolute"
}],
"additional_data": [{
"\": "\"
}]
}
```
:::info
**occurrence_type:** neste campo é informada a ação pretendida. Podem ser: registration, edit, write_off
**registration:** Para criar um novo QR Code
**edit:** Para editar um QR Code já existente (Conforme descrito no item abaixo).
**write_off:** para baixar um QR Code ativo.
**interest_amount:** valor em reais (R$) de juros cobrados por dia de atraso.
**fine_amount:** valor da multa por atraso, em reais (R$).
**discounts:** informação do desconto por pagamento antecipado. Caso não seja aplicável, enviar uma lista vazia ([]).
**additional_data:** são metatags customizáveis que podem ser apresentadas para o pagador no momento do pagamento. Seguem o seguinte padrão: ”\ ”: “\ “.
**tag_name:** possui uma limitação de 100 caracteres e tag_value possui uma limitação de 320 caracteres.
:::
**Response**
ENDPOINT /baas/qrcode/dynamic
MÉTODO POST
Response Body
```json
{
"qr_code_type": "dynamic_term",
"amount": 100,
"expiration_seconds": null,
"max_payment_days": 180,
"receiver_conciliation_id": "3bd19ada234141bf9f1fc5ce0b216723",
"payer_name": "QI Tech",
"payer_document_number": "98765432100",
"payer_person_type": "natural",
"payer_request": "O que voce achou da experiencia",
"pix_message": null,
"modality_alteration": false,
"expiration_date": "2025-09-24",
"rebate_amount": 10,
"interest_amount": 10,
"fine_amount": 10,
"paid_amount": null,
"discounts": [{
"discount_type": "absolute",
"limit_date": "2023-02-24",
"amount": 20
}],
"additional_data": [{
"\": "\"
}],
"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"
}
```
O campo “base_64“ é a URI do PIX Copia e Cola vinculado a este QR Code PIX Dinâmico.
**6.2.2. Gerando QR Code PIX Dinâmico com Pagamento Instantâneo:** É um tipo de QR Code PIX semelhante ao Estático, porém facilita a conciliação por parte do recebedor do pagamento e pode ter vencimento intradia (podendo durar apenas 5 minutos, por exemplo).
Para gerar este tipo de QR Code PIX é necessário apenas uma requisição no Endpoint “***/baas/qrcode/dynamic***”.
**Request**
ENDPOINT /baas/qrcode/dynamic
MÉTODO POST
Request Body
```json
{
"amount": 100,
"occurrence_type": "registration",
"qr_code_type": "dynamic_instant",
"pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
"expiration_seconds": 360,
"payer_name": "QI Tech",
"payer_document_number": "98765432100",
"payer_person_type": "natural",
"payer_request": "Valor referente a compra 1234",
"additional_data": [{
"\": "\"
}]
}
```
**Response**
ENDPOINT /baas/qrcode/dynamic
MÉTODO POST
Response Body
```json
{
"qr_code_type": "dynamic_instant",
"amount": 100,
"expiration_seconds": 360,
"max_payment_days": null,
"receiver_conciliation_id": "8e5af204fa5844eca9707c4facc5e5f5",
"payer_name": "QI Tech",
"payer_document_number": "98765432100",
"payer_person_type": "natural",
"payer_request": "Valor referente a compra 1234",
"pix_message": null,
"modality_alteration": false,
"expiration_date": null,
"rebate_amount": null,
"interest_amount": null,
"fine_amount": null,
"paid_amount": null,
"discounts": [],
"additional_data": [{
"\": "\"
}],
"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 Editar dados de QR Code PIX Dinâmico:** Para editar os dados de um QR Code PIX Dinâmico, é necessário informar a “***qr_code_key***“ do QR Code PIX e “***occurrence_type***” igual a “***edit***”. Nesse caso, é preciso reenviar todos os dados novamente.
**Request**
ENDPOINT /baas/qrcode/dynamic
MÉTODO POST
Request Body
```json
{
"qr_code_key": "3bd19ada-2341-41bf-9f1f-c5ce0b216723",
"amount": 200,
"qr_code_type": "dynamic_term",
"occurrence_type": "edit",
"max_payment_days": 180,
"expiration_date": "2025-09-24",
"pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
"payer_name": "QI Tech",
"payer_document_number": "98765432100",
"payer_person_type": "natural",
"payer_request": "O que voce achou da experiencia",
"rebate_amount": 0,
"interest_amount": 1,
"fine_amount": 2,
"discounts": [{
"limit_date": "2023-02-24",
"amount": 20,
"discount_type": "absolute"
}],
"additional_data": [{
"\": "\"
}]
}
```
**Response**
ENDPOINT /baas/qrcode/dynamic
MÉTODO POST
Response Body
```json
{
"qr_code_type": "dynamic_term",
"amount": 200,
"expiration_seconds": null,
"max_payment_days": 180,
"receiver_conciliation_id": "3bd19ada234141bf9f1fc5ce0b216723",
"payer_name": "QI Tech",
"payer_document_number": "98765432100",
"payer_person_type": "natural",
"payer_request": "O que voce achou da experiencia",
"pix_message": null,
"modality_alteration": false,
"expiration_date": "2025-09-24",
"rebate_amount": 10,
"interest_amount": 10,
"fine_amount": 10,
"paid_amount": null,
"discounts": [{
"discount_type": "absolute",
"limit_date": "2023-02-24",
"amount": 20
}],
"additional_data": [{
"\": "\"
}],
"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. Excluir QR Code PIX Dinâmico:** Para baixar um QR Code PIX Dinâmico, é necessário informar a “***qr_code_key***“ do QR Code PIX e “***occurrence_type***” igual a “***write_off***”.
**Request**
ENDPOINT /baas/qrcode/dynamic
MÉTODO POST
Request Body
```json
{
"qr_code_key": "3bd19ada-2341-41bf-9f1f-c5ce0b216723",
"occurrence_type": "write_off"
}
```
**Response**
ENDPOINT /baas/qrcode/dynamic
MÉTODO POST
Response Body
```json
{
"qr_code_type": "dynamic_term",
"amount": null,
"expiration_seconds": 86400,
"max_payment_days": null,
"receiver_conciliation_id": "3bd19ada234141bf9f1fc5ce0b216723",
"payer_name": null,
"payer_document_number": null,
"payer_person_type": "natural",
"payer_request": null,
"pix_message": null,
"modality_alteration": false,
"expiration_date": null,
"rebate_amount": null,
"interest_amount": null,
"fine_amount": null,
"paid_amount": null,
"discounts": [],
"additional_data": [],
"origin": "system",
"origin_key": null,
"pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
"qr_code_key": "3bd19ada-2341-41bf-9f1f-c5ce0b216723",
"occurrence_type": "write_off",
"end_to_end_id": null,
"base_64": null,
"image": null,
"source_account_branch": null,
"source_account_financial_institution": null,
"source_account_ispb": null,
"source_account_number": null,
"source_account_digit": null,
"qr_code_occurrence_key": "46001adf-ffe2-4534-b60e-f6c16b9af56e"
}
```
**6.4. Decodificando QR Code PIX:** Para decodificar um QR Code seja ele dinâmico ou estático, deve ser usado o seguinte endpoint:
**Request**
ENDPOINT /baas/pix/qrcode
MÉTODO POST
Request Body
```json
{
"qr_code_payload": "\"
}
```
:::info
Neste endpoint deve ser informada a URI do Pix Copia e Cola (link do Pix Copia e Cola).
:::
---
### 7 - Gerenciar Chaves PIX
:::info
A “***pix_key***” pode ser um **CPF**, **CNPJ**, **E-mail**, **Celular** ou uma **Chave Aleatória** (UUID), seguindo as seguintes formatações:
**CPF:** Número inteiro com 11 dígitos.
**CNPJ:** Número inteiro com 14 dígitos.
**E-mail:** Texto contendo ao menos um “@”.
**Celular:** Texto contendo os seguintes valores: “+55” + “[DDD do celular]“ + “\ ”. Ex: “+5511987654321“.
**Chave Aleatória:** UUID.
:::
**7.1. Criar Chave PIX CNPJ e Aleatória:** Para criar uma chave PIX CNPJ ou Chave Aleatória, basta acionar o endpoint “***/baas/pix/keys***“, alterando apenas o “***pix_key_type***“ para “**cnpj**”, “**cpf**“ ou “**random_key**”.
**Request**
ENDPOINT /baas/pix/keys
MÉTODO POST
Request Body
```json
{
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"pix_key_type": "random_key"
}
```
ou
Request Body
```json
{
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"pix_key_type": "cnpj",
"pix_key": "09080702000105"
}
```
ou
**payload.json**
```json
{
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"pix_key_type": "cpf",
"pix_key": "03882617038"
}
```
**Response**
ENDPOINT /baas/pix/keys
MÉTODO POST
Response Body
```json
{
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"created_at": "2022-09-02T18:20:52",
"pix_key": {
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"created_at": "2022-09-02T18:20:51",
"pix_key": "09080702000105",
"pix_key_status": "pending_confirmation",
"pix_key_type": "cnpj",
"updated_at": "2022-09-02T18:20:51"
},
"pix_key_request_key": "d60abf67-ad9c-42ee-9089-d26c8fc855b9",
"request_data": {
"account_created_at": "2022-09-02T22:44:36",
"account_digit": "2",
"account_number": "2359934",
"account_type": "checking",
"branch_number": "0001",
"key": "09080702000105",
"owner_document_number": "09080702000105",
"owner_name": "VOVO LUCIA CONVENIENCIA LTDA",
"owner_person_type": "legal",
"trading_name": "VOVO LUCIA"
},
"request_failure_reason": null,
"request_status": "pending",
"request_type": "inclusion",
"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
"updated_at": "2022-09-02T18:20:52"
}
```
:::caution Atenção
No caso da Response de criação de uma Chave PIX **Aleatória**, o campo “***pix_key***“ retornará um valor nulo, já que se trata de um
processo assíncrono onde a chave é gerada pelo Banco Central. Para recuperar o valor da chave aleatória gerada, é necessária realizar uma consulta à lista de chaves cadastradas em uma conta, conforme descrito no item “**Consultar Chaves PIX cadastradas em uma conta**, ou aguardar o webhook de inclusão.“.
:::
:::info
Como se trata de um processo assíncrono para verificar se as chave PIX **CNPJ** ou **CPF** estão ativas, é necessário realizar uma consulta à lista de chaves cadastradas em um conta, conforme descrito no item “**Consultar Chaves PIX cadastradas em uma conta**", ou aguardar o webhook de inclusão.
:::
**Webhook**
- WEBHOOK_TYPE key_inclusion
Response Body
```json
{
"pix_key": "c232142c-ddbf-41d6-a54f-3b90c28b97dc",
"account_key": "94945886-7a6f-43e6-a307-e36c959e4903",
"webhook_type": "key_inclusion",
"pix_key_status": "active",
"pix_key_request_key": "e274eb13-40b3-4902-978e-8e5fa267af53",
"pix_key_request_type": "inclusion",
"pix_key_request_status": "approved"
}
```
**7.2. Criar Chave PIX E-mail e Celular:** Para criar uma chave PIX **E-mail** ou **Celular** deve-se acionar dois endpoints:
1 - Para criação da chave: POST no endpoint “***/baas/pix/keys***“, alterando o campo “***pix_key_type***“ para “**email**” ou “**phone_number**”. Neste momento, será enviado um Token para o E-mail ou Celular informado no campo “pix_key“.
2 - Para aprovação da chave: PATCH no endpoint “**/baas/pix/keys/[pix_key_request_key]**“, informando o Token recebido na etapa anterior.
**Request**
ENDPOINT /baas/pix/keys
MÉTODO POST
Request Body
```json
{
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"pix_key_type": "email",
"pix_key": "vovo.lucia@gmail.com.br"
}
```
ou
Request Body
```json
{
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"pix_key_type": "phone_number",
"pix_key": "+5511987654321"
}
```
**Response**
ENDPOINT /baas/pix/keys
MÉTODO POST
Response Body
```json
{
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"created_at": "2022-09-02T17:41:55",
"pix_key": {
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"created_at": "2022-09-02T17:41:54",
"pix_key": "pedro.pinho@qitech.com.br",
"pix_key_status": "pending_confirmation",
"pix_key_type": "email",
"updated_at": "2022-09-02T17:41:54"
},
"pix_key_request_key": "f6209b7e-82da-44a8-9cfa-6ad0a689adb2",
"request_data": {
"account_created_at": "2022-09-02T22:44:36",
"account_digit": "2",
"account_number": "2359934",
"account_type": "checking",
"branch_number": "0001",
"key": "pedro.pinho@qitech.com.br",
"owner_document_number": "09080702000105",
"owner_name": "VOVO LUCIA CONVENIENCIA LTDA",
"owner_person_type": "legal",
"trading_name": "VOVO LUCIA"
},
"request_failure_reason": null,
"request_status": "pending",
"request_type": "inclusion",
"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
"updated_at": "2022-09-02T17:41:55"
}
```
:::info
**IMPORTANTE:** O valor retornado no campo “***pix_key_request_key***“ deve ser utilizado na URL da requisição para aprovação da criação da Chave PIX.
:::
**7.3. Aprovação da Chave PIX E-mail ou Celular solicitada:**
**Request**
ENDPOINT /baas/pix/keys/ PIX_KEY_REQUEST_KEY /twofa_validation
MÉTODO PATCH
Request Body
```json
{
"verification_code": "756816"
}
```
**7.4. Reenviar o código de verificação:**
**Request**
- MÉTODO PATCH
- ENDPOINT /baas/pix/keys/ PIX_KEY_REQUEST_KEY /resend_twofa
**payload.json**
```json
{}
```
**7.5. Consultar Chaves PIX cadastradas em uma conta:**
**Request**
ENDPOINT /baas/pix/keys
MÉTODO GET
PARAMETERS account_key
Response Body
```json
{
"data": [
{
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"created_at": "2022-09-02T17:17:31",
"pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
"pix_key_status": "active",
"pix_key_type": "random_key",
"updated_at": "2022-09-02T17:17:31"
},
{
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"created_at": "2022-09-02T18:20:51",
"pix_key": "09080702000105",
"pix_key_status": "active",
"pix_key_type": "cnpj",
"updated_at": "2022-09-02T18:20:51"
}
]
}
```
**7.6. Exclusão de Chaves PIX:**
**Request**
ENDPOINT /baas/pix/keys
MÉTODO DELETE
PARAMETERS /baas/pix/keys/[PIX-KEY]
Payload: { }
Response Body
```json
Response:
{
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"created_at": "2022-09-02T20:00:36",
"pix_key": {
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"created_at": "2022-09-02T18:20:51",
"pix_key": "09080702000105",
"pix_key_status": "inactivated",
"pix_key_type": "cnpj",
"updated_at": "2022-09-02T20:00:36"
},
"pix_key_request_key": "dced4317-c1e7-4da4-a75a-42f855c7598e",
"request_data": {},
"request_failure_reason": null,
"request_status": "approved",
"request_type": "deletion",
"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
"updated_at": "2022-09-02T20:00:36"
}
```
---
### 8 - Pagamento QR Code PIX
**8.1. Pagando um QR Code PIX Estático:**
Para realizar o pagamento de um QR Code PIX Estático, é necessário realizar três chamadas:
Decodificar o QR Code PIX: **/baas/pix/qrcode**
Criação do pedido de transferência: **/baas/pix_transfer**
Aprovação da transferência: **/baas/pix_transfer_approval**
A informação que deve ser utilizada para decodificação do QR Code PIX Estático é a URI do PIX Copia e Cola vinculada ao QR Code.
:::info
**Exemplo de URI PIX Copia e Cola:** 00020126580014br.gov.bcb.pix01360598e5d1-2cfc-4857-abf8-12d495aa0a6d52040000530398654040.225802BR5925VOVO LUCIA CONVENIENCIA L6009sao paulo610912345-78062070503***63043A5A
:::
**Request**
ENDPOINT /baas/pix/qrcode
MÉTODO POST
Request Body
```json
{
"qr_code_payload": "\"
}
```
**Response**
ENDPOINT /baas/pix/qrcode
MÉTODO POST
Response Body
```json
{
"end_to_end_id": "E3240250220221120030008388062101",
"qr_code_data": {
"additional_data": null,
"amount": 30,
"ispb_number": "32402502",
"receiver_conciliation_id": "***",
"target_account_branch": "0001",
"target_account_digit": "5",
"target_account_number": "2",
"target_account_type": "checking",
"target_bank_code": 329,
"target_bank_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
"target_document_number": "32402502000135",
"target_name": "QI SOCIEDADE DE CREDITO DIRETO S.A.",
"target_person_type": "legal",
"target_pix_key": "316bd44f-2202-4c33-9dc0-096192acd427"
},
"qr_code_key": "1608e022-e42d-49d8-bacf-da5844570635",
"qr_code_payload": "00020126580014br.gov.bcb.pix0136316bd44f-2202-4c33-9dc0-096192acd427520400005303986540530.005802BR5925QI SOCIEDADE DE CREDITO D6009sao paulo610912345-78062070503***63048698",
"qr_code_type": "static"
}
```
:::caution Atenção
A requisição para pagar um PIX QR Code Estático é a mesma utilizada na transferência PIX com a as seguintes alterações:
**1 -** Adição de um novo campo “***end_to_end_id***”. Deve ser informado o mesmo valor retornado da decodificação do QR Code Estático;
**2 -** Informar no campo “***transaction_amount***“ o mesmo valor retornado no campo “***qr_code_data.amount***” da decodificação do QR Code Estático;
**3 -** Alterar o campo “***pix_transfer_typ***e” para “static“, para solicitação do pagamento via “/baas/pix_trasnfer”.
:::
:::info
A única diferença desta Response em relação a Response de Aprovação de Transferência PIX, é o valor do campo “***pix_transfer_type***“, que é retornado como sendo “***static***”.
:::
**8.2. Pagando um QR Code PIX Dinâmico:**
Para realizar o pagamento de um QR Code PIX Dinâmico, é necessário realizar três chamadas:
Decodificar o QR Code PIX: **/baas/pix/qrcode**
Criação do pedido de transferência: **/baas/pix_transfer**
Aprovação da transferência: **/baas/pix_transfer_approval**
A informação que deve ser utilizada para decodificação do QR Code PIX Dinâmico é a URI do PIX Copia e Cola vinculada ao QR Code.
:::info
A única alteração no “/baas/pix/qrcode“ entre é QR Code PIX Estático e o QR Code PIX Dinâmico, é a resposta do endpoint.
:::
**Response**
ENDPOINT baas/pix/qrcode
MÉTODO POST
Response Body
```json
{
"end_to_end_id": "E3240250220221120162904592385040",
"qr_code_data": {
"account_type": "checking",
"additional_data": [],
"address": "Avenida Brigadeiro Faria Lima",
"amount": 35,
"category_code": "0000",
"city": "Sao Paulo",
"created_at": "2022-09-01T20:20:11",
"days_after_due_accepted": 180,
"discount_amount": null,
"due_date": "2022-11-30",
"fee_amount": null,
"fine_amount": null,
"ispb_number": "32402502",
"original_amount": null,
"payer_document_number": "10932327656",
"payer_name": "Payer Name",
"payer_person_type": "natural",
"postal_code": "01452000",
"presented_at": "2022-09-01T16:29:04",
"question_to_payer": "QR Code Payment",
"receiver_conciliation_id": "a6c3f35b342047e58ac105a0ae0c0c6f",
"receiver_url": null,
"reduction_amount": null,
"reusable_qrcode": "yes",
"revision": 1,
"state": "SP",
"status": "active",
"target_account_branch": "0001",
"target_account_digit": "5",
"target_account_number": "2",
"target_bank_code": 329,
"target_bank_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
"target_document_number": "32402502000135",
"target_name": "QI SOCIEDADE DE CREDITO DIRETO S.A.",
"target_person_type": "legal",
"target_pix_key": "316bd44f-2202-4c33-9dc0-096192acd427",
"target_trading_name": null
},
"qr_code_key": "a1bcf9be-918d-431e-ae79-a75f78337423",
"qr_code_payload": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/a6c3f35b-3420-47e5-8ac1-05a0ae0c0c6f5204000053039865802BR5902QI6009Sao Paulo61080145200062070503***6304AFEE",
"qr_code_type": "dynamic_term"
}
```
:::caution Atenção
A requisição para pagar um PIX QR Code Dinâmico é a mesma utilizada na transferência PIX com a as seguintes alterações:
**1 -** Adição de um novo campo “***end_to_end_id***”. Deve ser informado o mesmo valor retornado da decodificação do QR Code Dinâmico.
**2 -**Informar no campo “***transaction_amount***“ o mesmo valor retornado no campo “qr_code_data.amount” da decodificação do QR Code Dinâmico;
**3 -** Alterar o campo “***pix_transfer_type***” para “***dynamic_term***“, para solicitação do pagamento via “**/baas/pix_transfer**”.
**4 -** Adição de um novo campo “***receiver_conciliation_id***”. Deve ser informado o mesmo valor retornado da decodificação do QR Code Dinâmico.
:::
:::info
A única diferença desta Response em relação a Response de Aprovação de Transferência PIX, é o valor do campo “***pix_transfer_type***“, que é retornado como sendo “***dynamic_term***”.
::::
---
# Criação de Cessões
URL: /documentation/cessoes/criacao_de_cessao_0eaeffec-ee95-4cb1-a266-bcb52f23237d
A API de cessão permite a criação e consulta de cessões diretamente pelo cliente. É possível criar uma cessão utilizando a key (UUID4) de configuração de cessão e consultar informações gerais da cessão através de endpoints específicos.
:::caution Atenção
Esse serviço está disponível apenas para parceiros com configuração de cessão cadastrados, por favor consulte nosso suporte para mais detalhes.
:::
## Criação de Cessão
Para criar uma cessão, é necessário realizar um POST no endpoint com a chave de configuração do cliente (**assignment_configuration_key**), o conjunto de **credit_operation_keys** das operações de crédito integrantes da cessão, e a **daily_assignment_interest_rate**, que corresponde à taxa de juros diária de cessão. Tal taxa está na mesma base de dias do contrato em questão.
### Request
ENDPOINT /v2/assignment/assignment_configuration/[assignment_configuration_key]/assignment
MÉTODO POST
### Params
| Campo | Descrição |
| ------------------------------ | --------------------------------------------------------- |
| `assignment_configuration_key` | Chave identificadora da configuração de cessão do cliente |
Request Body
```json
{
"credit_operation_keys": ["key1", "key2", "key3"],
"daily_assignment_interest_rate": 0.0003
}
```
:::caution Atenção
Caso a **daily_assignment_interest_rate** não seja informada no Request para os contratos específicos, será usada a taxa de cessão cadastrada na configuração de cessão do cliente.
:::
### Response
STATUS 201
Response Body
```json
[
{
"assignment_key": "868a2951-efff-4e41-8adf-bc36871a20fb",
"creation_datetime": "2023-10-01T12:00:00",
"reference_date": "2023-10-01",
"total_amount": 120000,
"number_of_items": 3,
"status": "pending_items_calculation",
"created_at": "2023-10-01T11:00:00"
}
]
```
## Consulta de Cessão
Para consultar uma cessão específica, o cliente pode realizar um GET no endpoint utilizando a chave identificadora da cessão (**assignment_key**).
### Request
ENDPOINT /v2/assignment/[assignment_key] MÉTODO GET
### Params
| Campo | Descrição |
| ---------------- | ------------------------------ |
| `assignment_key` | Chave identificadora da cessão |
### Response
STATUS 200
Response Body
```json
{
"assignment_key": "77997168-5d61-430f-b5ae-08eb3d7b8c0e",
"creation_datetime": "2023-10-01T12:00:00",
"reference_date": "2023-10-01",
"total_amount": 120000,
"number_of_items": 5,
"term_of_assignment_url": "https://example.com/assignment.pdf",
"status": "settled",
"signable_term_url": "https://example.com/signable_term.pdf"
}
```
## Consulta de Itens da Cessão
Para consultar os contratos na cessão, utilize o GET no endpoint com a mesma **assignment_key**.
### Request
ENDPOINT /v2/assignment/[assignment_key]/assignment_items MÉTODO GET
### Params
| Campo | Descrição |
| ---------------- | ------------------------------ |
| `assignment_key` | Chave identificadora da cessão |
### Response
O retorno é uma lista de informações de cada contrato na cessão (status 200), paginado:
### Response
STATUS 200
Response Body
```json
{
"data": [
{
"assignment_item_key": "439b1257-82ac-4741-a416-a4428a9a7327",
"control_number": "0001",
"credit_operation_key": "d7f2ba40-30ea-4462-890c-6a99a7d85659",
"issuer_name": "João Santos",
"issuer_document_number": "12345678912",
"issue_amount": 50000,
"disbursed_amount": 45000,
"disbursement_date": "2023-01-01",
"number_of_installments": 12,
"contract_number": "XXX182938",
"present_amount": 48000,
"status": "settled",
"endorsement_url": "https://example.com/endorsement.pdf",
"purchaser_document_number": "1234567890001"
}
],
"pagination": {
"page": 1,
"page_size": 10
}
}
```
---
# Abertura de conta escrow PF
URL: /documentation/contas/abertura_de_conta_escrow/abertura_de_conta_escrow_pf
## Request
ENDPOINT /escrow
MÉTODO POST
**Request Body**
```json
{
"account_owner": {
"person_type": "natural",
"name": "Patrícia Tereza Bernardes",
"mother_name": "Maria Mariane",
"birth_date": "1990-05-06",
"nationality": "nationality",
"is_pep": false,
"individual_document_number": "34651104630",
"document_identification": "3c24579b-9810-4fa6-9b08-fe67d237160a",
"email": "api@qitech.com.br",
"address": {
"street": "Av. Brigadeiro Faria Lima",
"state": "SP",
"city": "São Paulo",
"neighborhood": "Jardim Paulistano",
"number": "2391",
"postal_code": "01452905",
"complement": "1o. Andar"
},
"phone": {
"country_code": "055",
"area_code": "11",
"number": "999999999"
},
"proof_of_residence": "780456bd-1eec-4e5f-82c0-d8c3921497ea"
},
"destination_list": [
{
"account_branch": "0001",
"account_digit": "4",
"account_number": "15570",
"document_number": "34651104630",
"financial_institutions_code_number": "329",
"name": "Patrícia Tereza Bernardes",
"ted_account_type": "deposit_account"
}
],
"signed_contract": {
"document_key": "4d7f4e29-4b58-4905-9a69-b1f9215263f5",
"signatures": [
{
"authenticity": {
"timestamp": "1970-01-01T00:00:01.080100Z",
"facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb",
"lang": "-35.8916627",
"lat": "-7.2226067",
"ip_address": "177.51.1.000",
"session_id": "jdifj329842"
},
"signer": {
"name": "IVANILDO DE SENA LIMA",
"email": "teste@gmail.com",
"phone": {
"country_code": "055",
"area_code": "11",
"number": "999999999"
},
"document_number": "99999999999"
},
"authentication_type": "opt-in"
}
]
}
}
```
### Body Params
| Campo |Tipo | Descrição | Caracteres |
|---|---| ---|---|
| `account_owner` * | object | Objeto Dono da conta |**[Objeto account_owner](#objeto-account_owner)** |
| `destination_list` | object | lista de contas de destino, que são aquelas para onde é permitida a transferência de recursos. | **[Objeto destination_list](#objeto-destination_list)** |
| `signed_contract` *| object | Objeto contento as informações da assinatura do contrato. | **[Objeto signed_contract](#objeto-signed_contract)** |
### Objeto account_owner
| Campo | Tipo | Descrição | Caracteres |
|---| ---| ---| ---|
| `address` | string | Endereço do cliente. | **[Objeto adress](#objeto-address)** | |
| `birth_date` * | string | Data de nascimento da pessoa (formato "AAAA-MM-DD") | |
| `document_identification` * | string | DOCUMENT_KEY do PDF do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) | |
| `email` * | string | Email do cliente. | |
| `individual_document_number` | string | CPF da pessoa (apenas números). Limitado a 11 caracteres. | |
| `is_pep` * | string | Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep).| |
| `mother_name` * | string | Nome da mãe do cliente em caso de PF. | 100 |
| `name` * | string | Razão social em caso de operações PJ ou Nome da pessoa em caso de operações PF. | 100 |
| `nationality` * | string | Nacionalidade do cliente. | 50 |
| `person_type` * | string | Identificador de que o objeto enviado é uma pessoa física ou jurídica.| |
| `phone` | string | Objeto com dados do telefone | **[Objeto phone](#objeto-phone)**|
| `proof_of_residence` | string | DOCUMENT_KEY do PDF do comprovante de endereço do endereço enviado (enviado previamente).| |
### Objeto address
Este objeto, presente tanto no objeto PF quanto no objeto PJ, é um simples objeto para representar um endereço.
| Campo | Descrição | Exemplo | Máx. Caracteres |
|---|---|---|---|
| `street` *| string | Rua do endereço | 100 |
| `state` *| string | Estado do endereço (com dois caracteres maiúsculos) | 2 |
| `city` *| string | Cidade do endereço | 100 |
| `neighborhood` *| string |Bairro do endereço | 100 |
| `number` *| string | Número da rua | 10 |
| `postal_code` *| string |CEP do endereço (http://www.buscacep.correios.com.br/sistemas/buscacep/) (apenas números) | 8 |
| `complement` *| string |Complemento do endereço (texto livre) | 100 |
### Objeto signed_contract
| Campo | Tipo | Descrição | Caracteres |
|-------|--------|------------------|---------------|
| **document_key** * | uuidv4 | Chave única de identificação do documento do **Termo de Abertura de Conta** ou **Contrato de Conta Escrow**. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36 |
| **signatures** * | list | Dados de assinatura do documento enviado. Cada item da lista, corresponde a um assinante do documento. | [Objeto signatures](#objeto-signatures) |
### Objeto signatures
| Campo | Tipo | Descrição | Caracteres |
|-------|------------|-------------------|-------------------|
| **authenticity** * | object | Conjunto de dados que evidenciam a assinatura eletrônica realizada pelo assinante. | [Objeto authenticity](#objeto-authenticity) |
| **signer** * | object | Objeto contendo os dados de um dos assinantes do documento. | [Objeto signer](#objeto-signer)|
| **authentication_type** * | enumerator | Tipo de assinatura. Sempre será "**opt-in**"| "**opt-in**" |
### Objeto authenticity
| Campo | Tipo | Descrição | Caracteres |
|-------|--------|-------------------------|------------|
| **timestamp** * | string | Data e hora do momento da assinatura do documento. | 27 |
| **facial_recognition_key** | uuidv4 | Chave única de identificação da foto da selfie do titular da conta. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36 |
| **lang** | string | Coordenada de longitude da geolocalização do assinante capturada no momento da assinatura. | - |
| **lat** | string | Coordenada de latitude da geolocalização do assinante capturada no momento da assinatura. | - |
| **ip_address** | string | Endereço IP do dispositivo do assinante. | - |
| **session_id** | string | ID da seção do assinante no momento da assinatura. | - |
### Objeto signer
| Campo | Tipo | Descrição | Caracteres |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| **name** * | string | Nome do assinante. | - |
| **email** * | string | Email do assinante. | - |
| **phone** * | object | Objeto com dados do telefone do assinante | **[Objeto phone](#objeto-phone)** |
| **document_number** * | string | CPF do assinante. | 11 |
### Objeto phone
| Campo | Descrição | Exemplo | Máx. Caracteres |
| --- | --- | --- | --- |
|`country_code` *| string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 |
| `area_code` *| string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2 |
| `number` *| string |Número de telefone (apenas números) | 10 |
### Objeto phone
| Campo | Descrição | Exemplo | Máx. Caracteres |
| --- | --- | --- | --- |
|`country_code` *| string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 |
| `area_code` *| string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2 |
| `number` *| string |Número de telefone (apenas números) | 10 |
### Objeto destination_list
| Campo | Descrição | Exemplo | Máx. Caracteres |
| --- | --- | --- | --- |
|`account_branch` *| string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 |
| `account_digit` *| string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2 |
| `account_number` *| string |Número de telefone (apenas números) | 10 |
| `document_number` *| string |Número de telefone (apenas números) | 10 |
| `financial_institutions_code_number` *| string |Código COMPE da instituição financeira (https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf) (com 3 dígitos). | 3 |
| `name` *| string |Nome da pessoa física ou razão social da pessoa jurídica. | 10 |
| `ted_account_type` *| enum |Tipo da conta de destino. | **[Enumeradores](#enumeradores-ted_account_type)** |
### Enumeradores ted_account_type
| Enumerador | Tradução |
|---|---|
| checking_account | conta corrente |
| deposit_account | conta depósito |
| guaranteed_account | conta de garantia |
| investment_account | conta de investimento |
| payment_account | conta de pagamento |
| saving_account | conta poupança |
## Response
STATUS 200
**Response Body**
```json
{
"data": {
"account_info": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "66777",
"financial_institution_code": "329"
},
"account_manager": {
"company_representatives": [
{
"document_number": "08141163701",
"name": "Aurora Simone Catarina Nogueira"
}
],
"document_number": "09456933000162",
"name": "Kaique e Giovanna Contábil ME"
},
"account_owner": {
"company_representatives": [
{
"document_number": "38689533370",
"name": "Priscila Rayssa Barros"
},
{
"document_number": "85324558400",
"name": "Caio Bruno Dias"
}
],
"document_number": "98916615000167",
"name": "Alice e Isis Advocacia ME"
},
"allowed_transfer_account_list": [
{
"account_branch": "0001",
"account_digit": "2",
"account_number": "532312",
"document_number": "49067117153",
"financial_institution": {
"code": 341,
"ispb": 60701190,
"name": "Itaú Unibanco S.A."
},
"name": "Juan Anthony Farias"
},
{
"account_branch": "0002",
"account_digit": "9",
"account_number": "537612",
"document_number": "39063217000123",
"financial_institution": {
"code": 33,
"ispb": 90400888,
"name": "Banco Santander (Brasil) S. A."
},
"name": "Farias Advogados"
}
],
"allowed_user": {
"document_number": "13708610440",
"name": "Renato Noah Pinto"
}
},
"event_datetime": "2019-11-07 18:15:07",
"key": "61341599-790b-4236-b42f-060634eba88f",
"status": "waiting_administrator_approval",
"webhook_type": "escrow"
}
```
STATUS 400
**Response Body**
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
---
# Abertura de conta escrow PJ
URL: /documentation/contas/abertura_de_conta_escrow/abertura_de_conta_escrow_pj
## Request
ENDPOINT /escrow
MÉTODO POST
**Request Body**
```json
{
"account_manager": {
"address": {
"city": "São Paulo",
"complement": "",
"neighborhood": "Vila Madalena",
"number": "40",
"postal_code": "05435030",
"state": "SP",
"street": "Rua das batatas"
},
"cnae_code": "6619-3/99",
"company_document_number": "99999999000188",
"company_representatives": [
{
"address": {
"city": "São Paulo",
"complement": "",
"neighborhood": "Vila Madalena",
"number": "40",
"postal_code": "05435030",
"state": "SP",
"street": "Rua da Alegria"
},
"birth_date": "1982-12-30",
"email": "teste@email.tech",
"individual_document_number": "99999999999",
"is_pep": false,
"final_beneficiary": true,
"mother_name": "Ana Perdigão",
"name": "João Victor",
"nationality": "Brasileira",
"person_type": "natural",
"phone": {
"area_code": "12",
"country_code": "055",
"number": "999999999"
},
"document_identification": "a28b9c7d-f0c3-4310-ac6d-61898d29b18d",
"proof_of_residence": "a28b9c7d-f0c3-4310-ac6d-61898d29b18d"
}
],
"company_statute": "a28b9c7d-f0c3-4310-ac6d-61898d29b18d",
"directors_election_minute": "a28b9c7d-f0c3-4310-ac6d-61898d29b18d",
"email": "email@teste.tech",
"foundation_date": "2021-10-05",
"name": "TESTE TECH LTDA.",
"person_type": "legal",
"phone": {
"area_code": "11",
"country_code": "55",
"number": "999999999"
},
"trading_name": "TESTE TECH LTDA."
},
"account_owner": {
"address": {
"city": "Caraguatatuba",
"complement": "complemento",
"neighborhood": "Jaraguazinho",
"number": "924",
"postal_code": "11675200",
"state": "SP",
"street": "Praça da Rua"
},
"cnae_code": "4721-1/02",
"company_statute": "70448962-8f01-4835-b031-755514192641",
"company_document_number": "49999999000130",
"company_type": "ltda",
"email": "email@yteste.com",
"foundation_date": "2017-09-16",
"name": "NOME DA EMPRESA",
"person_type": "legal",
"phone": {
"area_code": "19",
"country_code": "055",
"number": "988888888"
},
"trading_name": "Pães e Doces",
"company_representatives": [
{
"name": "Marco Ayo",
"address": {
"city": "Recife",
"complement": null,
"neighborhood": "Fundão",
"number": "137",
"postal_code": "522222220",
"state": "PE",
"street": "Rua dos Camaroes"
},
"email": "marcos.teste@teste.com",
"birth_date": "1972-02-02",
"individual_document_number": "55555555555",
"document_identification": "70448962-8454-4835-b031-755514192641",
"document_identification_number": "999999999",
"is_pep": false,
"final_beneficiary": true,
"marital_status": "single",
"mother_name": "Sueli da Mata",
"nationality": "Brasileira",
"person_type": "natural",
"phone": {
"area_code": "88",
"country_code": "055",
"number": "999999999"
}
}
]
},
"destination_list": [
{
"account_branch": "0001",
"account_digit": "2",
"account_number": "123321",
"document_number": "99999999999",
"financial_institutions_code_number": "341",
"name": "Conta Destino Teste SA."
}
],
"allowed_user": {
"email": "teste@email.com",
"individual_document_number": "99999999999",
"name": "Luiz Alberto ",
"person_type": "natural",
"phone": {
"country_code": "055",
"area_code": "12",
"number": "999999999"
}
},
"signed_contract": {
"document_key": "4d7f4e29-4b58-4905-9a69-b1f9215263f5",
"signatures": [
{
"authenticity": {
"timestamp": "1970-01-01T00:00:01.080100Z",
"facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb",
"lang": "-35.8916627",
"lat": "-7.2226067",
"ip_address": "177.51.1.000",
"session_id": "jdifj329842"
},
"signer": {
"name": "IVANILDO DE SENA LIMA",
"email": "teste@gmail.com",
"phone": {
"country_code": "055",
"area_code": "11",
"number": "999999999"
},
"document_number": "99999999999"
},
"authentication_type": "opt-in"
}
]
}
}
```
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `account_manager` * | object | Objeto que possui pessoa responsável pelas movimentações da conta. | **[Objeto adress](#objeto-address)** |
| `account_owner` * | object | Objeto Dono da conta. | **[Objeto account_owner](#objeto-account_owner)** |
| `allowed_user` * | object | Objeto que possui pessoa que terá acesso à conta para consultas. | **[Objeto allowed_user](#objeto-allowed_user)** |
| `destination_list` * | object | Lista de contas de destino, que são aquelas para onde é permitida a transferência de recursos. | **[Objeto destination_list](#objeto-destination_list)** |
| `signed_contract` *| object | Objeto contento as informações da assinatura do contrato. | **[Objeto signed_contract](#objeto-signed_contract)** |
### Objeto account_manager
| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `address` *| object | Endereço do cliente. | **[Objeto address](#objeto-address)** |
| `cnae_code` * | string | Classificação Nacional de Atividades Econômicas | 14 |
| `company_document_number` | object | CNPJ | 14|
| `company_statute` *| string | DOCUMENT_KEY do PDF do estatuto da empresa (enviado previamente). | chave uuid |
| `directors_election_minute` *| string | DOCUMENT_KEY do PDF da Ata de Representantes Legais da empresa (enviado previamente). | chave uuid |
| `email` *| string | Email institucional da empresa. | |
| `foundation_date` *| date | Data de abertura da empresa (formato "AAAA-MM-DD"). |
| `name` *| string | Razão social. | |
| `person_type` *| string | Identificador de que o objeto enviado é uma pessoa jurídica. Deve conter SEMPRE o valor "legal" para Objeto PJ. |
| `phone` | string | Objeto com dados do telefone | **[Objeto phone](#objeto-phone)**||
| `trading_name` *| string | Nome fantasia da empresa | |
### Objeto company_representatives
| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `person_type` * | string |Identificador de que o objeto enviado é uma pessoa física. Deve conter SEMPRE o valor "natural" para Objeto PF.| 11 |
| `name` * |string | Razão social em caso de operações PJ ou Nome da pessoa em caso de operações PF. Limitado a 100 caracteres.| 11 |
| `mother_name` * | string |Nome da mãe da pessoa.| 11 |
| `birth_date` * | string | Data de nascimento da pessoa (formato "AAAA-MM-DD") | 11 |
| `nationality` * | string | Nacionalidade do cliente. Limitado a 50 caracteres.| 11 |
| `is_pep` * | string | Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep).| 11 |
| `final_beneficiary` | boolean | Declaração se o representante é beneficiário final da empresa. | - |
| `individual_document_number` | string | CPF da pessoa (apenas números). | 11 |
| `document_identification` * | string | DOCUMENT_KEY do PDF do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) | UUUUID |
| `proof_of_residence` * | UUUUID | DOCUMENT_KEY do PDF do comprovante de residência (enviado previamente) | UUUUID |
| `email` * | string | Email da pessoa. | 11 |
| `address` | string | Objeto endereço da pessoa. | 11 |
### Objeto address
Este objeto, presente tanto no objeto PF quanto no objeto PJ, é um simples objeto para representar um endereço.
| Campo | Descrição | Exemplo | Máx. Caracteres |
|---|---|---|---|
| `street` *| string | Rua do endereço | 10 |
| `state` *| string | Estado do endereço (com dois caracteres maiúsculos) | 2 |
| `city` *| string | Cidade do endereço | 10 |
| `neighborhood` *| string |Bairro do endereço | 10 |
| `number` *| string | Número da rua | 10 |
| `postal_code` *| string |CEP do endereço (http://www.buscacep.correios.com.br/sistemas/buscacep/) (apenas números) | 8 |
| `complement` *| string |Complemento do endereço (texto livre) | 100 |
### Objeto account_owner
| Campo| Tipo | Descrição | Caracteres |
|------|--------|-----------|-------------|
| `address`* | object | Objeto endereço do titular da conta | **[Objeto address](#objeto-address)** |
| `cnae_code` * | string | Classificação Nacional de Atividades Econômicas | 9 |
| `company_document_number` * | string | CNPJ | 14|
| `company_statute` * | string | DOCUMENT_KEY do PDF do estatuto da empresa (enviado previamente). | 36|
| `company_type` | enum | Tipo da empresa | **[Enumeradores company_type](#enumeradores-company_type)** |
| `company_representatives` * | list | Lista dos representantes legais da empresa | **[Objeto company_representatives](#objeto-company_representatives)** |
| `email` * | string | Email institucional da empresa. | 254 |
| `foundation_date` * | string | Data de abertura da empresa (formato "AAAA-MM-DD"). | 10|
| `name` *| string | Razão social. | 100 |
| `person_type` * | enum | Identificador de que o objeto enviado é uma pessoa jurídica. Deve conter SEMPRE o valor "legal" para Objeto PJ.| **[Enumeradores person_type](#enumeradores-person_type)** |
| `phone` * | object | Telefone do titular da conta. | **[Objeto phone](#objeto-phone)** | - |
| `trading_name` * | string | Nome fantasia. | 200 |
### Objeto allowed_user
| Campo | Descrição | Exemplo | Máx. Caracteres |
|---|---|---|---|
| `email` * | string | Email do usuário da conta. | 10 |
| `individual_document_number` * | string | CPF do usuário da conta (apenas números). | 10 |
| `name` * | string | Nome do usuário da conta. | 10 |
| `person_type` * | string | Identificador de que o objeto enviado é uma pessoa física. Deve conter SEMPRE o valor "natural". | 10 |
| `phone` | string | Objeto telefone do usuário. | **[Objeto phone](#objeto-phone)** |
### Objeto destination_list
| Campo | Descrição | Exemplo | Máx. Caracteres |
| --- | --- | --- | --- |
| `account_branch` * | string | Número da agência. | 3 |
| `account_digit` * | string | Dígito verificador da conta (obrigatório caso haja). | 3 |
| `account_number` * | string | Número da conta. | 3 |
| `document_number` * | string | CPF ou CNPJ da pessoa (apenas números). | 3 |
| `financial_institutions_code_number` * | string | Código COMPE da instituição financeira (https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf)| 3 |
| `name` * | string | Nome da pessoa física ou razão social da pessoa jurídica. |
| `ted_account_type` * | enum | Tipo da conta de destino. | **[Enumeradores](#enumeradores-ted_account_type)** |
### Objeto signed_contract
| Campo | Tipo | Descrição | Caracteres |
|-------|--------|------------------|---------------|
| **document_key** * | uuidv4 | Chave única de identificação do documento do **Termo de Abertura de Conta** ou **Contrato de Conta Escrow**. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36 |
| **signatures** * | list | Dados de assinatura do documento enviado. Cada item da lista, corresponde a um assinante do documento. | [Objeto signatures](#objeto-signatures) |
### Objeto signatures
| Campo | Tipo | Descrição | Caracteres |
|-------|------------|-------------------|-------------------|
| **authenticity** * | object | Conjunto de dados que evidenciam a assinatura eletrônica realizada pelo assinante. | [Objeto authenticity](#objeto-authenticity) |
| **signer** * | object | Objeto contendo os dados de um dos assinantes do documento. | [Objeto signer](#objeto-signer)|
| **authentication_type** * | enumerator | Tipo de assinatura. Sempre será "**opt-in**"| "**opt-in**" |
### Objeto authenticity
| Campo | Tipo | Descrição | Caracteres |
|-------|--------|-------------------------|------------|
| **timestamp** * | string | Data e hora do momento da assinatura do documento. | 27 |
| **facial_recognition_key** | uuidv4 | Chave única de identificação da foto da selfie do titular da conta. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36 |
| **lang** | string | Coordenada de longitude da geolocalização do assinante capturada no momento da assinatura. | - |
| **lat** | string | Coordenada de latitude da geolocalização do assinante capturada no momento da assinatura. | - |
| **ip_address** | string | Endereço IP do dispositivo do assinante. | - |
| **session_id** | string | ID da seção do assinante no momento da assinatura. | - |
### Objeto signer
| Campo | Tipo | Descrição | Caracteres |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| **name** * | string | Nome do assinante. | - |
| **email** * | string | Email do assinante. | - |
| **phone** * | object | Objeto com dados do telefone do assinante | **[Objeto phone](#objeto-phone)** |
| **document_number** * | string | CPF do assinante. | 11 |
### Objeto phone
| Campo | Descrição | Exemplo | Máx. Caracteres |
| --- | --- | --- | --- |
|`country_code` *| string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 |
| `area_code` *| string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2 |
| `number` *| string |Número de telefone (apenas números) | 10 |
## Response
STATUS 200
**Response Body**
```json
{
"data": {
"account_info": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "66777",
"financial_institution_code": "329"
},
"account_manager": {
"company_representatives": [
{
"document_number": "08141163701",
"name": "Aurora Simone Catarina Nogueira"
}
],
"document_number": "09456933000162",
"name": "Kaique e Giovanna Contábil ME"
},
"account_owner": {
"company_representatives": [
{
"document_number": "38689533370",
"name": "Priscila Rayssa Barros"
},
{
"document_number": "85324558400",
"name": "Caio Bruno Dias"
}
],
"document_number": "98916615000167",
"name": "Alice e Isis Advocacia ME"
},
"allowed_transfer_account_list": [
{
"account_branch": "0001",
"account_digit": "2",
"account_number": "532312",
"document_number": "49067117153",
"financial_institution": {
"code": 341,
"ispb": 60701190,
"name": "Itaú Unibanco S.A."
},
"name": "Juan Anthony Farias"
},
{
"account_branch": "0002",
"account_digit": "9",
"account_number": "537612",
"document_number": "39063217000123",
"financial_institution": {
"code": 33,
"ispb": 90400888,
"name": "Banco Santander (Brasil) S. A."
},
"name": "Farias Advogados"
}
],
"allowed_user": {
"document_number": "13708610440",
"name": "Renato Noah Pinto"
}
},
"event_datetime": "2019-11-07 18:15:07",
"key": "61341599-790b-4236-b42f-060634eba88f",
"status": "waiting_administrator_approval",
"webhook_type": "escrow"
}
```
STATUS 400
**Response Body**
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
---
# Introdução
URL: /documentation/contas/abertura_de_conta_escrow/introducao
As contas de livre movimentação são quaisquer contas bancárias cujo saldo pode ser sacado movimentado pelo cliente, no todo ou em parte.
Abertura de conta
Assim como a emissão de dívidas, a solicitação de abertura de conta é feita com uma única chamada (não esquecendo que os documentos devem ser previamente enviados).
Recebido esse pedido de conta a QI Tech é responsável por executar o compliance e abrir a conta. Na prática:
1 - Solicitação da abertura de conta (solicitado via request)
2 - Validação de compliance (informado resultado via webhook)
3 - Abertura da conta (informado resultado via webhook)
---
# Abertura de conta PF
URL: /documentation/contas/abertura_de_conta/abertura_de_conta_pf
## Request
ENDPOINT /account
MÉTODO POST
Request Body
```json
{
"account_owner": {
"address": {
"street": "Av. Brigadeiro Faria Lima",
"state": "SP",
"city": "São Paulo",
"neighborhood": "Jardim Paulistano",
"number": "2391",
"postal_code": "01452905",
"complement": "1o. Andar"
},
"birth_date": "1990-05-06",
"document_identification": "3c24579b-9810-4fa6-9b08-fe67d237160a",
"email": "api@qitech.com.br",
"individual_document_number": "34651104630",
"is_pep": false,
"mother_name": "Maria Mariane",
"name": "Qi Tech Ltda.",
"nationality": "nationality",
"person_type": "natural",
"phone": {
"country_code": "055",
"area_code": "11",
"number": "999999999"
},
"proof_of_residence": "780456bd-1eec-4e5f-82c0-d8c3921497ea"
},
"signed_contract": {
"document_key": "4d7f4e29-4b58-4905-9a69-b1f9215263f5",
"signatures": [
{
"authenticity": {
"timestamp": "1970-01-01T00:00:01.080100Z",
"facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb",
"lang": "-35.8916627",
"lat": "-7.2226067",
"ip_address": "177.51.1.000",
"session_id": "jdifj329842"
},
"signer": {
"name": "IVANILDO DE SENA LIMA",
"email": "teste@gmail.com",
"phone": {
"country_code": "055",
"area_code": "11",
"number": "999999999"
},
"document_number": "99999999999"
},
"authentication_type": "opt-in"
}
]
}
}
```
:::info Copiando e Colando o Payload de exemplo
Antes de iniciar os testes, a document_key do campo document_identification deve ser substituida pela chave retornada no upload de documentos dos titulares da conta.
:::
:::info Mock de CPF/CNPJ
Para simular situações de aprovação, reprovação e analise manual pode ser utilizado o primeiro digito do CPF/CNPJ do owner da conta:
0 à 7 -> Análise Manual
8 -> Reprovação Automática
9 -> Aprovação Automática
:::
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|---|---| ---|---|
| `account_owner` | object | Objeto Dono da conta |**[Objeto account_owner](#objeto-account_owner)** |
| `signed_contract` *| object | Objeto contento as informações da assinatura do contrato. | **[Objeto signed_contract](#objeto-signed_contract)** |
### Objeto account_owner
| Campo | Tipo | Descrição | Caracteres |
|---| ---| ---| ---|
| `address` | string | Endereço do cliente. | **[Objeto adress](#objeto-address)** | |
| `birth_date` * | string | Data de nascimento da pessoa (formato "AAAA-MM-DD") | |
| `document_identification` * | string | DOCUMENT_KEY do PDF do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) | |
| `document_identification_back` * | string | DOCUMENT_KEY do PDF do verso documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) | |
| `document_identification_type` * | string | Tipo do documento enviado previamente (RG ou CNH) | |
| `email` * | string | Email do cliente. | |
| `individual_document_number` | string | CPF da pessoa (apenas números). Limitado a 11 caracteres. | |
| `is_pep` * | string | Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep).| |
| `mother_name` * | string | Nome da mãe do cliente em caso de PF. | 100 |
| `name` * | string | Razão social em caso de operações PJ ou Nome da pessoa em caso de operações PF. | 100 |
| `nationality` * | string | Nacionalidade do cliente. | 50 |
| `person_type` * | string | Identificador de que o objeto enviado é uma pessoa física ou jurídica.| |
| `phone` | string | Objeto com dados do telefone | **[Objeto phone](#objeto-phone)**|
| `proof_of_residence` | string | DOCUMENT_KEY do PDF do comprovante de endereço do endereço enviado (enviado previamente).| |
### Objeto address
Este objeto, presente tanto no objeto PF quanto no objeto PJ, é um simples objeto para representar um endereço.
| Campo | Descrição | Exemplo | Máx. Caracteres |
|---|---|---|---|
| `street` *| string | Rua do endereço | 100 |
| `state` *| string | Estado do endereço (com dois caracteres maiúsculos) | 2 |
| `city` *| string | Cidade do endereço | 100 |
| `neighborhood` *| string |Bairro do endereço | 100 |
| `number` *| string | Número da rua | 10 |
| `postal_code` *| string |CEP do endereço (http://www.buscacep.correios.com.br/sistemas/buscacep/) (apenas números) | 8 |
| `complement` *| string |Complemento do endereço (texto livre) | 100 |
### Objeto signed_contract
| Campo | Tipo | Descrição | Caracteres |
|-------|--------|------------------|---------------|
| **document_key** * | uuidv4 | Chave única de identificação do documento do **Termo de Abertura de Conta** ou **Contrato de Conta Escrow**. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36 |
| **signatures** * | list | Dados de assinatura do documento enviado. Cada item da lista, corresponde a um assinante do documento. | [Objeto signatures](#objeto-signatures) |
### Objeto signatures
| Campo | Tipo | Descrição | Caracteres |
|-------|------------|-------------------|-------------------|
| **authenticity** * | object | Conjunto de dados que evidenciam a assinatura eletrônica realizada pelo assinante. | [Objeto authenticity](#objeto-authenticity) |
| **signer** * | object | Objeto contendo os dados de um dos assinantes do documento. | [Objeto signer](#objeto-signer)|
| **authentication_type** * | enumerator | Tipo de assinatura. Sempre será "**opt-in**"| "**opt-in**" |
### Objeto authenticity
| Campo | Tipo | Descrição | Caracteres |
|-------|--------|-------------------------|------------|
| **timestamp** * | string | Data e hora do momento da assinatura do documento. | 27 |
| **facial_recognition_key** | uuidv4 | Chave única de identificação da foto da selfie do titular da conta. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36 |
| **lang** | string | Coordenada de longitude da geolocalização do assinante capturada no momento da assinatura. | - |
| **lat** | string | Coordenada de latitude da geolocalização do assinante capturada no momento da assinatura. | - |
| **ip_address** | string | Endereço IP do dispositivo do assinante. | - |
| **session_id** | string | ID da seção do assinante no momento da assinatura. | - |
### Objeto signer
| Campo | Tipo | Descrição | Caracteres |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| **name** * | string | Nome do assinante. | - |
| **email** * | string | Email do assinante. | - |
| **phone** * | object | Objeto com dados do telefone do assinante | **[Objeto phone](#objeto-phone)** |
| **document_number** * | string | CPF do assinante. | 11 |
### Objeto phone
| Campo | Descrição | Exemplo | Máx. Caracteres |
| --- | --- | --- | --- |
|`country_code` *| string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 |
| `area_code` *| string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2 |
| `number` *| string |Número de telefone (apenas números) | 10 |
## Response
STATUS 200
Response Body
```json
{
"data": {
"account_info": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "70091",
"financial_institution_code": "329",
"account_key": "7986dcc7-4331-478f-af47-adfbdf7f4a36"
},
"account_owner": {
"document_number": "08141163701",
"name": "Aurora Simone Catarina Nogueira"
}
},
"event_datetime": "2019-11-04 16:34:41",
"key": "f834af4d-ab4b-442f-96c9-f9940d8066d4",
"status": "pending_kyc_analysis",
"webhook_type": "account"
}
```
STATUS 400
Response Body
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
---
# Abertura de conta PJ
URL: /documentation/contas/abertura_de_conta/abertura_de_conta_pj
## Abertura de conta PJ com autenticação de dois fatores (2FA)
### Request
ENDPOINT /account
MÉTODO POST
Request Body
```json
{
"account_owner": {
"address": {
"city": "Caraguatatuba",
"complement": "complemento",
"neighborhood": "Jaraguazinho",
"number": "924",
"postal_code": "11675200",
"state": "SP",
"street": "Praça Jorge Vitório de Souza"
},
"cnae_code": "4721-1/02",
"company_statute": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
"company_document_number": "46073462000130",
"company_type": "ltda",
"email": "marcos.alves@yopmail.com",
"foundation_date": "2017-09-16",
"name": "NOME DA EMPRESA",
"person_type": "legal",
"phone": {
"area_code": "19",
"country_code": "055",
"number": "988888888"
},
"trading_name": "Pães e Doces",
"company_representatives": [{
"name": "Marcos Felipe Henrique Alves",
"address": {
"city": "Recife",
"complement": null,
"neighborhood": "Fundão",
"number": "137",
"postal_code": "52221110",
"state": "PE",
"street": "Rua Camapuã"
},
"email": "marcos.alves@yopmail.com",
"birth_date": "1972-02-02",
"individual_document_number": "08531309069",
"document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
"document_identification_number": "339122924",
"is_pep": false,
"final_beneficiary": true,
"marital_status": "single",
"mother_name": "Sueli Isadora Alves",
"nationality": "Brasileira",
"person_type": "natural",
"phone": {
"area_code": "88",
"country_code": "055",
"number": "995924634"
}
}]
},
"account_manager": {
"address": {
"city": "São Paulo",
"complement": "s/c",
"neighborhood": "Pinheiros",
"number": "215",
"postal_code": "05427000",
"state": "SP",
"street": "Rua Gilberto Sabino"
},
"cnae_code": "4721-1/02",
"company_statute": "39e2bf16-26fc-4684-b4c0-97e46029e916",
"company_document_number": "35082434000162",
"company_type": "ltda",
"email": "partneremail@partner.com",
"foundation_date": "2018-09-16",
"name": "Razão Social do Parceiro",
"person_type": "legal",
"phone": {
"area_code": "11",
"country_code": "055",
"number": "987791122"
},
"trading_name": "Parceiro QI",
"company_representatives": [{
"name": "Nome do Socio da Empresa Parceira",
"address": {
"city": "São Paulo",
"complement": null,
"neighborhood": "Pinheiros",
"number": "45",
"postal_code": "04758001",
"state": "SP",
"street": "Rua do sócio"
},
"email": "nomesocio@partner.com",
"birth_date": "1972-02-02",
"individual_document_number": "34527070835",
"document_identification": "ceca505b-b5ef-4e0b-ab62-a6e03d8d636a",
"document_identification_number": "368335446",
"document_identification_type": "rg",
"is_pep": false,
"final_beneficiary": true,
"marital_status": "single",
"mother_name": "Mãe do sócio",
"nationality": "Brasileira",
"person_type": "natural",
"phone": {
"area_code": "11",
"country_code": "055",
"number": "915185434"
}
}]
},
"allowed_user": {
"email": "nomegerente@partner.com",
"individual_document_number": "34651104630",
"name": "Luiz Alberto Da Silva",
"person_type": "natural",
"phone": {
"country_code": "055",
"area_code": "11",
"number": "991611135"
}
},
"signed_contract": {
"document_key": "4d7f4e29-4b58-4905-9a69-b1f9215263f5",
"signatures": [
{
"authenticity": {
"timestamp": "1970-01-01T00:00:01.080100Z",
"facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb",
"lang": "-35.8916627",
"lat": "-7.2226067",
"ip_address": "177.51.1.000",
"session_id": "jdifj329842"
},
"signer": {
"name": "IVANILDO DE SENA LIMA",
"email": "teste@gmail.com",
"phone": {
"country_code": "055",
"area_code": "11",
"number": "999999999"
},
"document_number": "99999999999"
},
"authentication_type": "opt-in"
}
]
}
}
```
## Abertura de conta PJ
### Request
ENDPOINT /account
MÉTODO POST
Request Body
```json
{
"account_owner": {
"address": {
"city": "Caraguatatuba",
"complement": "complemento",
"neighborhood": "Jaraguazinho",
"number": "924",
"postal_code": "11675200",
"state": "SP",
"street": "Praça Jorge Vitório de Souza"
},
"cnae_code": "4721-1/02",
"company_statute": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
"company_document_number": "46073462000130",
"company_type": "ltda",
"email": "marcos.alves@yopmail.com",
"foundation_date": "2017-09-16",
"name": "NOME DA EMPRESA",
"person_type": "legal",
"phone": {
"area_code": "19",
"country_code": "055",
"number": "988888888"
},
"trading_name": "Pães e Doces",
"company_representatives": [{
"name": "Marcos Felipe Henrique Alves",
"address": {
"city": "Recife",
"complement": null,
"neighborhood": "Fundão",
"number": "137",
"postal_code": "52221110",
"state": "PE",
"street": "Rua Camapuã"
},
"email": "marcos.alves@yopmail.com",
"birth_date": "1972-02-02",
"individual_document_number": "08531309069",
"document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
"document_identification_number": "339122924",
"is_pep": false,
"final_beneficiary": true,
"marital_status": "single",
"mother_name": "Sueli Isadora Alves",
"nationality": "Brasileira",
"person_type": "natural",
"phone": {
"area_code": "88",
"country_code": "055",
"number": "995924634"
}
}]
},
"account_manager": {
"address": {
"city": "São Paulo",
"complement": "s/c",
"neighborhood": "Pinheiros",
"number": "215",
"postal_code": "05427000",
"state": "SP",
"street": "Rua Gilberto Sabino"
},
"cnae_code": "4721-1/02",
"company_statute": "39e2bf16-26fc-4684-b4c0-97e46029e916",
"company_document_number": "35082434000162",
"company_type": "ltda",
"email": "partneremail@partner.com",
"foundation_date": "2018-09-16",
"name": "Razão Social do Parceiro",
"person_type": "legal",
"phone": {
"area_code": "11",
"country_code": "055",
"number": "987791122"
},
"trading_name": "Parceiro QI",
"company_representatives": [{
"name": "Nome do Socio da Empresa Parceira",
"address": {
"city": "São Paulo",
"complement": null,
"neighborhood": "Pinheiros",
"number": "45",
"postal_code": "04758001",
"state": "SP",
"street": "Rua do sócio"
},
"email": "nomesocio@partner.com",
"birth_date": "1972-02-02",
"individual_document_number": "34527070835",
"document_identification": "ceca505b-b5ef-4e0b-ab62-a6e03d8d636a",
"document_identification_number": "368335446",
"document_identification_type": "rg",
"is_pep": false,
"final_beneficiary": true,
"marital_status": "single",
"mother_name": "Mãe do sócio",
"nationality": "Brasileira",
"person_type": "natural",
"phone": {
"area_code": "11",
"country_code": "055",
"number": "915185434"
}
}]
},
"allowed_user": {
"email": "teste@email.com",
"individual_document_number": "99999999999",
"name": "Luiz Alberto ",
"person_type": "natural",
"phone": {
"country_code": "055",
"area_code": "12",
"number": "999999999"
}
},
"signed_contract": {
"document_key": "4d7f4e29-4b58-4905-9a69-b1f9215263f5",
"signatures": [
{
"authenticity": {
"timestamp": "1970-01-01T00:00:01.080100Z",
"facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb",
"lang": "-35.8916627",
"lat": "-7.2226067",
"ip_address": "177.51.1.000",
"session_id": "jdifj329842"
},
"signer": {
"name": "IVANILDO DE SENA LIMA",
"email": "teste@gmail.com",
"phone": {
"country_code": "055",
"area_code": "11",
"number": "999999999"
},
"document_number": "99999999999"
},
"authentication_type": "opt-in"
}
]
}
}
```
:::info Copiando e Colando o Payload de exemplo
Antes de iniciar os testes, as document_keys(UUIDs) dos campos company_statute e document_identification devem ser substituidas pelas chaves retornadas no upload de documentos dos titulares da conta.
:::
:::info Mock de CPF/CNPJ
Para simular situações de aprovação, reprovação e analise manual pode ser utilizado o primeiro digito do CPF/CNPJ do owner da conta:
0 à 7 -> Análise Manual
8 -> Reprovação Automática
9 -> Aprovação Automática
:::
### Response
STATUS 200
Response Body
```json
{
"data": {
"account_info": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "5283431",
"financial_institution_code": "329"
},
"account_owner": {
"document_number": "46073462000130",
"name": "NOME DA EMPRESA"
},
"allowed_user": {
"document_number": "34651104630",
"name": "Luiz Alberto Da Silva"
}
},
"event_datetime": "2023-05-05 14:48:32",
"key": "5b5371ae-279c-4aa7-bc1c-776e01fea7cf",
"status": "pending_kyc_analysis",
"webhook_type": "account"
}
```
STATUS 400
Response Body
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
### Request Body Params
| Campo | Tipo | Descrição | Caracteres |
|-----------------------|--------|------------------------------------------------------------------------------|-------------------------------------------------------|
| **account_owner** * | object | Objeto Dono da conta | **[Objeto account_owner](#objeto-account_owner)** |
| **allowed_user** * | object | Usuário vinculado a conta. | **[Objeto allowed_user](#objeto-allowed_user)** |
| **account_manager** | object | Dados do parceiro integrador que realizará a movimentação da conta via API. | **[Objeto account_manager](#objeto-account_manager)** |
| `signed_contract` *| object | Objeto contento as informações da assinatura do contrato. | **[Objeto signed_contract](#objeto-signed_contract)** |
### Objeto account_owner
| Campo | Tipo | Descrição | Caracteres |
|-------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|
| **address** * | object | Objeto endereço do titular da conta | **[Objeto address](#objeto-address)** |
| **cnae_code** * | string | Classificação Nacional de Atividades Econômicas | 9 |
| **company_document_number** * | string | CNPJ | 14 |
| **company_statute** * | string | DOCUMENT_KEY do PDF do estatuto da empresa (enviado previamente). | 36 |
| **company_type** | enum | Tipo da empresa | **[Enumeradores company_type](#enumeradores-company_type)** |
| **company_representatives** * | list | Lista dos representantes legais da empresa | **[Objeto company_representatives](#objeto-company_representatives)** |
| **email** * | string | Email institucional da empresa. | 254 |
| **foundation_date** * | string | Data de abertura da empresa (formato "AAAA-MM-DD"). | 10 |
| **name** * | string | Razão social. | 100 |
| **person_type** * | enum | Identificador de que o objeto enviado é uma pessoa jurídica. Deve conter SEMPRE o valor "legal" para Objeto PJ. | **[Enumeradores person_type](#enumeradores-person_type)** |
| **phone** * | object | Telefone do titular da conta. | **[Objeto phone](#objeto-phone)** | - |
| **trading_name** * | string | Nome fantasia. | 200 |
### Objeto allowed_user
| Campo | Tipo | Descrição | Caracteres |
|----------------------------------|--------|--------------------------------------------------------------------------------------------------|------------------------------------------------------------|
| **email** * | string | Email do usuário da conta. | 254 |
| **individual_document_number** * | string | CPF do usuário da conta (apenas números). | 11 |
| **name** * | string | Nome do usuário da conta. | 100 |
| **person_type** * | enum | Identificador de que o objeto enviado é uma pessoa física. Deve conter SEMPRE o valor "natural". | **[Enumeradores person_type](#enumeradores-person_type)** |
| **phone** | object | Telefone do usuário. | **[Objeto phone](#objeto-phone)** |
### Objeto account_manager
| Campo | Tipo | Descrição | Caracteres |
|-------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------|
| **address** * | object | Objeto endereço do parceiro integrador | **[Objeto address](#objeto-address)** |
| **cnae_code** * | string | Classificação Nacional de Atividades Econômicas | 9 |
| **company_document_number** * | string | CNPJ | 14 |
| **company_statute** * | string | DOCUMENT_KEY do PDF do estatuto da empresa (enviado previamente). | 36 |
| **company_type** | enum | Tipo da empresa | **[Enumeradores company_type](#enumeradores-company_type)** |
| **company_representatives** * | list | Lista dos representantes legais da empresa | **[Objeto company_representatives](#objeto-company_representatives)** |
| **email** * | string | Email institucional da empresa. | 254 |
| **foundation_date** * | string | Data de abertura da empresa (formato "AAAA-MM-DD"). | 10 |
| **name** * | string | Razão social. | 100 |
| **person_type** * | enum | Identificador de que o objeto enviado é uma pessoa jurídica. Deve conter SEMPRE o valor "legal" para Objeto PJ. | **[Enumeradores person_type](#enumeradores-person_type)** |
| **phone** * | object | Telefone do parceiro integrador. | **[Objeto phone](#objeto-phone)** |
| **trading_name** * | string | Nome fantasia. | 200 |
### Objeto company_representatives
| Campo | Tipo | Descrição | Caracteres |
|------------------------------------|---------|--------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
| **name** * | string | Nome do representante da empresa | 100 |
| **address** * | object | Objeto endereço do representante da empresa | **[Objeto address](#objeto-address)** |
| **email** * | string | Email do representante da empresa | 254 |
| **birth_date** * | string | Data de nascimento representante da empresa (formato "AAAA-MM-DD") | 10 |
| **individual_document_number** * | string | CPF do representante da empresa (apenas números). | 11 |
| **document_identification** | string | DOCUMENT_KEY do PDF do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) | 36 |
| **document_identification_number** | string | Número do documento de identificação com foto da pessoa (RG ou CNH) | 16 |
| **is_pep** * | boolean | Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep). | - |
| **final_beneficiary** | boolean | Declaração se o representante é beneficiário final da empresa. | - |
| **marital_status** | enum | Estado civil do representante da empresa | **[Enumeradores marital status](#enumeradores-marital_status)** |
| **mother_name** * | string | Nome da mãe do representante da empresa | 100 |
| **nationality** | string | Nacionalidade do representante da empresa | 50 |
| **person_type** * | enum | Identificador de que o objeto enviado é uma pessoa física | **[Enumeradores person_type](#enumeradores-person_type)** |
| **phone** * | object | Objeto com dados do telefone do representante da empresa | **[Objeto phone](#objeto-phone)** |
### Objeto address
Este objeto, presente tanto no objeto PF quanto no objeto PJ, é um simples objeto para representar um endereço.
| Campo | Descrição | Exemplo | Caracteres |
|--------------------|-----------|-------------------------------------------------------------------------------------------|------------|
| **street** * | string | Rua do endereço | 500 |
| **state** * | enum | Estado do endereço (com dois caracteres maiúsculos) | 2 |
| **city** * | string | Cidade do endereço | 255 |
| **neighborhood** * | string | Bairro do endereço | 500 |
| **number** * | string | Número da rua | 10 |
| **postal_code** * | string | CEP do endereço (http://www.buscacep.correios.com.br/sistemas/buscacep/) (apenas números) | 8 |
| **complement** | string | Complemento do endereço (texto livre) | 500 |
### Objeto signed_contract
| Campo | Tipo | Descrição | Caracteres |
|-------|--------|------------------|---------------|
| **document_key** * | uuidv4 | Chave única de identificação do documento do **Termo de Abertura de Conta** ou **Contrato de Conta Escrow**. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36 |
| **signatures** * | list | Dados de assinatura do documento enviado. Cada item da lista, corresponde a um assinante do documento. | [Objeto signatures](#objeto-signatures) |
### Objeto signatures
| Campo | Tipo | Descrição | Caracteres |
|-------|------------|-------------------|-------------------|
| **authenticity** * | object | Conjunto de dados que evidenciam a assinatura eletrônica realizada pelo assinante. | [Objeto authenticity](#objeto-authenticity) |
| **signer** * | object | Objeto contendo os dados de um dos assinantes do documento. | [Objeto signer](#objeto-signer)|
| **authentication_type** * | enumerator | Tipo de assinatura. Sempre será "**opt-in**"| "**opt-in**" |
### Objeto authenticity
| Campo | Tipo | Descrição | Caracteres |
|-------|--------|-------------------------|------------|
| **timestamp** * | string | Data e hora do momento da assinatura do documento. | 27 |
| **facial_recognition_key** | uuidv4 | Chave única de identificação da foto da selfie do titular da conta. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36 |
| **lang** | string | Coordenada de longitude da geolocalização do assinante capturada no momento da assinatura. | - |
| **lat** | string | Coordenada de latitude da geolocalização do assinante capturada no momento da assinatura. | - |
| **ip_address** | string | Endereço IP do dispositivo do assinante. | - |
| **session_id** | string | ID da seção do assinante no momento da assinatura. | - |
### Objeto signer
| Campo | Tipo | Descrição | Caracteres |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| **name** * | string | Nome do assinante. | - |
| **email** * | string | Email do assinante. | - |
| **phone** * | object | Objeto com dados do telefone do assinante | **[Objeto phone](#objeto-phone)** |
| **document_number** * | string | CPF do assinante. | 11 |
### Objeto phone
| Campo | Descrição | Exemplo | Máx. Caracteres |
| --- | --- | --- | --- |
|`country_code` *| string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 |
| `area_code` *| string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2 |
| `number` *| string |Número de telefone (apenas números) | 10 |
### Enumeradores person_type
| Enum | Description |
|-------------|-------------------|
| **natural** | Pessoa física |
| **legal** | Pessoa jurídica |
### Enumeradores document_identification_type
| Enum | Description |
|---------|----------------------------------------|
| **rg** | RG - Registro Geral |
| **cnh** | CNH - Carteira Nacional de Habilitação |
### Enumeradores company_type
| Enum | Description |
|----------------------------|--------------------------------------------------------------------------|
| **ltda** | Limitada |
| **sa** | Sociedade Anônima |
| **micro_enterprise** | Micro Empresa |
| **freelancer** | Freelancer |
| **sa_opened** | Sociedade Anônima de Capital Aberto |
| **sa_closed** | Sociedade Anônima de Capital Fechado |
| **se_ltda** | Sociedade Empresária Limitada |
| **se_cn** | Sociedade Empresária em Nome Coletivo |
| **se_cs** | Sociedade Empresária em Comandita Simples |
| **se_ca** | Sociedade Empresária em Comandita por Ações |
| **scp** | Sociedade em Conta de Participação |
| **ei** | Empresário Individual |
| **ese** | Estabelecimento, no Brasil, de Sociedade Estrangeira |
| **eeab** | Estabelecimento, no Brasil, de Empresa Binacional Argentino-Brasileira |
| **ssp** | Sociedade Simples Pura |
| **ss_ltda** | Sociedade Simples Limitada |
| **ss_cn** | Sociedade Simples em Nome Coletivo |
| **ss_cs** | Sociedade Simples em Comandita Simples |
| **eireli_ne** | Empresa Individual de Responsabilidade Limitada (de Natureza Empresária) |
| **eireli_ns** | Empresa Individual de Responsabilidade Limitada (de Natureza Simples) |
| **eireli** | Empresa de Responsabilidade Individual |
| **mei** | Micro Empreendedor Individual |
| **me** | Micro Empresa |
| **cop** | Cooperativa |
| **private_association** | Sociedade Privada |
### Enumeradores marital_status
| Enum | Description |
|--------------|---------------|
| **single** | Solteiro(a) |
| **married** | Casado(a) |
| **widower** | Viúvo(a) |
| **divorced** | Divorciado(a) |
| **separated** | Separado(a) |
---
# Rascunho de Conta Livre Movimentação - Pessoa Jurídica
URL: /documentation/contas/abertura_de_conta/draft_checking_legal_person
O fluxo Draft Checking Legal Person permite criar uma solicitação de abertura de conta em duas etapas:
1. **POST**: Cria um draft (rascunho) com **flexibilidade máxima** - aceita desde dados mínimos até dados completos
2. **PATCH**: Submete o draft para processamento, **validando completude** de todos os campos obrigatórios
**Importante**: Este fluxo está sendo preparado para integração com **Monte Bravo**. A divisão de campos entre POST e PATCH será ajustada após alinhamento com Monte Bravo sobre quais dados estarão disponíveis em cada momento do processo.
## Criar Draft de Conta PJ
### Request
ENDPOINT /v2/account_request/draft_checking_legal_person
MÉTODO POST
### Descrição
Este endpoint cria um **draft** de abertura de conta para Pessoa Jurídica (Legal Person). O POST aceita **desde dados mínimos até dados completos**, oferecendo máxima flexibilidade.
### Estratégia de Flexibilidade
- **Dados mínimos**: CNPJ + Nome + Tipo de pessoa
- **Dados parciais**: Adicione campos conforme disponíveis
- **Dados completos**: Envie tudo de uma vez (menos comum)
### Exemplo 1: Payload MÍNIMO (apenas obrigatórios)
Request Body
```json
{
"account_owner": {
"company_document_number": "46073462000130",
"name": "EMPRESA EXEMPLO TECNOLOGIA LTDA",
"person_type": "legal"
}
}
```
```json
{
"request_control_key": "3571e292-3a83-4011-904d-20ee963022ef",
"account_owner": {
"company_document_number": "46073462000130",
"name": "EMPRESA EXEMPLO TECNOLOGIA LTDA",
"person_type": "legal"
}
}
```
**Comportamento**: Se o mesmo `request_control_key` for usado novamente, retorna erro 409 (Conflict) ao invés de criar um novo draft.
### Exemplo 2: Payload COMPLETO (todos os dados de uma vez)
Request Body
```json
{
"account_owner": {
"company_document_number": "46073462000130",
"name": "EMPRESA EXEMPLO TECNOLOGIA LTDA",
"person_type": "legal",
"email": "empresa@exemplo.com.br",
"phone": {
"country_code": "055",
"area_code": "11",
"number": "999999999"
},
"trading_name": "Empresa Exemplo",
"company_type": "LTDA",
"foundation_date": "2010-01-15",
"cnae_code": "6209-1/00",
"company_statute": "92c93e9e-b249-46b7-8c2e-95d4955a3c39",
"monthly_revenue": 150000.00,
"address": {
"street": "Av. Brigadeiro Faria Lima",
"state": "SP",
"city": "São Paulo",
"neighborhood": "Jardim Paulistano",
"number": "2391",
"postal_code": "01452905",
"complement": "Conjunto 102"
},
"company_representatives": [
{
"name": "João Carlos da Silva",
"email": "joao.silva@exemplo.com.br",
"birth_date": "1985-03-20",
"individual_document_number": "12345678901",
"is_pep": false,
"final_beneficiary": true,
"mother_name": "Maria da Silva",
"nationality": "brasileira",
"person_type": "natural",
"phone": {
"country_code": "055",
"area_code": "11",
"number": "988888888"
},
"address": {
"street": "Rua das Flores",
"state": "SP",
"city": "São Paulo",
"neighborhood": "Jardins",
"number": "123",
"postal_code": "01310100",
"complement": "Apto 45"
},
"representative_relationship": "ceo",
"gender": "male",
"marital_status": "married",
"documents": {
"cnh": {
"ocr_key": "7a73be1a-0b66-4c0a-932a-1d1d02efdc4c"
}
}
}
]
}
}
```
### Response
STATUS 201
Response Body
```json
{
"account_request_key": "abc123-def456-...",
"account_request_status": "draft",
"account_info": {
"account_number": "1638634",
"account_digit": "3",
"account_branch": "0001"
}
}
```
:::warning Atenção
O campo `account_request_key` deve ser armazenado e será utilizado para submeter o draft via PATCH.
:::
### Request Body Params
| Campo | Tipo | Descrição | Caracteres |
|-------------------------------|--------|------------------------------------------------------------------------------|---------------------------------------------------------------------|
| `request_control_key` | string | UUID para garantir idempotência (36 caracteres) | 36 |
| `reserved_account_key` | string | UUID de conta reservada previamente (36 caracteres) | 36 |
| `account_owner` * | object | Informações do titular da conta (Pessoa Jurídica) | **[Objeto account_owner](#objeto-account_owner-post)** |
### Objeto account_owner (POST)
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `company_document_number` * | string | CNPJ da empresa (14 dígitos, apenas números) | 14 |
| `name` * | string | Razão social da empresa | 100 |
| `person_type` * | enum | Tipo de pessoa (sempre "legal") | **[Enumeradores person_type](#enumeradores-person_type)** |
| `email` | string | Email da empresa (formato email válido) | 254 |
| `phone` | object | Telefone da empresa | **[Objeto phone](#objeto-phone)** |
| `trading_name` | string | Nome fantasia | 200 |
| `company_type` | enum | Tipo societário | **[Enumeradores company_type](#enumeradores-company_type)** |
| `foundation_date` | string | Data de fundação (formato: YYYY-MM-DD) | 10 |
| `cnae_code` | string | Código CNAE da atividade | 9 |
| `company_statute` | string | UUID do estatuto social (formato UUID) | 36 |
| `monthly_revenue` | number | Faturamento mensal | - |
| `address` | object | Endereço completo da empresa | **[Objeto address](#objeto-address)** |
| `company_representatives` | array | Lista de representantes legais (mínimo 1 item se enviado) | **[Objeto company_representatives](#objeto-company_representatives)** |
:::info Campos Obrigatórios no POST
Apenas 3 campos são obrigatórios no POST:
- `company_document_number`
- `name`
- `person_type`
Todos os demais campos são opcionais e podem ser enviados conforme disponibilidade.
:::
:::warning Validação de Representantes
Se `company_representatives` for enviado no POST, deve ter **pelo menos 1 item** (`minItems: 1`). Cada representante deve ter todos os campos obrigatórios (ver seção PATCH). O campo `documents` dentro de cada representante é **opcional no POST**.
:::
---
## Submeter Draft de Conta PJ
### Request
ENDPOINT /v2/account_request/{account_request_key}/draft_checking_legal_person
MÉTODO PATCH
### Descrição
Este endpoint **submete o draft** para processamento. O PATCH **valida completude** - todos os campos obrigatórios devem estar presentes no payload do PATCH.
**⚠️ IMPORTANTE**: O PATCH **sobrescreve completamente** os dados do `account_owner` com o payload enviado. Isso significa que:
- Você deve enviar **TODOS** os campos obrigatórios no payload do PATCH, mesmo que já tenham sido enviados no POST
- Dados enviados apenas no POST serão **perdidos** se não forem reenviados no PATCH
- O comportamento é de **substituição completa**, não de merge/atualização parcial
- O campo `documents` dentro de cada `company_representative` é **obrigatório** e deve conter pelo menos um tipo de documento válido (RG, CNH, RNE, CRNM, Passaporte ou CIN Digital)
Após a submissão bem-sucedida, o status muda de `draft` para `pending_bacen_validation` e inicia a validação do Bacen Protege+.
### Request Body
Request Body
```json
{
"account_owner": {
"company_document_number": "46073462000130",
"name": "EMPRESA EXEMPLO TECNOLOGIA LTDA",
"person_type": "legal",
"email": "empresa@exemplo.com.br",
"phone": {
"country_code": "055",
"area_code": "11",
"number": "999999999"
},
"trading_name": "Empresa Exemplo",
"company_type": "LTDA",
"foundation_date": "2010-01-15",
"cnae_code": "6209-1/00",
"company_statute": "92c93e9e-b249-46b7-8c2e-95d4955a3c39",
"monthly_revenue": 150000.00,
"address": {
"street": "Av. Brigadeiro Faria Lima",
"state": "SP",
"city": "São Paulo",
"neighborhood": "Jardim Paulistano",
"number": "2391",
"postal_code": "01452905",
"complement": "Conjunto 102"
},
"company_representatives": [
{
"name": "João Carlos da Silva",
"email": "joao.silva@exemplo.com.br",
"birth_date": "1985-03-20",
"individual_document_number": "12345678901",
"is_pep": false,
"final_beneficiary": true,
"mother_name": "Maria da Silva",
"nationality": "brasileira",
"person_type": "natural",
"phone": {
"country_code": "055",
"area_code": "11",
"number": "988888888"
},
"address": {
"street": "Rua das Flores",
"state": "SP",
"city": "São Paulo",
"neighborhood": "Jardins",
"number": "123",
"postal_code": "01310100",
"complement": "Apto 45"
},
"representative_relationship": "ceo",
"gender": "male",
"marital_status": "married",
"documents": {
"rg": {
"ocr_front_key": "0aa8a4ca-5873-49bd-851c-1f2c71a1cc28",
"ocr_back_key": "29f6e346-7fae-4dcb-9ea1-2a3e4ef593ea"
},
"cnh": {
"ocr_key": "7479c8e4-2a5d-4b4d-b2eb-4b841ec9390d"
}
},
"face": "68da08f1-6cf4-4dce-a297-7b2f09311784"
}
]
},
"additional_documents": [
"61f2a65e-0ddf-4932-874f-9231794963da"
]
}
```
### Response
STATUS 200
Response Body
```json
{
"account_request_key": "abc123-def456-...",
"account_request_status": "pending_bacen_validation",
"account_info": {
"account_number": "1638634",
"account_digit": "3",
"account_branch": "0001"
}
}
```
:::info Fluxo Bacen Protege+
Após a submissão bem-sucedida, o status muda para `pending_bacen_validation`. O sistema realiza uma validação prévia junto ao Bacen Protege+ antes de prosseguir com a análise de KYC. Após aprovação do Bacen, o status será atualizado para `pending_kyc_analysis` automaticamente.
:::
### Request Body Params
| Campo | Tipo | Descrição | Caracteres |
|-----------------------|--------|------------------------------------------------------------------------------|---------------------------------------------------------------------|
| `additional_documents` | array | Lista de UUIDs de documentos adicionais (array de UUIDs) | - |
| `account_owner` * | object | Informações completas do titular da conta (Pessoa Jurídica) | **[Objeto account_owner (PATCH)](#objeto-account_owner-patch)** |
### Objeto account_owner (PATCH)
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `company_document_number` * | string | CNPJ (14 dígitos, apenas números, padrão: `^[0-9]{14}$`) | 14 |
| `name` * | string | Razão social | 100 |
| `person_type` * | enum | Sempre `"legal"` | **[Enumeradores person_type](#enumeradores-person_type)** |
| `email` * | string | Email da empresa (formato email válido) | 254 |
| `phone` * | object | Telefone da empresa | **[Objeto phone](#objeto-phone)** |
| `trading_name` * | string | Nome fantasia | 200 |
| `company_type` * | enum | Tipo societário | **[Enumeradores company_type](#enumeradores-company_type)** |
| `foundation_date` * | string | Data de fundação (formato: YYYY-MM-DD) | 10 |
| `cnae_code` * | string | Código CNAE da atividade | 9 |
| `company_statute` * | string | UUID do estatuto social (formato UUID) | 36 |
| `monthly_revenue` * | number | Faturamento mensal | - |
| `address` * | object | Endereço completo da empresa | **[Objeto address](#objeto-address)** |
| `company_representatives` * | array | Lista de representantes legais (mínimo 1 item obrigatório) | **[Objeto company_representatives](#objeto-company_representatives)** |
:::warning Campos Obrigatórios no PATCH
**TODOS** os campos marcados com `*` são obrigatórios no PATCH. O schema JSON valida a completude de todos os campos antes de processar a submissão.
:::
### Objeto phone
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `country_code` * | string | Código do país (1-3 dígitos, padrão: `^[0-9]{1,3}$`) | 1-3 |
| `area_code` * | string | DDD (1-3 dígitos, padrão: `^[0-9]{1,3}$`) | 1-3 |
| `number` * | string | Número do telefone (1-10 dígitos, padrão: `^[0-9]{1,10}$`) | 1-10 |
| `type` | enum | Tipo de telefone (opcional: `"residential"`, `"commercial"`, `"mobile"`, `"fax"`) | - |
### Objeto address
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `street` * | string | Rua/Logradouro | 1-500 |
| `neighborhood` * | string | Bairro | 0-100 |
| `number` * | string | Número | 1-10 |
| `postal_code` * | string | CEP (8 dígitos, apenas números, padrão: `^\d{8}$`) | 8 |
| `city` * | string | Cidade | 1-100 |
| `state` * | enum | Estado (2 caracteres maiúsculos) | **[Enumeradores state](#enumeradores-state)** |
| `complement` | string | Complemento (opcional, máximo 500 caracteres) | 0-500 |
### Objeto company_representatives
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `name` * | string | Nome completo | 100 |
| `address` * | object | Endereço completo (mesma estrutura do address da empresa) | **[Objeto address](#objeto-address)** |
| `email` * | string | Email (formato email válido) | 5-200 |
| `birth_date` * | string | Data de nascimento (formato: YYYY-MM-DD, padrão: `\d{4}-((0[1-9])|(1[0-2]))-((0[1-9])|([1-2][0-9])|(3[0-1]))`) | 10 |
| `individual_document_number` * | string | CPF (11 dígitos, apenas números, padrão: `^[0-9]{11}$`) | 11 |
| `is_pep` * | boolean | Se é Pessoa Politicamente Exposta | - |
| `final_beneficiary` | boolean | Declaração se o representante é beneficiário final da empresa. | - |
| `mother_name` * | string | Nome da mãe | 100 |
| `nationality` * | string | Nacionalidade | 50 |
| `person_type` * | enum | Sempre `"natural"` | **[Enumeradores person_type](#enumeradores-person_type)** |
| `phone` * | object | Telefone (mesma estrutura do phone da empresa) | **[Objeto phone](#objeto-phone)** |
| `documents` * | object | Documentos para antifraude (obrigatório no PATCH) | **[Objeto documents](#objeto-documents)** |
| `face` | string | UUID da foto facial (36 caracteres) | 36 |
| `document_identification` | string | UUID do documento de identificação (formato UUID) | 36 |
| `document_identification_number` | string | Número do documento de identificação | 16 |
| `marital_status` | enum | Estado civil | **[Enumeradores marital_status](#enumeradores-marital_status)** |
| `gender` | enum | Gênero | **[Enumeradores gender](#enumeradores-gender)** |
| `representative_relationship` | enum | Relação com a empresa | **[Enumeradores representative_relationship](#enumeradores-representative_relationship)** |
### Objeto documents
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `rg` | object | Chaves OCR do upload da frente e verso do RG | **[Objeto rg](#objeto-rg)** |
| `cnh` | object | Chave OCR do upload da CNH | **[Objeto cnh](#objeto-cnh)** |
| `cnh_digital` | object | Chave OCR do upload da CNH digital | **[Objeto cnh_digital](#objeto-cnh_digital)** |
| `national_registry_of_foreigners` | object | Chaves OCR do upload da frente e verso do RNE | **[Objeto national_registry_of_foreigners](#objeto-national_registry_of_foreigners)** |
| `national_migration_registry` | object | Chaves OCR do upload da frente e verso do CRNM | **[Objeto national_migration_registry](#objeto-national_migration_registry)** |
| `passport` | object | Chave OCR do upload do passaporte | **[Objeto passport](#objeto-passport)** |
| `cin_digital` | object | Chave OCR do upload da Cédula de Identidade Nacional digital | **[Objeto cin_digital](#objeto-cin_digital)** |
### Objeto rg
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `ocr_front_key` * | uuidv4 | Chave OCR do upload da imagem da frente do RG | 36 |
| `ocr_back_key` * | uuidv4 | Chave OCR do upload da imagem do verso do RG | 36 |
OU
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `ocr_key` * | uuidv4 | Chave OCR do upload da imagem do RG | 36 |
### Objeto cnh
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `ocr_front_key` * | uuidv4 | Chave OCR do upload da imagem da frente da CNH | 36 |
| `ocr_back_key` * | uuidv4 | Chave OCR do upload da imagem do verso da CNH | 36 |
OU
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `ocr_key` * | uuidv4 | Chave OCR do upload da imagem da CNH | 36 |
### Objeto cnh_digital
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `ocr_key` * | uuidv4 | Chave OCR do upload da imagem da CNH digital | 36 |
### Objeto national_registry_of_foreigners
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `ocr_front_key` * | uuidv4 | Chave OCR do upload da imagem da frente do RNE | 36 |
| `ocr_back_key` * | uuidv4 | Chave OCR do upload da imagem do verso do RNE | 36 |
OU
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `ocr_key` * | uuidv4 | Chave OCR do upload da imagem do RNE | 36 |
### Objeto national_migration_registry
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `ocr_front_key` * | uuidv4 | Chave OCR do upload da imagem da frente do CRNM | 36 |
| `ocr_back_key` * | uuidv4 | Chave OCR do upload da imagem do verso do CRNM | 36 |
OU
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `ocr_key` * | uuidv4 | Chave OCR do upload da imagem do CRNM | 36 |
### Objeto passport
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `ocr_key` * | uuidv4 | Chave OCR do upload da imagem do passaporte | 36 |
### Objeto cin_digital
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `ocr_key` * | uuidv4 | Chave OCR do upload da imagem da Cédula de Identidade Nacional digital | 36 |
:::info Informação
As chaves OCR (`ocr_key` ou `ocr_front_key` e `ocr_back_key`) do upload das imagens dos documentos são fornecidas como resposta do upload das imagens no antifraude. A `face_recognition_key` é retornada na resposta do reconhecimento facial.
:::
### Response Body Params
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `account_request_key` * | string | Chave de identificação da requisição de criação | - |
| `account_request_status` * | string | Status da requisição (muda para `pending_bacen_validation` após submissão) | - |
| `account_info` * | object | Objeto contendo as informações da conta | **[Objeto account_info](#objeto-account_info)** |
### Objeto account_info
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `account_branch` * | string | Número da Agência | 4 |
| `account_digit` * | string | Dígito verificador da conta | 1 |
| `account_number` * | string | Número da conta | - |
### Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição(ptbr)
`translation`|
|---| --- | --- | --- | --- |
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema|
| 400 | - | Bad Request | Invalid request body | Corpo da requisição inválido |
| 404 | QIT000404 | Not Found | Resource could not be found | Recurso não encontrado|
| 409 | - | Conflict | Duplicate request_control_key | Chave de controle duplicada |
---
## Diferenças entre POST e PATCH
| Aspecto | POST (Criar Draft) | PATCH (Submeter Draft) |
|---------|-------------------|------------------------|
| **Objetivo** | Criar draft com flexibilidade | Validar completude e submeter ao Bacen |
| **Campos Obrigatórios** | Apenas CNPJ + Nome + Tipo | TODOS os campos + 1 representante completo **com documents** |
| **documents** | Opcional por representante | **Obrigatório por representante** (objeto com documentos OCR) |
| **Representantes** | Opcional | Obrigatório (mínimo 1) |
| **Validação** | Mínima (apenas 3 campos) | Completa (todos os campos obrigatórios) |
| **Status Inicial** | N/A | `draft` (deve estar neste status) |
| **Status Final** | `draft` | `pending_bacen_validation` |
| **Validação Bacen** | Não | Sim |
| **Análise KYC** | Não | Sim (após Bacen) |
| **Idempotência** | Sim (via `request_control_key`) | Não |
---
## Cenários de Uso
### Cenário 1: Cliente tem apenas dados básicos inicialmente
```
POST → {CNPJ, nome, tipo} [status: draft]
...cliente coleta mais dados...
PATCH → {todos os campos + documents por representante} [status: pending_bacen_validation]
```
### Cenário 2: Cliente tem todos os dados de uma vez
```
POST → {todos os campos} [status: draft]
PATCH → {todos os campos} [status: pending_bacen_validation]
```
### Cenário 3: Cliente envia dados parciais gradualmente
```
POST → {CNPJ, nome, tipo, email} [status: draft]
...cliente coleta mais dados...
PATCH → {todos os campos incluindo representantes com documents} [status: pending_bacen_validation]
```
---
## Enumeradores
### Enumeradores person_type
| Enum | Descrição |
|------|-----------|
| `natural` | Pessoa física |
| `legal` | Pessoa jurídica |
### Enumeradores company_type
| Enum | Descrição |
|------|-----------|
| `ltda` | Limitada |
| `sa` | Sociedade Anônima |
| `micro_enterprise` | Micro Empresa |
| `freelancer` | Freelancer |
| `sa_opened` | Sociedade Anônima de Capital Aberto |
| `sa_closed` | Sociedade Anônima de Capital Fechado |
| `se_ltda` | Sociedade Empresária Limitada |
| `se_cn` | Sociedade Empresária em Nome Coletivo |
| `se_cs` | Sociedade Empresária em Comandita Simples |
| `se_ca` | Sociedade Empresária em Comandita por Ações |
| `scp` | Sociedade em Conta de Participação |
| `ei` | Empresário Individual |
| `ese` | Estabelecimento, no Brasil, de Sociedade Estrangeira |
| `eeab` | Estabelecimento, no Brasil, de Empresa Binacional Argentino-Brasileira |
| `ssp` | Sociedade Simples Pura |
| `ss_ltda` | Sociedade Simples Limitada |
| `ss_cn` | Sociedade Simples em Nome Coletivo |
| `ss_cs` | Sociedade Simples em Comandita Simples |
| `eireli_ne` | Empresa Individual de Responsabilidade Limitada (de Natureza Empresária) |
| `eireli_ns` | Empresa Individual de Responsabilidade Limitada (de Natureza Simples) |
| `eireli` | Empresa de Responsabilidade Individual |
| `mei` | Micro Empreendedor Individual |
| `me` | Micro Empresa |
| `cop` | Cooperativa |
| `private_association` | Sociedade Privada |
### Enumeradores state
| Enum | Descrição |
|------|-----------|
| `AC` | Acre |
| `AL` | Alagoas |
| `AM` | Amazonas |
| `AP` | Amapá |
| `BA` | Bahia |
| `CE` | Ceará |
| `DF` | Distrito Federal |
| `ES` | Espírito Santo |
| `GO` | Goiás |
| `MA` | Maranhão |
| `MG` | Minas Gerais |
| `MS` | Mato Grosso do Sul |
| `MT` | Mato Grosso |
| `PA` | Pará |
| `PB` | Paraíba |
| `PE` | Pernambuco |
| `PI` | Piauí |
| `PR` | Paraná |
| `RJ` | Rio de Janeiro |
| `RN` | Rio Grande do Norte |
| `RO` | Rondônia |
| `RR` | Roraima |
| `RS` | Rio Grande do Sul |
| `SC` | Santa Catarina |
| `SE` | Sergipe |
| `SP` | São Paulo |
| `TO` | Tocantins |
| `EX` | Exterior |
### Enumeradores marital_status
| Enum | Descrição |
|------|-----------|
| `single` | Solteiro(a) |
| `married` | Casado(a) |
| `widower` | Viúvo(a) |
| `divorced` | Divorciado(a) |
| `separated` | Separado(a) |
### Enumeradores gender
| Enum | Descrição |
|------|-----------|
| `male` | Masculino |
| `female` | Feminino |
### Enumeradores representative_relationship
| Enum | Descrição |
|------|-----------|
| `ceo` | CEO / Diretor Presidente |
| `analyst` | Analista |
| `partner` | Sócio |
| `director` | Diretor |
| `attorney` | Procurador |
| `signer` | Assinante |
---
## Fluxo Completo
1. **POST** `/v2/account_request/draft_checking_legal_person`
- Cria draft com dados disponíveis
- Status: `draft`
- Retorna: `account_request_key`
2. **(Opcional)** Coletar dados adicionais
3. **PATCH** `/v2/account_request/{account_request_key}/draft_checking_legal_person`
- Valida completude de todos os campos
- Envia para Bacen Protege+
- Status: `pending_bacen_validation`
4. **Bacen Protege+ valida** (assíncrono)
- Status: `pending_kyc_analysis` (se aprovado)
5. **KYC analisa pessoa jurídica**
- Status: `approved` (se tudo OK)
6. **Conta criada e pronta para uso**
---
---
# fluxo_de_abertura_de_conta
URL: /documentation/contas/abertura_de_conta/fluxo_de_abertura_de_conta
### Conta de livre movimentação
As contas de livre movimentação são quaisquer contas bancárias cujo saldo pode ser sacado movimentado pelo cliente, no todo ou em parte.
Abertura de conta
Assim como a emissão de dívidas, a solicitação de abertura de conta é feita com uma única chamada (não esquecendo que os documentos devem ser previamente enviados).
Recebido esse pedido de conta a QI Tech é responsável por executar o compliance e abrir a conta. Na prática:
1 - Solicitação da abertura de conta (solicitado via request)
2 - Validação de compliance (informado resultado via webhook)
3 - Abertura da conta (informado resultado via webhook)
---
# Introdução
URL: /documentation/contas/abertura_de_conta/introducao
Uma das funcionalidades que podemos oferecer em nossa integração é a possibilidade de gerenciar contas e transferências para contas da QI Tech ou de outras instituições financeiras via API, mas não é só isso, provemos a possibilidade de fazer a ABERTURA de uma conta via API. Seja para você mesmo, ou para terceiros.
Assim como as demais APIs a liberação do serviço deve ser feita junto ano nosso time e as chamadas são autenticadas.
Nas subseções abaixo veremos como abrir e gerenciar uma conta de pagamento dentro da QI Tech.
---
# Webhooks de abertura de conta
URL: /documentation/contas/abertura_de_conta/webhooks_contas
A resposta da solicitação de abertura de conta poderá retornar o status “pending_kyc_analysis” a depender da configuração de integração do parceiro.
Neste caso, a resposta sobre a aprovação ou reprovação da abertura da conta será retornada de forma assíncrona via webhook.
O número de conta será reservado no momento da solicitação de abertura, porém neste momento **a conta ainda não estará aberta**. Somente após a conclusão da análise de KYC da QI Tech a conta estará aberta.
## Contas de Pessoa Jurídica
# Account Opened
WEBHOOK_TYPE account
STATUS account_opened
Webhook Body
```json
{
"data": {
"account_info": {
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"account_digit": "2",
"account_branch": "0001",
"account_number": "2359934",
"financial_institution_code": "329"
},
"allowed_user": {
"name": "Juliana Tereza Bernardes",
"document_number": "12364480084"
},
"account_owner": {
"name": "VOVO LUCIA CONVENIENCIA LTDA",
"document_number": "12380702000105"
}
},
"event_datetime": "2022-09-02 22:39:39",
"key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
"status": "account_opened",
"webhook_type": "account"
}
```
# Account Rejected
WEBHOOK_TYPE account
STATUS account_rejected
Webhook Body
```json
{
"data": {
"account_info": {
"account_digit": "2",
"account_branch": "0001",
"account_number": "2359934",
"financial_institution_code": "329"
},
"allowed_user": {
"name": "Juliana Tereza Bernardes",
"document_number": "97564480084"
},
"account_owner": {
"name": "VOVO LUCIA CONVENIENCIA LTDA",
"document_number": "09080702000105"
}
},
"event_datetime": "2022-09-02 22:39:39",
"key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
"status": "account_rejected",
"webhook_type": "account"
}
```
## Contas de Pessoa Física
# Account Opened
WEBHOOK_TYPE account
STATUS account_opened
Webhook Body
```json
{
"key":"b5978088-2860-4b78-bd44-77b961354014",
"data":{
"account_info":{
"account_key":"b7593804-2223-48b3-8a61-f48a651de1d4",
"account_digit":"5",
"account_branch":"0001",
"account_number":"3998360",
"financial_institution_code":"329"
},
"account_owner":{
"name":"Pedro Pinho",
"document_number":"97634408077"
}
},
"status":"account_opened",
"webhook_type":"account",
"event_datetime":"2024-01-09 14:35:46"
}
```
# Account Rejected
WEBHOOK_TYPE account
STATUS account_rejected
Webhook Body
```json
{
"key":"84864614-2860-4b78-bd44-77b961354014",
"data":{
"account_info":{
"account_key":"1435dbavf-2860-4b78-bd44-77b961354014",
"account_digit":"5",
"account_branch":"0001",
"account_number":"3998360",
"financial_institution_code":"329"
},
"account_owner":{
"name":"Pedro Pinho",
"document_number":"97634408077"
}
},
"status":"account_rejected",
"webhook_type":"account",
"event_datetime":"2024-01-09 14:35:46"
}
```
---
# Criar conta destino para escrow
URL: /documentation/d88ff174-100d-4b55-80b7-86e11f508400
Este endpoint permite criar uma conta destino para uma conta escrow
## Request
### Request Endpoint
ENDPOINT /account/ ACCOUNT_KEY /destination
MÉTODO POST
### Request Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` * | uuid4 | Chave única de identificação da conta. | 36 |
Request Body: adição de conta destino
```json
{
"name": "Minha conta destino",
"ted_account_type": "checking_account",
"document_number": "51297635200133",
"account_branch": "3422",
"account_digit": "8",
"account_number": "08042",
"financial_institutions_code_number": "329"
}
```
### Body Params
| Campo | Tipo | Descrição |
|----------------------------------------------|--------|-----------------------------------|
| `name` * | string | Nome do destinatário |
| `ted_account_type` * | enum | Tipo de conta destino. |
| `account_branch` * | string | Agência da conta destino . |
| `account_digit` * | string | digito da conta destino. |
| `account_number` * | string | número da conta destino. |
| `financial_institutions_code_number` * | string | código do banco da conta destino. |
## Response
### Success Response
STATUS 201
Response Body:
```json
{}
```
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Descrição em português",
"code": "Código"
}
```
| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|-----------------------------------------------|-------------------------------------------------|---------------------------------------------------------|
| 404 | ACC000006 | Not found | Account not found for the given key ACCOUNT_KEY | Conta não encontrada para a seguinte chave ACCOUNT_KEY |
| 403 | ACC000219 | Requester not allowed to perform this action | Requester not allowed to create destination | Requester não autorizado a criar conta destino |
---
# Recuperação de termo de aceite e cancelamento de cadastro no DDA
URL: /documentation/dda/recuperacao_termo
Os termos de aceite e cancelamento do DDA (Débito Direto Autorizado) são documentos que regulamentam a autorização do cliente para utilizar o serviço de débito direto em sua conta bancária, bem como o procedimento para cancelar essa autorização, se desejado.
O termo de aceite do DDA é o documento em que o cliente formalmente consente e autoriza o débito automático das suas contas e faturas em sua conta bancária. Esse termo estabelece os direitos e responsabilidades do cliente e da instituição financeira, além de definir as condições de uso do DDA. Ele geralmente contém informações como identificação do cliente e da instituição financeira, autorização para débito automático, identificação dos pagamentos autorizados, período de vigência, direitos e responsabilidades do cliente, e direitos e responsabilidades da instituição financeira.
Já o termo de cancelamento de adesão ao DDA é o documento que permite ao cliente revogar a autorização concedida anteriormente e solicitar o cancelamento do serviço de débito direto. Esse termo geralmente requer a assinatura do cliente e a notificação da instituição financeira para interromper os débitos automáticos. É importante seguir o procedimento de cancelamento estabelecido pelo banco, que pode incluir o envio de uma solicitação por escrito, preenchimento de formulários específicos ou comunicação por meios eletrônicos.
Ambos os termos têm como objetivo garantir a transparência e a segurança nas transações financeiras do cliente, fornecendo uma base legal para o serviço de débito direto. O termo de aceite formaliza a autorização inicial e estabelece os termos e condições do serviço, enquanto o termo de cancelamento permite ao cliente encerrar a adesão ao DDA, caso não deseje mais utilizar essa forma de pagamento automático.
:::info Informação
Caso a conta seja reativada no DDA após um cancelamento, o termo de cancelamento não será retornado em consultas posteriores.
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /term/ TYPE
MÉTODO GET
### Path Params
| Campo | Tipo | Descrição | Caracteres |
| ------------- | ------ | ---------------------------------------------------------- | ---------- |
| `account_key` | string | Chave de identificação da conta cadastrada no DDA | 36 |
| `type` | enum | [Enumeradores tipo de termo.](#enumeradores-tipo-de-termo) | - |
### Enumeradores tipo de termo
| Enumerador | Descrição |
| -------------- | ------------------------------ |
| `agreement` | Assinatura DDA |
| `cancellation` | Cancelamento de assinatura DDA |
## Response
STATUS 200
Response Body
```json
{
"authorization_term": {
"document_number": "12345678910",
"signature": {
"signer": {
"name": "Jose da Silva",
"email": "ownermail@mail.com",
"phone": {
"number": "0987654321",
"area_code": "11",
"country_code": "55"
},
"document_number": "12345678910"
},
"authentication_type": "opt_in",
"authenticity": {
"timestamp": "1970-01-01T00:00:01.080100Z",
"ip_address": "177.51.1.000",
"fingerprint": {
"browser": "Mozila"
},
"third_party_additional_data": {},
"session_id": "10c33308-866f-47e5-bec8-2e512e9c0237"
},
"signed_object": {
"raw_text": "Lorem ipsum dolor sit amet, consectetur a...."
}
}
}
}
```
| Campo | Tipo | Descrição | Caracteres |
| -------------------- | ------ | ------------------------------------------ | ---------- |
| `authorization_term` | object | Dados da autorização assinada pelo pagador | - |
---
# acg1
URL: /documentation/documentacoes ocultas/agc1/acg1
## Request
- ENDPOINT /baas/historic_card_settlement
- MÉTODO POST
**body.json**
```json
{
"person_type": "natural",
"name": "João Ninguem",
"document_number": "42866592832",
"signatures": [{
"signed_object": {
"raw_text": "Lorem ipsum dolor sit amet, consectetur a....",
"document_key": "79003de0-2590-455d-9b73-426b8ca284eb",
"document_md5": "7521bd5621d97af26b2c1721fc4023a8"
},
"authenticity": {
"timestamp": "1970-01-01 00:00:01",
"ip_address": "179.104.42.245",
"session_id": "ddb1d063-4fdf-4330-af9c-3316e9142ff3",
"facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb",
"document_key": "79003de0-2590-455d-9b73-426b8ca284eb",
"document_md5": "79003de0-2590-455d-9b73-426b8ca284eb"
},
"signer": {
"name": "IVANILDO DE SENA LIMA",
"email": "ivanlima2604@gmail.com",
"phone": {
"country_code": "055",
"area_code": "11",
"number": "999999999"
},
"document_number": "61766976204"
},
"authentication_type": "opt-in"
}]
}
```
### Body Params
| Campo | Tipo | Descrição |
|---|---| ---|
| `person_type` | enum | Tipo de pessoa a ser consultada. | -- |
| `name` | string | Nome do consultado. | -- |
| `document_number` | string | CPF ou CNPJ do consultado. | -- |
| `signatures` | array of objects | Lista contendo objetos de signatarios. | -- |
## Enumeradores
### Enumeradores marital_status
| Enumerador | Tradução |
|---|---|
| natural | Pessoa fisica |
| legal | Pessoa juridica |
## Response
status: 201
**Response Body: PF**
```json
{
"person_type": "natural",
"name": "Sample Natural Person",
"document_number": "50727483161",
"signers": [
{
"name": "Sample Natural Person",
"document_number": "50727483161",
"email": "sample@gmail.com",
"phone_number": "34987654321",
"signature": {
"authenticity": {
"ip_address": "127.0.0.1",
"session_id": "120a0a3ae723ff2858f9e0360f123723",
"third_party_access_token": "558f1a0b-38de-4b8d-b678-14b052adb1db",
"third_party_additional_data": {}
},
"signable_object": {
"document_key": "a43c1dde-0ecd-4086-8b94-714277a2dcee",
"document_md5": "57c0906e3c9902403ba373d9a7650f0a"
}
}
}
],
"historic_card_settlement_key": "74bf0f2e-8c53-4b5b-90bf-a0d21022bcff",
"status": "signed",
"historic_card_settlement_date": "2022-05-18T19:38:44"
}
```
status: 201
**Response Body: PJ**
```json
{
"person_type": "legal",
"name": "Sample Legal Person",
"document_number": "28001500",
"signers": [
{
"name": "Sample Signer",
"document_number": "50727483161",
"email": "sample@gmail.com",
"phone_number": "34987654321",
"signature": {
"authenticity": {
"ip_address": "127.0.0.1",
"session_id": "120a0a3ae723ff2858f9e0360f123723",
"third_party_access_token": "candidate - 37767",
"third_party_additional_data": {}
},
"signable_object": {
"document_key": "a43c1dde-0ecd-4086-8b94-714277a2dcee",
"document_md5": "57c0906e3c9902403ba373d9a7650f0a"
}
}
}
],
"historic_card_settlement_key": "c2d4bfd3-6eaf-40ee-9eb1-697992336dbb",
"status": "signed",
"historic_card_settlement_date": "2022-05-18T19:37:38"
}
```
status: 400
**body.json**
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
## Webhooks
Após o envio de uma solicitação de consulta o resto do fluxo fica a cargo da QI Tech. Será então enviado um webhook apresentando dois modelos distintos:
- Em caso de consulta encontrada com sucesso, receberá um campo "**status**" com o valor "**completed**", neste caso, o objeto "**data**" trará as demais informações da consulta.
- Em caso de documento não encontrado na base para o período consultado, receberá um campo "**status**" com o valor "**not_found**", informando que a consulta não trouxe nenhuma informação.
## Exemplo de sucesso
No webhook temos o objeto "**data**" com os campos:
"**valueless_months**": Número de meses sem atividade.
"**card_schemes**": São os arranjos de pagamentos que constituíram o valor total liquidado.
"**value**": Valor total liquidado em cartões.
```json
{
"status": "completed",
"webhook_type": "historic_card_settlement",
"data": {
"valueless_months": 0,
"card_schemes": [
{
"code": "003",
"enumerator": "credit_mastercard",
"description": "Mastercard Crédito"
}
],
"value": 847.86
},
"event_datetime": "2022-05-18T20:57:00",
"key": "38934f1b-204f-4fc4-844d-5ad562ff36f6"
}
```
## Em caso de consulta não encontrada
```json
{
"status": "not_found",
"webhook_type": "historic_card_settlement",
"event_datetime": "2022-05-18T20:57:00",
"key": "38934f1b-204f-4fc4-844d-5ad562ff36f6"
}
```
---
# introducao
URL: /documentation/documentacoes ocultas/agc1/introducao
O histórico de liquidação de cartão é um novo sistema de consultas que fornece informações sobre os pagamentos liquidados de recebíveis de cartões de um determinado cliente em um período específico.
Estes dados são disponibilizados às instituições financeiras pelo banco central através de um sistema chamado ACG1. Para acessa-los a QI Tech precisa de uma autorização do consultado. Assim que as assinaturas forem efetuadas você receberá todas as informações relativas aos 12 meses anteriores à data de consulta.
Isso inclui:
- Valor Total agregado de pagamentos liquidados neste período.
- Quais os Arranjos de pagamentos que constituíram este valor total.
- Quantidade de meses em que não houve nenhum pagamento;
:::danger Atenção!
Assim como as demais APIs a liberação do serviço deve ser feita junto ao nosso time e as chamadas são autenticadas.
:::
## Fluxo de consulta
Para executar a consulta do histórico de liquidação de cartão, a QI Tech precisa enviar um documento ao Banco Central formalizando e solicitando a consulta. Este documento é gerado dentro do nosso fluxo interno com base no payload enviado ao nosso endpoint 16.1.
O Fluxo de consulta consiste em:
- Solicitação da consulta via requisição;
- Recebimento do webhook com o resultado da consulta;
---
# Permissão (Geral):
URL: /documentation/documentacoes ocultas/perfis_de_acesso
#### Observador
Não consegue realizar nenhuma ação na plataforma, somente visualiza os dados disponíveis.
- Exportar relatórios;
- Download de comprovantes
- Exportar extratos.
#### Operador
Tem todos os poderes do "observador" e ainda tem poderes para:
- Cadastrar operação;
- Registrar boletos;
- Comandar instruções de boletos;
- Incluir pedido de abertura de conta escrow;
- Incluir solicitação de TED, PIX e pagamento de boletos;
- Solicitar consulta SCR;
#### Administrador
Tem todos os poderes do operador e ainda tem poderes para:
- Aprovar pagamentos (ted, pix e boleto);
- fazer a gestão de acessos do portal e inclusão de chaves de integração,
- cadastro de webhooks.
---
# cancelamento_de_solicitacao.md
URL: /documentation/documentacoes ocultas/scr/cancelamento_de_solicitacao.md
## Request
- ENDPOINT /scr
- MÉTODO DELETE
**body.json**
```json
{
"key": "56b330f0-fb6e-4dab-bede-8ae2ecb3f4c6",
"requester_person_key": "1da2dbd0-af45-4b4d-b685-896e449fa216"
}
```
### Body Params
| Campo | Tipo | Descrição |
|---|---| ---|
| `key` | enum | Chave da solicitação (SCR_KEY). | -- |
| `requester_person_key` | string | Chave do solicitante. | -- |
## Response
status: 200
**Response Body**
```json
{
"consent_term": null,
"consulted_at": null,
"created_at": "2020-04-24",
"report_end_date": "2020-03",
"report_start_date": "2020-01",
"result_document": null,
"origin_key": "353b7aea-0bc5-4981-8015-16f7ba4252d4",
"scr_status": "canceled",
"signers": [
{
"name": "Diretor 1",
"document_number": "03030230074",
"email": "diretor1@email.com"
},
{
"name": "Diretor 2",
"document_number": "03030230074",
"email": "diretor2@email.com"
}
],
"subject_document_number": "05305188000108",
"subject_name": "Padaria do Joao Ninguem",
"subject_person_type": "legal"
}
```
status: 400
**body.json**
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
---
# consultar_solicitacao
URL: /documentation/documentacoes ocultas/scr/consultar_solicitacao
## Request
Pensando em facilitar o processo, caso o cliente queira fazer uma nova consulta com novas datas base à alguem que já fora previamente consultado, oferecemos a operação /scr/redo. A vantagem de utilizar esta operação é que, caso o documento de autorização para aquela pessoa ainda esteja válido, não haverá a criação de um novo documento para assinatura¹ e a consulta será criada imediatamente. O formato de assinatura do header e do body desta requisição é descrito em detalhes aqui.
- ENDPOINT /scr/ SCR_KEY
- MÉTODO GET
### Path Params
| Campo | Tipo | Descrição |
|---|---| ---|
| `scr_key` | string | Chave da solicitação de consulta SCR. | -- |
## Response
status: 200
**Response Body**
```json
{
"consent_term": null,
"consulted_at": null,
"created_at": "2020-04-24",
"report_end_date": "2020-03",
"report_start_date": "2020-01",
"result_document": null,
"origin_key": "db5d1627-841f-4ddd-97f8-925557531718",
"scr_status": "pending_signature",
"signers": [
{
"name": "Diretor 1",
"document_number": "03030230074",
"email": "diretor1@email.com"
},
{
"name": "Diretor 2",
"document_number": "03030230074",
"email": "diretor2@email.com"
}
],
"subject_document_number": "05305188000108",
"subject_name": "Padaria do Joao Ninguem",
"subject_person_type": "legal"
}
```
status: 400
**body.json**
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
---
# consultar_solicitacoes
URL: /documentation/documentacoes ocultas/scr/consultar_solicitacoes
## Request
Pensando em facilitar o processo, caso o cliente queira fazer uma nova consulta com novas datas base à alguem que já fora previamente consultado, oferecemos a operação /scr/redo. A vantagem de utilizar esta operação é que, caso o documento de autorização para aquela pessoa ainda esteja válido, não haverá a criação de um novo documento para assinatura¹ e a consulta será criada imediatamente. O formato de assinatura do header e do body desta requisição é descrito em detalhes aqui.
- ENDPOINT /scr
- MÉTODO GET
## QUERY PARAMS
| Campo | Tipo | Descrição |
|---|---| ---|
| `origin_key` | string | Chave de identificação da operação. Retorna todas as consultas referentes à aquela operação. | -- |
| `subject_person_type` | enum | Filtro de tipo de pessoa consultada. | -- |
| `subject_document_number` | string | Filtro de "CPF" ou "CNPJ", não aceita parcial. | -- |
| `created_at_start_date` | string | Filtro de inicio da faixa de data de criação (formato: YYYY-MM-DD). | -- |
| `created_at_end_date` | string | Filtro de fim da faixa de data de criação (formato: YYYY-MM-DD). | -- |
| `consulted_at_start_date` | string | Filtro de inicio da faixa de data de consulta (formato: YYYY-MM-DD). | -- |
| `consulted_at_end_date` | datetime | Filtro de fim da faixa de data de consulta (formato: YYYY-MM-DD).| -- |
| `scr_status` | enum | Filtro de status da consulta. | -- |
| `page` | integer | Página atual que está sendo consultada. | -- |
| `page_size` | integer | Quantidade de resultados que cabem na página. | -- |
## Enumeradores
### Enumeradores person_type
| Enumerador | Tradução |
|---|---|
| natural | Pessoa fisica |
| legal | Pessoa juridica |
### Enumeradores scr_status
| Enumerador | Tradução |
|---|---|
| created | Criado |
| pending_signature | Assinatura pendente |
| signed | Assinado|
| rejected | Rejeitado |
| consulted | Consultado |
| error | Com erro |
| canceled | Cancelado |
## Response
status: 200
**Response Body**
```json
{
"data": [
{
"consent_term": null,
"consulted_at": null,
"created_at": "2020-04-24",
"report_end_date": "2020-03",
"report_start_date": "2020-01",
"result_document": null,
"origin_key": "db5d1627-841f-4ddd-97f8-925557531718",
"scr_status": "pending_signature",
"signers": [
{
"name": "Diretor 1",
"document_number": "03030230074",
"email": "diretor1@email.com"
},
{
"name": "Diretor 2",
"document_number": "03030230074",
"email": "diretor2@email.com"
}
],
"subject_document_number": "05305188000108",
"subject_name": "Padaria do Joao Ninguem",
"subject_person_type": "legal"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"rows_per_page": 100,
"total_pages": 1,
"total_rows": 55
}
}
```
status: 400
**body.json**
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
---
# introducao
URL: /documentation/documentacoes ocultas/scr/introducao
Uma das funcionalidades que podemos oferecer em nossa integração é a possibilidade de consulta dos dados disponíveis no SCR de uma pessoa física ou jurídica via API. Com apenas uma solicitação de consulta enviada via request, a QI Tech se encarrega de enviar o pedido de autorização aos consultados, realizar a consulta (após autorizada) e despachar os resultados ao solicitante via webhook.
Além disso, para consultas PJ é possível, com uma única solicitação, consultar a empresa e seus representantes, gerando uma consulta separa para cada um dos documentos.
Assim como as demais APIs a liberação do serviço deve ser feita junto ano nosso time e as chamadas são autenticadas.
Nas subseções abaixo veremos como executar uma consulta ao SCR.
## Fluxo de consulta ao SCR
O Fluxo de consulta ao SCR consiste em:
- Solicitação da consulta (solicitado via request)
- Assinatura da autorização da consulta pelo consultado ou os representantes (enviado via e-mail)
- Realização da consulta (informado resultado via webhook)
---
# refazer_consulta
URL: /documentation/documentacoes ocultas/scr/refazer_consulta
## Request
Pensando em facilitar o processo, caso o cliente queira fazer uma nova consulta com novas datas base à alguem que já fora previamente consultado, oferecemos a operação /scr/redo. A vantagem de utilizar esta operação é que, caso o documento de autorização para aquela pessoa ainda esteja válido, não haverá a criação de um novo documento para assinatura¹ e a consulta será criada imediatamente. O formato de assinatura do header e do body desta requisição é descrito em detalhes aqui.
- ENDPOINT /scr/redo
- MÉTODO POST
**body.json**
```json
{
"report_start_date": "2019-02",
"report_end_date": "2020-03",
"origin_key": "bf6b5e8b-93df-4443-b1fc-d760db6ea4ff"
}
```
### Body Params
| Campo | Tipo | Descrição |
|---|---| ---|
| `report_start_date` | enum | Data de início da consulta (formato "AAAA-MM"). | -- |
| `report_end_date` | string | Data final da consulta (formato "AAAA-MM"). | -- |
| `origin_key` | string | Chave do SCR original (SRC_KEY) que será utilizada para refazer a consulta. | -- |
## Response
status: 200
**Response Body**
```json
{
"consent_term":"https://urldasassinaturas.com/assinaturas.zip",
"consulted_at":"2020-05-08",
"created_at":"2020-05-08",
"origin_key":"353b7aea-0bc5-4981-8015-16f7ba4252d4",
"report_end_date":"2020-03",
"report_start_date":"2019-02",
"result_document":"https://urldodocumento.com/documento_consulta.pdf",
"scr_key":"10b3feb4-6afa-425b-8537-99c2aa7afd74",
"scr_status":"consulted",
"signers":[
{
"document_number":"41184562067",
"email":"joao.ninguem@yopmail.com",
"name":"Joao Ninguem"
}
],
"subject_document_number":"41184562067",
"subject_name":"Joao Ninguem",
"subject_person_type":"natural"
}
```
status: 400
**body.json**
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
---
# solicitacao_de_consulta
URL: /documentation/documentacoes ocultas/scr/solicitacao_de_consulta
## Request
- ENDPOINT /scr
- MÉTODO POST
**body.json**
```json
{
"person_type": "natural",
"name": "João Ninguem",
"document_number": "42866592832",
"check_representatives": true,
"report_start_date": "2019-02",
"report_end_date": "2020-03",
"signatures": [{
"signed_object": {
"raw_text": "Lorem ipsum dolor sit amet, consectetur a....",
"document_key": "79003de0-2590-455d-9b73-426b8ca284eb",
"document_md5": "7521bd5621d97af26b2c1721fc4023a8"
},
"authenticity": {
"timestamp": "1970-01-01 00:00:01",
"ip_address": "179.104.42.245",
"session_id": "ddb1d063-4fdf-4330-af9c-3316e9142ff3",
"facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb",
"document_key": "79003de0-2590-455d-9b73-426b8ca284eb",
"document_md5": "79003de0-2590-455d-9b73-426b8ca284eb"
},
"signer": {
"name": "IVANILDO DE SENA LIMA",
"email": "ivanlima2604@gmail.com",
"phone": {
"country_code": "055",
"area_code": "11",
"number": "999999999"
},
"document_number": "61766976204"
},
"authentication_type": "opt-in"
}]
}
```
### Body Params
| Campo | Tipo | Descrição |
|---|---| ---|
| `person_type` | enum | Tipo de pessoa a ser consultada. | -- |
| `name` | string | Nome do consultado. | -- |
| `document_number` | string | CPF ou CNPJ do consultado. | -- |
| `check_representatives` | boolean | Campo determinante para que haja a consulta dos representantes da empresa (booleano "true" ou "false", se omitido considera-se falso). | -- |
| `report_start_date` | string | Data de início da consulta (formato "AAAA-MM"). A data mínima disponível para consulta na QI Tech é 2019-02. | -- |
| `report_end_date` | string | Data final da consulta (formato "AAAA-MM"). | -- |
| `signatures` | array of objects | Lista contendo objetos de signatarios. | -- |
## Enumeradores
### Enumeradores person_type
| Enumerador | Tradução |
|---|---|
| natural | Pessoa fisica |
| legal | Pessoa juridica |
## Response
status: 200
**Response Body: PF**
```json
{
"person_type": "legal",
"name": "Padaria do Joao Ninguem",
"document_number": "05305188000108",
"signers": [
{
"name": "Diretor 1",
"document_number": "41184562067",
"email": "diretor1@email.com"
},
{
"name": "Diretor 2",
"document_number": "18631260070",
"email": "diretor2@email.com"
}
],
"report_start_date": "2019-02",
"report_end_date": "2020-03" ,
"check_representatives": true
}
```
status: 200
**Response Body: PJ**
```json
{
"webhook_type": "scr",
"key": "f33384e8-13ed-4e43-adf3-1ba20a4a6004",
"status": "pending_signature",
"event_datetime": "1970-01-01 00:00:01"
}
```
status: 400
**body.json**
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
---
# webhook
URL: /documentation/documentacoes ocultas/scr/webhook
Após o envio de uma solicitação de consulta SCR com sucesso o resto do fluxo fica a cargo da QI Tech. O acompanhamento do resultado da operação é dado via Webhook seguindo o fluxo previamente estipulado. O padrão utilizado é: em caso de sucesso é enviado um webhook informando os dados da consulta, em caso de falha, um webhook é enviado informando que a solicitação foi rejeitada. Além disso o cliente pode escolher durante a contratação do serviço se os dados da consulta serão entregues apenas em pdf ou completo, que no caso retorna além do PDF todos os dados da consulta em JSON. Neste momento o cliente também recebe a chave individual da consulta scr **SCR_KEY**.
## Exemplos de sucesso
Consulta somente em PDF:
```json
{
"data": {
"consent_term": "https://urldasassinaturas.com/assinaturas.zip",
"consulted_at": "2020-05-08",
"created_at": "2020-05-08",
"origin_key": OPERATION_KEY,
"report_end_date": "2020-03",
"report_start_date": "2019-02",
"result_document": "https://urldodocumento.com/documento_consulta.pdf",
"scr_key": SCR_KEY,
"scr_status": "consulted",
"signers": [
{
"document_number": "41184562067",
"email": "joao.ninguem@yopmail.com",
"name": "Joao Ninguem",
}
],
"subject_document_number": "41184562067",
"subject_name": "Joao Ninguem",
"subject_person_type": "natural",
},
"webhook_type": "scr",
"event_datetime": EVENT_DATE_TIME,
"status": "consulted",
"key": OPERATION_KEY,
}
```
Consulta completa:
```json
{
"data":{
"consent_term":"https://urldasassinaturas.com/assinaturas.zip",
"consulted_at":"2020-05-08",
"created_at":"2020-05-08",
"origin_key": OPERATION_KEY,
"report_end_date":"2020-03",
"report_start_date":"2019-02",
"result_document":"https://urldodocumento.com/documento_consulta.pdf",
"scr_key": SCR_KEY,
"scr_status":"consulted",
"scr_data":[
{
"reference_date":"2020-03",
"financial_institution_count":"3",
"operation_count":"10",
"assumed_coobligation":"10235",
"receive_coobligation":"23569",
"start_relationship":"2000-05-01",
"disagreement_operation_count":"2",
"disagreement_operation_value":"523",
"subjudice_operations_count":"1",
"subjudice_operations_value":"10000",
"indirect_risk":"200000",
"error":{
"error_code":"",
"description":"",
"error_type":""
},
"operation_items":[
{
"due_value": "46800",
"exchange_variation": "N",
"category_sub":{
"category":{
"category_code": 2,
"category_description": "Empréstimos"
},
"category_sub_code": 3,
"description": "crédito pessoal - sem consignação em folha de pagam."
},
"due_type":{
"due_type_group": "Vencido",
"due_code": "205",
"description": "Créditos vencidos de 1 a 14 dias",
}
}
]
}
],
"signers":[
{
"document_number":"41184562067",
"email":"joao.ninguem@yopmail.com",
"name":"Joao Ninguem"
}
],
"subject_document_number":"41184562067",
"subject_name":"Joao Ninguem",
"subject_person_type":"natural"
},
"webhook_type":"scr",
"event_datetime": EVENT_DATE_TIME,
"status":"consulted",
"key": OPERATION_KEY
}
```
Consulta com representantes:
```json
{
"data":[
{
"consent_term":"https://urldasassinaturas.com/assinaturas.zip",
"consulted_at":"2020-08-12",
"created_at":"2020-08-12",
"origin_key": OPERATION_KEY,
"report_end_date":"2019-07",
"report_start_date":"2019-06",
"result_document":"https://urldodocumento.com/documento_consulta.pdf",
"scr_key": SCR_KEY,
"scr_status":"consulted",
"signed_at":"2020-08-12",
"signers":[
{
"document_number":"00152300074",
"email":"joao.ninguem@yopmail.com",
"name":"João Almeida"
}
],
"subject_document_number":"97381542000193",
"subject_name":"Beazini Pizzas",
"subject_person_type":"legal"
},
{
"consent_term":"https://urldasassinaturas.com/assinaturas.zip",
"consulted_at":"2020-08-12",
"created_at":"2020-08-12",
"origin_key":OPERATION_KEY,
"report_end_date":"2019-07",
"report_start_date":"2019-06",
"result_document":"https://urldodocumento.com/documento_consulta.pdf",
"scr_key":SCR_KEY,
"scr_status":"consulted",
"signed_at":"2020-08-12",
"signers":[
{
"document_number":"00152300074",
"email":"joao.ninguem@yopmail.com",
"name":"João Almeida"
}
],
"subject_document_number":"00152300074",
"subject_name":"João Almeida",
"subject_person_type":"natural"
}
],
"webhook_type":"scr",
"event_datetime":"EVENT_DATE_TIME",
"status":"consulted",
"key": OPERATION_KEY
}
```
## Exemplo de falha
```json
{
"data": {
"consent_term": null,
"consulted_at": "2020-05-08",
"created_at": "2020-05-08",
"origin_key": OPERATION_KEY,
"report_end_date": "2020-03",
"report_start_date": "2019-02",
"result_document": null,
"scr_key": SCR_KEY,
"scr_status": "rejected",
"signers": [
{
"document_number":"41184562067",
"email":"joao.ninguem@yopmail.com",
"name":"Joao Ninguem"
}
],
"subject_document_number": "41184562067",
"subject_name": "Joao Ninguem",
"subject_person_type": "natural",
},
"webhook_type": "scr",
"event_datetime": EVENT_DATE_TIME,
"status": "rejected",
"key": OPERATION_KEY,
}
```
---
# Recalcular contrato de crédito
URL: /documentation/emissao_de_divida/reprocessar_contrato
Este endpoint pode ser utilizado para efetuar o recálculo de uma operação de crédito, através do ajuste do valor de parcela.
## Request
ENDPOINT /debt/ DEBT-KEY /recalculate_operation
MÉTODO POST
**Request Body**
```json
{
"financial": {
"installment_face_value": 250,
"disbursement_date": "2025-01-20"
}
}
```
### Path Params
| Campo | Tipo | Descrição |
|---|---| ---|
| `debt_key` * | string | Chave da dívida devolvida no momento da criação da operação de crédito. |
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `financial` * | string | Objeto financial simplificado que trás a data de desembolso | [Objeto financial](#objeto-financial) |
### Objeto financial
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `installment_face_value` | float | Valor de parcela | 10 |
## Response
STATUS 200
**Response Body**
```json
{
"data": {
"additional_iof": 38000,
"annual_cet": "253,2642%",
"assignment_amount": 10000000,
"base_iof": 69331,
"borrower": {
"document_number": "89940878025962",
"name": "Parmalat"
},
"cet": "11,0900%",
"collaterals": [],
"contract": {
"external_contract_key": "2f0b8b6e-0b60-47f0-b27f-e291c028549b",
"number": "1907258737/P",
"signature_information": [
{
"signature_url": "https://sign.qitech.com.br/s/hNrwjda",
"signer_document_number": "94632180173",
"signer_email": "pedro.alves@yopmail.com",
"signer_external_key": "07a1c438-43a4-49a9-85a9-29667507453b",
"signer_name": "Pedro Felipe Henrique Alves",
"signer_role": "issuer"
},
{
"signature_url": "https://sign.qitech.com.br/s/EaTajda",
"signer_document_number": "34651104630",
"signer_email": "patricia.tereza@yopmail.com",
"signer_external_key": "61a1ea50-769a-410a-8ef8-09f0ce4611f6",
"signer_name": "Patrícia Tereza Bernardes",
"signer_role": "guarantor"
}
],
"urls": [
"https://storage.googleapis.com/sandbox-doc-api/documents/abedfeab-dcf8-4e13-897b-da02c222cef4/SALGADINHO_SALETE_LTDA-PARMALAT-CCB-1907258737-20220512165254.pdf"
]
},
"contract_fee_amount": 50000,
"contract_fees": [
{
"fee_amount": 50000,
"fee_type": "tac"
}
],
"external_contract_fee_amount": 0,
"external_contract_fees": [],
"installments": [
{
"additional_costs": [],
"advanced_paid_amount": 0,
"bank_slip_key": null,
"business_due_date": "2019-08-26",
"calendar_days": 32,
"digitable_line": null,
"due_date": "2019-08-26",
"due_interest": null,
"due_principal": 10000000,
"fine_amount": null,
"has_interest": true,
"installment_key": "81e4a732-d300-4e39-b6d5-2d9ac8df429b",
"installment_number": 1,
"installment_payment": [],
"installment_status": "created",
"installment_type": "principal",
"original_due_principal": 10000000,
"original_pre_fixed_amount": 1125598.54,
"original_principal_amortization_amount": 1000000,
"original_total_amount": null,
"paid_amount": 0,
"paid_at": null,
"payments": [],
"post_fixed_amount": null,
"pre_fixed_amount": 1125598.54,
"principal_amortization_amount": 1000000,
"tax_amount": 1312,
"total_amount": null,
"total_paid_amount": 0,
"workdays": 22
}, ... x [número de parcelas]
],
"iof_charge_method": "financed",
"issue_amount": 10000000,
"net_external_contract_fee_amount": 0,
"number_of_installments": 10,
"post_fixed_interest_base": "workdays",
"post_fixed_interest_rate": 1,
"prefixed_interest_rate": {
"annual_rate": 2.32,
"created_at": null,
"daily_rate": 0.0033388,
"interest_base": "calendar_days",
"monthly_rate": 0.10516767
},
"requester_identifier_key": "b7ddbcfb-3de0-49d8-8014-07972d8b27f2",
"total_iof": 107331,
"total_pre_fixed_amount": 5935915.16
},
"event_datetime": "2022-05-12 16:53:10",
"key": "b7ddbcfb-3de0-49d8-8014-07972d8b27f2",
"status": "waiting_signature",
"webhook_type": "debt"
}
```
STATUS 400
**Response Body**
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
---
# Catálogo de Erros
URL: /documentation/erros/catalogo_de_erros
Todas as APIs da QI Tech retornam erros em um formato padronizado:
```json
{
"title": "HTTP Status code name",
"description": "An english description of the error",
"translation": "Uma descrição em português do erro",
"code": "ERROR_UNIQUE_CODE"
}
```
## Erros Globais (GDF)
Erros comuns a todas as APIs da plataforma.
| Código HTTP | Código do Erro | Título | Descrição | Resolução |
|-|-|-|-|-|
| 400 | GDF000003 | Bad Request | No API Client Key received | Inclua o header `API-CLIENT-KEY` com sua chave de API na requisição. |
| 401 | GDF000014 | QI Unauthenticated | Failed while decoding the authentication token | Verifique se o token JWT está sendo assinado corretamente com sua chave privada EC512. Consulte o [teste de autenticação](/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2). |
| 404 | GDF000018 | Not Found | No ClientIntegration found for api_client_key | Verifique se a `API-CLIENT-KEY` enviada corresponde à chave cadastrada no painel QI Tech. |
## Erros de Homologação do Emissor (ISS)
| Código HTTP | Código do Erro | Título | Descrição |
|-|-|-|-|
| 400 | ISS000003 | Bad Request | Emissor já existe na base de dados. |
| 404 | ISS000004 | Not Found | Representante do emissor não encontrado. |
| 404 | ISS000005 | Not Found | Conta bancária não encontrada. |
| 404 | ISS000006 | Not Found | Documento do emissor não encontrado. |
| 404 | ISS000007 | Not Found | Documento do representante do emissor não encontrado. |
| 404 | ISS000008 | Not Found | Contato do emissor não encontrado. |
| 404 | ISS000009 | Not Found | Emissor não encontrado. |
| 404 | ISS000010 | Not Found | Grupo de assinantes não encontrado. |
| 400 | ISS000011 | Bad Request | Emissor deve estar no estado in_filling para permitir esta ação. |
| 400 | ISS000012 | Bad Request | Não é permitido deletar a conta principal, defina uma nova conta principal primeiro. |
| 400 | ISS000013 | Bad Request | Não é permitido deletar o contato principal, defina um novo contato principal primeiro. |
| 400 | ISS000014 | Bad Request | Emissor precisa ter ao menos uma informação de contato. |
| 400 | ISS000015 | Bad Request | Acesso aos dados do emissor já foi concedido. |
| 400 | ISS000016 | Bad Request | Falha ao enviar mensagem ao emissor, tente novamente. |
| 400 | ISS000017 | Bad Request | Link inválido. |
| 400 | ISS000018 | Bad Request | Documento enviado é inválido ou de baixa qualidade. |
## Erros de Homologação do Investidor (INV)
| Código HTTP | Código do Erro | Título | Descrição |
|-|-|-|-|
| 400 | INV000003 | Bad Request | Investidor já existe na base de dados. |
| 404 | INV000004 | Not Found | Representante do investidor não encontrado. |
| 404 | INV000005 | Not Found | Conta bancária não encontrada. |
| 404 | INV000006 | Not Found | Documento do investidor não encontrado. |
| 404 | INV000007 | Not Found | Documento do representante do investidor não encontrado. |
| 404 | INV000008 | Not Found | Contato do investidor não encontrado. |
| 404 | INV000009 | Not Found | Investidor não encontrado. |
| 404 | INV000010 | Not Found | Grupo de assinantes não encontrado. |
| 400 | INV000011 | Bad Request | Investidor deve estar no estado in_filling para permitir esta ação. |
| 400 | INV000012 | Bad Request | Não é permitido deletar a conta principal, defina uma nova conta principal primeiro. |
| 400 | INV000013 | Bad Request | Não é permitido deletar o contato principal, defina um novo contato principal primeiro. |
| 400 | INV000014 | Bad Request | Investidor precisa ter ao menos uma informação de contato. |
| 400 | INV000015 | Bad Request | Acesso aos dados do investidor já foi concedido. |
| 400 | INV000016 | Bad Request | Falha ao enviar mensagem ao investidor, tente novamente. |
| 400 | INV000017 | Bad Request | Link inválido. |
| 400 | INV000018 | Bad Request | Documento enviado é inválido ou de baixa qualidade. |
## Erros de Emissão de Nota Comercial (COM)
| Código HTTP | Código do Erro | Título | Descrição |
|-|-|-|-|
| 400 | COM000001 | Bad Request | Documento fornecido não é válido. |
| 400 | COM000002 | Bad Request | Tenant precisa ser configurado antes de utilizar este endpoint. |
| 409 | COM000003 | Conflict | Configuração para este tenant já existe. |
| 400 | COM000004 | Bad Request | Investidor com a chave informada não permitido. Verifique o cadastro. |
| 400 | COM000005 | Bad Request | Emissor com a chave informada não permitido. Verifique o cadastro. |
| 400 | COM000006 | Bad Request | Operação com mais de um investidor não disponível. |
| 404 | COM000007 | Not Found | Operação não encontrada. |
| 403 | COM000008 | Forbidden | Operação não pertence ao tenant. |
| 400 | COM000010 | Bad Request | Operação não pode ser atualizada fora do status in_filling. |
## Erros de Integralização (INT)
| Código HTTP | Código do Erro | Título | Descrição |
|-|-|-|-|
| 400 | INT000001 | Bad Request | Tipo de integralização inválido. |
| 404 | INT000002 | Not Found | Integralização não encontrada. |
| 400 | INT000003 | Bad Request | Integralização não pode ser atualizada fora do status in_filling. |
| 400 | INT000004 | Bad Request | Tipo de pagamento inválido. |
---
# Atualização de dados dos investidores na Operação
URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-investidores
Este endpoint permite a atualização dos dados dos investidores em uma operação.
---
## **Atualização de dados dos investidores na Operação (PUT)**
### **Request**
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /investors
MÉTODO PUT
### **Path Params**
| Campo | Tipo | Descrição | Caracteres Máx. |
|-------------------|--------|-----------------------------------------------|-----------------|
| `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 |
Request Body
```json
{
"investors": [
{
"investor_key": "a1a75b66-6f7e-4bcc-9ff5-6f8adf7cae09",
"investor_name": "Ultimate Cascade",
"investor_document_number": "31.424.651/0001-32",
"subscription_quantity": 1000000,
"bank_account": {
"account_type": "checking",
"account_digit": "3",
"account_branch": "0001",
"account_number": "33400254",
"financial_institution_ispb": "32402502",
"financial_institution_code_number": "329"
}
}
]
}
```
### **Request Body Params**
### **Objeto investors**
| Campo | Tipo | Descrição |
| ----------------------------- | ------ | ------------------------------ |
| `investor_key` * | string | Chave única do investidor. |
| `subscription_percentage` * | number | Percentual de subscrição. |
| `bank_account` * | object | Conta bancária do investidor. |
### **Objeto bank_account**
| Campo | Tipo | Descrição |
| --------------------------------------- | ------ | ------------------------------------------ |
| `account_number` * | string | Número da conta bancária. |
| `account_digit` * | string | Dígito da conta bancária. |
| `account_branch` * | string | Agência da conta bancária. |
| `financial_institution_code_number` * | string | Código da instituição financeira. |
| `financial_institution_ispb` * | string | Código ISPB da instituição financeira. |
| `account_type` * | string | Tipo da conta (`checking`, `savings`). |
## **Response**
STATUS 200
Response Body
```json
{
"tenant_key": "13a6a1d5-7a3c-4627-a0a6-9fd746662ca4",
"operation_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74",
"operation_type": "commercial_paper",
"operation_status": "issued",
"backoffice_analysis_status": "approved",
"issuer_key": "9e08fd62-ce43-4c95-99e0-4386e980d618",
"issuer_name": "Blue Logic",
"issuer_document_number": "97.923.586/0001-06",
"issuer_bank_account": {
"account_type": "checking",
"account_digit": "3",
"account_branch": "0001",
"account_number": "4464541",
"financial_institution_ispb": "32402502",
"financial_institution_code_number": "329"
},
"issuer_onboarding_approved": true,
"issue_number": 1,
"issue_series": 1,
"contract_number": "0000000001",
"issue_date": "2025-02-03",
"financial_base_date": "2025-02-03",
"commercial_paper_template_key": "68956441-d46c-44ed-93b9-b1806dd6ada9",
"commercial_paper_document_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/commercial_paper/2cb87abc-8bdf-4df3-be98-b7afb53b14c8",
"adhesion_term_template_key": "58743ab9-99bd-439a-93af-16e4c5fccd6f",
"adhesion_term_document_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/adhesion_term/fe74eaed-2f44-45b4-b972-83fa222cbf1c",
"envelope_signature_status": "signed",
"envelope_key": "4d7f28b4-185f-482d-929e-d1af937cb27b",
"envelope_signature_url": "https://sandbox.certifiqi.com.br/sign?batch-group=c4747fe6-2cc0-41a9-8972-84b44f8fff8a",
"envelope_signed_files_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/signed_files",
"financial": {
"financial_base_date": "2025-02-03",
"issue_quantity": 1000000,
"unit_price": 1.0,
"issue_amount": 1000000.0,
"released_amount": 1000000.0,
"cet": 5.0,
"annual_cet": 79.59,
"number_of_installments": 5,
"prefixed_interest_rate": {
"daily_rate": 0.0016053474,
"annual_rate": 0.795856326,
"monthly_rate": 0.05,
"interest_base": "calendar_days_365"
},
"fine_delay_rate": {
"monthly_rate": 0.01,
"interest_base": "calendar_days_365"
},
"contract_fine_rate": 0.02,
"financial_index": null,
"post_fixed_interest_rate": null,
"fees": [
{
"type": "internal",
"amount": 2.0,
"fee_type": "bookkeeping_fee",
"fee_amount": 20000.0,
"amount_type": "percentage"
},
{
"type": "external",
"amount": 5.0,
"fee_type": "structuring_fee",
"fee_amount": 50000.0,
"amount_type": "percentage"
}
],
"installment_list": [
{
"installment_number": 1,
"workdays": 20,
"calendar_days": 30,
"principal_amortization_unit_price": 0.18122484,
"principal_amortization_amount": 181224.84138231,
"interest_amount": 49298.45861769,
"amount": 230523.3,
"due_principal": 1000000.0,
"due_interest": 0.0,
"due_date": "2025-03-05",
"has_interest": true
},
{
"installment_number": 2,
"workdays": 21,
"calendar_days": 29,
"principal_amortization_unit_price": 0.19153595,
"principal_amortization_amount": 191535.95353305,
"interest_amount": 38987.34646695,
"amount": 230523.3,
"due_principal": 818775.15861769,
"due_interest": 0.0,
"due_date": "2025-04-03",
"has_interest": true
},
{
"installment_number": 3,
"workdays": 19,
"calendar_days": 32,
"principal_amortization_unit_price": 0.19748652,
"principal_amortization_amount": 197486.52331007,
"interest_amount": 33036.77668993,
"amount": 230523.3,
"due_principal": 627239.20508464,
"due_interest": 0.0,
"due_date": "2025-05-05",
"has_interest": true
},
{
"installment_number": 4,
"workdays": 21,
"calendar_days": 29,
"principal_amortization_unit_price": 0.21005991,
"principal_amortization_amount": 210059.90840452,
"interest_amount": 20463.39159548,
"amount": 230523.3,
"due_principal": 429752.68177457,
"due_interest": 0.0,
"due_date": "2025-06-03",
"has_interest": true
},
{
"installment_number": 5,
"workdays": 21,
"calendar_days": 30,
"principal_amortization_unit_price": 0.21969277,
"principal_amortization_amount": 219692.77337005,
"interest_amount": 10830.52662995,
"amount": 230523.3,
"due_principal": 219692.77337005,
"due_interest": 0.0,
"due_date": "2025-07-03",
"has_interest": true
}
]
},
"tags": [],
"investor_list": [
{
"investor_key": "a1a75b66-6f7e-4bcc-9ff5-6f8adf7cae09",
"investor_name": "Ultimate Cascade",
"investor_document_number": "31.424.651/0001-32",
"subscription_percentage": 100.0,
"subscription_quantity": 1000000,
"investor_onboarding_approved": true,
"bank_account": {
"account_type": "checking",
"account_digit": "3",
"account_branch": "0001",
"account_number": "33400254",
"financial_institution_ispb": "32402502",
"financial_institution_code_number": "329"
},
"updated_at": null
}
],
"related_party_list": [
{
"related_party_key": "1ac83d43-41cb-4ad0-a7ca-add6c3a3171c",
"name": "Blue Logic",
"document_number": "97.923.586/0001-06",
"role_type": "issuer",
"is_active": true,
"updated_at": null,
"trading_name": "Blue Logic",
"cnae_code": "47.21-1-02",
"company_type": "ltda",
"foundation_date": "2007-10-25",
"person_type": "legal",
"street": "Rua Romualdo de Souza Brito",
"neighborhood": "Centro",
"number": "89",
"postal_code": "08150-470",
"city": "São Paulo",
"state": "SP",
"complement": "Letra C",
"signer_group_list": [
{
"signer_group_key": "fa2cbede-a501-41e1-bf70-078bb0d4ac7b",
"minimum_required_signers": 1,
"signers": [
{
"name": "John Doe",
"email": "123.456.789-00@yopmail.com",
"phone_number": "+5511988887777",
"document_number": "123.456.789-00",
"is_group_mandatory": true
}
]
}
],
"document_list": [],
"contact_information_list": [
{
"name": "John Doe",
"email": "123.456.789-00@yopmail.com",
"is_default": true,
"phone_number": "+5516982399722",
"document_number": "123.456.789-00",
"issuer_contact_information_key": "6e9714f4-d652-4ca0-89e2-13e9e2ec3414"
}
]
},
{
"related_party_key": "bab03c76-a12a-4d88-aaf8-70799e3b1b30",
"name": "Ultimate Cascade",
"document_number": "31.424.651/0001-32",
"role_type": "investor",
"is_active": true,
"updated_at": null,
"trading_name": "Ultimate Cascade",
"cnae_code": "47.21-1-02",
"company_type": "ltda",
"foundation_date": "2007-10-25",
"person_type": "legal",
"street": "Rua Romualdo de Souza Brito",
"neighborhood": "Centro",
"number": "89",
"postal_code": "08150-470",
"city": "São Paulo",
"state": "SP",
"complement": "Letra C",
"signer_group_list": [
{
"signer_group_key": "ccb36b0b-40b5-42e0-bc41-0e8fce57f3ca",
"minimum_required_signers": 1,
"signers": [
{
"name": "John Doe",
"email": "123.456.789-00@yopmail.com",
"phone_number": "+5516982399722",
"document_number": "123.456.789-00",
"is_group_mandatory": true
}
]
}
],
"document_list": [],
"contact_information_list": [
{
"name": "John Doe",
"email": "123.456.789-00@yopmail.com",
"is_default": true,
"phone_number": "+5511988887777",
"document_number": "123.456.789-00",
"investor_contact_information_key": "26299c0f-2127-45d4-b22e-f2b494d2f7ae"
}
]
}
],
"collateral_list": [
{
"collateral_key": "d8fdb578-1e2a-4b79-8267-5b1763e56754",
"collateral_type": "fiduciary_alienation_property"
}
],
"metadata_list": [
{
"metadata_key": "convenio",
"metadata_value": "12398129038"
}
],
}
```
### **Response Body Params**
| Campo | Tipo | Descrição |
| ---------------------------- | ------ | ----------------------------------------------------- |
| `tenant_key` * | string | Chave única do tenant. |
| `operation_key` * | string | Chave única da operação. |
| `operation_status` * | string | Status da operação. |
| `issuer_key` * | string | Chave única do emissor. |
| `issuer_name` * | string | Nome do emissor. |
| `issuer_document_number` * | string | Documento do emissor. |
| `financial` * | object | **[Objeto financial](#objeto-financial-response)** |
### Objeto financial response
| Campo | Tipo | Descrição | Caracteres Máx. |
| ---------------------------- | ------- | ---------------------------------------------------------- | ---------------------------------------------------------------------- |
| `financial_base_date` * | string | Data base financeira da operação (formato "YYYY-MM-DD"). | - |
| `issue_amount` * | number | Valor total emitido da operação. | - |
| `released_amount` * | number | Valor líquido liberado na operação. | - |
| `issue_quantity` * | integer | Quantidade total de unidades emitidas. | - |
| `unit_price` * | number | Preço unitário da emissão. | - |
| `cet` * | number | Custo Efetivo Total (CET) em percentual. | - |
| `annual_cet` * | number | CET anual em percentual. | - |
| `number_of_installments` * | integer | Número total de parcelas. | - |
| `prefixed_interest_rate` * | object | Objeto contendo detalhes da taxa de juros prefixada. | **[Objeto prefixed_interest_rate](#objeto-prefixed_interest_rate)** |
| `fees` | array | Lista de taxas associadas à operação. | **[Objeto fees](#objeto-fees)** |
| `installments` | array | Lista de detalhes das parcelas geradas na operação. | **[Objeto installments](#objeto-installments)** |
| `fine_delay_rate` * | object | Objeto contendo detalhes da multa por atraso. | **[Objeto fine_delay_rate](#objeto-fine_delay_rate)** |
| `contract_fine_rate` * | number | Multa contratual aplicada em percentual. | - |
### Objeto prefixed_interest_rate
| Campo | Tipo | Descrição | Caracteres Máx. |
| ------------------- | ------ | ------------------------------- | ---------------------------------------------------------------- |
| `interest_base` * | string | Base de cálculo para os juros. | **[Enumeradores interest_base](#enumeradores-interest_base)** |
| `monthly_rate` * | number | Taxa de juros mensal aplicada. | - |
| `daily_rate` * | number | Taxa de juros diária aplicada. | - |
| `annual_rate` * | number | Taxa de juros anual aplicada. | - |
### Objeto fees
| Campo | Tipo | Descrição | Caracteres Máx. |
| ----------------- | ------ | ---------------------------------------- | ---------------------------------------------------------------- |
| `amount` * | number | Valor percentual da taxa. | - |
| `fee_amount` * | number | Valor monetário correspondente à taxa. | - |
| `amount_type` * | string | Tipo do valor da taxa. | **[Enumeradores amount_type](#enumeradores-amount_type)** |
| `fee_type` * | string | Tipo da taxa. | **[Enumeradores fee_type](#enumeradores-fee_type)** |
| `type` * | string | Destinatário da taxa. | **[Enumeradores fee_recipient](#enumeradores-fee_recipient)** |
### Objeto installments
| Campo | Tipo | Descrição |
| --------------------------------------- | ------- | ----------------------------------------------------- |
| `installment_number` * | integer | Número da parcela. |
| `workdays` * | integer | Dias úteis até o vencimento da parcela. |
| `calendar_days` * | integer | Dias corridos até o vencimento da parcela. |
| `principal_amortization_amount` * | number | Valor amortizado do principal. |
| `principal_amortization_unit_price` * | number | Valor amortizado por unidade. |
| `interest_amount` * | number | Valor dos juros aplicados na parcela. |
| `amount` * | number | Valor total da parcela. |
| `due_date` * | string | Data de vencimento da parcela (formato "YYYY-MM-DD"). |
---
# Consulta de templates disponíveis
URL: /documentation/escrituracao/emissao-de-notas/geracao-minutas/consulta-minutas-disponiveis
Este endpoint permite a consulta de todos os templates disponíveis para serem utilizados no sistema de escrituração.
### **Request**
ENDPOINT /document_template/document_template
MÉTODO GET
### **Query Params**
| Campo | Tipo | Descrição | Obrigatório |
|----------------------------|----------|-----------------------------------------------|-------------|
| `document_type` | string | Tipo do documento | Não |
---
## Response
STATUS 200
Response Body
```json
{
"data" : [
{
"document_key": "a846cc4a-b542-4f66-9823-b6d5458bd127",
"document_type": "adhesion_term"
},
{
"document_key": "a846cc4a-b542-4f66-9823-b6d5458bd127",
"document_type": "commercial_paper"
}
]
}
```
### **Response Body Params**
| Campo | Tipo | Descrição | Caracteres Máx. |
|------------------|----------|------------------------------------------------|-----------------|
| `document_key` * | string | Chave única do template (UUID v4). | 36 |
| `document_type` * | string | Tipo do documento gerado. | 50 |
---
# Roteiro de Integração — API de Escrituração de Notas Comerciais (NC) com Auto-Assinatura
URL: /documentation/escrituracao/roteiro-integracao/integration-guide-nc-auto-signature
Este roteiro descreve todos os recursos e funcionalidades que precisam ser testados pelo parceiro
integrador no ambiente de **Sandbox** da QI Tech, antes da entrada em ambiente de produção para
emissão de notas comerciais (NC).
Trata-se de uma versão personalizada do roteiro padrão de integração de NC da QI Tech, adaptada para
o **fluxo de emissão totalmente automatizado**: uma vez que o emissor esteja cadastrado, aprovado e
habilitado para auto-assinatura, todas as emissões seguintes ocorrem de ponta a ponta via API, sem
etapa manual de assinatura.
:::warning Atenção
**Todos os testes devem ser obrigatoriamente realizados no ambiente de Sandbox da QI Tech. As
operações realizadas em ambiente de Sandbox são operações financeiras fictícias, servindo apenas para
teste de funcionalidade das APIs.**
:::
---
## 1. Escopo e fases
O fluxo é dividido em seis fases. As fases 0 a 4 se apoiam em funcionalidades já disponíveis na API, incluindo a habilitação da auto-assinatura (Fase 2), que já está publicada. A Fase 6 é dividida em duas: a transferência de recursos para a conta de liquidação da WL (6.1) utiliza endpoints de BaaS que já existem e podem ser homologados hoje; o pagamento ao fornecedor (6.2) depende de novo desenvolvimento.
| Legenda | Significado |
| --- | --- |
| ✅ | Disponível hoje — pode ser homologado em Sandbox imediatamente |
| 🆕 | Novo desenvolvimento — contrato do endpoint a ser publicado; a homologação começa após a liberação |
| ⚙️ | Executado pela QI Tech (sem ação do integrador, mas o integrador precisa observar o status resultante) |
| `*` | Etapa obrigatória para o aceite da homologação |
:::warning Premissa de sequenciamento
**A habilitação só pode ser solicitada depois que o cadastro do emissor é aprovado** — e pode, e
deve, ser concluída **antes da primeira emissão**. O termo de adesão é assinado em um **envelope
próprio, com um link por assinante**, independente de qualquer operação: não é preciso criar uma NC
para habilitá-la, nem existe uma "primeira emissão manual" obrigatória. A Fase 2 é, portanto, um portão único por
emissor, e não uma etapa por operação — concluída antes da primeira emissão, todas as emissões
daquele emissor já saem com assinatura automática.
:::
---
## 2. Fluxo ponta a ponta
```mermaid
flowchart TD
A[Fase 0 · Troca de chaves, autenticação, webhooks] --> B{Emissor já
cadastrado na QI Tech?}
B -- Sim --> C[Fase 1A · Reutilizar cadastro existente]
B -- Não --> D[Fase 1B · Cadastrar emissor do zero]
C --> E[Emissor aprovado]
D --> E
E --> F[Fase 2 · Integrador solicita a habilitação
POST auto_signature]
F --> F2[Mesma chamada gera o termo
e abre o envelope de assinatura]
F2 --> G[Termo de adesão assinado uma única vez
cada assinante no seu próprio link]
G --> H[QI Tech emite certificado privado
na CertifiQI — apenas documentos de NC ⚙️]
H --> I[Status da auto-assinatura: enabled]
I --> J[Fase 4 · NC criada via API]
J --> K[Enviada para análise → aprovada automaticamente]
K --> L[Termo Constitutivo assinado automaticamente
via certificado privado]
L --> M[Fase 5 · Boletim de subscrição
emitido e assinado automaticamente]
M --> N[Webhook · Boletim de subscrição assinado]
N --> O[Fase 6.1 · Sistema do cliente comanda transferência
BaaS para a conta de liquidação da WL 🆕]
O --> P[Fase 6.2 · Pagamento da conta de liquidação
para o fornecedor 🆕]
```
---
## 3. Fase 0 — Cadastro e autenticação na API
| Código | Etapa | Descrição | Documentação | Pré-requisito | Status |
| --- | --- | --- | --- | --- | --- |
| CAB0001* | Troca de chave pública | Realizar a troca de chave pública com o time de operações da plataforma (suporte-dcm@qitech.com.br) | [Documentação](/documentation/escrituracao/introducao/troca_de_chaves) | — | ✅ |
| CAB0002* | Teste de autenticação | Após o recebimento da chave de API, realizar os testes de autenticação de chamada | [Documentação](/documentation/escrituracao/introducao/teste-autenticacao/teste_de_autenticacao)
[Documentação](/documentation/escrituracao/introducao/teste-autenticacao/endpoints_de_teste) | CAB0001 | ✅ |
| CAB0003* | Configuração de webhooks | Configurar a URL para a qual a QI Tech enviará os webhooks | [Documentação](/documentation/escrituracao/introducao/autenticacao_webhooks)
[Documentação](/documentation/escrituracao/configuracao-webhooks)
[Documentação](/documentation/escrituracao/webhooks-escrituracao) | CAB0001, CAB0002 | ✅ |
:::warning Atenção
Neste fluxo, a configuração de webhooks é obrigatória, e não opcional. Como a análise, a aprovação e a
assinatura são automáticas, o integrador não possui nenhum ponto de conferência manual — os webhooks
são a única forma de acompanhar o avanço da operação sem polling.
:::
---
## 4. Fase 1 — Homologação do emissor
:::warning Atenção
**Caso o cliente já tenha realizado a integração com os cadastros de cedente da QI Tech, é possível
reutilizar esses cadastros, o que simplifica consideravelmente a homologação no sistema.**
:::
### 4.1 Fase 1A — Emissor cadastrado no sistema de cedentes da QI Tech
| Código | Etapa | Descrição | Documentação | Pré-requisito | Status |
| --- | --- | --- | --- | --- | --- |
| CED1001* | Reutilizar cadastro de cedente | Reutilizar um cadastro de cedente existente por CNPJ | [Documentação](/documentation/escrituracao/homologacao-emissor/solicitacao-acesso) | CAB0002 | ✅ |
| CED1002* | Listar emissores cadastrados | Listar os emissores cadastrados, filtrando por CNPJ ou nome | [Documentação](/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-filtro) | CED1001 | ✅ |
| CED1003* | Detalhes do emissor | Consultar os detalhes de um emissor cadastrado pela `issuer_key` | [Documentação](/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-chave) | CED1001 | ✅ |
### 4.2 Fase 1B — Emissor cadastrado pelo sistema
| Código | Etapa | Descrição | Documentação | Pré-requisito | Status |
| --- | --- | --- | --- | --- | --- |
| CED0001* | Cadastro básico do emissor | Criar o emissor com seus dados cadastrais básicos | [Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/cadastro-basico) | CAB0002 | ✅ |
| CED0002* | Upload / remoção de documentos do emissor | Anexar e remover documentos associados a um emissor cadastrado | [Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor)
[Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor-remocao) | CED0001 | ✅ |
| CED0003* | Cadastro / remoção de representantes do emissor | Adicionar e remover representantes associados a um emissor cadastrado | [Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor)
[Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor-remocao) | CED0001 | ✅ |
| CED0004* | Upload / remoção de documentos de representantes | Anexar e remover documentos associados a um representante de um emissor cadastrado | [Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor)
[Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor-remocao) | CED0001, CED0003 | ✅ |
| CED0005* | Cadastro / remoção de conta bancária do emissor | Adicionar e remover uma conta bancária associada a um emissor cadastrado | [Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor)
[Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor-remocao) | CED0001 | ✅ |
| CED0006* | Cadastro / remoção de grupos de assinantes do emissor | Adicionar e remover grupos de assinantes associados a um emissor cadastrado | [Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor)
[Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor-remocao) | CED0001, CED0003 | ✅ |
| CED0007* | Cadastro / remoção de informações de contato do emissor | Adicionar e remover informações de contato associadas a um emissor cadastrado | [Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor)
[Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor-remocao) | CED0001 | ✅ |
| CED0008* | Envio do emissor para análise | Mover o emissor para o status de análise, enviando-o ao processo de validação | [Documentação](/documentation/escrituracao/homologacao-emissor/envio-analise/) | CED0001 → CED0007 | ✅ |
| CED0009* | Alteração do cadastro do emissor | Reabrir o emissor para edição | [Documentação](/documentation/escrituracao/homologacao-emissor/alteracao-cadastro/) | CED0001 → CED0007 | ✅ |
| CED0010* | Listar emissores cadastrados | Listar os emissores cadastrados, filtrando por CNPJ ou nome | [Documentação](/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-filtro) | CED0001 | ✅ |
| CED0011* | Detalhes do emissor | Consultar os detalhes de um emissor cadastrado pela `issuer_key` | [Documentação](/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-chave) | CED0001 | ✅ |
:::warning Portão para a Fase 2
O grupo de assinantes cadastrado em **CED0006** define qual representante assinará em nome do
emissor. Esse mesmo grupo de assinantes é quem assina o termo de adesão da auto-assinatura na Fase 2 e cuja
alçada o certificado privado representa. Cadastre-o corretamente antes de enviar o emissor para
análise — uma alteração posterior exige repetir a Fase 2.
:::
---
## 5. Fase 2 — Habilitação da auto-assinatura ✅
Esta fase ocorre **uma única vez por emissor**, logo após a aprovação do cadastro, e resulta em um
certificado privado da QI Tech com escopo exclusivo aos documentos de NC desta integração.
**A habilitação é solicitada pelo integrador**, com um `POST` que só é aceito depois que o cadastro
do emissor está aprovado. Não há criação automática. O cliente precisa estar habilitado para
auto-assinatura — uma configuração feita pela QI Tech, que inclui o template do termo de adesão.
**A solicitação já abre o envelope.** A geração do termo e a criação do envelope acontecem dentro
da própria chamada, que responde em `pending_signature` com a `envelope_key` — os links de
assinatura podem ser consultados na sequência, sem esperar por webhook.
**O que o termo de adesão autoriza.** Ele concede à QI Tech um mandato limitado para emitir e
custodiar um certificado privado interno, liberado na CertifiQI, a ser utilizado exclusivamente para
assinar os documentos deste fluxo de NC em nome do emissor — nunca para qualquer outro documento,
produto ou contraparte. É assinado uma única vez pelo grupo de assinantes cadastrado no emissor —
**cada assinante recebe o seu próprio link de assinatura**.
**Quando é assinado.** O termo tem **envelope e link de assinatura próprios**, gerados na
habilitação e independentes de qualquer operação. Ele pode ser assinado assim que o emissor é
aprovado, **antes da primeira emissão** — que é o caminho recomendado, porque leva o emissor à
primeira operação já com a assinatura automática ativa. Se a Fase 2 ainda não tiver sido concluída
quando a operação for criada, ela simplesmente segue pelo fallback manual do QI SIGN, como qualquer
emissor em status diferente de `enabled`.
| Código | Etapa | Descrição | Documentação | Pré-requisito | Status |
| --- | --- | --- | --- | --- | --- |
| ASG0001* | Habilitação do cliente para auto-assinatura | A QI Tech habilita o cliente e configura o template do termo de adesão. Sem isso, nenhum emissor do cliente tem auto-assinatura criada | [Documentação](/documentation/escrituracao/homologacao-emissor/auto-assinatura/inicio) | — | ⚙️ |
| ASG0002* | Solicitar a habilitação | `POST /issuer_management/issuer/{issuer_key}/auto_signature` para um emissor aprovado. A mesma chamada gera o termo de adesão e abre o envelope: retorna a `issuer_auto_signature_key` e a `envelope_key` já em `pending_signature`. Recusado com `ISS0000032` se o emissor não estiver aprovado | [Documentação](/documentation/escrituracao/homologacao-emissor/auto-assinatura/solicitacao-auto-assinatura) | ASG0001, CED0011 ou CED1003 | ✅ |
| ASG0003 | Webhook — termo enviado para assinatura | Receber o webhook `issuer_management.auto_signature_status_change` com status `pending_signature`. Confirma o que a resposta do ASG0002 já trouxe, e avisa os demais consumidores do tenant | [Documentação](/documentation/escrituracao/webhooks-escrituracao) | CAB0003, ASG0002 | ✅ |
| ASG0004* | Consultar os links de assinatura | `GET .../auto_signature/signers` devolve um link por assinante, com o status individual de cada um. Direcionar **cada assinante do emissor ao seu próprio link**. Os links independem de qualquer operação — podem ser usados antes da primeira emissão | [Documentação](/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-links-assinatura) | ASG0002 | ✅ |
| ASG0005* | Webhook — auto-assinatura habilitada | Receber o webhook com status `enabled`, que confirma que o termo foi assinado e o emissor está habilitado à assinatura automática | [Documentação](/documentation/escrituracao/webhooks-escrituracao) | CAB0003, ASG0004 | ✅ |
| ASG0006* | Consultar status da auto-assinatura | Consultar a habilitação pela `issuer_key` e confirmar a transição para `enabled`, com o histórico de eventos. Nenhuma NC pode depender da assinatura automática antes de esse status ser atingido | [Documentação](/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-auto-assinatura) | ASG0002 | ✅ |
| ASG0007 | Emissão do certificado privado | A QI Tech cria o certificado privado e o libera na CertifiQI, com escopo restrito aos documentos de NC deste emissor. Hoje é manual (uma única vez por emissor, executado pela QI Tech); a automação está no roadmap e não bloqueia o go-live | — | ASG0005 | ⚙️ |
| ASG0008 | Cancelar a auto-assinatura | Cancelar a habilitação — necessário quando o grupo de assinantes muda ou a pedido do emissor. Solicitado à QI Tech; não há endpoint público. Após o cancelamento, as emissões voltam ao fluxo manual até que uma nova habilitação seja solicitada | — | ASG0006 | ⚙️ |
:::info Cancelamento automático
A auto-assinatura é cancelada automaticamente quando o emissor deixa o status `approved` — ou seja,
quando passa para `reproved`, `expired` ou `canceled`. A habilitação precisa ser refeita após a nova
aprovação do cadastro.
:::
### 5.1 Máquina de status da habilitação
| Status | Significado | Comportamento de assinatura de uma nova NC |
| --- | --- | --- |
| _sem auto-assinatura_ | Habilitação nunca solicitada, ou cliente não habilitado | Assinatura manual (QI SIGN) |
| `pending_term_generation` | Habilitação solicitada; termo de adesão ainda não gerado | Assinatura manual |
| `pending_signature` | Termo gerado e enviado para assinatura; links dos assinantes disponíveis | Assinatura manual — o termo é assinado em links próprios, fora da operação |
| `enabled` | Termo assinado; emissor habilitado à assinatura automática | **Automática** |
| `reproved` | Envelope do termo recusado, cancelado ou expirado | Assinatura manual (QI SIGN) |
| `canceled` | Habilitação cancelada | Assinatura manual (QI SIGN) |
:::warning Requisito de homologação
O integrador deve demonstrar, em Sandbox, que seu sistema lê o status da habilitação antes de criar
uma operação e roteia corretamente nos dois sentidos: assinatura automática quando `enabled` e o
fallback do QI SIGN (COM0015 / COM0016) em todos os demais status. Uma integração que assume `enabled`
vai quebrar para todo emissor cuja Fase 2 ainda não tenha sido concluída.
:::
---
## 6. Fase 3 — Homologação do investidor
:::warning Atenção
**Caso o cliente opere com fundos fixos, estes podem ser cadastrados durante o setup, o que simplifica
consideravelmente a integração.** Para este fluxo, o caminho de fundos fixos é a configuração
esperada.
:::
### 6.1 Investidores cadastrados durante o setup — caminho recomendado
| Código | Etapa | Descrição | Documentação | Pré-requisito | Status |
| --- | --- | --- | --- | --- | --- |
| INV1001* | Listar investidores cadastrados | Listar os fundos cadastrados, filtrando por CNPJ ou nome | [Documentação](/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-filtro) | CAB0002 | ✅ |
| INV1002* | Detalhes do investidor | Consultar os detalhes de um investidor cadastrado pela `investor_key` | [Documentação](/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-chave) | CAB0002 | ✅ |
### 6.2 Investidores cadastrados pelo sistema — apenas se não forem utilizados fundos fixos
| Código | Etapa | Descrição | Documentação | Pré-requisito | Status |
| --- | --- | --- | --- | --- | --- |
| INV0001* | Cadastro básico do investidor | Criar o investidor com seus dados cadastrais básicos | [Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/cadastro-basico) | CAB0002 | ✅ |
| INV0002* | Upload / remoção de documentos do investidor | Anexar e remover documentos associados a um investidor cadastrado | [Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/documentos-investidor)
[Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/documentos-investidor-remocao) | INV0001 | ✅ |
| INV0003* | Cadastro / remoção de representantes do investidor | Adicionar e remover representantes associados a um investidor cadastrado | [Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/representantes-investidor)
[Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/representantes-investidor-remocao) | INV0001 | ✅ |
| INV0004* | Upload / remoção de documentos de representantes | Anexar e remover documentos associados a um representante de um investidor cadastrado | [Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/documentos-representantes-investidor)
[Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/documentos-representantes-investidor-remocao) | INV0001, INV0003 | ✅ |
| INV0005* | Cadastro / remoção de conta bancária do investidor | Adicionar e remover uma conta bancária associada a um investidor cadastrado | [Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/conta-bancaria-investidor)
[Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/conta-bancaria-investidor-remocao) | INV0001 | ✅ |
| INV0006* | Cadastro / remoção de grupos de assinantes do investidor | Adicionar e remover grupos de assinantes associados a um investidor cadastrado | [Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/assinantes-investidor)
[Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/assinantes-investidor-remocao) | INV0001 | ✅ |
| INV0007* | Cadastro / remoção de informações de contato do investidor | Adicionar e remover informações de contato associadas a um investidor cadastrado | [Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/informacao-contato-investidor)
[Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/informacao-contato-investidor-remocao) | INV0001 | ✅ |
| INV0008* | Envio do investidor para análise | Mover o investidor para o status de análise, enviando-o ao processo de validação | [Documentação](/documentation/escrituracao/homologacao-investidor/envio-analise/) | INV0001 → INV0007 | ✅ |
| INV0009* | Alteração do cadastro do investidor | Reabrir o investidor para edição | [Documentação](/documentation/escrituracao/homologacao-investidor/alteracao-cadastro/) | INV0001 → INV0007 | ✅ |
| INV0010* | Listar investidores cadastrados | Listar os fundos cadastrados, filtrando por CNPJ ou nome | [Documentação](/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-filtro) | INV0001 | ✅ |
| INV0011* | Detalhes do investidor | Consultar os detalhes de um investidor cadastrado pela `investor_key` | [Documentação](/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-chave) | INV0001 | ✅ |
---
## 7. Fase 4 — Emissão da NC
Com emissores e investidores cadastrados, as notas comerciais podem ser emitidas. A emissão via API é
a premissa central desta integração: o fluxo por tela não funciona no volume pretendido.
### 7.1 Criação da operação
| Código | Etapa | Descrição | Documentação | Pré-requisito | Status |
| --- | --- | --- | --- | --- | --- |
| COM0001* | Simular condições financeiras | Simular as condições financeiras e o cronograma de pagamento de uma operação | [Documentação](/documentation/escrituracao/emissao-de-notas/simulacao) | CAB0002 | ✅ |
| COM0002* | Criar operação de NC | Criar uma nova operação de nota comercial a partir dos dados financeiros e do investidor | [Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/criar-operacao) | COM0001, CED0011/CED1003, INV1002 | ✅ |
| COM0003* | Cadastro / remoção de partes relacionadas | Adicionar e remover partes relacionadas a uma operação | [Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/cadastrar-parte-relacionada) | COM0002 | ✅ |
| COM0004* | Upload / remoção de documentos de representantes de partes relacionadas | Anexar e remover documentos associados a representantes de partes relacionadas | [Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-documento) | COM0002, COM0003 | ✅ |
| COM0005* | Cadastro / remoção de grupos de assinantes de partes relacionadas | Adicionar e remover grupos de assinantes associados a representantes de partes relacionadas | [Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-grupo-assinantes) | COM0002, COM0003 | ✅ |
| COM0006 | Prévia do Termo Constitutivo | Gerar uma minuta do Termo Constitutivo de uma operação a partir de um template predefinido | [Documentação](/documentation/escrituracao/emissao-de-notas/geracao-minutas/gerar-minuta-contrato) | COM0002 | ✅ |
| COM0007* | Alterar template do Termo Constitutivo | Alterar o template do Termo Constitutivo utilizado por uma operação | [Documentação](/documentation/escrituracao/emissao-de-notas/geracao-minutas/alterar-template-tc) | COM0002 | ✅ |
| COM0008* | Upload de documentos | Realizar o upload de documentos associados a uma operação. A `document_key` retornada pode ser utilizada, por exemplo, no sistema de garantias | [Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/upload-documento) | COM0002 | ✅ |
| COM0009* | Cadastro de garantias | Adicionar garantias associadas a uma operação | [Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/cadastro-garantia) | COM0002, COM0008 | ✅ |
| COM0010* | Cadastro / remoção de partes relacionadas de um contrato ou garantia | Adicionar e remover partes relacionadas a um contrato ou garantia específica da operação | [Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-parte-relacionada-em-documento) | COM0002, COM0003 | ✅ |
| COM0011* | Envio da operação para análise | Mover a operação para "em análise", enviando-a ao processo de validação de compliance | [Documentação](/documentation/escrituracao/emissao-de-notas/envio-para-analise) | COM0002 → COM0009 | ✅ |
| COM0012* | Envio de ata de aprovação assinada | Enviar a ata de aprovação assinada externamente para emissores SA ou COP, em payload base64, analisada e aprovada | [Documentação](/documentation/escrituracao/emissao-de-notas/envio-ata-aprovacao) | COM0002 | ✅ |
| COM0013* | Consulta de operações por filtro | Consultar operações de nota comercial utilizando filtros opcionais | [Documentação](/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-filtros) | COM0002 → COM0009 | ✅ |
| COM0014* | Consulta de operação por chave | Consultar os detalhes completos de uma operação específica pela sua chave única | [Documentação](/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-chave) | COM0002 → COM0009 | ✅ |
| COM0024* | Declarar o beneficiário terceiro na criação | Enviar `third_party_disbursement` no corpo da criação da operação, indicando que o valor liberado será pago a um fornecedor e não à conta de liquidação do emissor. Requer habilitação prévia | [Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/criar-operacao) | COM0002 | ⚙️ 🆕 |
| COM0025* | Alterar o beneficiário terceiro | Substituir a instrução de desembolso a terceiro de uma operação ainda em `in_filling` — trocar entre TED, boleto e Pix ou corrigir os dados do beneficiário | [Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/desembolso-terceiro) | COM0002 | ⚙️ 🆕 |
:::info Desembolso para terceiro — recurso sob habilitação 🆕
O recurso não vem habilitado por padrão; solicite a habilitação à QI Tech antes de integrar. Sem ela
a criação da operação é recusada com `COM000062` e nada é persistido.
Três trilhas, mutuamente exclusivas:
- **TED** — `payment_method: "ted"` com `target_account`.
- **Boleto** — `payment_method: "bank_slip"` com `digitable_line` de 47 dígitos, cujos 10 últimos
dígitos (em centavos) precisam ser exatamente o `released_amount` da operação.
- **Pix** 🆕 — `payment_method: "pix"` com `pix_key` e `pix_key_type` (`cpf`, `cnpj`, `phone`,
`email` ou `evp`). A chave viaja **sem formatação** para CPF e CNPJ.
Em TED e boleto o beneficiário é identificado pelos próprios dados de pagamento. Como uma chave
Pix não diz quem recebe, a trilha Pix exige também o objeto **`beneficiary`** 🆕 — a qualificação
completa do terceiro, com os mesmos campos de uma parte relacionada, usada para registrar o
pagamento na ata. Esse objeto é aceito, opcionalmente, também em TED e boleto.
O beneficiário viaja junto da operação e é assinado com ela. O pagamento é executado
automaticamente no desembolso — **não há endpoint de pagamento a ser chamado** (ver §9.2).
:::
### 7.2 Assinatura — caminho automático (emissor com auto-assinatura `enabled`) 🆕
| Código | Etapa | Descrição | Documentação | Pré-requisito | Status |
| --- | --- | --- | --- | --- | --- |
| COM0020* | Aprovação automática | Com a auto-assinatura em `enabled` e as condições operacionais previamente aprovadas, a operação passa de análise para aprovada sem intervenção manual. O integrador observa a transição via webhook | [Documentação](/documentation/escrituracao/emissao-de-notas/aprovacao-automatica) *(pendente de publicação)* | COM0011, ASG0006 | ⚙️ 🆕 |
| COM0021* | Assinatura automática do Termo Constitutivo | A QI Tech assina o Termo Constitutivo em nome do emissor utilizando o certificado privado liberado na CertifiQI. Nenhum link de assinatura é gerado para o emissor | [Documentação](/documentation/escrituracao/emissao-de-notas/assinatura-automatica) *(pendente de publicação)* | COM0020 | ⚙️ 🆕 |
| COM0022* | Webhook — operação assinada | Receber o webhook que confirma que todas as assinaturas da operação foram concluídas | [Documentação](/documentation/escrituracao/webhooks-escrituracao) | CAB0003, COM0021 | 🆕 |
| COM0023* | Consulta de documentos assinados | Consultar os documentos assinados da operação pela sua chave única, incluindo o relatório de evidências de assinatura | [Documentação](/documentation/escrituracao/emissao-de-notas/consulta-link-assinado-qisign) | COM0022 | ✅ |
| COM0026* | Envio do log de aceite do cliente | Anexar à operação, em payload base64, o PDF com as evidências de aceite do cliente final. Envio opcional, aceito apenas em `in_filling` e apenas quando o emissor tem a auto-assinatura em `enabled` | [Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/log-aceite) | COM0002, ASG0006 | ⚙️ 🆕 |
:::info Log de aceite — a evidência do consentimento do cliente 🆕
No caminho automático nenhum link de assinatura é gerado para o cliente final, então o consentimento
dele não fica registrado pelo envelope de assinatura. O log de aceite é onde essa evidência entra: um
PDF com o registro do aceite, anexado à operação enquanto ela está em `in_filling`.
O envio é **opcional** — a emissão não depende dele e nada é bloqueado na sua ausência. O documento é
guardado como evidência: não entra no envelope de assinatura, não entra no pacote de documentos
assinados (COM0023) e não altera a aprovação automática (COM0020). A operação passa a expor
`acceptance_log_document_key` na consulta por chave.
Emissor sem auto-assinatura em `enabled` é recusado com `COM000077`. Um reenvio substitui o documento
vigente; não há endpoint de remoção.
:::
### 7.3 Assinatura — fallback manual (QI SIGN)
Obrigatório para qualquer emissor cujo status de habilitação não seja `enabled` — inclusive um
emissor cuja Fase 2 ainda não tenha sido concluída. **Não há uma "primeira emissão manual"
obrigatória**: se a auto-assinatura já estiver ativa quando a operação for criada, a primeira
emissão já é automática.
| Código | Etapa | Descrição | Documentação | Pré-requisito | Status |
| --- | --- | --- | --- | --- | --- |
| COM0015* | Consulta de links de assinatura QI SIGN | Consultar todos os links de assinatura de uma operação específica via QI SIGN, pela sua chave única | [Documentação](/documentation/escrituracao/emissao-de-notas/consulta-link-assinatura-qisign) | COM0002 → COM0009 | ✅ |
| COM0016* | Consulta de links de contratos assinados | Consultar todos os documentos assinados de uma operação específica via QI SIGN, pela sua chave única | [Documentação](/documentation/escrituracao/emissao-de-notas/consulta-link-assinado-qisign) | COM0002 → COM0009 | ✅ |
---
## 8. Fase 5 — Subscrição e integralização
Com a operação assinada, o boletim de subscrição é gerado automaticamente e disponibilizado para
assinatura do investidor. Quando o investidor também está habilitado para auto-assinatura, esta etapa
também não exige interação humana.
| Código | Etapa | Descrição | Documentação | Pré-requisito | Status |
| --- | --- | --- | --- | --- | --- |
| INT0001* | Consulta de processo de integralização por chave | Consultar os detalhes de um processo de integralização pela sua chave única | [Documentação](/documentation/escrituracao/integralizacao-cotas/consulta-processo-integralizacao) | COM0022 | ✅ |
| INT0002* | Consulta de subscrição | Consultar uma subscrição em andamento | [Documentação](/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/consulta-subscricao-cotas) | INT0001 | ✅ |
| INT0003 | Cadastro de subscrição | Cadastrar a intenção de um investidor de subscrever um número específico de cotas — útil quando a data de subscrição precisa ser deslocada | [Documentação](/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/cadastro-subscricao) | INT0001, INT0002 | ✅ |
| INT0004 | Cancelamento de subscrição | Cancelar uma subscrição — útil quando a data de subscrição precisa ser deslocada | [Documentação](/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/cancelar-subscricao) | INT0001, INT0002 | ✅ |
| INT0005* | Webhook — boletim de subscrição assinado | Receber o webhook que confirma que o boletim de subscrição foi assinado. Este é o gatilho que o sistema do cliente utiliza para comandar a transferência de recursos da Fase 6.1 (TFI0002) | [Documentação](/documentation/escrituracao/webhooks-escrituracao) | CAB0003, INT0002 | 🆕 |
---
## 9. Fase 6 — Transferência de recursos e pagamento 🆕
A Fase 6 possui duas pernas. A primeira (**6.1**) é disparada pelo próprio sistema do integrador ao
receber o webhook de assinatura do boletim de subscrição, e move os recursos para a conta de
liquidação da WL. A segunda (**6.2**) paga o fornecedor a partir dessa conta.
### 9.1 Perna 1 — Transferência para a conta de liquidação da WL 🆕
**Gatilho.** O webhook de `boletim de subscrição assinado` (**INT0005**) é o evento que autoriza a
transferência de recursos. Ao recebê-lo, o sistema do cliente comanda um pagamento na API de BaaS,
enviando uma transferência para a conta de liquidação da WL. A QI Tech não inicia essa transferência —
é uma ação do lado do integrador, e o webhook é seu único gatilho. Nada nesta perna pode ser disparado
antes da chegada do INT0005: uma transferência comandada contra um boletim não assinado não possui
operação que a lastreie.
Como origem e destino são QI Contas, trata-se de uma **transferência interna** (QI Conta → QI Conta),
que liquida em tempo real e não depende dos trilhos de Pix ou TED.
| Código | Etapa | Descrição | Documentação | Pré-requisito | Status |
| --- | --- | --- | --- | --- | --- |
| TFI0001* | Consultar a conta de liquidação da WL | Consultar a conta de liquidação da WL que receberá os recursos, incluindo seus identificadores e saldo | [Documentação](/documentation/movimentacao_de_contas/consulta_de_transacoes) | CAB0002 | ✅ |
| TFI0002* | Comandar a transferência interna | Ao receber o INT0005, comandar a transferência da QI Conta de origem para a conta de liquidação da WL. A requisição deve carregar a chave única da operação para que o crédito possa ser conciliado de volta à NC | [Documentação](/documentation/baas/ted/realizar_transferencia) | INT0005, TFI0001 | ✅ |
| TFI0003* | Consultar a transferência | Consultar a transferência comandada e confirmar que ela liquidou na conta de liquidação da WL | [Documentação](/documentation/movimentacao_de_contas/consulta_de_transferencias_realizadas) | TFI0002 | ✅ |
| TFI0004* | Webhook — transação liquidada | Receber o webhook de movimentação que confirma o crédito na conta de liquidação da WL. Este é o gatilho da perna 6.2 | [Documentação](/documentation/movimentacao_de_contas/webhook_movimentacoes) | CAB0003, TFI0002 | ✅ |
| TFI0005 | Comprovante de transferência | Solicitar o comprovante da transferência para registro e trilha de auditoria do próprio integrador | [Documentação](/documentation/movimentacao_de_contas/comprovante_de_transferencia) | TFI0002 | ✅ |
:::warning Idempotência
O webhook pode ser entregue mais de uma vez. O integrador deve chavear a transferência pela operação,
de modo que um INT0005 reentregue não comande uma segunda transferência para a mesma NC. A
conciliação entre a chave da operação e a transação creditada é responsabilidade do integrador.
:::
#### TFI0002 — Comandar a transferência interna
ENDPOINT /account/ ACCOUNT_KEY /ted
MÉTODO POST
A `ACCOUNT_KEY` é a QI Conta de origem que será debitada. O `target_account` é a conta de liquidação
da WL — no caminho interno, seu `ispb` é o da própria QI Tech (`32402502`), o que faz a transferência
liquidar conta a conta em vez de sair pelo trilho de TED.
Request Body
```json
{
"request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
"target_account": {
"account_branch": "0001",
"account_number": "2359934",
"account_digit": "2",
"owner_document_number": "09080702000105",
"owner_name": "Conta de Liquidação WL",
"ispb": "32402502",
"account_type": "checking_account"
},
"transaction_amount": 150000.00
}
```
:::warning A `request_control_key` é a chave de idempotência
Derive-a de forma determinística a partir da chave da operação de NC, em vez de gerar um UUID novo a
cada tentativa. Um INT0005 reentregue que produza a mesma `request_control_key` é rejeitado como
duplicidade, em vez de pagar a conta de liquidação duas vezes.
:::
Response Body — 201
```json
{
"request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
"ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"created_at": "2021-10-22T20:30:23.459Z",
"ted_status": "sent",
"transaction_amount": 150000.00,
"fee_amount": 0.0,
"transaction_key": "46804f32-101e-4702-8fbc-c2dbc4c2caec"
}
```
#### TFI0004 — Webhook de confirmação do crédito
O crédito na conta de liquidação da WL chega como um webhook `account_transaction`, com `data.amount`
positivo e `source_sub_type` = `internal_funds_transfer`. Faça o casamento de `data.transaction_key`
com a `transaction_key` retornada pelo TFI0002 para fechar o ciclo de volta à operação de NC.
WEBHOOK_TYPE account_transaction
Webhook Body
```json
{
"key": "",
"data": {
"amount": 150000.00,
"origin": {
"name": "Conta de Origem",
"branch": "0001",
"document": "32402502000135",
"account_key": "5d068423-6094-49e4-b15b-7740038295a8",
"account_digit": "5",
"account_number": "00002"
},
"timestamp": "2022-09-02T21:36:33.446120",
"destination": {
"name": "Conta de Liquidação WL",
"branch": "0001",
"document": "09080702000105",
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"account_digit": "2",
"account_number": "2359934"
},
"reference_key": "983b4a28-7de6-4e71-97ef-60fb50c7b013",
"reference_type": "movement_request",
"account_balance": 150000.00,
"source_sub_type": "internal_funds_transfer",
"transaction_key": "46804f32-101e-4702-8fbc-c2dbc4c2caec",
"source_sub_type_str": "Transferência Interna"
},
"datetime": "2022-09-02T21:36:33.446120",
"webhook_type": "account_transaction"
}
```
:::danger Não mapeie os webhooks de forma restrita
Campos adicionais podem ser incluídos aos payloads dos webhooks da QI Tech a qualquer momento. Faça um
parsing defensivo — uma integração que rejeita campos desconhecidos vai quebrar em uma release futura.
:::
### 9.2 Perna 2 — Pagamento ao fornecedor 🆕
A conta de liquidação do emissor é aberta gratuitamente pela QI Tech no momento da emissão e é
referenciada no pacote de assinatura da NC. Pagar o fornecedor a partir da conta de liquidação do
próprio emissor preserva a relação comercial: o fornecedor vê o pagamento chegando do seu próprio
cliente.
**O pagamento não é uma chamada do integrador.** O beneficiário é declarado na própria operação
(`third_party_disbursement`, ver COM0024/COM0025 no §7.1), assinado junto do Termo Constitutivo, e o
desembolso é executado automaticamente pela QI Tech quando os recursos liquidam. O integrador
acompanha por webhook — não existe endpoint de "iniciar pagamento" a ser chamado nesta trilha.
| Código | Etapa | Descrição | Documentação | Pré-requisito | Status |
| --- | --- | --- | --- | --- | --- |
| PAY0001* | Consultar a conta de liquidação do emissor | Consultar a conta de liquidação aberta para o emissor na emissão, incluindo seus identificadores e saldo | [Documentação](/documentation/baas/contas/consulta-conta) *(a confirmar)* | COM0022 | 🆕 |
| PAY0002* | Confirmar recursos disponíveis | Confirmar que os recursos transferidos na perna 6.1 liquidaram na conta de liquidação | [Documentação](/documentation/movimentacao_de_contas/consulta_de_transacoes) | TFI0004 | ✅ |
| PAY0003* | Desembolso automático ao beneficiário | Com `third_party_disbursement` declarado na operação, a QI Tech paga o fornecedor a partir da conta de liquidação do emissor, por TED, boleto ou Pix, sem ação do integrador | [Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/desembolso-terceiro) | PAY0002, COM0024 | ⚙️ 🆕 |
| PAY0004* | Consultar status do pagamento | Consultar o status do desembolso pela chave da transação na conta de liquidação | [Documentação](/documentation/movimentacao_de_contas/consulta_de_transacoes) | PAY0003 | 🆕 |
| PAY0005* | Webhook — pagamento liquidado | Receber o webhook que confirma que o fornecedor foi pago | [Documentação](/documentation/baas/webhooks) *(a confirmar)* | CAB0003, PAY0003 | 🆕 |
#### Trilhas disponíveis
| Trilha | `payment_method` | Campo | Roteamento |
| --- | --- | --- | --- |
| TED | `ted` | `target_account` | Pelo `financial_institution_ispb` |
| Boleto | `bank_slip` | `digitable_line` (47 dígitos) | Pela própria linha digitável |
| Pix | `pix` | `pix_key` + `pix_key_type` | Pela chave, no arranjo Pix |
Na trilha Pix, o objeto `beneficiary` é obrigatório — a chave sozinha não identifica o recebedor.
**QR code** não é uma trilha suportada e não está previsto.
:::warning Boleto — o valor precisa bater com o valor liberado
O valor do boleto é lido dos **10 últimos dígitos da linha digitável, em centavos**, e precisa ser
igual ao `financial.released_amount` da operação. Qualquer diferença é recusada com `COM000061`.
Como o `released_amount` calculado difere do valor solicitado em `financial` por causa das taxas, o
caminho prático é: criar a operação, ler o `released_amount` da resposta e só então anexar um boleto
daquele valor exato. **Não altere o valor de uma linha digitável real** — isso invalida seus dígitos
verificadores e o boleto deixa de ser pagável.
:::
:::warning Escopo da fase 1
**Uma NC por pagamento.** O boleto tem de cobrir o valor liberado integral: split de pagamento — uma
nota financiando vários pagamentos, ou parte ao fornecedor e parte ao emissor — não é suportado nesta
fase e está previsto para a fase 2. O integrador deve modelar suas requisições de acordo: uma
operação, um beneficiário, valor integral.
:::
---
## 10. Resumo dos webhooks
Como o fluxo elimina todos os pontos de conferência manual, estes são os eventos que o integrador
precisa consumir para acompanhar uma operação de ponta a ponta.
| Evento | Fase | O que ele libera |
| --- | --- | --- |
| Status do emissor alterado | 1 | Portão de aprovação — libera a solicitação da habilitação da Fase 2 |
| Auto-assinatura em `pending_signature` | 2 | Envelope aberto na solicitação — confirma que os links de assinatura estão disponíveis |
| Auto-assinatura em `enabled` | 2 | Todas as emissões seguintes podem ocorrer automaticamente |
| Status da operação alterado | 4 | Visibilidade sobre análise → aprovada |
| Operação assinada | 4 | Geração do boletim de subscrição |
| Boletim de subscrição assinado | 5 | **Gatilho da transferência de recursos para a conta de liquidação da WL (TFI0002)** |
| Movimentação de conta (`internal_funds_transfer`) | 6.1 | Recursos confirmados na conta de liquidação da WL — libera o pagamento ao fornecedor |
| Pagamento liquidado | 6.2 | Fecha o ciclo |
---
## 11. Pontos em aberto a serem fechados antes do go-live
| # | Ponto em aberto | Responsável | Impacto |
| --- | --- | --- | --- |
| 1 | Confirmar as condições operacionais da NC — número de parcelas, formas de pagamento e template de contrato. A auto-assinatura precisa cobrir todos os modos operacionais utilizados pelo cliente; qualquer coisa fora do conjunto previamente aprovado cai no fluxo de assinatura manual | Cliente | Bloqueia a definição do escopo da auto-assinatura |
| 2 | ~~Definir a forma de pagamento ao fornecedor~~ **Resolvido em parte 🆕** — TED e boleto estão implementados e disponíveis mediante habilitação. **Pix por chave** também está implementado e disponível mediante habilitação, exigindo o objeto `beneficiary`; **QR code** não é suportado nem previsto | Cliente | Não bloqueia mais a Fase 6 |
| 3 | ~~Pagamento a terceiros — estimativa de 4 semanas~~ **Resolvido 🆕** — entregue por um caminho diferente do previsto: o beneficiário é declarado na operação e o desembolso é automático, sem endpoint de pagamento. Pendente apenas a publicação da documentação e a habilitação dos clientes | QI Tech | Desbloqueado |
| 4 | Criação do certificado via API — hoje é manual (uma única vez por emissor, executado pela QI Tech); prazo em avaliação. **Não bloqueia o go-live** | QI Tech | Afeta a escalabilidade do onboarding, não as primeiras operações |
| 5 | ~~Publicação dos contratos dos endpoints da Fase 2 (ASG)~~ **Resolvido** — a Fase 2 está documentada em [Auto-assinatura do emissor](/documentation/escrituracao/homologacao-emissor/auto-assinatura/inicio). Pendente apenas o comportamento de aprovação/assinatura automática (COM0020–COM0022) | QI Tech | Bloqueia a homologação da Fase 4 automática |
| 6 | Split de pagamento confirmado como escopo da fase 2 — **confirmado pela implementação 🆕**: o boleto tem de igualar o valor liberado integral, portanto uma operação paga exatamente um beneficiário | Cliente + QI Tech | Define a fronteira da fase 1 |
| 7 | Confirmar qual QI Conta é debitada como **origem** da transferência da perna 6.1, e se a conta de liquidação da WL é a mesma conta referenciada no pacote de assinatura da NC ou uma conta separada | Cliente + QI Tech | Define a `ACCOUNT_KEY` e o `target_account` do TFI0002 |
| 8 | Habilitar o desembolso para terceiro para os clientes que vão utilizá-lo — não vem habilitado por padrão, e sem isso a criação da operação é recusada com `COM000062` 🆕 | QI Tech | Bloqueia o uso do recurso pelo cliente |
| 9 | Publicar a página do objeto `third_party_disbursement` e adicionar `COM000061`, `COM000062` e `COM000063` ao catálogo de erros 🆕 | QI Tech | Bloqueia a homologação da trilha de desembolso a terceiro |
| 10 | Publicar a trilha **Pix por chave** na documentação — o objeto `beneficiary`, os tipos de `pix_key_type` e o código `COM000071` no catálogo de erros 🆕 | QI Tech | Bloqueia a homologação da trilha Pix |
---
## 12. Mapeamento de erros
Os erros originados das APIs de emissor, investidor e nota comercial estão catalogados no
[**Catálogo de Erros**](/documentation/escrituracao/catalogo-erros/catalogo-erros).
A solicitação da habilitação recusa com `ISS0000032` quando o emissor não está aprovado,
`ISS0000033` quando o cliente não está habilitado e `ISS0000029` quando já existe uma habilitação
ativa. A consulta retorna `ISS0000028` quando o emissor não possui habilitação ativa — o que também
acontece depois de um `reproved` ou `canceled`. Os demais erros específicos de
auto-assinatura — tentativa de emissão com a habilitação fora de `enabled`, condição operacional fora
do escopo aprovado ou divergência entre o grupo de assinantes e o titular do certificado — serão
adicionados ao mesmo catálogo quando o comportamento de assinatura automática (COM0020–COM0022) for
publicado.
---
# Roteiro de Integração de escrituração de notas comerciais
URL: /documentation/escrituracao/roteiro-integracao/roteiro-integracao-padrao
O roteiro de homologação descreve todos os recursos e funcionalidades que precisam
ser testados pelo parceiro integrador no ambiente de sandbox da QI Tech (ambiente de testes),
antes da entrada em ambiente de produção para emissão de notas comerciais.
Este roteiro descreve todos os recursos e funcionalidades envolvidos no produto.
:::warning Atenção
**Todos os testes devem ser obrigatoriamente realizados no ambiente de Sandbox da QI Tech (ambiente de testes).
As operações realizadas em ambiente de Sandbox são operações financeiras fictícias, servindo apenas para teste de funcionalidade das APIs.**
:::
## Cadastro e Autenticação API Escrituração
| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| CAB0001* | Troca de chaves públicas | Realizar a troca de chaves públicas com o time operações de plataforma (suporte-dcm@qitech.com.br) | [Link Documentação](/documentation/escrituracao/introducao/troca_de_chaves) | |
| CAB0002* | Teste de autenticação de chamadas | Após receber a chave de api com o time de plataformas, finalizar teste de autenticação de chamadas |[Link Documentação](/documentation/escrituracao/introducao/teste-autenticacao/teste_de_autenticacao)
[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 emissor para cadastros feitos pelo sistema de escrituração
| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| CED0001* | Cadastro Básico do emissor | Criar o emissor, informando as informações básicas do cadastro. | [Link Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/cadastro-basico) |
| CED0002* | Envio e remoção de Documentos do Emissor | Envio e remoção de documentos associados a um emissor previamente cadastrado | [Link Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor)
[Link Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor-remocao) | CED0001 |
| CED0003* | Cadastro e remoção de Representantes do Emissor | Envio e remoção de representantes associados a um emissor previamente cadastrado | [Link Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor)
[Link Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor-remocao) | CED0001 |
| CED0004* | Envio e remoção de Documentos do Representante do Emissor | envio e remoção de documentos associados a um representante de um emissor previamente cadastrado | [Link Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor)
[Link Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor-remocao) | CED0001, CED0003 |
| CED0005* | Cadastro e remoção de Conta Bancária do Emissor | cadastro e remoção de conta bancária associada a um emissor previamente cadastrado | [Link Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor)
[Link Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor-remocao) | CED0001 |
| CED0006* | Cadastro e remoção de Grupos de Assinantes do Emissor | cadastro e remoção de grupos de assinantes associados a um emissor previamente cadastrado | [Link Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor)
[Link Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor-remocao) | CED0001 |
| CED0007* | Cadastro e remoção de Informações de Contato do Emissor | cadastro e remoção de informações de contato associadas a um emissor previamente cadastrado | [Link Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor)
[Link Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor-remocao) | CED0001 |
| CED0008* | Envio para Análise do Emissor | Este endpoint permite alterar o status de um emissor para análise, enviando-o para o processo de validação. | [Link Documentação](/documentation/escrituracao/homologacao-emissor/envio-analise/) | CED0001, CED0002, CED0003, CED0004, CED0005, CED0006, CED0007 |
| CED0009* | Alteração de Cadastro do Emissor | alterar emissor para permitir edição | [Link Documentação](/documentation/escrituracao/homologacao-emissor/alteracao-cadastro/) | CED0001, CED0002, CED0003, CED0004, CED0005, CED0006, CED0007 |
| CED0010* | Listagem dos emissores cadastrados | Listagem dos cedentes cadastrados, com filtros por CNPJ, nome | [Link Documentação](/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-filtro)
| CED0011* | Detalhes do emissor | Visualizar os detalhes de um emissor cadastrado, por issuer_key | [Link Documentação](/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-chave) |
## Homologação do Investidor
:::warning Atenção
**Para o fluxo de homologação do investidor, caso o cliente tenha fundos fixos, é possível realizar o cadastro desses no setup, simplificando a integração.**
:::
### Homologação do investidor para cadastros feitos no setup
| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| INV1001* | Listagem dos investidores cadastrados | Listagem dos fundos cadastrados, com filtros por CNPJ, nome | [Link Documentação](/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-filtro) |
| INV1002* | Detalhes do investidor | Visualizar os detalhes de um investidor cadastro, por investor_key | [Link Documentação](/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-chave) |
### Homologação do investidor para cadastros feitos pelo sistema de escrituração
| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| INV0001* | Cadastro Básico do investidor | Criar o investidor, informando as informações básicas do cadastro. | [Link Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/cadastro-basico) |
| INV0002* | Envio e remoção de Documentos do investidor | Envio e remoção de documentos associados a um investidor previamente cadastrado | [Link Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/documentos-investidor)
[Link Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/documentos-investidor-remocao) | INV0001 |
| INV0003* | Cadastro e remoção de Representantes do investidor | Envio e remoção de representantes associados a um investidor previamente cadastrado | [Link Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/representantes-investidor)
[Link Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/representantes-investidor-remocao) | INV0001 |
| INV0004* | Envio e remoção de Documentos do Representante do investidor | envio e remoção de documentos associados a um representante de um investidor previamente cadastrado | [Link Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/documentos-representantes-investidor)
[Link Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/documentos-representantes-investidor-remocao) | INV0001, INV0003 |
| INV0005* | Cadastro e remoção de Conta Bancária do investidor | cadastro e remoção de conta bancária associada a um investidor previamente cadastrado | [Link Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/conta-bancaria-investidor)
[Link Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/conta-bancaria-investidor-remocao) | INV0001 |
| INV0006* | Cadastro e remoção de Grupos de Assinantes do investidor | cadastro e remoção de grupos de assinantes associados a um investidor previamente cadastrado | [Link Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/assinantes-investidor)
[Link Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/assinantes-investidor-remocao) | INV0001 |
| INV0007* | Cadastro e remoção de Informações de Contato do investidor | cadastro e remoção de informações de contato associadas a um investidor previamente cadastrado | [Link Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/informacao-contato-investidor)
[Link Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/informacao-contato-investidor-remocao) | INV0001 |
| INV0008* | Envio para Análise do investidor | Este endpoint permite alterar o status de um investidor para análise, enviando-o para o processo de validação. | [Link Documentação](/documentation/escrituracao/homologacao-investidor/envio-analise/) | INV0001, INV0002, INV0003, INV0004, INV0005, INV0006, INV0007 |
| INV0009* | Alteração de Cadastro do investidor | alterar investidor para permitir edição | [Link Documentação](/documentation/escrituracao/homologacao-investidor/alteracao-cadastro/) | INV0001, INV0002, INV0003, INV0004, INV0005, INV0006, INV0007 |
| INV0010* | Listagem dos investidores cadastrados | Listagem dos fundos cadastrados, com filtros por CNPJ, nome | [Link Documentação](/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-filtro)
| INV0011* | Detalhes do investidor | Visualizar os detalhes de um investidor cadastrado, por investor_key | [Link Documentação](/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-chave) |
## Emissão de nota comercial
Após os cadastros de emissores e investidores, é possível realizar a emissão de notas comerciais. Para isso, existem algumas combinações de fluxos de emissão, que serão contempladas abaixo.
| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| COM0001* | Simulação de condições financeiras | simular as condições financeiras e o fluxo de pagamentos de uma operação | [Link Documentação](/documentation/escrituracao/emissao-de-notas/simulacao) |
| COM0002* | Cadastro de Operação de Nota Comercial | criar uma nova operação de nota comercial com base nos dados financeiros e de investidores. | [Link Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/criar-operacao) | COM0001 |
| COM0003* | Cadastro e Remoção de Partes Relacionadas | cadastro e a remoção de partes relacionadas a uma operação | [Link Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/cadastrar-parte-relacionada) | COM0002 |
| COM0004* | Envio e Remoção de Documentos de Representantes de Partes Relacionadas | envio e a remoção de documentos associados a representantes de partes relacionadas a uma operação | [Link Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-documento)| COM0002, COM0003 |
| COM0005* | Envio e Remoção de Grupos de Assinantes de Representantes de Partes Relacionadas | envio e a remoção de grupos de assinantes associados a representantes de partes relacionadas a uma operação | [Link Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-grupo-assinantes) | COM0002, COM0003 |
| COM0006 | Pré-visualizar Termo Constitutivo | geração de uma minuta do Termo Constitutivo para uma operação específica, utilizando um template predefinido. | [Link Documentação](/documentation/escrituracao/emissao-de-notas/geracao-minutas/gerar-minuta-contrato) | COM0002 |
| COM0007* | Alterar Template do Termo Constitutivo | alteração do template do Termo Constitutivo para uma operação específica | [Link Documentação](/documentation/escrituracao/emissao-de-notas/geracao-minutas/alterar-template-tc) | COM0002 |
| COM0008* | Envio de documentos | envio de documentos associados a uma operação. O "document_key" retornado poderá ser utilizado, por exemplo, no sistema de garantias | [Link Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/upload-documento) | COM0002 |
| COM0009* | Envio de Garantia na Operação | adição de garantias associadas a uma operação | [Link Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/cadastro-garantia) | COM0002, COM0008 |
| COM0010* | Cadastro e Remoção de Partes Relacionadas de um contrato/Garantia | cadastro e a remoção de partes relacionadas de um contrato/garantia específicos da operação | [Link Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-parte-relacionada-em-documento) | COM0002, COM0003 |
| COM0011* | Enviar Operação para Análise | alterar o status de uma operação para "em análise", enviando-a para o processo de validação de compliance pelo escriturador | [Link Documentação](/documentation/escrituracao/emissao-de-notas/envio-para-analise) | COM0002, COM0003, COM0004, COM0005, COM0006, COM0007, COM0008, COM0009 |
| COM0012* | Enviar Atas de Aprovação Assinadas | Este endpoint permite enviar as atas de aprovação de empresas do tipo SA ou COP assinadas de forma externa para o sistema de escrituação, enviando um base64 que será analisado e aprovado pelo escriturador. | [Link Documentação](/documentation/escrituracao/emissao-de-notas/envio-ata-aprovacao) | COM0002 |
| COM0013* | Consulta de Operações por Filtros | consultar operações de nota comercial utilizando filtros opcionais | [Link Documentação](/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-filtros) | COM0002, COM0003, COM0004, COM0005, COM0006, COM0007, COM0008, COM0009 |
| COM0014* | Consulta de Operação por Chave | consultar os detalhes completos de uma operação específica, utilizando sua chave única. | [Link Documentação](/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-chave) | COM0002, COM0003, COM0004, COM0005, COM0006, COM0007, COM0008, COM0009 |
### Caso assinatura seja via QI SIGN
| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| COM0015* | Consulta dos Links para assinatura via QI SIGN da Operação | consultar todos os links para assinatura de uma operação específica via QI SIGN, utilizando sua chave única. | [Link Documentação](/documentation/escrituracao/emissao-de-notas/consulta-link-assinatura-qisign) | COM0002, COM0003, COM0004, COM0005, COM0006, COM0007, COM0008, COM0009 |
| COM0016* | Consulta do Link dos contratos assinados via QI SIGN da Operação | consultar todos os documentos assinados de uma operação específica via QI SIGN, utilizando sua chave única | [Link Documentação](/documentation/escrituracao/emissao-de-notas/consulta-link-assinado-qisign) | COM0002, COM0003, COM0004, COM0005, COM0006, COM0007, COM0008, COM0009 |
## Processo de integralização/Subscrição
| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| INT0001* | Consulta de Integralização por Chave | consultar os detalhes de um processo de integralização utilizando sua chave única | [Link Documentação](/documentation/escrituracao/integralizacao-cotas/consulta-processo-integralizacao) |
| INT0002* | Consulta de Subscrição | consultar uma subcrição em andamento | [Link Documentação](/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/consulta-subscricao-cotas) | INT0001 |
| INT0003 | Cadastro de Subscrição | registrar a intenção de um investidor em subscrever uma quantidade específica de cotas de uma integralização (útil caso seja necessário deslocar a data de uma subscrição) | [Link Documentação](/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/cadastro-subscricao) | INT0001, INT0002 |
| INT0004 | Cancelar subscrição | cancelar subscrição (útil caso seja necessário deslocar a data de uma subscrição) | [Link Documentação](/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/cancelar-subscricao) | INT0001, INT0002 |
# Roteiro de Integração de Amortização Extraordinária
Este roteiro descreve, em ordem, os passos que o integrador executa para registrar uma amortização extraordinária na QI Tech — desde a identificação das parcelas-alvo até o 201 da chamada de criação. A criação é fire-and-forget: o integrador apenas **cria** o evento; a liquidação, o cancelamento e a finalização são orquestrados internamente pela QI Tech (account-liquidation-api liquida quando o pagamento entra; a rotina diária de settlement do security-service decide cancelar ou finalizar). A referência completa do endpoint de criação é apresentada na seção de **Endpoints**.
Antes de começar, confirme que o [Conceito](/documentation/escrituracao/amortizacao-extraordinaria/conceito) já está claro, especialmente os cinco valores possíveis de `amortization_type` e o papel do `reference_date`.
:::warning Atenção
**Todos os testes devem ser obrigatoriamente realizados no ambiente de Sandbox da QI Tech. Chamadas de amortização extraordinária movimentam `installment.paid_amount` e consomem Valor Presente — valide o fluxo completo em sandbox antes de habilitar em produção.**
:::
## Pré-requisitos
- **API key configurada** — [Troca de chaves](/documentation/escrituracao/introducao/troca_de_chaves).
- **Security criado e integralizado** — [Emissão de notas](/documentation/escrituracao/emissao-de-notas/inicio) e [Integralização de cotas](/documentation/escrituracao/integralizacao-cotas/inicio).
- **Conceitos do produto** compreendidos — [Conceito](/documentation/escrituracao/amortizacao-extraordinaria/conceito).
## Fluxo passo a passo
O fluxo completo tem quatro etapas. Cada linha da tabela indica quem executa a ação, qual chamada ou evento ocorre e o que merece atenção durante a execução.
| # | Etapa | Responsável | Chamada / Evento | Observação |
|---|-------|-------------|------------------|------------|
| 1 | Identificar parcelas-alvo | Integrador | `GET /security/security/{security_key}` | Obtém `installment_number` e os valores correntes das parcelas, usados para escolher o tipo e o montante da amortização. Não é necessário extrair `installment_key` — a criação trabalha apenas com os números das parcelas. |
| 2 | Criar a amortização extraordinária | Integrador | [`POST /event_conciliation/extraordinary_event`](../amortizacao-extraordinaria/endpoints/criar-amortizacao.md) | Envie `security_key`, `investment_key`, `amortization_type`, `amount`, `reference_date`, `due_date` e, quando aplicável, `installment_list` (array de `installment_number`, inteiros ≥ 1). A resposta 201 traz o `extraordinary_event_conciliation_key` (evento extraordinário de amortização único) e a lista `event_conciliation_list` (evento de conciliação de cada parcela). A partir daqui é fire-and-forget para o integrador. |
| 3 | Confirmar pagamento externo | Integrador / Provedor | Conciliação de recebíveis | Aguarde a confirmação do recebimento dos valores pelo canal combinado. Os eventos de conciliação da parcela permanecem em `pending_conciliation` enquanto o pagamento não chega. Para acompanhar o status de um evento extraordinário pela sua chave, use [`GET /event_conciliation/extraordinary_event/{extraordinary_event_conciliation_key}`](../amortizacao-extraordinaria/endpoints/consultar-amortizacao.md). |
| 4 | Liquidação ou finalização automática | QI Tech | Orquestração interna | Ao detectar a entrada do pagamento, a QI Tech (via account-liquidation-api) liquida cada parcela. Caso o pagamento não chegue, a rotina diária de settlement do security-service finaliza ou cancela o evento. Em ambos os casos não há ação do integrador. |
Ao criar, o evento nasce em `pending_conciliation`. A transição para `paid` ocorre só depois da etapa 4 do fluxo acima.
## Pontos de atenção
:::warning Atenção
- **`reference_date`** é obrigatório e fornecido pelo chamador — deve corresponder à data de quitação do evento extraordinário.
- **Liquidação, finalização e cancelamento são internos** — o integrador apenas cria o evento; a QI Tech orquestra o restante. Não há webhook tenant-facing dedicado para as transições de status do `event_conciliation` extraordinário.
- Para investidores em `internal_legacy_system` (CTVM), a liquidação interna é assíncrona — o estado final (`paid` ou `settlement_failed`) é definido pelo cron de autoconciliate.
:::
## Próximos passos
Para a referência completa do endpoint de criação, consulte [Criar Amortização Extraordinária](../amortizacao-extraordinaria/endpoints/criar-amortizacao.md). Para acompanhar o status dos eventos extraordinários ainda pendentes de conciliação, consulte [Consultar Amortização Extraordinária](../amortizacao-extraordinaria/endpoints/consultar-amortizacao.md). As regras de negócio detalhadas (tolerância, discriminação por `reference_date`, ordem de distribuição por tipo, fluxo interno de liquidação e cancelamento) estão consolidadas em [Regras de Negócio](../amortizacao-extraordinaria/regras-de-negocio.md). Para cenários completos passo-a-passo com JSON bodies reais, veja [Exemplos](../amortizacao-extraordinaria/exemplos.md). Para o cenário em que uma nova operação recompra amortizações extraordinárias em aberto, consulte [Amortização com Recompra](../amortizacao-extraordinaria/recompra-de-operacao.md).
## Mapeamento de erros
Os erros originários das apis de emissores, investidores e nota comercial podem ser encontrados em [**Link Catálogo de Erros**](/documentation/escrituracao/catalogo-erros/catalogo-erros)
---
# Roteiro de Integração de escrituração de notas comerciais
URL: /documentation/escrituracao/roteiro-integracao/roteiro-integracao-padrao-external
O roteiro de homologação descreve todos os recursos e funcionalidades que precisam
ser testados pelo parceiro integrador no ambiente de sandbox da QI Tech (ambiente de testes),
antes da entrada em ambiente de produção para emissão de notas comerciais.
Este roteiro descreve todos os recursos e funcionalidades envolvidos no produto.
:::warning Atenção
**Todos os testes devem ser obrigatoriamente realizados no ambiente de Sandbox da QI Tech (ambiente de testes).
As operações realizadas em ambiente de Sandbox são operações financeiras fictícias, servindo apenas para teste de funcionalidade das APIs.**
:::
## Cadastro e Autenticação API Escrituração
| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| CAB0001* | Troca de chaves públicas | Realizar a troca de chaves públicas com o time operações de plataforma (suporte-dcm@qitech.com.br) | [Link Documentação](/documentation/escrituracao/introducao/troca_de_chaves) | |
| CAB0002* | Teste de autenticação de chamadas | Após receber a chave de api com o time de plataformas, finalizar teste de autenticação de chamadas |[Link Documentação](/documentation/escrituracao/introducao/teste-autenticacao/teste_de_autenticacao)
[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: /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 |
---
# Crédito Consignado INSS
URL: /documentation/guides/INSS/intro
Guias de integração para operações de crédito consignado destinadas a beneficiários do INSS. As páginas
estão agrupadas por **família de endpoint**: uma consulta é documentada uma vez e serve as duas jornadas.
## Consultas
Endpoints de consulta ao INSS/Dataprev, comuns a todas as jornadas.
- **[Lista de Benefícios](/documentation/guides/INSS/inquiries/lista-de-beneficios)** — `POST /social_security/benefits_request`, com o Termo de Autorização. Primeiro passo de qualquer operação.
- **[Dados do Benefício](/documentation/guides/INSS/inquiries/dados-do-beneficio)** — `POST /social_security/balance_request`: saldo, margem e situação. Pré-requisito da averbação.
- **[Consulta Offline de Saldo](/documentation/guides/INSS/inquiries/offline-balance-request)** — últimos dados salvos, de forma síncrona, sem consumir consulta na Dataprev.
- **[Última Resposta da Averbação](/documentation/guides/INSS/inquiries/ultima-resposta)** — recupera sob demanda o último retorno da Dataprev.
- **[Portabilidade de Origem](/documentation/guides/INSS/inquiries/portabilidade-de-origem)** — dados do contrato portado da instituição credora original.
- **[Participantes do CTC](/documentation/guides/INSS/inquiries/participantes-ctc)** — instituições participantes da Núclea/CIP.
## Crédito Novo e Refinanciamento Puro
- **[Fluxo Completo](/documentation/guides/INSS/new-credit-and-refinancing/end-to-end)** — a ordem das chamadas, da consulta ao desembolso.
- **[Simulação](/documentation/guides/INSS/new-credit-and-refinancing/simulacao)** — `POST /debt_simulation`.
- **[Emissão](/documentation/guides/INSS/new-credit-and-refinancing/emissao)** — `POST /debt` com a garantia `social_security`.
- **[Formalização](/documentation/guides/INSS/new-credit-and-refinancing/formalizacao)** — dados complementares da IN 138 e assinatura da CCB.
- **[Recálculo](/documentation/guides/INSS/new-credit-and-refinancing/recalculate)** — ajusta parcelas e taxas de uma operação existente.
- **[Falha no Desembolso](/documentation/guides/INSS/new-credit-and-refinancing/pos-desembolso)** — TED e Pix devolvidos, e a reapresentação de pagamento.
## Portabilidade + Refinanciamento
- **[Fluxo Completo](/documentation/guides/INSS/portability+refinancing/end-to-end)** — a ordem das chamadas de uma portabilidade com ou sem Troco.
- **[Simulação](/documentation/guides/INSS/portability+refinancing/simulacao)** — fixando a taxa ou o valor liberado.
- **[Digitação da Proposta](/documentation/guides/INSS/portability+refinancing/proposta)** — `POST /v2/credit_transfer/proposal`.
- **[Formalização](/documentation/guides/INSS/portability+refinancing/formalizacao)** — documentos e assinatura da proposta.
- **[Máquinas de Status](/documentation/guides/INSS/portability+refinancing/maquinas-de-status)** — status da portabilidade e do refinanciamento (Troco).
- **[Correção de Dados](/documentation/guides/INSS/portability+refinancing/correcao-de-dados)** — com ou sem nova assinatura da CCB.
- **[Recálculo e Reformalização](/documentation/guides/INSS/portability+refinancing/reformalization)** — corrige o refinanciamento e a carência.
- **[Recálculo da Portabilidade](/documentation/guides/INSS/portability+refinancing/recalculate-portability)** — reduz o saldo devedor para caber na margem.
- **[Diminuir o Valor das Parcelas](/documentation/guides/INSS/portability+refinancing/diminuir-parcela)**.
- **[Alterando o Cessionário](/documentation/guides/INSS/portability+refinancing/alterando-cessionario)** — `purchaser_document_number` no aceite.
## Reservas
- **[Averbação e Desaverbação](/documentation/guides/INSS/reservations/averbacao-e-desaverbacao)** — a constituição da garantia na Dataprev, a teimosinha e a desaverbação.
- **[Fila Prioritária](/documentation/guides/INSS/reservations/priority-reservation)** — marca a reserva como `fixed_rate` para priorização no processamento.
- **[Fura-fila](/documentation/guides/INSS/reservations/priority-request)** — requisição síncrona com balde de fichas.
- **[Anuência](/documentation/guides/INSS/pending_confirmation)** — quando o beneficiário precisa confirmar a operação.
## Assinaturas
- **[Em grupo](/documentation/guides/INSS/signatures/batch-group-signature)** — agrupa múltiplas operações do mesmo beneficiário em uma única assinatura.
## Referência
- **[Enumeradores](/documentation/guides/INSS/reference/enumeradores)** — retornos da Dataprev, status e tipos de benefício. Única definição; as outras páginas linkam para cá.
- **[Mocks (Sandbox)](/documentation/guides/INSS/mocks-sandbox)** — CPFs e cenários de teste.
---
# Assinatura em lote (INSS)
URL: /documentation/guides/INSS/signatures/batch-signature
Assinatura em lote (INSS)
Fluxo para agrupar **várias operações** em **um único envelope de assinatura** do QI Sign: você abre o lote, cria as operações referenciando o lote, confere (opcionalmente limpa) e dispara o envio para assinatura.
:::caution Fluxo legado
Este é o fluxo de **lote externo** (`document_batch_key`). Ele permanece disponível, mas o caminho recomendado para novas integrações é a **[Assinatura em grupo](/documentation/guides/INSS/signatures/batch-group-signature)** (`document_batch_group_key`), que reúne as operações em uma pasta e dispara **uma única assinatura** para o beneficiário. Consulte a [tabela de migração](/documentation/guides/INSS/signatures/batch-group-signature#migracao).
:::
:::caution Regras do lote
**Mesma titularidade:** todas as operações do lote devem ser do **CPF** ou do **mesmo representante legal**. Incluir CPF “A” e CPF “B” no mesmo lote gera **erro síncrono** no `POST` da operação.
**Tipos permitidos:** por ora o fluxo aceita operações INSS de Crédito Novo e Cartão Consignado no mesmo lote.
:::
---
## Abrir o lote
Request
ENDPOINT /document/document_batch
MÉTODO POST
Body
type
string
obrigatório
Fixo: social_security_external_batch .
certifier_type
string
obrigatório
Fixo: qi_sign .
batch_name
string
obrigatório
Nome do lote para identificação; **máximo 100 caracteres**. Use um identificador único por lote na sua operação.
request_control_key
string (UUID v4)
obrigatório
Chave de **idempotência**; não reutilize entre lotes distintos.
personal_document
object
opcional
Documento de identificação do tomador já coletado pelo parceiro, para dispensar a foto do documento durante a assinatura. Veja **[Documento de identificação pré-coletado](#documento-de-identificacao-pre-coletado)**.
**Python**
```python title="ENDPOINT"
POST /document/document_batch
```
**curl**
```bash title="ENDPOINT"
curl -X POST \
'https://api-auth.sandbox.qitech.app/document/document_batch' \
-H 'AUTHORIZATION: eyJhbGciOiJFUzUxMiJ9.eyJwYXlsb2FkX21kNSI6...' \
-H 'API-CLIENT-KEY: YOUR_API_CLIENT_KEY' \
-H 'Content-Type: application/json' \
-d '{
"type": "social_security_external_batch",
"certifier_type": "qi_sign",
"batch_name": "Lote INSS - pedido-2025-03-001",
"request_control_key": "5ed20003-0610-46d2-88cc-a5d0de640696"
}'
```
```json title="REQUEST BODY (exemplo)"
{
"type": "social_security_external_batch",
"certifier_type": "qi_sign",
"batch_name": "Lote INSS - pedido-2025-03-001",
"request_control_key": "5ed20003-0610-46d2-88cc-a5d0de640696"
}
```
Response
STATUS 201
Atributos
document_batch_key
string
Identificador do lote. Guarde para os próximos passos.
```json title="RESPONSE BODY"
{
"document_batch_key": "17f35e19-a039-468f-aaa7-84aa8edec3dc"
}
```
---
## Documento de identificação pré-coletado {#documento-de-identificacao-pre-coletado}
Se o seu fluxo já coleta o documento de identificação do tomador (RG, CNH etc.) antes da assinatura, envie-o na **abertura do lote** pelo objeto `personal_document`. As imagens são encaminhadas ao QI Sign junto com a criação do envelope e a etapa de captura do documento chega **pré-atendida** na jornada — o tomador não precisa fotografar o documento novamente.
Os arquivos ficam vinculados ao lote, mas **não são assinados**: eles não entram no envelope como documentos assináveis e não participam do `send_to_signature`.
O envio acontece em duas etapas.
### 1. Suba os arquivos
Faça o upload de cada arquivo pelo [fluxo de upload de documentos](/documentation/upload_de_documentos/upload_de_documentos) e guarde a `document_key` retornada — **um arquivo por lado** do documento, ou **um arquivo único** no caso de documento digital.
Não é preciso classificar o arquivo no upload: é o **campo** em que você informa a chave que declara qual lado do documento ela representa.
| Campo | Arquivo esperado |
|---|---|
| `document_identification_front_key` | Frente do documento de identificação |
| `document_identification_back_key` | Verso do documento de identificação |
| `document_identification_full_key` | Documento digital completo, em arquivo único |
### 2. Referencie as chaves na abertura do lote
Personal Document Object
type
string
obrigatório
Tipo do documento de identificação. Veja **[Tipos aceitos](#tipos-de-documento-aceitos)**.
document_identification_front_key
string
condicional
`document_key` da **frente**. Obrigatório no modo frente e verso, junto com `..._back_key`.
document_identification_back_key
string
condicional
`document_key` do **verso**. Obrigatório no modo frente e verso, junto com `..._front_key`.
document_identification_full_key
string
condicional
`document_key` do **arquivo único** (documento digital). Não pode ser combinado com as chaves de frente e verso.
```json title="REQUEST BODY (abertura do lote com documento pré-coletado)"
{
"type": "social_security_external_batch",
"certifier_type": "qi_sign",
"batch_name": "Lote INSS - pedido-2025-03-001",
"request_control_key": "5ed20003-0610-46d2-88cc-a5d0de640696",
"personal_document": {
"type": "rg",
"document_identification_front_key": "3b28a1a6-51c0-4f0e-9b64-2c98d6a3f1e0",
"document_identification_back_key": "9d47c2b1-8f3a-4e5d-a1c2-7b6e5d4f3a2b"
}
}
```
### Tipos de documento aceitos {#tipos-de-documento-aceitos}
| `type` | Documento | Frente e verso | Arquivo único |
|---|---|---|---|
| `rg` | Registro Geral (RG) | ✔ | — |
| `cnh` | Carteira Nacional de Habilitação | ✔ | ✔ |
| `cin` | Carteira de Identidade Nacional | — | ✔ |
- **Frente e verso:** envie `document_identification_front_key` + `document_identification_back_key`.
- **Arquivo único:** envie apenas `document_identification_full_key` (documento digital, ex.: CNH digital).
O conjunto de tipos efetivamente aceito também depende da jornada de assinatura configurada para o seu requester. Um `type` fora dessa configuração retorna `DOC000130`.
:::caution Regras do documento pré-coletado
- Envie **frente + verso** **ou** o **arquivo único** — nunca os dois modos juntos.
- Cada `type` suporta modos específicos; combinação inválida retorna `DOC000128`.
- Os arquivos devem pertencer ao seu requester e já ter o **upload concluído**. Chave inexistente ou de outro requester retorna `DOC000004`; arquivo ausente retorna `DOC000049`.
- Cada arquivo só pode ser usado em **um lote**. Reaproveitar uma `document_key` já vinculada retorna `DOC000137`.
- O envio é feito **apenas na abertura do lote** — não é possível adicionar ou trocar o documento depois. Se algum arquivo for rejeitado, a criação do lote falha por inteiro (nenhum lote é criado).
- A requisição precisa identificar o **titular** dos arquivos: envie o header `SELECTED-AGENT`. Sem ele, a abertura retorna `QIT000004`.
:::
---
## Incluir operações no lote
Ao criar cada operação, envie **`document_batch_key` na raiz do JSON** (mesmo nível dos demais campos principais do produto).
Cartão POST /payroll_card_reservation/social_security
Empréstimo POST /debt
document_batch_key
string
obrigatório no fluxo com lote
O mesmo document_batch_key retornado na abertura do lote; envie na raiz do payload de criação da operação.
```json title="Trecho ilustrativo (raiz do payload)"
{
"document_batch_key": "17f35e19-a039-468f-aaa7-84aa8edec3dc"
}
```
O restante do body segue o contrato de cada endpoint. Consulte os [roteiros de crédito consignado INSS](/documentation/guides/INSS/new-credit-and-refinancing/end-to-end) conforme o produto.
---
## Consultar documentos do lote
Request
ENDPOINT /document/document_batch/ DOCUMENT_BATCH_KEY
MÉTODO GET
Path params
document_batch_key
string
obrigatório
Chave do lote.
Recomendado antes de fechar o lote para conferir tipos e chaves de documento agrupados.
**Python**
```python title="ENDPOINT"
GET /document/document_batch/YOUR_DOCUMENT_BATCH_KEY
```
**curl**
```bash title="ENDPOINT"
curl -X GET \
'https://api-auth.sandbox.qitech.app/document/document_batch/YOUR_DOCUMENT_BATCH_KEY' \
-H 'AUTHORIZATION: eyJhbGciOiJFUzUxMiJ9.eyJwYXlsb2FkX21kNSI6...' \
-H 'API-CLIENT-KEY: YOUR_API_CLIENT_KEY' \
-H 'Content-Type: application/json'
```
Response
STATUS 200
Atributos
document_batch_key
string
Chave do lote.
documents
array
Lista de documentos; cada item costuma trazer document_key e document_type (ex.: ccb_pre_price_days , payroll_card_term ).
```json title="RESPONSE BODY (exemplo)"
{
"document_batch_key": "1eee4ec2-05f5-45ef-aa64-38bb3d9de02f",
"documents": [
{
"document_key": "5cca1dad-28fe-4f19-8bbb-0edd6f042384",
"document_type": "ccb_pre_price_days"
},
{
"document_key": "c109d589-ae18-4f4f-ad31-2879bf714c71",
"document_type": "withdrawal_operation_term"
},
{
"document_key": "085e3098-0bdb-4472-a4ae-dafc1bafda53",
"document_type": "payroll_card_term"
},
{
"document_key": "eafdb3bd-5c21-415f-bdc2-8e366d54094c",
"document_type": "payroll_card_consent_term"
}
]
}
```
---
## Limpar documentos do lote
Remove todos os documentos vinculados ao lote (para reagrupar do zero, se necessário).
Request
ENDPOINT /document/document_batch/ DOCUMENT_BATCH_KEY /documents
MÉTODO DELETE
Path params
document_batch_key
string
obrigatório
Chave do lote.
**Python**
```python title="ENDPOINT"
DELETE /document/document_batch/YOUR_DOCUMENT_BATCH_KEY/documents
```
**curl**
```bash title="ENDPOINT"
curl -X DELETE \
'https://api-auth.sandbox.qitech.app/document/document_batch/YOUR_DOCUMENT_BATCH_KEY/documents' \
-H 'AUTHORIZATION: eyJhbGciOiJFUzUxMiJ9.eyJwYXlsb2FkX21kNSI6...' \
-H 'API-CLIENT-KEY: YOUR_API_CLIENT_KEY' \
-H 'Content-Type: application/json'
```
Response
STATUS 200
Corpo de resposta conforme padrão da API para sucesso neste recurso (pode ser vazio ou objeto mínimo).
```json title="RESPONSE BODY (exemplo)"
{}
```
---
## Enviar para assinatura
Fecha o lote e dispara os documentos para assinatura no QI Sign.
Request
ENDPOINT /document/document_batch/ DOCUMENT_BATCH_KEY /send_to_signature
MÉTODO PUT
Path params
document_batch_key
string
obrigatório
Chave do lote.
**Body:** objeto JSON vazio `{}`.
**Python**
```python title="ENDPOINT"
PUT /document/document_batch/YOUR_DOCUMENT_BATCH_KEY/send_to_signature
```
**curl**
```bash title="ENDPOINT"
curl -X PUT \
'https://api-auth.sandbox.qitech.app/document/document_batch/YOUR_DOCUMENT_BATCH_KEY/send_to_signature' \
-H 'AUTHORIZATION: eyJhbGciOiJFUzUxMiJ9.eyJwYXlsb2FkX21kNSI6...' \
-H 'API-CLIENT-KEY: YOUR_API_CLIENT_KEY' \
-H 'Content-Type: application/json' \
-d '{}'
```
```json title="REQUEST BODY"
{}
```
Response
STATUS 200
```json title="RESPONSE BODY (exemplo)"
{}
```
---
## Erros
| HTTP | Código | Título (exemplo) | Endpoint | Quando ocorre |
|------|--------|------------------|----------|---------------|
| 404 | DOC000007 | (lote não encontrado) | `GET /document/document_batch/DOCUMENT_BATCH_KEY` | `document_batch_key` inexistente |
| 409 | DOC000103 | Bad Request | POST /document/document_batch | `request_control_key` duplicado (idempotência violada de forma inválida) |
| 400 | DOC000128 | Bad Request | POST /document/document_batch | O `type` não suporta o modo enviado (frente e verso × arquivo único) |
| 400 | DOC000129 | Bad Request | POST /document/document_batch | A jornada configurada para o requester não coleta documento de identificação |
| 400 | DOC000130 | Bad Request | POST /document/document_batch | O `type` não está entre os tipos aceitos pela configuração do requester |
| 400 | DOC000137 | Bad Request | POST /document/document_batch | `document_key` do documento pré-coletado já vinculada a outro lote |
| 404 | DOC000004 | Bad Request | POST /document/document_batch | `document_key` do documento pré-coletado não encontrada (inclui arquivo de outro requester) |
| 400 | DOC000049 | Bad Request | POST /document/document_batch | Documento pré-coletado sem arquivo — upload não concluído antes da abertura |
| 403 | QIT000004 | Bad Request | POST /document/document_batch | `personal_document` enviado sem o header `SELECTED-AGENT` |
**Exemplo de erro (idempotência)**
```json
{
"code": "DOC000103",
"title": "Bad Request",
"description": "request_control_key already exists",
"translation": "Chave de controle da request já existe.",
"http_status": 409
}
```
:::info Conflito de titularidade ou tipo
Validações de **mesmo CPF/representante** e de **tipo de operação** no lote costumam retornar erro no POST da operação ( /debt ou /payroll_card_reservation/social_security ), não no endpoint do lote. O corpo de erro segue o catálogo do recurso chamado.
:::
:::info Migração de paths
Endpoints antigos foram substituídos pelos paths abaixo:
| Antigo | Novo |
|--------|------|
| `POST /document_batch/external` | `POST /document/document_batch` |
| `GET /document_batch/external/DOCUMENT_BATCH_KEY` | `GET /document/document_batch/DOCUMENT_BATCH_KEY` |
| `PUT /document_batch/DOCUMENT_BATCH_KEY/send_to_signature` | `PUT /document/document_batch/DOCUMENT_BATCH_KEY/send_to_signature` |
:::
---
# Consignado Público - Visão Geral
URL: /documentation/guides/publico/visao_geral
**Consignado Público** é a consignação em folha de **servidores públicos estaduais e municipais**. O ente consignante — o estado ou o município que paga a folha — mantém o registro da margem consignável de cada servidor, e é nele que a QI Tech reserva a parcela mensal que garante a operação.
:::caution API em desenvolvimento
Esta seção documenta um produto em construção. As páginas marcadas como *em desenvolvimento* ainda não têm conteúdo, e o que já está publicado pode mudar até o lançamento.
:::
:::info O que esta seção cobre
O **cartão consignado** de servidor público é contratado pelo [Manual Cartão Consignado](/documentation/manual_cartao_beneficio/visao_geral), na fonte `public_payroll` — esta seção contém a referência de margem, entes e averbação que aquele manual consulta. Além disso, o fluxo de averbação do crédito consignado sem ser de cartão se encontra aqui.
:::
## Como uma operação é endereçada {#como-uma-operacao-e-enderecada}
Uma operação de Consignado Público é endereçada em dois passos.
**A rota nomeia o ente.** A esfera — `state` ou `municipal` — e o enumerador do ente são os dois primeiros segmentos:
```
/public_payroll/{entity_level}/{consignment_entity}/...
```
**O corpo identifica o servidor.** Quais campos fazem isso **depende do ente**: cada ente mantém a sua folha em uma plataforma de consignação, e as plataformas não identificam o servidor da mesma forma. Umas exigem o órgão pagador, outras uma senha do servidor, outras apenas a matrícula.
É por isso que a seção trabalha com **perfis de consignação**. Ver [Perfis de consignação](#perfis-de-consignacao) e, para os campos de cada perfil, [Entes Consignantes](/documentation/guides/publico/entes#perfis-de-consignacao).
## Perfis de consignação {#perfis-de-consignacao}
Um **perfil** é o conjunto do que varia entre plataformas de consignação:
- **Como o servidor é identificado** — quais campos o corpo precisa carregar.
- **Como a margem é informada** — a estrutura do documento de consulta, e se ele detalha a margem por cargo, por produto ou em um valor único.
- **Quais enumeradores valem** — produtos, situações de margem, tipos de vínculo e motivos de recusa são definidos pela plataforma, não pela QI Tech.
Entes na mesma plataforma compartilham um perfil, e portanto compartilham exatamente os mesmos payloads. Cada perfil é documentado uma vez; a tabela de entes diz qual perfil cada ente usa.
## A jornada de uma contratação {#a-jornada}
1. **Consulta de margem** — descobre os vínculos do CPF no ente e a margem disponível em cada um. Assíncrona. Ver [Consulta de Margem](/documentation/guides/publico/consulta-de-margem).
2. **Simulação** — calcula as condições da operação a partir da margem. *Em desenvolvimento.*
3. **Emissão** — cria a operação e o instrumento de crédito. *Em desenvolvimento.*
4. **Formalização** — assinatura e documentos do servidor. *Em desenvolvimento.*
5. **Averbação** — reserva a margem no ente. É a etapa que pode falhar por margem insuficiente e, em alguns entes, depende da aprovação do próprio servidor. Ver [Reserva de Margem](/documentation/guides/publico/reserva).
6. **Desembolso** — liberação do valor contratado. *Em desenvolvimento.*
Cada mudança de status é notificada por webhook. Ver [Webhooks](/documentation/guides/publico/webhooks).
## Conteúdo desta seção
| Página | Conteúdo | |
|---|---|---|
| **[Entes Consignantes](/documentation/guides/publico/entes)** | Entes atendidos, perfis de consignação e particularidades de cada ente | |
| **[Consulta de Margem](/documentation/guides/publico/consulta-de-margem)** | Descoberta de vínculos e margem disponível | |
| **[Reserva de Margem](/documentation/guides/publico/reserva)** | Acompanhamento da averbação, cancelamento e comprovante | |
| **[Crédito Novo](/documentation/guides/publico/credito-novo/simulacao)** | Simulação, emissão e formalização | Em desenvolvimento |
| **[Portabilidade](/documentation/guides/publico/portabilidade)** | Transferência de operação de outra instituição | Em desenvolvimento |
| **[Refinanciamento](/documentation/guides/publico/refinanciamento)** | Renegociação de operação ativa | Em desenvolvimento |
| **[Webhooks](/documentation/guides/publico/webhooks)** | Notificações de mudança de status | |
| **[Enumeradores](/documentation/guides/publico/enumeradores)** | Status, motivos, produtos e tipos de reserva | |
## Glossário
| Termo | Significado |
|---|---|
| **Ente consignante** (`consignment_entity`) | O governo estadual ou municipal que paga a folha e mantém o registro de margem consignável. |
| **Vínculo** | A relação do servidor com o ente que sustenta a consignação. Como ele é identificado depende do [perfil](#perfis-de-consignacao) do ente. |
| **Margem consignável** | Valor mensal do salário ou provento que pode ser comprometido com consignações. |
| **Averbação** | Registro da operação no ente, que reserva a margem e ordena o desconto em folha. |
| **Desaverbação** | Remoção de uma averbação existente, liberando a margem. |
| **Consulta de margem** (`balance_inquiry`) | Pergunta ao ente sobre os vínculos e a margem de um CPF. O resultado é uma fotografia, com validade no mês da observação. |
| **Perfil de consignação** | O que varia entre plataformas de consignação: identificação do servidor, estrutura do documento de margem e enumeradores. |
| **Comprovante** (`protocol`) | Recibo que prova que uma averbação ou desaverbação foi executada no ente. |
---
# Assinar Documento
URL: /documentation/iaas/investidor/compartilhado/assinar_documento
---
### Introdução
Este recurso confirma a assinatura de um documento gerado para a formalização do cadastro do investidor via método **opt-in**. Os tipos suportados são: ficha cadastral (pessoa física ou jurídica), termo de investidor qualificado e termo de investidor profissional.
Diferente de **[Enviar Documento Assinado](/documentation/iaas/investidor/compartilhado/enviar_documento_assinado)** (que faz upload do arquivo final assinado), este recurso apenas registra a comprovação da assinatura por meio do hash de opt-in coletado pelo distribuidor.
:::warning Atenção
Este recurso está disponível apenas para integrações que atuam como **Distribuidor** com `document_signature` configurado como `opt-in`. O documento deve estar com status `generated`.
:::
### Input / Output
Como ***input*** envie o `opt_in_hash` que comprova a assinatura.
Como ***output***, quando a confirmação finaliza o lote, é retornada a chave `investor_document_key`.
### Request
ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/document_batch/{document_batch_key}/document/{investor_document_key}/sign_document`
MÉTODO `PUT`
STATUS `200`
### Request body
```json title='Request Body'
{
"opt_in_hash": "OPT_IN_HASH"
}
```
### Body params
| Campo | Tipo | Descrição | Obrigatório |
|---------------|--------|--------------------------------------------|-------------|
| `opt_in_hash` | string | Hash de verificação da assinatura opt-in | Sim |
:::warning Atenção
Durante o processo de integração será exigido um meio de autenticação da hash enviada.
:::
### Response
```json title='Response Body'
{
"investor_document_key": "UUID"
}
```
---
# Atualização Cadastral
URL: /documentation/iaas/investidor/compartilhado/atualizacao_cadastral
---
### Introdução
Após o cadastro inicial de um investidor já ter sido aprovado, novos ciclos de cadastro podem ser abertos sempre que houver necessidade de **atualização cadastral** — seja por mudança de dados, vencimento de documentos ou solicitação de uma nova análise pela QI Tech.
Diferente do cadastro inicial, a atualização **não cria um novo investidor**: ela apenas abre uma nova **análise cadastral** (`investor_analysis`) sobre o investidor existente. A partir disso, o fluxo segue exatamente o mesmo do cadastro original: envio dos dados, documentos, partes relacionadas e submissão para análise.
### Input / Output
Como ***input*** não é necessário enviar nenhum corpo de requisição — basta informar a `investor_key` do investidor que terá sua análise atualizada.
Como ***output*** será retornada a representação da nova análise cadastral, contendo a `investor_analysis_key` que deve ser utilizada nas etapas seguintes do fluxo.
### Request
ENDPOINT `/investor_registry/v2/investor/{investor_key}/investor_analysis`
MÉTODO `POST`
STATUS `201`
:::info
A requisição é enviada **sem corpo** (`body` vazio). Os dados da atualização serão enviados nas etapas subsequentes do fluxo, da mesma forma que no cadastro inicial.
:::
### Próximos passos
A partir do retorno da `investor_analysis_key`, o processo de atualização cadastral segue **o mesmo fluxo do cadastro inicial** descrito nesta seção:
1. Envio dos dados cadastrais (pessoa física/jurídica, endereço, patrimônio).
2. Envio de contas bancárias, suitability, grupos de assinantes, partes relacionadas e documentos — conforme aplicável ao tipo de investidor.
3. Envio do cadastro para análise.
4. Assinatura dos documentos gerados após a aprovação.
Consulte as etapas subsequentes desta seção para os detalhes de cada recurso.
---
# Atualizar Status do Grupo de Assinantes
URL: /documentation/iaas/investidor/compartilhado/atualizar_status_grupo_assinantes
---
### Introdução
Este recurso altera o status de um grupo de assinantes previamente cadastrado em uma análise cadastral — por exemplo, para inativar um grupo que não deve mais ser utilizado.
O grupo é identificado pela sua chave externa (`external_signer_group_key`), retornada na criação.
### Request
ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/signer_group/{external_signer_group_key}/status`
MÉTODO `PUT`
STATUS `202`
### Request body
```json title='Request Body'
{
"status": "inactive"
}
```
### Body params
| Campo | Tipo | Descrição | Obrigatório |
|----------|--------|-----------------------------------------------------------------|-------------|
| `status` | string | Novo status do grupo. Valores típicos: `active`, `inactive` | Sim |
### Response
`202 Accepted`. A representação atualizada do grupo é retornada no corpo.
---
# Consulta Informações de uma Análise Cadastral do Investidor
URL: /documentation/iaas/investidor/compartilhado/busca_informacoes_de_uma_analise_cadastral_do_investidor
---
### Introdução
Este recurso retorna a representação completa de uma **análise cadastral**, incluindo dados cadastrais preenchidos (`natural_person` / `legal_person`), endereço, patrimônio, suitability, contas bancárias, grupos de assinantes, partes relacionadas, investor owners, documentos da análise, lotes de documentos para assinatura e histórico de eventos de status.
### Input / Output
Não há corpo de requisição.
Como ***output*** será retornada a representação da análise cadastral identificada por `investor_analysis_key`.
### Request
ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}`
MÉTODO `GET`
STATUS `200`
:::info Endpoints relacionados
- **Análise em andamento** para um investidor: `GET /investor_registry/investor/{investor_key}/in_progress_investor_analysis`.
- **Listagem paginada de análises** do agente: `GET /investor_registry/investor_analyses`.
:::
### Response
Caso 01: Análise de Pessoa Jurídica — Fundo de Investimento
```json
{
"investor_analysis_key": "UUID",
"name": "Fundo XPTO Multimercado",
"document_number": "12.345.678/0001-90",
"analysis_datetime": "2025-04-29T12:07:55Z",
"status": "manually_approved",
"analysis_type": "v2",
"agent_key": "UUID",
"investor": {
"investor_key": "UUID",
"name": "Fundo XPTO Multimercado",
"document_number": "12.345.678/0001-90",
"person_type": "legal_person",
"investor_sub_type": "fund_class",
"status": "registered"
},
"registry_user": {
"registry_user_key": "UUID",
"name": "Sample Investor Name",
"document_number": "123.456.789-00",
"email": "user@example.com",
"phone": {
"number": "987654321",
"area_code": "11",
"international_dial_code": "55"
}
},
"email": "fundo@example.com",
"phone": {
"number": "987654321",
"area_code": "11",
"international_dial_code": "55"
},
"address": {
"uf": "SP",
"city": "São Paulo",
"number": "1000",
"street": "Avenida Paulista",
"country": "BRA",
"complement": "Sala 1010",
"postal_code": "01310-100",
"neighborhood": "Bela Vista"
},
"legal_person": {
"legal_name": "Fundo XPTO Multimercado FIC FIM",
"constitution_date": "2020-01-15",
"exclusive_fund_class": false
},
"net_worth": {
"total_net_worth": 25000000,
"total_financial_applications": 25000000,
"monthly_income": 0,
"other_incomes": 0,
"real_estate": 0,
"movable_assets": 0,
"investor_category": "professional"
},
"investor_category": "professional",
"bank_accounts": [
{
"bank_account_key": "UUID",
"main_account": true,
"account_digit": "8",
"account_branch": "2152",
"account_number": "43473205725488",
"financial_institution_code": "349",
"status": "active"
}
],
"signer_groups": [
{
"signer_group_key": "UUID",
"external_signer_group_key": "UUID",
"is_default": true,
"minimum_required_signers": 1,
"status": "active",
"signers": [
{
"name": "Representante Legal",
"document_number": "123.456.789-00",
"email": "rep@example.com",
"is_required_signer": true
}
]
}
],
"investor_owners": [
{
"external_investor_owner_key": "UUID",
"investor_owner_type": "fund_class_administrator",
"document_number": "07.228.314/0001-95",
"status": "active"
},
{
"external_investor_owner_key": "UUID",
"investor_owner_type": "fund_class_manager",
"document_number": "77.784.920/0001-72",
"status": "active"
}
],
"related_parties": [],
"representatives_analyses": [
{
"representative_analysis_key": "UUID",
"name": "Sample",
"document_number": "069.800.621-66",
"status": "pending_documents",
"documents": [],
"powers": [
"investor_registry.create_investor",
"investor_registry.update_investor_analysis"
]
}
],
"documents": [
{
"document_key": "UUID",
"type": "cnpj_card",
"status": "valid",
"observation": null
}
],
"document_batches": [
{
"document_batch_key": "UUID",
"status": "signed",
"documents": [
{
"investor_document_key": "UUID",
"document_type": "legal_person_registry_form",
"status": "signed",
"signature_method": "certifiqi"
}
]
}
],
"feedbacks": [],
"status_events": [
{"status": "pending_registry_data", "event_datetime": "2025-04-29T12:07:55Z"},
{"status": "sent_to_analysis", "event_datetime": "2025-04-29T12:08:00Z"},
{"status": "manually_approved", "event_datetime": "2025-04-29T13:00:00Z"}
]
}
```
### Investor Analysis
| Campo | Tipo | Descrição |
|-----------------------------|---------|--------------------------------------------------------------------------|
| `investor_analysis_key` | string | Chave única da análise cadastral |
| `name` | string | Nome (ou razão social) |
| `document_number` | string | CPF / CNPJ |
| `analysis_datetime` | string | Data/hora de criação da análise. Veja [Formato de data](#formato-data) |
| `analysis_type` | string | Enumerador de **[Analysis Type](#analysis-type)** |
| `status` | string | Enumerador de **[Investor Analysis Status](#analysis-status)** |
| `investor_category` | string | Enquadramento autodeclarado (`retail`, `qualified`, `professional`) |
| `suitability` | string | Perfil suitability calculado (quando aplicável) |
| `signature_method` | string | Método de assinatura definido para a análise |
| `expiration_date` | string | Data de expiração do cadastro |
| `investor` | object | Investidor associado |
| `email` | string | E-mail |
| `phone` | object | Objeto de **[Phone](#phone)** |
| `address` | object | Endereço — ver doc **Enviar Endereço** |
| `natural_person` | object | Dados de pessoa física — ver doc **Enviar Dados Cadastrais** |
| `legal_person` | object | Dados de pessoa jurídica — ver doc **Enviar Dados Cadastrais** |
| `net_worth` | object | Dados patrimoniais — ver doc **Enviar Patrimônio** |
| `bank_accounts` | array | Contas bancárias |
| `signer_groups` | array | Grupos de assinantes |
| `investor_owners` | array | Vínculos de propriedade (relevante para `fund_class`) |
| `related_parties` | array | Partes relacionadas |
| `documents` | array | Documentos enviados na análise |
| `document_batches` | array | Lotes de documentos para assinatura |
| `feedbacks` | array | Feedbacks trocados na análise — ver **[Listar Feedbacks](./feedback/listar_feedbacks)**. Um feedback `open` não altera o `status` da análise |
| `status_events` | array | Histórico de eventos de status |
### Legal Person — campos `fund_class`
Quando `investor.investor_sub_type` é `fund_class`, os campos abaixo são enriquecidos automaticamente a partir da base da CVM durante o envio para análise:
| Campo | Tipo | Descrição |
|------------------------|---------|--------------------------------------------------------------------------|
| `legal_name` | string | Razão social / nome da classe do fundo |
| `constitution_date` | string | Data de constituição |
| `exclusive_fund_class` | boolean | Indica se a classe é exclusiva |
### Phone
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|--------|------------------------|------------|
| `international_dial_code` | string | Código internacional | 1 - 3 |
| `area_code` | string | DDD | 2 |
| `number` | string | Número de telefone | 8 - 9 |
### Investor Analysis Status {#analysis-status}
| Enumerador | Descrição |
|---------------------------|--------------------------------------|
| `created` | Criada |
| `pending_registry_data` | Pendente dados cadastrais |
| `pending_documents` | Pendente documentos |
| `sent_to_analysis` | Enviada para análise |
| `in_manual_analysis` | Em análise manual |
| `in_compliance_analysis` | Em análise de compliance |
| `automatically_approved` | Aprovada automaticamente |
| `automatically_reproved` | Reprovada automaticamente |
| `manually_approved` | Aprovada manualmente |
| `manually_reproved` | Reprovada manualmente |
| `analysis_complete` | Análise concluída |
| `expired` | Expirada |
Para entender qual status exige ação sua e qual apenas aguarda a QI Tech, veja **[Ciclo de vida da análise cadastral](./ciclo_de_vida_da_analise)**.
### Analysis Type {#analysis-type}
| Enumerador | Descrição |
|----------------------------|-------------------------------------------------------------------------|
| `first_analysis` | Primeira análise cadastral do investidor |
| `registry_update_analysis` | Análise aberta por atualização cadastral ou renovação |
| `fund_class_transfer` | Análise gerada por transferência de classe de fundo |
### Formato de data {#formato-data}
Os campos de data/hora — `analysis_datetime`, `event_datetime` dos `status_events`, e os equivalentes nas demais rotas — são devolvidos em **ISO-8601 UTC com sufixo `Z`**, sem microssegundos:
```
2026-07-31T21:47:46Z
```
O campo `expiration_date` é uma **data pura**, sem hora, no formato `YYYY-MM-DD`.
:::info Se você observou outro formato
Até a correção aplicada em agosto de 2026, algumas rotas — entre elas `GET /investor_registry/investor/{investor_key}` — devolviam data/hora no formato `2026-07-31 21:47:46.138686` (com espaço, com microssegundos e sem `Z`). Esse comportamento era um desvio do padrão e foi corrigido: todas as rotas agora emitem `Z`.
Se a sua integração fez o parse do formato antigo, ajuste-a para ISO-8601. Recomendamos usar um parser ISO-8601 padrão da sua linguagem em vez de um formato fixo.
:::
---
# Consulta Informações do Investidor
URL: /documentation/iaas/investidor/compartilhado/busca_informacoes_do_investidor
---
### Introdução
Este recurso retorna os dados completos de um **investidor** — incluindo suas análises cadastrais, lotes de documentos, eventos de status, distribuidor e usuário cadastrador.
### Input / Output
Não há corpo de requisição. As chaves de identificação são passadas no *path*.
Como ***output*** será retornada a representação atual do investidor.
### Request
ENDPOINT `/investor_registry/investor/{investor_key}`
MÉTODO `GET`
STATUS `200`
:::info Endpoints relacionados
- **Listar investidores do agente**: `GET /investor_registry/investors` (paginado, com filtros `name`, `document_number`, `status`).
- **Listar investidores possuídos por um investor owner** (uso típico: fund class): `GET /investor_registry/investor/{investor_key}/investors`.
:::
### Response
Caso 01: Pessoa Física
```json
{
"investor_key": "UUID",
"name": "João da Silva",
"document_number": "123.456.789-00",
"status": "pending_analysis",
"email": "joao@example.com",
"person_type": "natural_person",
"phone": {
"number": "987654321",
"area_code": "11",
"international_dial_code": "55"
},
"distributor": {
"distributor_key": "UUID",
"name": "Distribuidor XPTO",
"document_number": "00.000.000/0000-00"
},
"analyses": [
{
"investor_analysis_key": "UUID",
"analysis_datetime": "2025-04-29 12:07:55.059999",
"status": "pending_registry_data"
}
],
"document_batches": [],
"status_events": [
{
"status": "pending_analysis",
"event_datetime": "2025-04-29 12:07:55.000000"
}
]
}
```
Caso 02: Pessoa Jurídica — Fundo de Investimento
```json
{
"investor_key": "UUID",
"name": "Fundo XPTO Multimercado",
"document_number": "12.345.678/0001-90",
"status": "registered",
"person_type": "legal_person",
"investor_sub_type": "fund_class",
"distributor": {
"distributor_key": "UUID",
"name": "Distribuidor XPTO",
"document_number": "00.000.000/0000-00"
},
"analyses": [
{
"investor_analysis_key": "UUID",
"analysis_datetime": "2025-04-29 12:07:55.059999",
"status": "manually_approved",
"registry_user": {
"registry_user_key": "UUID",
"kc_user_id": "UUID",
"name": "João da Silva",
"document_number": "000.000.000-00",
"email": "joao.silva@example.com",
"phone": {
"number": "123456789",
"area_code": "11",
"international_dial_code": "55"
}
}
}
],
"document_batches": [
{
"document_batch_key": "UUID",
"status": "signed",
"documents": [
{
"investor_document_key": "UUID",
"type": "legal_person_registry_form",
"status": "signed"
}
]
}
],
"status_events": [
{
"status": "registered",
"event_datetime": "2025-04-29 13:08:25.673902"
}
]
}
```
### Investor
| Campo | Tipo | Descrição |
|---------------------|---------|---------------------------------------------------------------------------------|
| `investor_key` | string | Chave única de identificação do investidor |
| `name` | string | Nome (ou razão social) do investidor |
| `document_number` | string | CPF / CNPJ do investidor |
| `email` | string | E-mail de contato |
| `phone` | object | Objeto de **[Phone](#phone)** |
| `status` | string | Enumerador de **[Investor Status](#investor-status)** |
| `person_type` | string | Enumerador de **[Person Type](#person-type)** |
| `investor_sub_type` | string | Enumerador de **[Investor Sub Type](#investor-sub-type)**, quando aplicável |
| `distributor` | object | Objeto de **[Distributor](#distributor)** |
| `analyses` | array | Lista de objetos de **[Investor Analysis](#investor-analysis)** |
| `document_batches` | array | Lista de objetos de **[Document Batch](#document-batch)** |
| `status_events` | array | Lista de objetos de **[Status Event](#status-event)** |
### Phone
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|--------|------------------------|------------|
| `international_dial_code` | string | Código internacional | 1 - 3 |
| `area_code` | string | DDD | 2 |
| `number` | string | Número de telefone | 8 - 9 |
### Investor Status {#investor-status}
| Enumerador | Descrição |
|-----------------------|-------------------------|
| `created` | Criado |
| `pending_analysis` | Pendente análise |
| `pending_documents` | Pendente documentos |
| `incomplete` | Cadastro incompleto |
| `pending_update` | Pendente atualização |
| `registered` | Cadastrado |
| `registry_expired` | Cadastro expirado |
### Person Type {#person-type}
| Enumerador | Descrição |
|-------------------|------------------|
| `natural_person` | Pessoa física |
| `legal_person` | Pessoa jurídica |
| `nominee` | Nominee / PCO |
### Investor Sub Type {#investor-sub-type}
| Enumerador | Descrição |
|--------------------------|---------------------------------|
| `default` | Pessoa jurídica regular |
| `financial_institution` | Instituição financeira |
| `fund_class` | Fundo de investimento |
| `non-resident` | Não-residente |
### Distributor {#distributor}
| Campo | Tipo | Descrição |
|---------------------|--------|----------------------------------------------------|
| `distributor_key` | string | Chave única do distribuidor |
| `name` | string | Nome do distribuidor |
| `document_number` | string | CNPJ do distribuidor |
### Investor Analysis {#investor-analysis}
| Campo | Tipo | Descrição |
|--------------------------|--------|------------------------------------------------------------------|
| `investor_analysis_key` | string | Chave única da análise cadastral |
| `analysis_datetime` | string | Data/hora de criação da análise |
| `status` | string | Enumerador de **[Investor Analysis Status](#analysis-status)** |
| `registry_user` | object | Objeto de **[Registry User](#registry-user)**, quando presente |
### Document Batch {#document-batch}
| Campo | Tipo | Descrição |
|----------------------|--------|--------------------------------------------------------|
| `document_batch_key` | string | Chave única do lote de documentos |
| `status` | string | Enumerador de **[Document Batch Status](#batch-status)**|
| `documents` | array | Lista de objetos de **[Investor Document](#investor-document)**|
### Investor Document {#investor-document}
| Campo | Tipo | Descrição |
|------------------------|--------|-----------------------------------------------------------------|
| `investor_document_key`| string | Chave única do documento do investidor |
| `type` | string | Enumerador de **[Document Type](#document-type)** |
| `status` | string | Enumerador de **[Investor Document Status](#document-status)** |
### Registry User {#registry-user}
| Campo | Tipo | Descrição |
|---------------------|--------|-------------------------------------------------|
| `registry_user_key` | string | Chave única do usuário cadastrador |
| `kc_user_id` | string | ID do usuário no KeyCloak |
| `name` | string | Nome |
| `document_number` | string | CPF |
| `email` | string | E-mail |
| `phone` | object | Objeto de **[Phone](#phone)** |
### Investor Analysis Status {#analysis-status}
| Enumerador | Descrição |
|---------------------------|--------------------------------------|
| `created` | Criada |
| `pending_registry_data` | Pendente dados cadastrais |
| `pending_documents` | Pendente documentos |
| `sent_to_analysis` | Enviada para análise |
| `in_manual_analysis` | Em análise manual |
| `automatically_approved` | Aprovada automaticamente |
| `automatically_reproved` | Reprovada automaticamente |
| `manually_approved` | Aprovada manualmente |
| `manually_reproved` | Reprovada manualmente |
| `expired` | Expirada |
### Document Batch Status {#batch-status}
| Enumerador | Descrição |
|--------------------------|---------------------------------|
| `creating_documents` | Documentos sendo gerados |
| `send_to_signature` | Enviado para assinatura |
| `pending_signature` | Aguardando assinatura |
| `signed` | Assinado |
### Document Type {#document-type}
| Enumerador | Descrição |
|--------------------------------|----------------------------------------|
| `cnh` | CNH |
| `rg` | RG |
| `rg_back` | RG — verso |
| `rg_front` | RG — frente |
| `proof_of_residence` | Comprovante de residência |
| `cnpj_card` | Cartão CNPJ |
| `financial_statements` | Demonstrações financeiras |
| `social_contract` | Contrato social |
| `company_statute` | Estatuto |
| `board_election_record` | Ata de eleição |
| `fund_prospectus` | Regulamento do fundo |
| `power_of_attorney` | Procuração |
| `billing_statement` | Fatura / extrato |
| `investor_qualification_proof` | Comprovação de qualificação |
| `qualified_investor_term` | Termo de investidor qualificado |
| `professional_investor_term` | Termo de investidor profissional |
| `natural_person_registry_form` | Ficha cadastral — pessoa física |
| `legal_person_registry_form` | Ficha cadastral — pessoa jurídica |
### Investor Document Status {#document-status}
| Enumerador | Descrição |
|--------------------|----------------------------------------|
| `sent_to_generate` | Enviado para ser gerado |
| `generated` | Gerado |
| `signed` | Assinado |
### Status Event {#status-event}
| Campo | Tipo | Descrição |
|------------------|--------|-----------------------------------------------------------------|
| `status` | string | Enumerador de status |
| `event_datetime` | string | Data/hora do evento |
---
# Buscar Lotes de Documentos para Assinatura
URL: /documentation/iaas/investidor/compartilhado/buscar_documentos_para_assinatura
---
### Introdução
Este recurso retorna os **lotes de documentos** (`document_batches`) gerados para um investidor após o envio da análise cadastral. Cada lote agrupa os documentos a serem assinados (ficha cadastral, termos de investidor qualificado/profissional, etc.) e expõe o status e o método de assinatura de cada documento.
### Input / Output
Não há corpo de requisição. Opcionalmente é possível filtrar por análise cadastral via query param.
Como ***output*** será retornada a lista de lotes do investidor.
### Request
ENDPOINT `/investor_registry/investor/{investor_key}/document_batches`
MÉTODO `GET`
STATUS `200`
### Query params
| Campo | Tipo | Descrição | Obrigatório |
|-------------------------|--------|----------------------------------------------------------------------|-------------|
| `investor_analysis_key` | string | Filtra os lotes pertencentes a uma análise cadastral específica | Não |
### Response
```json title='Response Body'
[
{
"document_batch_key": "UUID",
"status": "pending_signature",
"investor_analysis_key": "UUID",
"url": "https://docs.qitech.com.br/...",
"documents": [
{
"investor_document_key": "UUID",
"document_type": "legal_person_registry_form",
"status": "generated",
"signature_method": "certifiqi"
},
{
"investor_document_key": "UUID",
"document_type": "professional_investor_term",
"status": "generated",
"signature_method": "certifiqi"
}
]
}
]
```
### Document Batch Status
| Enumerador | Descrição |
|-------------------------|---------------------------------|
| `creating_documents` | Documentos sendo gerados |
| `pending_signer_groups` | Aguardando grupos de assinantes |
| `send_to_signature` | Enviados para assinatura |
| `pending_signature` | Aguardando assinatura |
| `signed` | Assinados |
:::info Detalhes de assinatura
Para detalhes de cada assinatura em um lote específico, utilize `GET /investor_registry/investor/{investor_key}/document_batch/{document_batch_key}/signature_details`.
:::
---
# Ciclo de vida da análise cadastral
URL: /documentation/iaas/investidor/compartilhado/ciclo_de_vida_da_analise
---
### Introdução
Depois do `submit`, a análise cadastral deixa de depender de você e passa a evoluir de forma **assíncrona**. Esta página descreve as etapas do fluxo, **em quais situações o cadastro volta a exigir a sua ação** e como acompanhar tudo isso por webhook.
---
### As etapas do fluxo
O cadastro percorre a sequência abaixo — **sempre para a frente**. As etapas 3 e 4 são **condicionais**: um cadastro sem pendências vai direto da análise automática para a aprovação. Nenhuma etapa devolve a análise para o preenchimento: quando a compliance precisa de um esclarecimento, ela abre um **feedback** sem alterar o status da análise.
```mermaid
flowchart TD
E1["1. Preenchimento
pending_registry_data"] -->|submit| E2["2. Análise automática
sent_to_analysis"]
E2 -->|sem pendências| A1["Aprovação
automatically_approved"]
E2 -->|recusa de compliance| R1["Recusa
automatically_reproved"]
E2 -->|requer revisão| E3["3. Análise manual
in_manual_analysis
etapa condicional"]
E3 -->|aprovado| A2["Aprovação
manually_approved"]
E3 -->|cadastro insuficiente| R2["Recusa
manually_reproved"]
E3 -->|requer compliance| E4["4. Análise de compliance
in_compliance_analysis
etapa condicional"]
E4 -->|aprovado| A2
E4 -->|cadastro insuficiente| R2
E4 -->|esclarecimentos| FB["Feedback aberto
feedback: open
a análise permanece em
in_compliance_analysis"]
FB -->|você responde
feedback: closed| E4
A1 --> E5["5. Documentos e assinatura
pending_documents"]
A2 --> E5
E5 --> E6["6. Cadastro concluído
analysis_complete"]
R2 --> N["Nova análise cadastral"]
```
| # | Etapa | Status da análise | Quem age |
|---|-------|-------------------|----------|
| 1 | **Preenchimento** — dados cadastrais, endereço, patrimônio, suitability, contas, partes relacionadas e documentos | `created` → `pending_registry_data` | **Você** |
| 2 | **Análise automática** — motores de risco e PLD processam o cadastro e produzem uma decisão: aprovação, recusa, ou encaminhamento para revisão humana | `sent_to_analysis` | QI Tech (automático) |
| 3 | **Análise manual** *(condicional)* — um analista revisa os dados cadastrais. **Esta etapa é pulada quando o cadastro é aprovado automaticamente** | `in_manual_analysis` | QI Tech (analista) |
| 4 | **Análise de compliance** *(condicional)* — revisão de PLD/compliance. **Também é pulada quando o cadastro é aprovado automaticamente.** É a etapa em que um **feedback** pode ser aberto pedindo esclarecimentos | `in_compliance_analysis` | QI Tech (analista) — **e você, se um feedback for aberto** |
| 5 | **Documentos e assinatura** — aprovada a análise, a QI Tech gera o lote de documentos de formalização e o cadastro segue para assinatura | `automatically_approved` / `manually_approved` → `pending_documents` | Depende da configuração da sua conta |
| 6 | **Conclusão** — o investidor está apto a operar | `analysis_complete` | — |
:::info As etapas 3 e 4 não são obrigatórias
Um cadastro completo e sem indicadores de risco vai de `sent_to_analysis` direto para `automatically_approved`. Quando você observa `in_manual_analysis` ou `in_compliance_analysis`, significa apenas que aquele cadastro foi encaminhado para revisão humana — **não é um erro e não exige ação sua enquanto durar**.
:::
:::info A etapa 5 depende da configuração da sua conta
A geração dos documentos e a coleta da assinatura variam conforme a sua integração seja configurada para que a QI Tech assuma essas responsabilidades, para assinatura por *opt-in*, ou para geração e assinatura externas. Consulte **Buscar Lotes de Documentos para Assinatura** e confirme com o seu contato técnico como a sua conta está configurada.
:::
---
### Quando o cadastro precisa da sua ação {#quando-agir}
Existem **três** situações, e só três, em que a bola está do seu lado depois do `submit`:
| Situação | Sinal | O que fazer |
|----------|-------|-------------|
| **Feedback aberto** | Um feedback com `status: open` — a **análise permanece em `in_compliance_analysis`** | Responder à mensagem do feedback. A sua resposta o encerra (`closed`) e a compliance retoma a avaliação. **Não há novo `submit`.** |
| **Recusa manual** | `manually_reproved` | Abrir uma **nova análise cadastral** com as correções do parecer. |
| **Assinatura** | `pending_documents` | Submeter documentos assinados, ou aguardar assinatura do cotista, dependendo da configuração/papel. |
Em **todos os demais status** — `sent_to_analysis`, `in_manual_analysis`, `in_compliance_analysis` sem feedback aberto, `automatically_approved`, `manually_approved` — o cadastro está com a QI Tech e não há nada a fazer além de aguardar.
#### Feedback: pedido de esclarecimento {#feedback}
Acontece na **etapa 4, a análise de compliance**. Quando o analista de compliance precisa de um complemento ou de um esclarecimento para concluir a avaliação, ele abre um **feedback** com a mensagem do que precisa ser esclarecido.
**A análise não volta atrás.** Ela permanece em `in_compliance_analysis` durante todo o ciclo do feedback — não retorna para `pending_registry_data`, não reabre para edição e não precisa de um novo `submit`. O feedback corre **em paralelo** à análise: abre em `open`, você responde, ele passa a `closed` e a compliance segue de onde parou.
1. **Receba o aviso** pelo webhook `investor_registry.feedback_status_change`, com `status: open`
2. **Leia o pedido** com [Listar Feedbacks](./feedback/listar_feedbacks), usando `origin_type=investor_analysis` com a `investor_analysis_key`, e `origin_type=related_party_analysis` com cada `external_related_party_key`. O texto está em `description` e no histórico de `messages`
3. **Responda** com [Enviar Mensagem em Feedback](./feedback/enviar_mensagem_feedback) — a sua mensagem é a resposta ao pedido
4. **O feedback é encerrado** (`closed`) e um novo `investor_registry.feedback_status_change` é disparado. Nada mais é exigido de você
:::info Feedback só existe na análise de compliance
A etapa de análise manual (etapa 3) não abre feedbacks: ela termina em aprovação ou em recusa. Se a sua integração recebeu um feedback, ele veio da análise de compliance.
:::
:::warning Não acompanhe feedbacks pelo status da análise
Como a análise continua em `in_compliance_analysis`, **nenhuma mudança de status sinaliza um feedback aberto**. A única notificação é o webhook `investor_registry.feedback_status_change`. Uma integração que só observa o status da análise não perceberá o pedido — e o cadastro ficará parado na compliance à espera de uma resposta que não virá.
:::
:::warning A análise continua bloqueada para edição
Permanecer em `in_compliance_analysis` significa que os endpoints de preenchimento — dados cadastrais, documentos, partes relacionadas, contas — continuam recusando alterações. O canal de resposta ao feedback é a **mensagem**. Se o esclarecimento exigir alterar o cadastro em si, a compliance recusará a análise e você abrirá uma nova por meio de **Atualização Cadastral**.
:::
:::info A sua resposta encerra o feedback
Enviar a mensagem move o feedback de `open` para `closed` — não é preciso aguardar um analista da QI Tech encerrá-lo. Se a resposta não for suficiente, a compliance abre um **novo** feedback.
:::
#### Recusa
A recusa é o caminho **mais comum** quando um cadastro não é aprovado, e vem em duas formas:
- **`automatically_reproved`** — recusa de **compliance**, aplicada automaticamente logo após o `submit`, ainda na etapa 2. O cadastro sequer chega à revisão humana.
- **`manually_reproved`** — recusa por um analista, na etapa 3 ou 4, quando o cadastro não reúne os dados mínimos para aprovação. Vem acompanhada de um parecer.
Nos dois casos a análise é **terminal**: ela não volta atrás, e nenhum dado dela pode mais ser alterado — tentativas de atualizar partes relacionadas, contas ou documentos são recusadas com `IVR000185`.
O caminho é abrir uma **nova análise cadastral** para o mesmo investidor, por meio de **Atualização Cadastral**, e refazer o preenchimento com as correções indicadas.
:::info Recusa e feedback são coisas diferentes
O **feedback** não altera o status da análise: ela segue em `in_compliance_analysis` e o pedido é resolvido com uma mensagem. A **recusa** encerra a análise e exige começar uma nova. Se a sua integração trata os dois casos igual, ela vai abrir análises desnecessárias — ou deixar de abrir as que precisa.
:::
---
### Referência de status da análise
| Status | Etapa | Significado | Ação esperada de você |
|--------------------------|-------|------------------------------------------------------------------|----------------------------------------------------|
| `created` | 1 | Análise recém-aberta | Preencher os dados cadastrais |
| `pending_registry_data` | 1 | Aguardando dados e documentos para o envio inicial | **Completar e enviar o `submit`** |
| `sent_to_analysis` | 2 | Em processamento | Aguardar |
| `in_manual_analysis` | 3 | Em revisão por um analista *(etapa condicional)* | Aguardar |
| `in_compliance_analysis` | 4 | Em revisão de compliance *(etapa condicional)* | Aguardar — **ou responder o feedback**, se algum for aberto |
| `automatically_approved` | 5 | Aprovada sem intervenção humana | Aguardar a geração dos documentos |
| `manually_approved` | 5 | Aprovada por um analista | Aguardar a geração dos documentos |
| `pending_documents` | 5 | Documentos gerados, aguardando assinatura | Depende da configuração da sua conta |
| `automatically_reproved` | — | Recusada automaticamente pela análise de compliance | **Abrir nova análise cadastral** |
| `manually_reproved` | — | Recusada por um analista, com parecer | **Abrir nova análise cadastral** com as correções |
| `analysis_complete` | 6 | Cadastro concluído — o investidor está apto a operar | Nenhuma |
| `expired` | — | Cadastro vencido (2 anos após a conclusão) | Abrir nova análise para renovação |
:::info `pending_registry_data` não é status de retorno
Ele aparece **uma única vez**, no preenchimento inicial, antes do primeiro `submit`. Nenhuma etapa posterior devolve a análise para esse status — em particular, a abertura de um feedback não o faz.
:::
---
### Webhooks {#webhooks}
O acompanhamento por webhook é a forma recomendada de seguir a análise — a alternativa é consultar periodicamente **Busca informações do investidor**, o que não escala.
:::info Configuração
Os webhooks são configurados **internamente pela QI Tech**, por integração. Não há endpoint público de cadastro. Informe ao seu contato técnico a URL que deve receber as notificações e quais eventos deseja assinar.
:::
#### Eventos disponíveis
| Evento | Quando dispara |
|-------------------------------------------------------|----------------------------------------------------------------------------------|
| `investor_registry.investor_analysis_result` | Resultado da análise automática — saída de `sent_to_analysis` para `automatically_approved`, `in_manual_analysis` ou `automatically_reproved` |
| `investor_registry.investor_analysis_status_change` | Qualquer outra mudança de status da análise, incluindo as decisões manuais (`manually_approved`, `manually_reproved`) e a entrada em `pending_documents` |
| `investor_registry.feedback_status_change` | **Abertura e encerramento de feedback** — ver **[Webhooks de feedback](#webhooks-feedback)** |
| `investor_registry.document_batch_status_change` | A cada mudança de status do lote de documentos para assinatura |
#### Formato do evento — análise
Eventos de análise carregam a chave da análise e o novo status:
```json title='Webhook Body — análise'
{
"webhook_type": "investor_registry.investor_analysis_status_change",
"webhook_datetime": "2026-07-31T21:47:46Z",
"data": {
"investor_analysis_key": "UUID",
"status": "in_compliance_analysis"
}
}
```
#### Webhooks de feedback {#webhooks-feedback}
O `investor_registry.feedback_status_change` é o **único** aviso de que um feedback foi aberto ou encerrado. Como a análise permanece em `in_compliance_analysis` durante todo o ciclo do feedback, nenhum evento de análise é disparado junto — quem não assinar este evento não fica sabendo do pedido.
O mesmo `webhook_type` cobre as duas pontas do ciclo, diferenciadas pelo campo `status`:
| `status` | Quando dispara | Ação esperada de você |
|----------|---------------------------------------------------------------------|-----------------------------------------------------------|
| `open` | A compliance abriu um feedback com um pedido de esclarecimento | Ler o pedido e **responder** com [Enviar Mensagem em Feedback](./feedback/enviar_mensagem_feedback) |
| `closed` | O feedback foi encerrado pela sua resposta | Nenhuma — é a confirmação de que o pedido foi resolvido |
**Abertura do feedback:**
```json title='Webhook Body — feedback aberto'
{
"webhook_type": "investor_registry.feedback_status_change",
"webhook_datetime": "2026-07-31T21:47:46Z",
"data": {
"investor_analysis_key": "UUID",
"feedback_key": "UUID",
"status": "open",
"origin_type": "investor_analysis",
"origin_key": "UUID"
}
}
```
**Encerramento do feedback**, disparado logo após a sua mensagem:
```json title='Webhook Body — feedback encerrado'
{
"webhook_type": "investor_registry.feedback_status_change",
"webhook_datetime": "2026-07-31T22:12:03Z",
"data": {
"investor_analysis_key": "UUID",
"feedback_key": "UUID",
"status": "closed",
"origin_type": "investor_analysis",
"origin_key": "UUID"
}
}
```
| Campo | Tipo | Descrição |
|-------------------------|--------|--------------------------------------------------------------------------------------|
| `investor_analysis_key` | string | Análise cadastral à qual o feedback pertence |
| `feedback_key` | string | Identificador do feedback |
| `status` | string | `open` ou `closed` — enumerador de **[Feedback Status](./feedback/listar_feedbacks#feedback-status)** |
| `origin_type` | string | Enumerador de **[Origin Type](./feedback/listar_feedbacks#origin-type)** — `investor_analysis` ou `related_party_analysis` |
| `origin_key` | string | Chave da entidade de origem: a `investor_analysis_key` ou a `external_related_party_key` |
O evento carrega apenas as chaves e o novo status — **não traz o texto do pedido**. Ao receber um `open`, chame [Listar Feedbacks](./feedback/listar_feedbacks) com o `origin_type` e o `origin_key` do evento para ler a `description` e o histórico de `messages`.
:::tip Os eventos que exigem ação sua
Assine, no mínimo, `investor_analysis_result`, `investor_analysis_status_change` e `feedback_status_change`. Juntos, eles cobrem as três situações da seção **[Quando o cadastro precisa da sua ação](#quando-agir)**: a recusa automática chega no primeiro; a recusa manual e a ida para assinatura, no segundo; o pedido de esclarecimento, no terceiro — e **só** no terceiro.
:::
---
# Consultar Análise em Andamento
URL: /documentation/iaas/investidor/compartilhado/consultar_analise_em_andamento
---
### Introdução
Este recurso retorna a **análise cadastral em andamento** (não finalizada) associada a um investidor. Útil para retomar um cadastro em progresso sem precisar conhecer a `investor_analysis_key`.
Considera-se "em andamento" qualquer análise cujo status ainda não tenha sido finalizado (criada, pendente de dados/documentos, enviada para análise, em análise manual).
### Request
ENDPOINT `/investor_registry/investor/{investor_key}/in_progress_investor_analysis`
MÉTODO `GET`
STATUS `200`
### Response
A análise cadastral em andamento é retornada no corpo da resposta. Para o formato completo, consulte **Busca informações de uma análise cadastral do investidor**.
---
# Atualizar Status da Conta Bancária
URL: /documentation/iaas/investidor/compartilhado/contas_bancarias/atualizar_status_conta_bancaria
---
### Introdução
Este recurso altera o status de uma conta bancária previamente cadastrada em uma análise cadastral — por exemplo, para inativar uma conta que não deve mais ser utilizada.
A conta é identificada pela sua chave externa (`external_bank_account_key`), retornada na criação.
### Request
ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/bank_account/{external_bank_account_key}/status`
MÉTODO `PUT`
STATUS `202`
### Request body
```json title='Request Body'
{
"status": "inactive"
}
```
### Body params
| Campo | Tipo | Descrição | Obrigatório |
|----------|--------|---------------------------------------------------------------|-------------|
| `status` | string | Novo status da conta. Valores típicos: `active`, `inactive` | Sim |
### Response
`202 Accepted`. A representação atualizada da conta é retornada no corpo.
---
# Definir Conta Bancária Principal
URL: /documentation/iaas/investidor/compartilhado/contas_bancarias/definir_conta_principal
---
### Introdução
Este recurso define (ou remove) uma conta bancária como **conta principal** do investidor dentro de uma análise cadastral. Apenas **uma** conta pode estar marcada como principal por vez — ao marcar uma como principal, a conta anteriormente principal é automaticamente desmarcada.
### Request
ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/bank_account/{external_bank_account_key}/default`
MÉTODO `PUT`
STATUS `202`
### Request body
```json title='Request Body'
{
"value": true
}
```
### Body params
| Campo | Tipo | Descrição | Obrigatório |
|---------|---------|-------------------------------------------------|-------------|
| `value` | boolean | `true` para definir esta conta como principal | Sim |
### Response
`202 Accepted`. A representação atualizada da conta é retornada no corpo.
---
# Enviar Conta Bancária do Investidor
URL: /documentation/iaas/investidor/compartilhado/contas_bancarias/enviar_contas_bancarias
---
### Introdução
Este recurso cadastra uma conta bancária para o investidor dentro de uma análise cadastral. **Cada conta deve ser enviada em uma requisição independente** — para cadastrar mais de uma conta, chame o endpoint múltiplas vezes.
### Input / Output
Como ***input*** envie os dados de uma conta bancária.
Como ***output*** serão retornadas as chaves da conta criada — `bank_account_key` e `external_bank_account_key` — e o seu `status`.
### Request
ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/bank_account`
MÉTODO `POST`
STATUS `201`
### Request body
Exemplo: conta principal individual
```json title='Request Body'
{
"financial_institution_code": "341",
"account_number": "12345678",
"account_digit": "9",
"account_branch": "0001",
"main_account": true
}
```
Exemplo: conta conjunta
```json title='Request Body'
{
"financial_institution_code": "341",
"account_number": "12345678",
"account_digit": "9",
"account_branch": "0001",
"shared_account_owners": [
{
"name": "Maria Silva",
"document_number": "068.045.160-95"
}
]
}
```
### Body params
| Campo | Tipo | Descrição | Caracteres | Obrigatório |
|------------------------------|---------|---------------------------------------------------------------------------------|------------|-------------|
| `financial_institution_code` | string | Código da instituição financeira (compe / ISPB curto) | 1 - 4 | Sim |
| `account_number` | string | Número da conta bancária (apenas dígitos) | 1 - 20 | Sim |
| `account_digit` | string | Dígito verificador da conta | 1 | Sim |
| `account_branch` | string | Número da agência (4 dígitos) | 4 | Sim |
| `main_account` | boolean | Indica se é a conta principal do investidor | - | Não |
| `shared_account_owners` | array | Lista de objetos de **[Shared Account Owner](#shared-account-owners)** | - | Não |
:::info
Apenas uma conta pode ser marcada como `main_account: true`. Se nenhuma conta for marcada como principal, a primeira cadastrada é assumida como principal.
:::
### Shared Account Owners {#shared-account-owners}
| Campo | Tipo | Descrição | Caracteres | Obrigatório |
|-------------------|--------|----------------------------------------------------------------------------|------------|-------------|
| `name` | string | Nome do co-titular da conta | - | Sim |
| `document_number` | string | CPF do co-titular (`XXX.XXX.XXX-XX`) | 14 | Sim |
### Response
```json title='Response Body'
{
"bank_account_key": "UUID",
"external_bank_account_key": "UUID",
"status": "active"
}
```
| Campo | Tipo | Descrição |
|-----------------------------|--------|----------------------------------------------------------------------------------------------|
| `bank_account_key` | string | Identificador interno da conta bancária criada |
| `external_bank_account_key` | string | Chave usada nas **rotas de manutenção** da conta: atualizar dados, atualizar status e definir conta principal |
| `status` | string | Status da conta na criação — sempre `active` |
---
# Criar investidor
URL: /documentation/iaas/investidor/compartilhado/criar_investidor
---
### Introdução
Este recurso tem como objetivo nos informar dados básicos para iniciar o cadastro de um **investidor**.
A criação de um investidor já dispara, em conjunto, a abertura de uma primeira **análise cadastral** vinculada a ele. Por isso, ao final desta chamada são retornadas duas chaves: ***investor_key*** (identifica o investidor) e ***investor_analysis_key*** (identifica a análise cadastral em andamento).
Os tipos de investidor são definidos pelo campo **`person_type`**: **pessoa física** (`natural_person`), **pessoa jurídica** (`legal_person`) e **por conta e ordem** (`nominee`). O campo **`investor_sub_type`** distingue subtipos como **fundo de investimento** (`fund_class`), que possuem regras próprias ao longo do fluxo de cadastro.
:::info Regra de aprovação em Homologação
No ambiente de Homologação, temos a seguinte regra para aprovações: CPF/CNPJ com início **1**: reprovação automática; CPF/CNPJ com início **8**: pendente de validação manual; o restante é aprovado automaticamente.
Essa regra é **exclusiva do ambiente de Homologação**. Em Produção não há qualquer comportamento equivalente: toda análise passa pelo fluxo real de compliance.
:::
### Input / Output
Como ***input*** envie os dados básicos do investidor. Os campos obrigatórios variam de acordo com **`person_type`** e **`investor_sub_type`**.
Como ***output*** serão retornadas a ***investor_key*** e a ***investor_analysis_key***. A ***investor_key*** identifica o investidor; a ***investor_analysis_key*** identifica a análise cadastral aberta junto com a criação. Um mesmo investidor pode possuir mais de uma análise cadastral ao longo do tempo (renovações, atualizações).
### Request
ENDPOINT `/investor_registry/investor`
MÉTODO `POST`
STATUS `201`
### Request body
Caso 01: Pessoa Física
```json title='Request Body'
{
"name": "João da Silva",
"document_number": "123.456.789-00",
"person_type": "natural_person",
"email": "joao.silva@example.com",
"phone": {
"international_dial_code": "55",
"area_code": "11",
"number": "987654321"
}
}
```
Caso 02: Pessoa Jurídica
```json title='Request Body'
{
"name": "Empresa XPTO Ltda",
"document_number": "12.345.678/0001-90",
"person_type": "legal_person",
"investor_sub_type": "default",
"registry_user": {
"name": "José da Silva",
"document_number": "123.456.789-00",
"email": "jose.silva@example.com",
"phone": {
"international_dial_code": "55",
"area_code": "11",
"number": "987654321"
}
}
}
```
:::warning Campos obrigatórios por `person_type`
Os campos obrigatórios mudam de acordo com o **`person_type`**. A ausência de qualquer um deles é recusada com `IVR000009`, cuja mensagem lista a relação completa exigida.
- **`natural_person`**: `name`, `document_number`, `person_type`, **`investor_sub_type`**
- **`legal_person`**: `name`, `document_number`, `person_type`, **`investor_sub_type`**
- **`nominee`**: `name`, `person_type`, `external_distribution_key`
**`investor_sub_type` é obrigatório também para pessoa física** — envie `default` quando não houver subtipo específico. `email` e `phone` são opcionais para um distribuidor, mas recomendados: sem `email`, nenhum usuário de acesso é criado para o investidor.
:::
:::info Sobre o `registry_user`
O **`registry_user`** representa o usuário (pessoa física) responsável por preencher os dados cadastrais do investidor. Para **pessoa física**, normalmente este usuário é o próprio investidor e o campo pode ser omitido. Para **pessoa jurídica**, é o representante que responderá pelo preenchimento.
Quando enviado, o objeto exige `name`, `document_number` e `email`. Se omitido em pessoa física, o usuário é derivado do `email` do próprio investidor — e, se o investidor também não tiver `email`, nenhum usuário é criado.
:::
:::warning `investor_owner_type` não é aceito de distribuidores
O campo `investor_owner_type` existe no schema, mas é **recusado** quando o investidor é criado por uma integração de distribuidor com `person_type` `natural_person` ou `legal_person`. Vínculos de carteira administrada e de fundo são estabelecidos pelo endpoint **Criar Investor Owner**, dentro da análise cadastral.
:::
### Investidor não residente {#nao-residente}
A residência é definida **na criação do investidor** e é imutável depois disso. Ela é controlada pelo campo `resident`.
```json title='Request Body — pessoa física não residente'
{
"name": "Maria Fernandes",
"document_number": "123.456.789-00",
"person_type": "natural_person",
"investor_sub_type": "default",
"resident": false,
"non_resident_type": "third_party_representation",
"investor_owners": [
{
"type": "non_resident_representative",
"name": "Representante Legal Brasil Ltda",
"document_number": "12.345.678/0001-90"
}
]
}
```
| Campo | Tipo | Descrição | Obrigatório |
|----------------------|---------|-----------------------------------------------------------------------------------------------------|-------------|
| `resident` | boolean | Define a residência da análise cadastral. Default `true` | Não |
| `non_resident_type` | string | `self_representation` ou `third_party_representation`. Obrigatório quando `resident: false` (`IVR000222`) | Condicional |
| `investor_owners` | array | Representante legal residente no Brasil, com `type: "non_resident_representative"` | Não |
#### Tipos de representação {#non-resident-type}
`non_resident_type` declara **como o investidor não residente é representado no Brasil**. É essa escolha que determina quais entidades você precisa cadastrar e quais documentos serão exigidos no envio para análise.
| Enumerador | Tipo de conta | Significado |
|------------------------------|--------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
| `third_party_representation` | Conta **4373** | O INR opera por meio de terceiros: existe um **custodiante**, responsável pela guarda dos ativos, e um **representante legal brasileiro**, responsável por representá-lo no país. Na prática, costumam ser a mesma entidade. |
| `self_representation` | Conta **CNR** (autocustódia / representação tributária) | O investidor é seu próprio custodiante e representante. **Não** existe custodiante nem representante terceiro. |
O que muda entre os dois:
| | `third_party_representation` | `self_representation` |
|------------------------------|-----------------------------------------------------------------------------------------------|--------------------------------|
| **Custodiante** | Parte relacionada do tipo `asset_custodian` | Não existe |
| **Representante** | Investor owner do tipo `non_resident_representative` — sempre **residente**, com CPF/CNPJ | Não existe |
| **Documentos de representação** | `custody_contract` (no custodiante) **e** `representation_contract` (no representante) — **ou** uma única `simplified_declaration` na análise | Nenhum |
:::warning Como a exigência documental é verificada
Em `third_party_representation`, o `custody_contract` só é reconhecido quando enviado em uma parte relacionada **ativa** do tipo `asset_custodian`, e o `representation_contract` só é reconhecido quando enviado em um investor owner **ativo** do tipo `non_resident_representative`. Enviar os dois contratos como documentos da análise cadastral não satisfaz a regra.
Se a combinação não for encontrada no `submit`, a resposta é `IVR000029`.
:::
Regras que valem para **os dois** tipos:
- `nif_number` é **obrigatório** no envio dos dados cadastrais (`IVR000224`);
- parte relacionada estrangeira sem CPF/CNPJ precisa de `passport` ou `foreign_id`;
- pessoa física nascida no Brasil (`natural_person.place_of_birth.country: "BRA"`) precisa de `final_departure_tax_return`.
:::info `non_resident_type` é imutável
O valor é fixado na criação do investidor. Você pode reenviá-lo nos dados cadastrais, mas apenas com o **mesmo** valor — divergência, ou envio em um cadastro residente, resulta em `IVR000225`.
:::
:::warning Residência e endereço precisam concordar
Com `resident: true` (default), o endereço enviado na etapa de endereço precisa ter `country: "BRA"`, senão `IVR000227`. Com `resident: false`, o `country` **não** pode ser `BRA`, senão `IVR000226`.
:::
### Body params
| Campo | Tipo | Descrição | Caracteres | Obrigatório |
|-----------------------------|----------|---------------------------------------------------------------------------------------------|--------------|-------------|
| `name` | string | Nome (ou razão social) do investidor | 1 - 255 | Sim |
| `person_type` | string | Enumerador de **[Person Type](#person-type)** | - | Sim |
| `investor_sub_type` | string | Enumerador de **[Investor Sub Type](#investor-sub-type)**. Exigido para `natural_person` e `legal_person` | - | Sim |
| `document_number` | string | CPF (`XXX.XXX.XXX-XX`) ou CNPJ (`XX.XXX.XXX/XXXX-XX`). Não exigido para `nominee` | 14 ou 18 | Sim* |
| `external_distribution_key` | string | Chave da distribuição externa. Exigido apenas para `nominee` | 1 - 100 | Sim* |
| `resident` | boolean | Residência da análise cadastral. Default `true`. Veja [Investidor não residente](#nao-residente) | - | Não |
| `non_resident_type` | string | `self_representation` ou `third_party_representation`. Exigido quando `resident: false` | - | Condicional |
| `investor_owners` | array | Representante legal residente, para investidor não residente | - | Não |
| `email` | string | E-mail do investidor | 1 - 255 | Não |
| `phone` | object | Objeto de **[Phone](#phone)** | - | Não |
| `registry_user` | object | Objeto de **[Registry User](#registry-user)** | - | Não |
| `external_id` | string | Identificador do investidor no seu sistema | 1 - 50 | Não |
### Phone
| Campo | Tipo | Descrição | Caracteres | Obrigatório |
|-----------------------------|----------|---------------------------------------------------------------------------------------------|--------------|-------------|
| `international_dial_code` | string | Código internacional (ex.: `55`) | 1 - 3 | Sim |
| `area_code` | string | DDD | 2 | Sim |
| `number` | string | Número do telefone | 8 - 9 | Sim |
### Registry User
| Campo | Tipo | Descrição | Caracteres | Obrigatório |
|---------------------|----------|------------------------------------------------------|--------------|-------------|
| `name` | string | Nome do usuário cadastrador | 1 - 255 | Sim |
| `document_number` | string | CPF do usuário (formato `XXX.XXX.XXX-XX`) | 14 | Sim |
| `email` | string | E-mail do usuário | 1 - 255 | Sim |
| `phone` | object | Objeto de **[Phone](#phone)** | - | Sim |
### Person Type {#person-type}
| Enumerador | Descrição |
|---------------------|------------------------------------------------------|
| `natural_person` | Pessoa física |
| `legal_person` | Pessoa jurídica |
| `nominee` | Por conta e ordem (PCO) |
:::info Cadastro `nominee` (PCO)
O fluxo por conta e ordem precisa ser previamente habilitado e acordado para uso em Produção. Fale com seu contato comercial antes de planejar a integração desse caso.
:::
### Investor Sub Type {#investor-sub-type}
| Enumerador | Descrição |
|--------------------------|--------------------------------------------------------------------------------------------|
| `default` | Investidor regular, pessoa física ou jurídica |
| `fund_class` | Fundo de investimento. Possui regras próprias de partes relacionadas, documentos e investor owners |
| `financial_institution` | Instituição financeira. Segue as mesmas regras de `default` |
| `non_resident` | Subtipo de classificação. **Não** define a residência da análise — para isso use `resident` |
### Response
```json title='Response Body'
{
"investor_key": "UUID",
"investor_analysis_key": "UUID"
}
```
---
# Definir Grupo de Assinantes Padrão
URL: /documentation/iaas/investidor/compartilhado/definir_grupo_assinantes_padrao
---
### Introdução
Este recurso define (ou remove) um grupo de assinantes como **grupo padrão** da análise cadastral. Apenas **um** grupo pode estar marcado como padrão por vez — ao marcar um grupo como padrão, o grupo anteriormente padrão é automaticamente desmarcado.
O grupo padrão é o utilizado por default na geração dos documentos para assinatura, caso a análise seja submetida sem informar explicitamente um `external_signer_group_key`.
### Request
ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/signer_group/{external_signer_group_key}/default`
MÉTODO `PUT`
STATUS `202`
### Request body
```json title='Request Body'
{
"value": true
}
```
### Body params
| Campo | Tipo | Descrição | Obrigatório |
|---------|---------|--------------------------------------------|-------------|
| `value` | boolean | `true` para definir este grupo como padrão | Sim |
### Response
`202 Accepted`. A representação atualizada do grupo é retornada no corpo.
---
# Enviar Cadastro do Investidor para Análise
URL: /documentation/iaas/investidor/compartilhado/enviar_cadastro_para_analise
---
### Introdução
Este recurso submete a **análise cadastral** preenchida para validação. A partir desse momento, os dados são enviados aos serviços de compliance e os documentos são gerados para assinatura.
:::warning Atenção
A **análise cadastral** ocorre de forma assíncrona. Recomendamos integrar com os **webhooks** de mudança de status para acompanhar a evolução — veja **[Ciclo de vida da análise cadastral](./ciclo_de_vida_da_analise)**.
:::
### Pré-requisitos {#pre-requisitos}
O `submit` só é aceito quando a análise já reúne todos os dados abaixo. Estes são os erros mais comuns nesta etapa, e a validação é feita **em sequência** — cada recusa pode estar escondendo a próxima pendência, então vale conferir a lista inteira antes de reenviar.
#### 1. Blocos de dados obrigatórios
Faltando qualquer um, a recusa é `IVR000150`, cuja mensagem lista exatamente as chaves ausentes.
| Investidor | Blocos exigidos |
|-----------------------------------------|---------------------------------------------------------------|
| `natural_person` | `natural_person`, `address`, `net_worth`, **`suitability`** |
| `legal_person` (`default`, `financial_institution`) | `legal_person`, `address`, `net_worth` |
| `legal_person` / `fund_class` | **Nenhum** — ver abaixo |
:::info Classes de fundo não têm blocos obrigatórios
Para `legal_person` / `fund_class`, os dados cadastrais, o endereço e o patrimônio são preenchidos automaticamente a partir da base pública da CVM no próprio `submit`. Suitability, grupos de assinantes e documentos do investidor também **não** são exigidos.
A única exigência condicional é a de **partes relacionadas**, e apenas quando a classe é **exclusiva** na CVM — ver o item 3 abaixo. Se o CNPJ não constar na base da CVM, o enriquecimento não acontece e o `submit` é recusado com `IVR000068`.
:::
#### 2. Suitability
- **Pessoa física**: sempre obrigatória. Sem ela, `IVR000150` acusa a chave `suitability` faltante
- **Pessoa jurídica `retail`**: obrigatória — a ausência é recusada com `IVR000133`
- **Pessoa jurídica `qualified` ou `professional`**: opcional
- **Classe de fundo (`fund_class`)**: não se aplica — a etapa é pulada
#### 3. Partes relacionadas e participação societária
Quantidade mínima, exigência de representante legal e percentual somado variam por tipo de investidor. A tabela completa está em **[Criar Parte Relacionada — Exigências por tipo de investidor](./related_party/criar_parte_relacionada#exigencias)**.
#### 4. Documentos
A matriz de documentos obrigatórios é validada aqui, e não no upload — ver a seção **Documentos Obrigatórios** na página **Enviar Documento do Investidor**. As recusas são `IVR000029` (documentos do investidor) e `IVR000030` (documentos de parte relacionada), ambas devolvendo na mensagem a matriz de opções aceitas.
Para `fund_class` **não há matriz de documentos do investidor**. Só podem ser cobrados documentos de **parte relacionada**, e apenas em classe exclusiva.
#### 5. Investor owners (apenas `fund_class`)
Uma classe de fundo precisa de um **administrador** e uma **gestora** ativos. Eles são criados **automaticamente** a partir dos dados da CVM no `submit`; o endpoint **Criar Investor Owner** cobre os vínculos adicionais. A ausência é recusada com `IVR000164` (administrador) ou `IVR000163` (gestora).
#### 6. Classe em funcionamento (apenas `fund_class`)
Somente classes **operacionais** na CVM são aceitas. Classes pré-operacionais, encerradas, canceladas ou incorporadas são recusadas na análise.
### Input / Output
O corpo é **opcional** — pode ser enviado vazio (`null` ou `{}`). Quando enviado, permite informar o método de assinatura e o grupo de assinantes que deverá ser utilizado para os documentos gerados.
Como ***output*** será retornada a representação atualizada da análise cadastral.
### Request
ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/submit`
MÉTODO `PUT`
STATUS `202`
### Request body
O corpo pode ser enviado vazio (`{}`) — neste caso a API utiliza o método de assinatura e o grupo de assinantes padrão da análise. Para sobrescrever esses valores, envie os campos opcionais abaixo.
```json title='Request Body'
{
"signature_method": "certifiqi",
"external_signer_group_key": "3f8a5a3e-1f0a-4d9b-8a6e-9b4c0e7d8f12"
}
```
### Body params
| Campo | Tipo | Descrição | Obrigatório |
|-----------------------------|--------|------------------------------------------------------------------------|-------------|
| `signature_method` | string | Enumerador de **[Signature Method](#signature-method)** | Não |
| `external_signer_group_key` | string | Chave externa do grupo de assinantes a ser utilizado para esta análise | Não |
### Signature Method {#signature-method}
Os únicos valores que uma integração pode informar são:
| Enumerador | Descrição |
|---------------------|----------------------------------------------------------------|
| `certifiqi` | Assinatura eletrônica via CertifiQI |
| `qi_sign.liveness` | Assinatura eletrônica com prova de vida |
:::info `opt_in` não é selecionável pela integração
`opt_in` é uma **configuração do distribuidor**, definida pela QI Tech na sua conta, e não um valor a ser enviado neste corpo. Se a sua conta estiver configurada como `opt_in`, o fluxo de assinatura é resolvido automaticamente e não é necessário informar `signature_method`.
:::
### Response
A análise cadastral atualizada é retornada no corpo da resposta.
---
# Enviar Dados Cadastrais do Investidor
URL: /documentation/iaas/investidor/compartilhado/enviar_dados_cadastrais
---
### Introdução
Este recurso tem como objetivo enviar os dados cadastrais específicos da pessoa que compõe a **análise cadastral** de um investidor.
O corpo enviado deve conter **um** dos blocos `natural_person` ou `legal_person`, coerente com o `person_type` informado na criação do investidor.
### Input / Output
Como ***input*** envie os dados cadastrais específicos do tipo de investidor.
Como ***output*** será retornada a representação atualizada da análise cadastral. As chaves ***investor_key*** e ***investor_analysis_key*** identificam o investidor e a análise atualizada.
:::info Investidor `fund_class`
Para classes de fundo (`investor_sub_type: "fund_class"`), esta etapa é **obrigatória** — envie o bloco `legal_person` com os dados de contato e, quando aplicável, o `giin_number`.
Razão social, data de constituição e patrimônio **não precisam ser enviados**: são preenchidos automaticamente a partir da base da CVM ao enviar a análise para validação.
:::
### Request
ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/registry_data`
MÉTODO `PUT`
STATUS `202`
### Request body
Exemplo: Pessoa Física
```json title='Request Body'
{
"name": "João da Silva",
"email": "joao.silva@example.com",
"phone": {
"international_dial_code": "55",
"area_code": "11",
"number": "987654321"
},
"natural_person": {
"birthdate": "1990-05-15",
"gender": "male",
"mother_name": "Maria da Silva",
"nationality": "BRA",
"place_of_birth": {
"country": "BRA",
"uf": "SP",
"city": "São Paulo"
},
"marital_status": "single",
"spouse": {
"name": "Maria Santos",
"document_number": "123.456.789-00"
},
"profession": "Engenheiro",
"occupation": "Engenheiro de Software",
"occupation_company": {
"name": "Empresa XYZ Ltda",
"document_number": "12.345.678/0001-90"
}
}
}
```
Exemplo: Pessoa Jurídica
```json title='Request Body'
{
"name": "Empresa XPTO Ltda",
"email": "contato@empresaxpto.com.br",
"phone": {
"international_dial_code": "55",
"area_code": "11",
"number": "1234567890"
},
"legal_person": {
"legal_name": "Empresa XPTO Limitada",
"constitution_date": "2020-01-15"
}
}
```
Exemplo: Pessoa Jurídica (`fund_class`)
```json title='Request Body'
{
"name": "Empresa XPTO Ltda",
"email": "contato@empresaxpto.com.br",
"phone": {
"international_dial_code": "55",
"area_code": "11",
"number": "1234567890"
},
"legal_person": {
"giin_number": "XXXXXX.XXXXX.XX.XXX",
}
}
```
### Body params
| Campo | Tipo | Descrição | Caracteres | Obrigatório |
|-------------------|----------|--------------------------------------------------------------------------------------|------------|-------------|
| `name` | string | Nome (ou razão social) do investidor | 1 - 255 | Não |
| `email` | string | E-mail de contato | 1 - 255 | Não |
| `phone` | object | Objeto de **[Phone](#phone)** | - | Não |
| `natural_person` | object | Objeto de **[Natural Person](#natural-person)** — obrigatório para pessoa física | - | Sim* |
| `legal_person` | object | Objeto de **[Legal Person](#legal-person)** — obrigatório para pessoa jurídica | - | Sim* |
\* É obrigatório enviar **exatamente um** entre `natural_person` ou `legal_person`, de acordo com o `person_type` do investidor.
### Natural Person {#natural-person}
| Campo | Tipo | Descrição | Caracteres | Obrigatório |
|------------------------|--------|-----------------------------------------------------------------|------------|-------------|
| `birthdate` | string | Data de nascimento (`YYYY-MM-DD`) | 10 | Sim |
| `mother_name` | string | Nome completo da mãe | 1 - 255 | Sim |
| `nationality` | string | Nacionalidade — código ISO de 3 letras (ex.: `BRA`) | 3 | Sim |
| `place_of_birth` | object | Objeto de **[Place of Birth](#place-of-birth)** | - | Sim |
| `marital_status` | string | Enumerador de **[Marital Status](#marital-status)** | - | Sim |
| `profession` | string | Profissão | 1 - 255 | Sim |
| `occupation` | string | Ocupação | 1 - 255 | Sim |
| `gender` | string | Enumerador de **[Gender](#gender)** | - | Não |
| `spouse` | object | Objeto de **[Spouse](#spouse)** | - | Não |
| `occupation_company` | object | Objeto de **[Occupation Company](#occupation-company)** | - | Não |
### Gender {#gender}
| Enumerador | Descrição |
|------------|--------------|
| `male` | Masculino |
| `female` | Feminino |
### Marital Status {#marital-status}
| Enumerador | Descrição |
|---------------------------------------------|-------------------------------------------------|
| `single` | Solteiro(a) |
| `married` | Casado(a) |
| `civil_union` | União estável |
| `divorced` | Divorciado(a) |
| `widowed` | Viúvo(a) |
| `married_with_partial_community_property` | Casado(a) em comunhão parcial de bens |
### Place of Birth {#place-of-birth}
| Campo | Tipo | Descrição | Caracteres | Obrigatório |
|-----------|--------|----------------------------------------------------|------------|-------------|
| `country` | string | Código ISO do país (3 letras, ex.: `BRA`) | 3 | Não |
| `uf` | string | Estado (UF) | - | Não |
| `city` | string | Cidade | - | Não |
### Spouse {#spouse}
| Campo | Tipo | Descrição | Caracteres | Obrigatório |
|-------------------|--------|----------------------------------------------------------------------|------------|-------------|
| `name` | string | Nome completo do cônjuge | 1 - 255 | Sim |
| `document_number` | string | CPF do cônjuge (`XXX.XXX.XXX-XX`) | 14 | Sim |
### Occupation Company {#occupation-company}
| Campo | Tipo | Descrição | Caracteres | Obrigatório |
|-------------------|--------|------------------------------------------------------------|------------|-------------|
| `name` | string | Nome da empresa | 1 - 255 | Sim |
| `document_number` | string | CNPJ da empresa (`XX.XXX.XXX/XXXX-XX`) | 18 | Sim |
### Legal Person {#legal-person}
| Campo | Tipo | Descrição | Caracteres | Obrigatório |
|---------------------|--------|--------------------------------------------------------------------------|------------|-------------|
| `legal_name` | string | Razão social da empresa | 1 - 255 | Não |
| `constitution_date` | string | Data de constituição (`YYYY-MM-DD`) | 10 | Não |
| `giin_number` | string | GIIN (`Global Intermediary Identification Number`), quando aplicável | 1 - 20 | Não |
### Phone {#phone}
| Campo | Tipo | Descrição | Caracteres | Obrigatório |
|---------------------------|--------|------------------------|------------|-------------|
| `international_dial_code` | string | Código internacional | 1 - 3 | Sim |
| `area_code` | string | DDD | 2 | Sim |
| `number` | string | Número de telefone | 8 - 9 | Sim |
### Response
A análise cadastral atualizada é retornada no corpo da resposta. Para o formato completo, consulte **Busca informações de uma análise cadastral do investidor**.
---
---
# Enviar Documento Assinado
URL: /documentation/iaas/investidor/compartilhado/enviar_documento_assinado
---
### Introdução
Este recurso faz o **upload do arquivo assinado** de um documento gerado para a formalização do cadastro do investidor, dentro de um `document_batch`. Os tipos suportados são: ficha cadastral (pessoa física ou jurídica), termo de investidor qualificado e termo de investidor profissional.
Utilize este recurso quando o distribuidor é responsável por gerar e assinar o documento externamente (configuração `document_generation: external`) e precisa enviar o arquivo PDF/imagem final ao QI Tech. Para confirmar uma assinatura via *opt-in*, utilize **[Assinar Documento](/documentation/iaas/investidor/compartilhado/assinar_documento)**.
:::warning Atenção
Este recurso está disponível apenas para integrações que atuam como **Distribuidor** com `document_generation` configurado como `external`. O documento deve estar com status `pending_external_upload`.
:::
### Input / Output
Como ***input*** envie o conteúdo do arquivo codificado em **base64**.
Como ***output***, quando o envio finaliza o lote, é retornada a chave `investor_document_key`.
### Request
ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/document_batch/{document_batch_key}/document/{investor_document_key}/signed_document`
MÉTODO `POST`
STATUS `201`
### Request body
```json title='Request Body'
{
"document_b64": "base64_encoded_document_content"
}
```
### Body params
| Campo | Tipo | Descrição | Obrigatório |
|----------------|--------|--------------------------------------------------------|-------------|
| `document_b64` | string | Conteúdo do arquivo assinado codificado em **base64** | Sim |
### Response
```json title='Response Body'
{
"investor_document_key": "UUID"
}
```
---
# Enviar Endereço do Investidor
URL: /documentation/iaas/investidor/compartilhado/enviar_endereco
---
### Introdução
Este recurso tem como objetivo enviar o endereço que compõe a **análise cadastral** de um investidor.
:::info Classe de fundo (`fund_class`) — etapa pulada
Classes de fundo **não enviam endereço**. O endereço é herdado automaticamente do **administrador** vinculado à classe durante o envio para análise, e o `submit` não exige o bloco `address` para esse subtipo. Pule esta etapa.
:::
### Input / Output
Como ***input*** envie os dados de endereço.
Como ***output*** será retornada a representação atualizada da análise cadastral.
### Request
ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/address`
MÉTODO `PUT`
STATUS `202`
Exemplo
```json title='Request Body'
{
"street": "Avenida Paulista",
"number": "1000",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"postal_code": "01310-100",
"uf": "SP",
"country": "BRA",
"complement": "Sala 1010"
}
```
### Body params
| Campo | Tipo | Descrição | Caracteres | Obrigatório |
|----------------|--------|------------------------------------------------------|------------|-------------|
| `street` | string | Logradouro | 1 - 255 | Sim |
| `number` | string | Número (somente dígitos) | 1 - 10 | Sim |
| `neighborhood` | string | Bairro | 1 - 255 | Sim |
| `city` | string | Cidade | 1 - 255 | Sim |
| `postal_code` | string | Código postal. No Brasil, CEP no formato `XXXXX-XXX`. No exterior, o formato local do país | 1 - 20 | Sim |
| `uf` | string | Unidade Federativa — ex.: `SP`, `CE`, `MG`. No exterior, use `EX` | 1 - 20 | Sim |
| `country` | string | Código ISO do país, 3 letras — ex.: `BRA`, `PRT` | 3 | Sim |
| `complement` | string | Complemento | 1 - 255 | Não |
### Endereço no exterior {#exterior}
`postal_code` e `uf` **não possuem validação de formato** — aceitam o padrão de qualquer país (até 20 caracteres cada). Um CEP português `1000-001` ou um ZIP norte-americano `10001` são aceitos como estão.
A única coerência exigida é entre a **residência da análise** e o `country`:
| `resident` da análise | `country` exigido | Erro se divergir |
|-----------------------|-------------------------|------------------|
| `true` (default) | obrigatoriamente `BRA` | `IVR000227` |
| `false` | qualquer um, exceto `BRA` | `IVR000226` |
:::warning Residência é definida na criação do investidor
`resident` **não** é um campo desta etapa e não pode ser alterado depois. Se você receber `IVR000227` ao enviar um endereço no exterior, a análise nasceu residente — é preciso criar o investidor com `resident: false` e `non_resident_type`, conforme a seção **Investidor não residente** da página **Criar Investidor**.
:::
### Response
A análise cadastral atualizada é retornada no corpo da resposta. Para o formato completo, consulte **Busca informações de uma análise cadastral do investidor**.
---
---
# Enviar Grupo de Assinantes
URL: /documentation/iaas/investidor/compartilhado/enviar_grupos_assinantes
---
### Introdução
Este recurso cadastra um **grupo de assinantes** que será responsável por assinar os documentos gerados na análise cadastral do investidor. **Cada grupo deve ser enviado em uma requisição independente** — para cadastrar mais de um grupo, chame o endpoint múltiplas vezes.
:::warning Atenção
Cada signatário enviado neste recurso será **validado contra os representantes legais** declarados em **[Criar Parte Relacionada](./related_party/criar_parte_relacionada.md)**. Portanto, todo `signer` deve **também** ser cadastrado previamente como parte relacionada com `legal_representative: true` (e, quando aplicável, `direct_beneficiary: true`). Signatários que não constarem entre os representantes legais da análise cadastral terão o cadastro recusado.
:::
:::info Classe de fundo (`fund_class`) — etapa pulada
Classes de fundo **não enviam grupos de assinantes**. A representação se dá pelos *investor owners* (administrador e gestora), e não por representantes legais — não há signatários a declarar. Pule esta etapa.
:::
### Input / Output
Como ***input*** envie a definição de um único grupo de assinantes.
Como ***output*** será retornada a representação do grupo criado.
### Request
ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/signer_group`
MÉTODO `POST`
STATUS `201`
### Request body
Exemplo
```json title='Request Body'
{
"is_default": true,
"minimum_required_signers": 2,
"expiration_date": "2025-12-31",
"signers": [
{
"name": "João Silva",
"document_number": "123.456.789-00",
"email": "joao.silva@example.com",
"is_required_signer": true
},
{
"name": "Maria Santos",
"document_number": "987.654.321-00",
"email": "maria.santos@example.com",
"is_required_signer": true
},
{
"name": "Pedro Oliveira",
"document_number": "456.789.123-00",
"email": "pedro.oliveira@example.com",
"is_required_signer": false
}
]
}
```
### Body params
| Campo | Tipo | Descrição | Obrigatório |
|-----------------------------|---------|--------------------------------------------------------------------------|-------------|
| `is_default` | boolean | Indica se este é o grupo padrão da análise | Sim |
| `minimum_required_signers` | number | Número mínimo de assinaturas necessárias (>= 1) | Sim |
| `signers` | array | Lista de objetos de **[Signers](#signers)** | Sim |
| `expiration_date` | string | Data de expiração do grupo (`YYYY-MM-DD`) | Não |
### Signers {#signers}
| Campo | Tipo | Descrição | Caracteres | Obrigatório |
|----------------------|---------|----------------------------------------------------------------------|------------|-------------|
| `name` | string | Nome do signatário | 1 - 255 | Sim |
| `document_number` | string | CPF ou CNPJ do signatário | 14 ou 18 | Sim |
| `email` | string | E-mail do signatário | - | Sim |
| `is_required_signer` | boolean | Indica se o signatário é obrigatório para considerar o grupo completo | - | Sim |
:::info Informação
- Apenas **um** grupo pode estar marcado como `is_default: true` por análise.
- `minimum_required_signers` deve ser menor ou igual ao total de signatários da lista.
- Pelo menos um signatário deve ter `is_required_signer: true`.
- Após `expiration_date`, o grupo não poderá mais ser utilizado para assinatura de documentos.
:::
### Response
O grupo de assinantes criado é retornado no corpo da resposta, incluindo a chave `external_signer_group_key`.
---
---
# Enviar Documento do Investidor
URL: /documentation/iaas/investidor/compartilhado/enviar_investor_document
---
### Introdução
Este recurso faz o upload de um documento que compõe a análise cadastral do investidor. Os documentos obrigatórios variam conforme o `person_type` e o `investor_sub_type` do investidor, bem como sua categoria (varejo, qualificado, profissional).
:::warning Atenção
- Este endpoint deve ser chamado **uma vez para cada documento** obrigatório
- A análise cadastral precisa estar no status `pending_registry_data`. Em outro status, a chamada é recusada com `IVR000026`
- Um mesmo `type` só aceita um envio bem-sucedido: veja [Reenvio e documento duplicado](#duplicado)
:::
:::info Classe de fundo (`fund_class`) — etapa pulada
Classes de fundo **não enviam documentos do investidor**. Não existe matriz de documentos obrigatórios para esse subtipo, e a ausência nunca bloqueia o `submit`. Pule esta etapa — ver **[Pessoa Jurídica — Fundo de Investimento](#fund-class)** abaixo.
:::
### Input / Output
Como ***input*** envie o conteúdo do arquivo em **base64**, o tipo do documento e a extensão.
Como ***output*** será retornada a representação do documento criado, identificado por `investor_analysis_document_key`, acompanhada da representação completa da análise cadastral à qual ele pertence.
### Request
ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/document`
MÉTODO `POST`
STATUS `201`
### Query params
| Campo | Tipo | Descrição | Obrigatório |
|---------|---------|--------------------------------------------------------------------------------------------------------------------------|-------------|
| `force` | boolean | Se `true`, força o envio mesmo quando há validação prévia falha. O documento entra obrigatoriamente em análise manual. | Não |
### Request body
Exemplo: CNH (Pessoa Física)
```json title='Request Body'
{
"type": "cnh",
"document_b64": "base64_encoded_document_content",
"file_extension": "pdf",
"document_data": {
"document_type": "CNH",
"issuer_entity": "DETRAN"
}
}
```
Exemplo: RG (frente e verso)
```json title='Request Body — Frente'
{
"type": "rg_front",
"document_b64": "base64_encoded_document_content",
"file_extension": "jpeg",
"document_data": {
"document_type": "RG",
"issuer_entity": "SSP",
"document_number": "20.932.206-8"
}
}
```
```json title='Request Body — Verso'
{
"type": "rg_back",
"document_b64": "base64_encoded_document_content",
"file_extension": "jpeg"
}
```
Exemplo: Cartão CNPJ (Pessoa Jurídica)
```json title='Request Body'
{
"type": "cnpj_card",
"document_b64": "base64_encoded_document_content",
"file_extension": "pdf"
}
```
### Body params
| Campo | Tipo | Descrição | Caracteres | Obrigatório |
|------------------|--------|--------------------------------------------------------------------|------------|-------------|
| `type` | string | Enumerador de **[Document Type](#document-type)** | - | Sim |
| `document_b64` | string | Conteúdo do arquivo codificado em base64 | - | Sim |
| `file_extension` | string | Extensão do arquivo. Valores aceitos: `pdf`, `jpeg` | - | Sim |
| `document_data` | object | Metadados livres do documento (ex.: número, órgão emissor) | - | Não |
| `observation` | string | Observação livre sobre o documento | até 500 | Não |
### Document Type {#document-type}
#### Identificação e comprovantes de pessoa física
| Enumerador | Descrição | Extensões |
|--------------------------------|------------------------------------------------------|----------------|
| `cnh` | CNH | `pdf`, `jpeg` |
| `rg_front` | RG — frente | `pdf`, `jpeg` |
| `rg_back` | RG — verso | `pdf`, `jpeg` |
| `passport` | Passaporte (identificação de estrangeiro) | `pdf`, `jpeg` |
| `foreign_id` | Documento de identidade estrangeiro (ex.: RNE) | `pdf`, `jpeg` |
| `proof_of_residence` | Comprovante de residência | `pdf`, `jpeg` |
| `billing_statement` | Fatura / extrato | `pdf`, `jpeg` |
#### Documentos societários de pessoa jurídica
| Enumerador | Descrição | Extensões |
|--------------------------------|------------------------------------------------------|----------------|
| `cnpj_card` | Cartão CNPJ | `pdf`, `jpeg` |
| `social_contract` | Contrato social | `pdf`, `jpeg` |
| `company_statute` | Estatuto | `pdf`, `jpeg` |
| `board_election_record` | Ata de eleição estatutária | `pdf`, `jpeg` |
| `financial_statements` | Demonstrações financeiras | `pdf`, `jpeg` |
| `organizational_chart` | Organograma societário | `pdf`, `jpeg` |
#### Representação, qualificação e contratos
| Enumerador | Descrição | Extensões |
|--------------------------------|------------------------------------------------------|----------------|
| `power_of_attorney` | Procuração | `pdf`, `jpeg` |
| `investor_qualification_proof` | Comprovação de qualificação / enquadramento | `pdf`, `jpeg` |
| `wallet_manager_contract` | Contrato de carteira administrada / intermediação | `pdf`, `jpeg` |
| `extra_document` | Documento avulso, sem tipo específico | `pdf`, `jpeg` |
#### Investidor não residente
| Enumerador | Descrição | Extensões |
|--------------------------------|------------------------------------------------------|----------------|
| `custody_contract` | Contrato de custódia | `pdf`, `jpeg` |
| `representation_contract` | Contrato de representação | `pdf`, `jpeg` |
| `simplified_declaration` | Declaração simplificada | `pdf`, `jpeg` |
| `final_departure_tax_return` | Declaração final de saída definitiva do país | `pdf`, `jpeg` |
:::warning Tipos gerados pela QI Tech
Os tipos `qualified_investor_term`, `professional_investor_term`, `natural_person_registry_form`, `legal_person_registry_form`, `investor_suitability_form` e `adhesion_term` aparecem na consulta do investidor, mas são **gerados pela QI Tech** para assinatura — não devem ser enviados por este endpoint.
:::
### Documentos Obrigatórios {#documentos-obrigatorios}
As combinações abaixo são conjuntos alternativos: basta satisfazer **uma** das opções de cada lista. A validação roda no envio para análise (`submit`) e recusa com `IVR000029`, devolvendo na mensagem a matriz exata que faltou.
#### Pessoa Física (`natural_person`)
Uma das opções:
| Opção | Documentos |
|-------|---------------------------------------------------|
| 1 | `cnh` **+** `proof_of_residence` |
| 2 | `rg_front` **+** `rg_back` **+** `proof_of_residence` |
#### Pessoa Jurídica (`legal_person` / `investor_sub_type: default`, `financial_institution`)
Uma das opções — sempre **ao menos um** documento societário **e** as demonstrações financeiras:
| Opção | Documentos |
|-------|--------------------------------------------------------|
| 1 | `board_election_record` **+** `financial_statements` |
| 2 | `company_statute` **+** `financial_statements` |
| 3 | `social_contract` **+** `financial_statements` |
O documento societário exigido depende do tipo jurídico da empresa — daí as três opções. Não é possível enviar apenas `financial_statements`.
:::warning Documentos obrigatórios
Embora esses documentos sejam o mínimo para envio de uma análise, caso, por exemplo, somente o `company_statute` não seja suficiente para definir firmas e poderes do cotista, a análise pode ser recusada exigindo também o `board_election_record`.
:::
#### Pessoa Jurídica — Classe de Fundo de Investimento (`investor_sub_type: fund_class`) {#fund-class}
**Nenhum documento é exigido — a etapa é pulada por completo.** Os dados da classe são obtidos por enriquecimento na base da CVM, e a representação é feita pelos investor owners (administrador e gestora).
Os únicos documentos que podem ser exigidos em um cadastro de classe de fundo são os das **partes relacionadas**, e apenas quando a classe é **exclusiva** na CVM — ver **[Enviar Documento da Parte Relacionada](./related_party/enviar_documento_parte_relacionada)**.
### Reenvio e documento duplicado {#duplicado}
Um tipo de documento é considerado **satisfeito** assim que existe, para aquela análise, um documento daquele tipo com status `valid` ou `in_manual_analysis`. A partir daí, novos envios do mesmo tipo são recusados:
```json
HTTP 409
{
"title": "Already exists valid document for investor analysis.",
"code": "IVR000023"
}
```
Enquanto **todos** os documentos de um tipo estiverem `invalid`, novos envios daquele tipo continuam sendo aceitos — é assim que se corrige um arquivo ilegível.
O tipo `extra_document` é a única exceção: aceita múltiplos envios sempre.
### Validação automática e `status` do documento {#validacao}
Documentos dos tipos `cnh`, `rg_front`, `rg_back` e `proof_of_residence` passam por validação automática (OCR) e voltam com um dos status abaixo. Os demais tipos entram diretamente em `in_manual_analysis`.
| Status | Significado |
|---------------------|------------------------------------------------------------------------------|
| `valid` | Validado automaticamente |
| `in_manual_analysis`| Encaminhado para conferência humana |
| `invalid` | Reprovado na validação automática — reenvie, ou use `force=true` |
`force=true` pula o efeito da reprovação automática: o documento é registrado como `in_manual_analysis` e passa a satisfazer a exigência do tipo.
:::info Sobre `investor_qualification_proof`
Este documento **não integra a matriz de obrigatórios** e sua ausência nunca bloqueia o `submit`. Ele atua depois: se o `total_financial_applications` declarado estiver abaixo do piso da categoria informada — R$ 1.000.000 para `qualified`, R$ 10.000.000 para `professional` — ele é utilizado para a validação. Investidores `fund_class` são isentos dessa verificação.
:::
### Response
```json title='Response Body'
{
"investor_analysis_document_key": "UUID",
"type": "cnh",
"status": "in_manual_analysis",
"observation": "Documento emitido em 2019, legibilidade reduzida no verso.",
"data": {
"type": "cnh",
"file_extension": "pdf",
"document_data": {
"document_type": "CNH",
"issuer_entity": "DETRAN"
}
},
"investor_analysis": { }
}
```
| Campo | Tipo | Descrição |
|----------------------------------|--------|------------------------------------------------------------------------------|
| `investor_analysis_document_key` | string | Identificador do documento. É a chave usada nas demais rotas de documento |
| `type` | string | Enumerador de **[Document Type](#document-type)** |
| `status` | string | `valid`, `invalid` ou `in_manual_analysis` — veja [Validação automática](#validacao) |
| `observation` | string | Observação enviada na requisição. `null` quando não informada |
| `data` | object | Eco dos campos enviados, sem o conteúdo em base64 |
| `investor_analysis` | object | Representação completa da análise cadastral — mesmo formato de **Busca informações de uma análise cadastral do investidor** |
---
# Enviar Patrimônio do Investidor
URL: /documentation/iaas/investidor/compartilhado/enviar_patrimonio
---
### Introdução
Este recurso registra as informações de patrimônio e enquadramento do investidor (varejo, qualificado ou profissional).
:::info Classe de fundo (`fund_class`) — etapa pulada
Classes de fundo **não enviam patrimônio**. Ele é calculado **automaticamente** a partir dos dados públicos da CVM ao enviar a análise para validação, e o `submit` não exige o bloco `net_worth` para esse subtipo. Pule esta etapa.
:::
### Input / Output
Como ***input*** envie os valores patrimoniais e a categoria autodeclarada do investidor.
Como ***output*** será retornada a representação atualizada da análise cadastral.
### Request
ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/net_worth`
MÉTODO `PUT`
STATUS `202`
Exemplo
```json title='Request Body'
{
"investor_category": "retail",
"total_net_worth": 250000,
"total_financial_applications": 80000,
"monthly_income": 15000,
"other_incomes": 0,
"real_estate": 150000,
"movable_assets": 20000,
"resource_origin": "Renda do trabalho"
}
```
### Body params
| Campo | Tipo | Descrição | Obrigatório |
|--------------------------------|--------|--------------------------------------------------------------------|-------------|
| `total_net_worth` | number | Patrimônio total (>= 0) | Sim |
| `total_financial_applications` | number | Total em aplicações financeiras (>= 0) | Sim |
| `monthly_income` | number | Renda ou faturamento mensal (>= 0) | Sim |
| `other_incomes` | number | Outras rendas mensais (>= 0) | Sim |
| `real_estate` | number | Patrimônio em imóveis (>= 0) | Sim |
| `movable_assets` | number | Patrimônio em bens móveis (>= 0) | Sim |
| `investor_category` | string | Enumerador de **[Investor Category](#investor-category)** | Sim |
| `resource_origin` | string | Origem dos recursos (até 255 caracteres) | Não |
### Investor Category {#investor-category}
| Enumerador | Descrição |
|----------------|---------------|
| `retail` | Varejo |
| `qualified` | Qualificado |
| `professional` | Profissional |
### Response
A análise cadastral atualizada é retornada no corpo da resposta. Para o formato completo, consulte **Busca informações de uma análise cadastral do investidor**.
---
# Consultar Feedback
URL: /documentation/iaas/investidor/compartilhado/feedback/consultar_feedback
---
### Introdução
Este recurso retorna um único **feedback** identificado por `feedback_key`, em uma representação **resumida**: chave, status, origem e o histórico de mensagens. É a rota indicada para confirmar se um feedback ainda está `open` ou já foi encerrado (`closed`) pela sua resposta.
:::info Esta rota devolve menos campos que a listagem
A resposta **não** inclui `description`, `category`, `type` nem `data`. Se você precisa do texto do pedido ou da categoria do feedback, use **[Listar Feedbacks](./listar_feedbacks)** — a listagem devolve o objeto completo. O formato das mensagens também é diferente entre as duas rotas; compare as tabelas abaixo antes de reaproveitar o seu parser.
:::
### Request
ENDPOINT `/investor_registry/investor/{investor_key}/feedback/{feedback_key}`
MÉTODO `GET`
STATUS `200`
Não há corpo de requisição nem query params.
### Response
O corpo é o **objeto direto**, sem envelope `data`.
```json title='Response Body'
{
"feedback_key": "UUID",
"status": "open",
"origin_type": "investor_analysis",
"origin_key": "UUID",
"messages": [
{
"message": "O comprovante de residência apresentado tem data superior a 90 dias.",
"sender_type": "distributor",
"created_at": "2026-07-31T21:47:46Z"
}
]
}
```
| Campo | Tipo | Descrição |
|----------------|--------|---------------------------------------------------------------------------|
| `feedback_key` | string | Identificador do feedback |
| `status` | string | Enumerador de **[Feedback Status](./listar_feedbacks#feedback-status)** |
| `origin_type` | string | Enumerador de **[Origin Type](./listar_feedbacks#origin-type)** |
| `origin_key` | string | Chave da entidade de origem |
| `messages` | array | Histórico de mensagens — ver **[Message](#message)**. Vazio se não houver |
### Message {#message}
| Campo | Tipo | Descrição |
|--------------|--------|--------------------------------------------------------------------------------------|
| `message` | string | Conteúdo da mensagem |
| `sender_type`| string | Tipo do agente que enviou (`distributor`, `investor`, `manager`, `administrator`, entre outros; mensagens escritas por analistas da QI Tech chegam com o tipo do agente interno) |
| `created_at` | string | Data/hora do envio, em ISO-8601 UTC (`2026-07-31T21:47:46Z`) |
### Escopo da busca
O feedback é localizado dentro do **cadastro do investidor** informado em `investor_key`, cobrindo as duas origens possíveis:
- feedbacks abertos sobre uma **análise cadastral** do investidor (`origin_type: investor_analysis`);
- feedbacks abertos sobre uma **parte relacionada** de qualquer análise desse investidor (`origin_type: related_party_analysis`).
Um `feedback_key` que exista, mas pertença a outro investidor, resulta em `404` com o código `IVR000089` — o mesmo retorno de uma chave inexistente.
### Erros
| Código | HTTP | Quando ocorre |
|-------------|------|---------------------------------------------------------------------------------|
| `IVR000089` | 404 | Feedback não encontrado para o investidor informado |
| `IVR000008` | 404 | Investidor não encontrado para as credenciais utilizadas |
---
# Enviar Mensagem em Feedback
URL: /documentation/iaas/investidor/compartilhado/feedback/enviar_mensagem_feedback
---
### Introdução
Este recurso adiciona uma nova **mensagem** a um feedback existente. É por aqui que você **responde** a um pedido de esclarecimento feito pela QI Tech — e é a mensagem que **encerra** o feedback.
:::info Como responder a um feedback
A resposta é uma única ação: **enviar a mensagem neste endpoint**. Ao recebê-la, o feedback passa de `open` para `closed` e a análise de compliance retoma a avaliação.
Não há `submit` a refazer: a análise permaneceu em `in_compliance_analysis` durante todo o ciclo do feedback. Veja **[Ciclo de vida da análise cadastral](../ciclo_de_vida_da_analise#feedback)**.
:::
### Request
ENDPOINT `/investor_registry/investor/{investor_key}/feedback/{feedback_key}/message`
MÉTODO `PUT`
STATUS `201`
### Request body
```json title='Request Body'
{
"message": "Confirmamos que o endereço declarado permanece válido; o titular reside no imóvel desde 2019.",
"origin_type": "investor_analysis",
"origin_key": "UUID"
}
```
### Body params
| Campo | Tipo | Descrição | Caracteres | Obrigatório |
|---------------|--------|--------------------------------------------------------------------------------------------|------------|-------------|
| `message` | string | Conteúdo da mensagem | 1 - 1000 | Sim |
| `origin_type` | string | Enumerador de **[Origin Type](./listar_feedbacks#origin-type)**. Apenas `investor_analysis` é aceito nesta rota | 1 - 50 | Sim |
| `origin_key` | string | Chave da entidade de origem (UUID) | 36 | Sim |
:::warning `origin_type` e `origin_key` devem coincidir com os do feedback
O par informado no corpo precisa ser exatamente o mesmo devolvido pelo feedback em **Listar Feedbacks**. Se não houver feedback com aquele `feedback_key` naquela origem, a chamada é recusada com `IVR000085`.
:::
:::warning Enviar mensagem encerra o feedback
Um feedback `open` passa a `closed` assim que a sua mensagem é registrada. **Envie tudo o que precisa dizer em uma única mensagem** — um feedback já encerrado não aceita novas mensagens, e não há endpoint para reabri-lo. Se a QI Tech precisar de mais alguma coisa, ela abre um **novo** feedback, com um novo `feedback_key`.
:::
### Response
O feedback atualizado é retornado no corpo da resposta, no mesmo formato de cada item de **[Listar Feedbacks](./listar_feedbacks)**, já com a nova mensagem incluída no array `messages` e com o `status` em `closed`.
### Webhook
O encerramento dispara um `investor_registry.feedback_status_change` com `status: closed`:
```json title='Webhook Body — feedback encerrado'
{
"webhook_type": "investor_registry.feedback_status_change",
"webhook_datetime": "2026-07-31T22:12:03Z",
"data": {
"investor_analysis_key": "UUID",
"feedback_key": "UUID",
"status": "closed",
"origin_type": "investor_analysis",
"origin_key": "UUID"
}
}
```
O detalhamento dos campos está em **[Webhooks de feedback](../ciclo_de_vida_da_analise#webhooks-feedback)**.
---
# Listar Feedbacks
URL: /documentation/iaas/investidor/compartilhado/feedback/listar_feedbacks
---
### Introdução
Este recurso lista os **feedbacks** abertos em torno de uma entidade da análise cadastral. Feedbacks são o canal pelo qual a QI Tech solicita **complementos e esclarecimentos** durante a análise — tipicamente pendências de PLD/compliance ou dados cadastrais a confirmar.
:::info O feedback não altera o status da análise
Um feedback é aberto na **análise de compliance** e corre **em paralelo** a ela: a análise permanece em `in_compliance_analysis`, não retorna para `pending_registry_data` e não exige um novo `submit`. Você responde à mensagem, o feedback é encerrado (`closed`) e a compliance retoma a avaliação.
Quando o cadastro não reúne os dados mínimos para aprovação, a análise é **recusada** e uma nova análise precisa ser aberta — não há feedback nesse caso. Veja **[Ciclo de vida da análise cadastral](../ciclo_de_vida_da_analise)** para a distinção completa.
:::
:::warning A abertura de um feedback só é notificada por webhook
Como o status da análise não muda, o único aviso é o `investor_registry.feedback_status_change` com `status: open`. Veja **[Webhooks de feedback](../ciclo_de_vida_da_analise#webhooks-feedback)**.
:::
### Request
ENDPOINT `/investor_registry/investor/{investor_key}/feedbacks`
MÉTODO `GET`
STATUS `200`
### Query params
| Campo | Tipo | Descrição | Obrigatório |
|---------------|---------|--------------------------------------------------------------------------------------------|-------------|
| `origin_type` | string | Enumerador de **[Origin Type](#origin-type)** | Sim |
| `origin_key` | string | Chave da entidade de origem (UUID) | Sim |
| `page` | integer | Página (>= 0). Default: `0` | Não |
| `limit` | integer | Tamanho da página. Default: `100` | Não |
:::warning `origin_type` e `origin_key` são obrigatórios
Não existe listagem de todos os feedbacks de um investidor: a consulta é sempre feita **por entidade de origem**. Para varrer um cadastro, consulte a análise cadastral e itere sobre a própria análise e sobre cada parte relacionada.
Um `origin_type` fora do enumerador é recusado com `IVR000075`.
:::
### Origin Type {#origin-type}
| Enumerador | Descrição | O que enviar em `origin_key` |
|--------------------------|--------------------------------------------------|------------------------------------|
| `investor_analysis` | Feedback sobre a análise cadastral como um todo | `investor_analysis_key` |
| `related_party_analysis` | Feedback sobre uma parte relacionada específica | `external_related_party_key` |
:::warning Não existe `origin_type` de documento
Feedbacks são abertos sobre a **análise** ou sobre a **parte relacionada**, nunca diretamente sobre um documento. Um pedido relacionado a um documento chega como feedback de `investor_analysis`, com a descrição indicando qual documento motivou o questionamento.
:::
### Response
```json title='Response Body'
{
"data": [
{
"feedback_key": "UUID",
"description": "O comprovante de residência apresentado tem data superior a 90 dias. Favor esclarecer se o endereço declarado permanece válido.",
"status": "open",
"category": "registry_data",
"type": "automatic",
"origin_type": "investor_analysis",
"origin_key": "UUID",
"data": {},
"messages": [
{
"text": "O comprovante de residência apresentado tem data superior a 90 dias.",
"datetime": "2026-07-31T21:47:46Z",
"agent": {
"username": "analista.qitech",
"email": "analista@qitech.com.br",
"user_key": "UUID",
"agent_type": "internal",
"agent_key": "UUID"
}
}
]
}
],
"is_last_page": true
}
```
| Campo | Tipo | Descrição |
|-----------------|---------|----------------------------------------------------------------------------------|
| `feedback_key` | string | Identificador do feedback |
| `description` | string | Texto do pedido, redigido pela QI Tech |
| `status` | string | Enumerador de **[Feedback Status](#feedback-status)** |
| `category` | string | Enumerador de **[Feedback Category](#feedback-category)** |
| `type` | string | `automatic` (aberto por regra do sistema) ou `manual` (aberto por um analista) |
| `origin_type` | string | Enumerador de **[Origin Type](#origin-type)** |
| `origin_key` | string | Chave da entidade de origem |
| `data` | object | Metadados do feedback |
| `messages` | array | Histórico de mensagens — ver **[Message](#message)** |
| `is_last_page` | boolean | `false` indica que há mais páginas |
### Message {#message}
| Campo | Tipo | Descrição |
|------------|--------|--------------------------------------------------------------------------------|
| `text` | string | Conteúdo da mensagem |
| `datetime` | string | Data/hora do envio, em ISO-8601 UTC (`2026-07-31T21:47:46Z`) |
| `agent` | object | Identificação de quem enviou: `username`, `email`, `user_key`, `agent_type`, `agent_key` |
:::info A resposta não devolve `page` nem `limit`
A paginação é sinalizada apenas por `is_last_page`. Controle o `page` do seu lado, incrementando enquanto `is_last_page` for `false`.
:::
### Feedback Status {#feedback-status}
| Enumerador | Descrição |
|------------|------------------------------------------------------------------------------------------------|
| `created` | Criado, ainda não disponibilizado |
| `open` | Aberto — aguarda sua resposta. Bloqueia a conclusão da análise |
| `closed` | Encerrado — a resposta foi registrada e o pedido está resolvido |
:::info A sua resposta encerra o feedback
Enviar a mensagem com **[Enviar Mensagem em Feedback](./enviar_mensagem_feedback)** move o feedback de `open` para `closed` — não é preciso aguardar um analista da QI Tech. Se a resposta não for suficiente, a compliance abre um **novo** feedback, com um novo `feedback_key`.
:::
### Feedback Category {#feedback-category}
| Enumerador | Descrição |
|-----------------|--------------------------------------------------------------------------------------------------------------------|
| `registry_data` | Dado cadastral a corrigir ou complementar — ex.: comprovação de qualificação ausente, renda declarada fora da faixa esperada |
| `compliance` | Esclarecimento de PLD/compliance, decorrente de indicadores da análise de risco |
A categoria indica **a natureza do que está sendo pedido** — um dado cadastral a esclarecer ou um esclarecimento de PLD. Para a sua integração o tratamento é o mesmo: responder ao ponto apontado com **[Enviar Mensagem em Feedback](./enviar_mensagem_feedback)**, o que encerra o feedback. A análise segue em `in_compliance_analysis` o tempo todo — não há `submit` a refazer.
---
# Criar Investor Owner
URL: /documentation/iaas/investidor/compartilhado/investor_owner/criar_investor_owner
---
### Introdução
Este recurso cria um vínculo de **propriedade / responsabilidade** (`investor_owner`) entre o investidor da análise e outro investidor já existente no sistema (identificado pelo CNPJ informado). É utilizado principalmente em fluxos de **carteira administrada** para registrar o gestor de carteira.
:::info Quando usar
- Para fundos de investimento (`fund_class`), os vínculos com **administrador** e **gestor** são criados **automaticamente** ao enviar a análise para validação, com base nos dados públicos da CVM. Este endpoint deve ser usado para registrar vínculos **adicionais** (ex.: investidor exclusivo, gestor de carteira), ou para fluxos diferentes do auto-enriquecimento.
- O investidor referenciado pelo `document_number` precisa estar previamente cadastrado no distribuidor.
:::
### Input / Output
Como ***input*** envie o CNPJ do investidor que será o "owner" e o tipo do vínculo.
Como ***output*** o status `201 Created` é retornado.
### Request
ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/investor_owner`
MÉTODO `POST`
STATUS `201`
### Request body
```json title='Request Body'
{
"investor_owner_type": "wallet_manager",
"document_number": "07.228.314/0001-95"
}
```
### Body params
| Campo | Tipo | Descrição | Caracteres | Obrigatório |
|--------------------------------|--------|--------------------------------------------------------------------------------------|------------|-------------|
| `investor_owner_type` | string | Enumerador de **[Investor Owner Type](#investor-owner-type)** | 1 - 50 | Sim |
| `document_number` | string | CNPJ do investidor que será o owner (`XX.XXX.XXX/XXXX-XX`) | 18 | Sim |
| `external_investor_owner_key` | string | Chave externa pré-definida para este vínculo. Caso omitida, é gerada automaticamente | 1 - 36 | Não |
### Investor Owner Type {#investor-owner-type}
| Enumerador | Descrição |
|-----------------------------|-------------------------------------------------------------------|
| `fund_class_administrator` | Administrador do fundo |
| `fund_class_manager` | Gestor do fundo |
| `wallet_manager` | Gestor de carteira |
### Atualizar status de um Investor Owner
Para inativar ou reativar um vínculo, utilize:
ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/investor_owner/{external_investor_owner_key}/status`
MÉTODO `PUT`
STATUS `202`
```json title='Request Body'
{
"status": "active"
}
```
---
# Enviar Documento de Investor Owner
URL: /documentation/iaas/investidor/compartilhado/investor_owner/enviar_documento_investor_owner
---
### Introdução
Este recurso faz o upload de um documento associado a um **investor owner** (vínculo de propriedade) de uma análise cadastral. Aplica-se principalmente aos fluxos de fundo de investimento, onde podem ser exigidos documentos do administrador, gestor ou investidor exclusivo.
### Input / Output
Como ***input*** envie o arquivo em **base64**, o tipo e a extensão.
Como ***output*** será retornada a representação do documento criado.
### Request
ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/investor_owner/{external_investor_owner_key}/document`
MÉTODO `POST`
STATUS `201`
### Request body
```json title='Request Body'
{
"type": "power_of_attorney",
"document_b64": "base64_encoded_document_content",
"file_extension": "pdf"
}
```
### Body params
| Campo | Tipo | Descrição | Obrigatório |
|------------------|--------|--------------------------------------------------------|-------------|
| `type` | string | Tipo do documento (ver enumerador em **Enviar Documento do Investidor**) | Sim |
| `document_b64` | string | Conteúdo do arquivo em base64 | Sim |
| `file_extension` | string | Extensão (`pdf` ou `jpeg`) | Sim |
| `document_data` | object | Metadados livres do documento | Não |
| `observation` | string | Observação livre (até 500 caracteres) | Não |
### Endpoints relacionados
- `GET .../investor_owner/{external_investor_owner_key}/document/{investor_owner_document_key}` — consultar um documento de investor owner.
- `PUT .../investor_owner/{external_investor_owner_key}/document/{investor_owner_document_key}/update` — atualizar o status de um documento.
---
# Atualizar Parte Relacionada
URL: /documentation/iaas/investidor/compartilhado/related_party/atualizar_parte_relacionada
---
### Introdução
Este recurso **corrige os dados** de uma parte relacionada já criada — percentual de participação, endereço, renda, tipo de vínculo ou qualquer outro campo enviado na criação.
É o caminho para resolver uma recusa de participação societária (`IVR000166`, `IVR000169`, `IVR000170`) sem precisar abrir uma nova análise cadastral: ajuste o percentual e reenvie o `submit`.
:::info Corrigir ou desativar?
- Para **ajustar dados** de uma parte que continua fazendo parte do cadastro, use este endpoint
- Para **remover** uma parte do cadastro, use **[Atualizar Status da Parte Relacionada](./atualizar_status_parte_relacionada)** com `status: "inactive"`. Não existe `DELETE` — partes relacionadas nunca são apagadas fisicamente
:::
### Input / Output:
Como ***input*** devem ser enviados os dados da parte relacionada. O corpo é uma **substituição completa**: envie todos os campos, não apenas os que mudaram.
Como ***output*** será retornada a representação atualizada da parte relacionada.
### Request
ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/related_party/{external_related_party_key}`
MÉTODO `PUT`
STATUS `200`
:::warning Use o `external_related_party_key`
A chave aceita nesta URL é o **`external_related_party_key`** devolvido na criação da parte relacionada — não o `related_party_key`. Uma chave desconhecida é recusada com `IVR000183`.
Atenção: as mensagens de erro do `submit` (`IVR000030`) citam a parte relacionada pelo `related_party_key` **interno**, que não funciona nesta rota. Para correlacionar as duas chaves, consulte a análise cadastral — o objeto de cada parte relacionada traz ambas.
:::
### Request body
```json title='Request Body'
{
"name": "João Silva",
"document_number": "123.456.789-00",
"person_type": "natural_person",
"related_party_type": "partner",
"resident": true,
"legal_representative": true,
"direct_beneficiary": true,
"participation_percentage": 0.85,
"monthly_income": 50000.00,
"address": {
"postal_code": "01000-000",
"street": "Rua das Flores",
"number": "123",
"neighborhood": "Centro",
"city": "São Paulo",
"uf": "SP",
"country": "BRA"
},
"email": "joao.silva@example.com",
"phone": {
"international_dial_code": "55",
"area_code": "11",
"number": "987654321"
}
}
```
### Body params
Os campos são os mesmos de **[Criar Parte Relacionada](./criar_parte_relacionada#body-params)**, com uma diferença:
| Campo | Diferença em relação à criação |
|-------------------|-----------------------------------------------------------------------------------------|
| `document_number` | **Sempre obrigatório** neste endpoint, inclusive para partes com `resident: false` |
Todas as demais regras condicionais continuam valendo — `address` obrigatório para `legal_person` ou quando `direct_beneficiary: true`, `monthly_income` obrigatório para pessoa física com `direct_beneficiary: true`, e assim por diante.
:::warning A análise não pode estar em estado terminal
A atualização é recusada com `IVR000185` quando a análise cadastral já está em um dos status finais: `automatically_approved`, `automatically_reproved`, `manually_approved`, `manually_reproved`, `analysis_complete` ou `expired`.
Se o cadastro já foi analisado, a correção passa por abrir uma nova análise via **Atualização Cadastral**.
:::
### Response
```json title='Response Body'
{
"related_party_key": "UUID",
"external_related_party_key": "UUID",
"name": "João Silva",
"document_number": "123.456.789-00",
"person_type": "natural_person",
"related_party_type": "partner",
"status": "active",
"resident": true,
"legal_representative": true,
"direct_beneficiary": true,
"address": {},
"participation_percentage": 0.85,
"monthly_income": 50000.00,
"email": "joao.silva@example.com",
"phone": {}
}
```
---
# Atualizar Status da Parte Relacionada
URL: /documentation/iaas/investidor/compartilhado/related_party/atualizar_status_parte_relacionada
---
### Introdução
Este recurso **ativa ou desativa** uma parte relacionada dentro de uma análise cadastral.
Para uma parte enviada por engano, ou que deixou de compor o quadro societário, é **desativada** por aqui. Partes com status `inactive` são ignoradas em todas as validações do envio para análise — não contam para a exigência de quantidade mínima, não contam para o requisito de representante legal, não somam participação societária e não têm documentos cobrados.
:::info Casos de uso
- **Sócio enviado por engano** → desative com `inactive`
- **Quadro societário mudou** → desative quem saiu e crie quem entrou
- **Participação somada acima de 100%** (`IVR000169`) → desative a parte duplicada, ou corrija o percentual com **[Atualizar Parte Relacionada](./atualizar_parte_relacionada)**
:::
### Input / Output:
Como ***input*** deve ser enviado o novo status.
Como ***output*** será retornada a confirmação da alteração.
### Request
ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/related_party/{external_related_party_key}/status`
MÉTODO `PUT`
STATUS `202`
### Request body
```json title='Request Body'
{
"status": "inactive"
}
```
### Body params
| Campo | Tipo | Descrição | Obrigatório |
|----------|--------|-------------------------------------------------------|-------------|
| `status` | string | Enumerador de **[Related Party Status](#status)** | Sim |
### Related Party Status {#status}
| Enumerador | Descrição |
|------------|-----------------------------------------------------------------------------------------------|
| `active` | Parte considerada em todas as validações do envio para análise |
| `inactive` | Parte desconsiderada em todas as validações. É o equivalente a remover a parte do cadastro |
:::warning A análise não pode estar em estado terminal
A alteração é recusada com `IVR000185` quando a análise cadastral já está em um dos status finais: `automatically_approved`, `automatically_reproved`, `manually_approved`, `manually_reproved`, `analysis_complete` ou `expired`.
:::
Uma `external_related_party_key` desconhecida na análise informada é recusada com `IVR000183`.
---
# Criar Parte Relacionada
URL: /documentation/iaas/investidor/compartilhado/related_party/criar_parte_relacionada
---
### Introdução
Este recurso tem como objetivo identificar os beneficiários finais (pessoas físicas) e controladores relacionados ao investidor pessoa jurídica, como sócios, diretores, administradores, etc ou procuradores de pessoa física.
:::warning Atenção
- Este endpoint deve ser chamado múltiplas vezes, uma vez para cada parte relacionada
- Para pessoa jurídica como parte relacionada, o `related_party_type` deve ser obrigatoriamente `parent_company` (exceto em `fund_class`)
- As exigências de quantidade, de representante legal e de participação mínima **variam conforme o tipo do investidor** — veja [Exigências por tipo de investidor](#exigencias) abaixo
- Para corrigir ou desativar uma parte relacionada já criada, use **Atualizar Parte Relacionada** e **Atualizar Status da Parte Relacionada**. Partes com status `inactive` deixam de ser consideradas em todas as validações do envio para análise
:::
### Exigências por tipo de investidor {#exigencias}
As validações abaixo são aplicadas no **envio para análise** (`submit`), não na criação da parte relacionada. Cada regra é avaliada em sequência, então uma recusa pode esconder a próxima pendência.
| Investidor | Partes relacionadas | Representante legal | Participação somada |
|---|---|---|---|
| **Pessoa física** (`natural_person`) | Opcional — envie apenas se houver procurador | Não exigido | Não validada |
| **Pessoa jurídica** (`legal_person` / `default`, `financial_institution`) | **Pelo menos uma** ativa, senão `IVR000134` | **Pelo menos uma** com `legal_representative: true`, senão `IVR000136` | **≥ 80%** e nunca acima de 100%, senão `IVR000166` / `IVR000169` |
| **Fundo** (`fund_class`) **não exclusivo** | Nenhuma — pode pular a etapa | Não exigido | Não validada |
| **Fundo** (`fund_class`) **exclusivo** | **Pelo menos uma**, obrigatoriamente do tipo `exclusive_investor`, senão `IVR000134` | **Proibido** — `exclusive_investor` não pode ser representante legal (`IVR000165`) | **Exatamente 100%**, senão `IVR000170` |
:::info Fundos de investimento
Em um fundo, a representação se dá pelos **investor owners** (administrador e gestora) — não é necessário enviar representantes legais como parte relacionada. O único `related_party_type` aceito em `fund_class` é `exclusive_investor`; qualquer outro valor é recusado com `IVR000172`.
O caráter exclusivo do fundo (`exclusive_fund_class`) é derivado automaticamente da classe CVM no momento da criação do investidor. Se o CNPJ não constar na base da CVM, o campo fica indefinido e o `submit` é recusado com `IVR000068` — use um CNPJ de fundo efetivamente registrado na CVM.
:::
:::info Sobre os Beneficiários Finais
*Beneficiário Final é a pessoa natural que, em última instância exerce posição de controle ou influência significativa na empresa, especialmente as que detêm 15% ou mais de participação direta ou indireta, exercem cargo de administração ou representam a empresa para fins legais.*
*Informar os dados das pessoas físicas que detêm 15% ou mais de participação societária direta ou indireta e administradores. Se nenhum dos sócios/acionistas detém individualmente participação igual ou maior a 15%, solicitamos enviar as informações dos 03 controladores que detêm os maiores percentuais de participação.*
**Conciliando a regra de 15% com o mínimo de 80%.** As duas regras convivem: a de 15% define *quem* precisa ser qualificado, a de 80% define *quanto* da cadeia societária precisa estar declarado. Uma sócia **pessoa jurídica** (`parent_company`) também conta para a soma — em capital pulverizado, declarar a holding controladora costuma ser o caminho para atingir o mínimo. Recomendamos enviar **pelo menos 85%** somados, para não depender de arredondamento.
O procurador (`attorney`), embora não detenha participação, exerce posição de controle e por isso é considerado beneficiário final. Envie-o com `participation_percentage: 0`.
Quando um beneficiário final pessoa física não puder ser plenamente qualificado, o cadastro da controladora pode bastar — porém poderão ser solicitados esclarecimentos por meio de [feedbacks](../feedback/listar_feedbacks).
:::
### Input / Output:
Como ***input*** devem ser enviados os dados da parte relacionada.
Como ***output*** será entregue uma ***external_related_party_key*** e os detalhes da parte relacionada criada.
### Request
ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/related_party`
MÉTODO `POST`
STATUS `201`
### Request body
Exemplo: Sócio Pessoa Física
```json title='Request Body'
{
"name": "João Silva",
"document_number": "123.456.789-00",
"person_type": "natural_person",
"related_party_type": "partner",
"resident": true,
"legal_representative": true,
"direct_beneficiary": true,
"address": {
"postal_code": "01000-000",
"street": "Rua das Flores",
"number": "123",
"neighborhood": "Centro",
"city": "São Paulo",
"uf": "SP",
"country": "BRA",
"complement": "Apto 101"
},
"participation_percentage": 0.5,
"monthly_income": 50000.00,
"email": "joao.silva@example.com",
"phone": {
"international_dial_code": "55",
"area_code": "11",
"number": "987654321"
}
}
```
Exemplo: Empresa Controladora (Pessoa Jurídica)
```json title='Request Body'
{
"name": "Empresa Controladora Ltda",
"document_number": "98.765.432/0001-11",
"person_type": "legal_person",
"related_party_type": "parent_company",
"resident": true,
"legal_representative": false,
"direct_beneficiary": true,
"address": {
"postal_code": "02000-000",
"street": "Avenida Principal",
"number": "456",
"neighborhood": "Jardim",
"city": "São Paulo",
"uf": "SP",
"country": "BRA"
},
"participation_percentage": 0.8,
"email": "contato@controladora.com.br",
"phone": {
"international_dial_code": "55",
"area_code": "11",
"number": "123456789"
}
}
```
### Body params
| Campo | Tipo | Descrição | Caracteres | Obrigatório |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `name` | string | Nome da parte relacionada | 1 - 255 | Sim |
| `person_type` | string | Enumerador de **[Person Type](#person-type-related-party)** | - | Sim |
| `related_party_type` | string | Enumerador de **[Related Party Type](#related-party-type)** | - | Sim |
| `resident` | boolean | Define se é residente no Brasil | - | Sim |
| `legal_representative` | boolean | Define se é representante legal | - | Sim |
| `direct_beneficiary` | boolean | Define se é beneficiário final | - | Sim |
| `participation_percentage` | number | Percentual de participação, em **fração de 0 a 1** (ex.: `0.5` = 50%) | - | Sim |
| `document_number` | string | CPF ou CNPJ. Obrigatório quando `resident: true` | 1 - 18 | Condicional |
| `address` | object | Objeto de **[Address](#address)**. Obrigatório quando `person_type` é `legal_person` **ou** quando `direct_beneficiary: true` | - | Condicional |
| `monthly_income` | number | Renda mensal. Obrigatório quando `person_type` é `natural_person` **e** `direct_beneficiary: true` | - | Condicional |
| `nationality` | string | Nacionalidade, código ISO de 3 letras maiúsculas (ex.: `BRA`). Default `BRA` para pessoa física. **Não aceito** para `legal_person` | 3 | Não |
| `email` | string | E-mail | 1 - 100 | Não |
| `phone` | object | Objeto de **[Phone](#phone)** | - | Não |
| `expiration_date` | string | Data de expiração (formato: YYYY-MM-DD) | 10 | Não |
:::warning Campos condicionais
`address` e `monthly_income` são recusados com `IVR000068` quando a condição acima é satisfeita e o campo não é enviado — mesmo que o schema os aceite como ausentes. Como a API valida um campo por vez, envie os dois já na primeira tentativa para partes com `direct_beneficiary: true`.
`nationality` enviado para uma parte relacionada `legal_person` é recusado com `IVR000238`.
:::
### Person Type (Related Party) {#person-type-related-party}
| Enumerador | Descrição |
|-----------------------------------|------------------------------------------------------------------------------|
| `natural_person` | Pessoa física |
| `legal_person` | Pessoa jurídica |
### Related Party Type {#related-party-type}
| Enumerador | Descrição |
|-----------------------------------|------------------------------------------------------------------------------|
| `president` | Presidente |
| `partner` | Sócio |
| `administrator` | Administrador |
| `director` | Diretor |
| `manager` | Gestor |
| `attorney` | Procurador |
| `parent_company` | Empresa controladora (apenas para pessoa jurídica) |
| `asset_custodian` | Custodiante de ativos |
| `exclusive_investor` | Investidor Exclusivo |
### Address {#address}
| Campo | Tipo | Descrição | Caracteres | Obrigatório |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `postal_code` | string | Código postal. Para endereço no Brasil, CEP no formato `XXXXX-XXX`. Para endereço no exterior, envie o código postal local no formato do país | 1 - 20 | Sim |
| `street` | string | Logradouro | 1 - 255 | Não |
| `number` | string | Número | 1 - 10 | Não |
| `neighborhood` | string | Bairro | 1 - 255 | Não |
| `city` | string | Cidade | 1 - 255 | Não |
| `uf` | string | Unidade federativa (ex.: `SP`). Para endereço no exterior, use `EX` | 1 - 20 | Não |
| `country` | string | País, código ISO de 3 letras (ex.: `BRA`) | 3 | Não |
| `complement` | string | Complemento | 1 - 255 | Não |
:::info Endereço no exterior
`postal_code` e `uf` **não** têm validação de formato — aceitam o padrão de qualquer país. A coerência exigida é entre `resident` e `country`: uma parte relacionada com `resident: true` precisa de `country: "BRA"` (senão `IVR000227`), e uma com `resident: false` não pode ter `country: "BRA"` (senão `IVR000226`).
:::
### Phone {#phone}
| Campo | Tipo | Descrição | Caracteres | Obrigatório |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `international_dial_code` | string | Código internacional | 1 - 3 | Sim |
| `area_code` | string | Código de área | 2 | Sim |
| `number` | string | Número de telefone | 8 - 9 | Sim |
### Response
```json title='Response Body'
{
"related_party_key": "UUID",
"external_related_party_key": "UUID",
"name": "João Silva",
"document_number": "123.456.789-00",
"person_type": "natural_person",
"related_party_type": "partner",
"status": "active",
"resident": true,
"legal_representative": true,
"direct_beneficiary": true,
"address": {...},
"participation_percentage": 0.5,
"monthly_income": 50000.00,
"email": "joao.silva@example.com",
"phone": {...}
}
```
---
# Enviar Documento da Parte Relacionada
URL: /documentation/iaas/investidor/compartilhado/related_party/enviar_documento_parte_relacionada
---
### Introdução
Este recurso tem como objetivo fazer upload dos documentos obrigatórios de cada parte relacionada criada.
:::warning Atenção
- Este endpoint deve ser chamado para **cada** parte relacionada criada que seja **pessoa física**
- A parte relacionada deve estar com status **`active`** para receber documentos
- Para pessoa física: é obrigatório enviar um documento de identificação — `cnh` **ou** o par `rg_front` + `rg_back`
- Para pessoa jurídica (`parent_company`): **nenhum** documento é exigido
- Um mesmo `type` só aceita um envio bem-sucedido: veja [Reenvio e documento duplicado](#duplicado)
:::
### Input / Output:
Como ***input*** deve ser enviado o documento em base64, o tipo do documento e a extensão do arquivo.
Como ***output*** será entregue uma ***related_party_document_key*** que identifica o documento enviado.
### Request
ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/related_party/{external_related_party_key}/document`
MÉTODO `POST`
STATUS `201`
### Request body
Exemplo: Documento de Identificação (CNH)
```json title='Request Body'
{
"type": "cnh",
"document_b64": "base64_encoded_document_content",
"file_extension": "pdf"
}
```
Exemplo: RG (Frente e Verso)
```json title='Request Body - Frente'
{
"type": "rg_front",
"document_b64": "base64_encoded_document_content",
"file_extension": "pdf"
}
```
```json title='Request Body - Verso'
{
"type": "rg_back",
"document_b64": "base64_encoded_document_content",
"file_extension": "pdf"
}
```
Exemplo: Procuração (para tipo attorney)
```json title='Request Body'
{
"type": "power_of_attorney",
"document_b64": "base64_encoded_document_content",
"file_extension": "pdf"
}
```
### Body params
| Campo | Tipo | Descrição | Caracteres | Obrigatório |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `type` | string | Tipo de documento | 1 - 50 | Sim |
| `document_b64` | string | Base 64 do documento | - | Sim |
| `file_extension` | string | Extensão do arquivo (pdf, png, jpeg) | 1 - 10 | Sim |
### Document Type (Related Party)
| Enumerador | Descrição | Extensões Suportadas | Uso |
|-----------------------------------|-----------------------------|-----------------------------|-------------------------------------|
| `cnh` | CNH | pdf, jpeg | Identificação (opção 1) |
| `rg_front` | Frente do RG | pdf, jpeg | Identificação (opção 2, com `rg_back`) |
| `rg_back` | Verso do RG | pdf, jpeg | Identificação (opção 2, com `rg_front`) |
| `passport` | Passaporte | pdf, jpeg | Identificação de parte estrangeira |
| `foreign_id` | Identidade estrangeira | pdf, jpeg | Identificação de parte estrangeira |
| `power_of_attorney` | Procuração | pdf, jpeg | Complementar, para `attorney` |
### Documentos Obrigatórios
A exigência é avaliada no envio para análise (`submit`) e recusada com `IVR000030`. Basta satisfazer **uma** das opções.
#### Parte relacionada pessoa física residente
| Opção | Documentos |
|-------|---------------------------------|
| 1 | `cnh` |
| 2 | `rg_front` **+** `rg_back` |
#### Parte relacionada pessoa física não residente
| Opção | Documentos |
|-------|------------------|
| 1 | `passport` |
| 2 | `foreign_id` |
#### Parte relacionada pessoa jurídica (`parent_company`)
Nenhum documento é exigido.
:::info Procuração
Para uma parte relacionada do tipo `attorney`, `power_of_attorney` é **obrigatório e complementar**: ele é exigido *além* da identificação, e não a substitui. A parte continua precisando de `cnh` ou do par `rg_front` + `rg_back`. A falta da procuração é recusada com `IVR000148`.
:::
### Reenvio e documento duplicado {#duplicado}
Um tipo é considerado satisfeito assim que existe, para aquela parte relacionada, um documento daquele tipo com status `valid` ou `in_manual_analysis`. Novos envios do mesmo tipo passam a ser recusados:
```json
HTTP 409
{
"title": "Already exists valid document for related party.",
"code": "IVR000141"
}
```
Enquanto **todos** os documentos de um tipo estiverem `invalid`, novos envios continuam sendo aceitos.
### Response
```json title='Response Body'
{
"related_party_document_key": "UUID",
"status": "in_manual_analysis"
}
```
:::info Validação automática
O documento é validado automaticamente após o upload. O status pode ser:
- `valid`: validado automaticamente
- `invalid`: reprovado na validação automática
- `in_manual_analysis`: encaminhado para conferência humana
Para documentos reprovados, é possível forçar o envio usando o parâmetro `force=true`. Ao utilizar essa flag o documento será submetido para avaliação manual, necessariamente — e passa a satisfazer a exigência do tipo.
:::
---
# Consultar Formulário Suitability
URL: /documentation/iaas/investidor/compartilhado/suitability/consultar_formulario_suitability
:::warning Atenção
O envio do `suitability` ***NÃO*** é necessário para investidores que sejam **Fundos de Investimento** ou **Pessoas Jurídicas** enquadradas como **qualificadas** ou **profissionais**.
:::
### Request:
:::info
O formulário suitability muda de acordo com o `person_type` do investidor sendo cadastrado. Para obter o formulário suitability a ser respondido é necessário realizar uma consulta no formulário vigente para o tipo de investidor.
:::
ENDPOINT `/investor_registry/v2/suitability_form`
MÉTODO `GET`
STATUS `200`
### Query params
| Campo | Tipo | Descrição | Caracteres | Obrigatório |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `person_type` | enumerator | `natural_person` \| `legal_person` | - | Sim |
### Response
Caso 01: Pessoa Jurídica
```json
{
"01": {
"title": "Por quanto tempo a empresa pretende manter seu dinheiro investido?",
"options": {
"A": {
"title": "Pretende manter os recursos aplicados em até 1 ano e utilizar parte importante ou a integridade dos recursos desta carteira nesse período."
},
"B": {
"title": "Pretende manter os recursos aplicados entre 2 e 3 anos e utilizar parte importante ou a integridade dos recursos desta carteira nesse período."
},
"C": {
"title": "Pretende manter os recursos aplicados entre 4 e 5 anos e utilizar os recursos desta carteira após esse período."
},
"D": {
"title": "Pretende manter os recursos aplicados por um período acima de 5 anos e não tem planos de utilizar esses recursos, por enquanto."
}
}
},
"02": {
"title": "Qual objetivo do investimento da empresa e a sua tolerância em relação aos riscos?",
"options": {
"A": {
"title": "Preservação do capital para não perder valor ao longo do tempo, assumindo baixos riscos de perdas."
},
"B": {
"title": "Aumento gradual do capital ao longo do tempo, assumindo médios riscos de perdas."
},
"C": {
"title": "Aumento do capital acima da taxa de retorno média do mercado, mesmo que isso implique assumir riscos de perdas elevadas."
},
"D": {
"title": "Obter no curto prazo retornos elevados e significativamente acima da taxa de retorno média do mercado, assumindo riscos elevados."
}
}
},
"03": {
"title": "Com quais produtos de investimento a pessoa responsável pela tomada de decisões sobre investimentos em nome da empresa tem familiaridade (conhecimento do produto e dos riscos envolvidos)?",
"options": {
"A": {
"title": "Renda Fixa (CDB, Tesouro Direto e Fundos de Renda Fixa)."
},
"B": {
"title": "Renda Fixa (LCI, LCA, Debêntures, CRI, CRA, Fundos de Renda Fixa, etc)."
},
"C": {
"title": "Renda Fixa, Fundos Multimercados, Renda Variável e Derivativos."
},
"D": {
"title": "Renda Fixa, Fundos Multimercados, Renda Variável e Operações Estruturadas (Fundos Estruturados, COE, Swaps e Derivativos)."
}
}
},
"04": {
"title": "Com quais produtos de investimento a empresa realizou operações 3 ou mais vezes nos últimos 2 anos?",
"options": {
"A": {
"title": "Não investi nos últimos 2 anos ou investi menos de 3 vezes."
},
"B": {
"title": "Renda Fixa (LCI, LCA, Debêntures, CRI, CRA, Fundos de Renda Fixa, etc)."
},
"C": {
"title": "Renda Fixa, Fundos Multimercados, Renda Variável e Derivativos."
},
"D": {
"title": "Renda Fixa, Multimercados, Renda Variável e Operações Estruturadas (Fundos Estruturados, COE, Swaps e Derivativos)."
}
}
},
"05": {
"title": "Qual a composição mais aproximada do seu portfólio de investimentos?",
"options": {
"A": {
"title": "Não possuo recursos investidos."
},
"B": {
"title": "A totalidade dos recursos está aplicada em Renda Fixa (CDB, Tesouro Direto e Fundos de Renda Fixa)."
},
"C": {
"title": "Entre 70% e 90% dos recursos estão aplicados em Renda Fixa (LCI, LCA, Debêntures, CRI, CRA, Fundos de Renda Fixa, etc) e entre 10% e 30% dos recursos estão aplicados em Fundos Multimercados, Renda Variável e Derivativos."
},
"D": {
"title": "Mais de 50% dos recursos estão aplicados em Renda Fixa, Fundos Multimercados, Renda Variável e Operações Estruturadas (Fundos Estruturados, COE, Swaps e Derivativos)."
}
}
},
"06": {
"title": "Qual a faixa de faturamento médio mensal?",
"options": {
"A": {
"title": "Até R$ 500.000,00."
},
"B": {
"title": "De R$ 500.000,01 a R$ 1.000.000,00."
},
"C": {
"title": "De R$ 100.000,01 a R$ 5.000.000,00."
},
"D": {
"title": "Acima de R$ 5.000.000,01."
}
}
},
"07": {
"title": "Indique a faixa que corresponde ao valor total do patrimônio da empresa (bens móveis, imóveis, etc.:",
"options": {
"A": {
"title": "Até R$ 500.000,00."
},
"B": {
"title": "De R$ 500.000,01 a R$ 1.000.000,00."
},
"C": {
"title": "De R$ 100.000,01 a R$ 5.000.000,00."
},
"D": {
"title": "Acima de R$ 5.000.000,01."
}
}
},
"08": {
"title": "Sobre os ativos que compõem o patrimônio da empresa, qual o percentual dos seus ativos financeiros (ex: aplicações financeiras)?",
"options": {
"A": {
"title": "Cerca de 30% são ativos financeiros."
},
"B": {
"title": "Cerca de 40% são ativos financeiros."
},
"C": {
"title": "Cerca de 60% são ativos financeiros."
},
"D": {
"title": "Cerca de 70% são ativos financeiros."
}
}
}
}
```
Caso 02: Pessoa Física
```json
{
"01": {
"title": "Durante qual período pretende manter os seus investimentos e qual a sua necessidade de utilização dos recursos ao longo do tempo?",
"options": {
"A": {
"title": "Pretende manter os recursos aplicados em até 1 ano e utilizar parte importante ou a integridade dos recursos desta carteira nesse período."
},
"B": {
"title": "Pretende manter os recursos aplicados entre 2 e 3 anos e utilizar parte importante ou a integridade dos recursos desta carteira nesse período."
},
"C": {
"title": "Pretende manter os recursos aplicados entre 4 e 5 anos e utilizar os recursos desta carteira após esse período."
},
"D": {
"title": "Pretende manter os recursos aplicados por um período acima de 5 anos e não tem planos de utilizar esses recursos, por enquanto."
}
}
},
"02": {
"title": "Qual objetivo do investimento e o seu perfil em relação à tolerância a riscos?",
"options": {
"A": {
"title": "Preservação do capital para não perder valor ao longo do tempo, assumindo baixos riscos de perdas."
},
"B": {
"title": "Aumento gradual do capital ao longo do tempo, assumindo médios riscos de perdas."
},
"C": {
"title": "Aumento do capital acima da taxa de retorno média do mercado, mesmo que isso implique assumir riscos de perdas elevadas."
},
"D": {
"title": "Obter no curto prazo retornos elevados e significativamente acima da taxa de retorno média do mercado, assumindo riscos elevados."
}
}
},
"03": {
"title": "Com quais produtos de investimento você tem familiaridade (conhecimento do produto e dos riscos envolvidos)?",
"options": {
"A": {
"title": "Renda Fixa (CDB, Tesouro Direto e Fundos de Renda Fixa)."
},
"B": {
"title": "Renda Fixa (LCI, LCA, Debêntures, CRI, CRA, Fundos de Renda Fixa, etc)."
},
"C": {
"title": "Renda Fixa, Fundos Multimercados, Renda Variável e Derivativos."
},
"D": {
"title": "Renda Fixa, Fundos Multimercados, Renda Variável e Operações Estruturadas (Fundos Estruturados, COE, Swaps e Derivativos)."
}
}
},
"04": {
"title": "Com quais produtos de investimento você operou 3 ou mais vezes nos últimos 2 anos?",
"options": {
"A": {
"title": "Não investi nos últimos 2 anos ou investi menos de 3 vezes."
},
"B": {
"title": "Renda Fixa (LCI, LCA, Debêntures, CRI, CRA, Fundos de Renda Fixa, etc)."
},
"C": {
"title": "Renda Fixa, Fundos Multimercados, Renda Variável e Derivativos."
},
"D": {
"title": "Renda Fixa, Multimercados, Renda Variável e Operações Estruturadas (Fundos Estruturados, COE, Swaps e Derivativos)."
}
}
},
"05": {
"title": "Qual a composição mais aproximada do seu portfólio de investimentos?",
"options": {
"A": {
"title": "Não possuo recursos investidos."
},
"B": {
"title": "A totalidade dos recursos está aplicada em Renda Fixa (CDB, Tesouro Direto e Fundos de Renda Fixa)."
},
"C": {
"title": "Entre 70% e 90% dos recursos estão aplicados em Renda Fixa (LCI, LCA, Debêntures, CRI, CRA, Fundos de Renda Fixa, etc) e entre 10% e 30% dos recursos estão aplicados em Fundos Multimercados, Renda Variável e Derivativos."
},
"D": {
"title": "Mais de 50% dos recursos estão aplicados em Renda Fixa, Fundos Multimercados, Renda Variável e Operações Estruturadas (Fundos Estruturados, COE, Swaps e Derivativos)."
}
}
},
"06": {
"title": "Qual opção melhor representa seu conhecimento sobre produtos e serviços financeiros a partir da sua formação acadêmica e experiência profissional?",
"options": {
"A": {
"title": "Não concluí o ensino superior e minha experiência profissional não aprimorou meu conhecimento sobre produtos e serviços financeiros."
},
"B": {
"title": "Concluí o ensino superior, mas minha experiência profissional não aprimorou meu conhecimento sobre produtos e serviços financeiros."
},
"C": {
"title": "Não concluí o ensino superior, mas pela minha experiência profissional desenvolvi conhecimento suficiente sobre produtos e serviços."
},
"D": {
"title": "Concluí o ensino superior e pela minha experiência profissional desenvolvi conhecimento suficiente sobre produtos e serviços financeiros."
}
}
},
"07": {
"title": "Qual a sua renda mensal?",
"options": {
"A": {
"title": "Até R$ 5.000,00."
},
"B": {
"title": "De R$ 5.000,01 a R$ 15.000,00."
},
"C": {
"title": "De R$ 15.000,01 a R$ 30.000,00."
},
"D": {
"title": "Acima de R$ 30.000,01."
}
}
},
"08": {
"title": "Qual é o valor do seu patrimônio? [ativos não financeiros (residência, terrenos, casa de campo e/ou praia, outros ativos) + ativos financeiros (aplicações financeiras).",
"options": {
"A": {
"title": "Até R$ 500.000,00."
},
"B": {
"title": "De R$ 500.000,01 a R$ 1.500.000,00."
},
"C": {
"title": "De R$ 1.500.000,01 a R$ 3.000.000,00."
},
"D": {
"title": "Acima de R$ 3.000.000,01."
}
}
},
"09": {
"title": "Sobre os ativos que compõem o seu patrimônio, qual o percentual dos seus ativos financeiros (ex: aplicações financeiras)?",
"options": {
"A": {
"title": "Cerca de 30% são ativos financeiros."
},
"B": {
"title": "Cerca de 40% são ativos financeiros."
},
"C": {
"title": "Cerca de 60% são ativos financeiros."
},
"D": {
"title": "Cerca de 70% são ativos financeiros."
}
}
}
}
```
---
# Enviar Resposta Suitability
URL: /documentation/iaas/investidor/compartilhado/suitability/enviar_suitability
---
### Introdução
Este recurso tem como objetivo enviar as respostas fornecidas para o formulário suitability respondido pelo investidor.
### Input / Output:
Os dados cadastrais mudam de acordo com os dados passados na etapa de **Criar investidor**. Segue abaixo exemplos de quais dados devem ser enviados para cada variação.
Como ***output*** será entregue uma ***investor_key*** e uma ***investor_analysis_key***. A ***investor_analysis_key*** é utilizada para identificar a **análise cadastral** atualizada.
A ***investor_key*** é utilizada para identificar o **investidor** ao qual a **análise cadastral** pertence.
:::warning Atenção
O envio do `suitability` é **opcional** para investidores que sejam Pessoa Jurídica enquadradas como qualificadas ou profissionais.
:::
:::info Classe de fundo (`fund_class`) — etapa pulada
Classes de fundo **não respondem suitability**. O bloco não é exigido no `submit` para esse subtipo. Pule esta etapa.
:::
### Request
ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/suitability`
MÉTODO `PUT`
STATUS `202`
Exemplo - Pessoa Jurídica
```json title='Request Body'
{
"01": "A",
"02": "A",
"03": "A",
"04": "A",
"05": "A",
"06": "A",
"07": "A",
"08": "A",
"09": "A"
}
```
### Body params
| Campo | Tipo | Descrição | Caracteres | Obrigatório |
|-------------------------|--------|----------------------------------------------------------------------------------------------------|------------|-------------|
| `01`..`NN` | string | Resposta para cada questão do formulário. Valor é a letra da alternativa (`A`–`D`) | 1 | Sim* |
\* As chaves numéricas (`01`, `02`, ...) representam o número da questão; o valor deve ser uma única letra maiúscula correspondente à alternativa escolhida.
### Response
A análise cadastral atualizada é retornada no corpo da resposta.
---
# Introdução
URL: /documentation/iaas/investidor/inicio
Nesta seção iremos explicar as ferramentas disponibilizadas para consultar as informações relacionadas ao Investidor.
Para ter acesso a esses serviços, entre em contato com o time [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br), para que seja feito as devidas liberações, tanto em ambiente de Homologação (Sandbox), quanto em ambiente produtivo.
### Informações da Posição do Investidor
Nesta ferramenta é possível resgatar uma lista de informações da Posição de Investimento do investidor, conforme descrito em: [5.8.2 Informações da Posição do Investidor](/documentation/iaas/investidor/informacoes_posicao_investidor).
### Informações sobre Boletim de Subscrição
Nesta ferramenta é possível resgatar uma lista de informações sobre os boletins de subscrição do investidor, conforme descrito em: [5.8.4 Informações sobre Boletim de Subscrição](/documentation/iaas/passivo/controle_de_oferta/informacoes_boletins_de_subscricao).
---
# Aprovação do Gestor
URL: /documentation/iaas/venda_ativos/assignment/aprovacao_recompra
:::info Aos Gestores
É importante mencionar que essa rota está disponível somente para Gestores. Caso ele não seja integrado, pode-se realizar esta ação via Portal.
:::
### Request
ENDPOINT /trade_resolve/fund_class/FUND_CLASS_KEY/assignment/EXTERNAL_ID
MÉTODO PUT
```json title='Request Body'
{
"assignment_status": "approved"
}
```
#### Enumeradores Assignment Status
| Enumerador | Descrição |
|--------------|---------------|
| **approved** | Para aprovar o Lote |
| **reproved** | Para reprovar o Lote |
### Response
STATUS 201
```json title='Response Body'
{
"assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
"status": "approved",
}
```
---
# Recuperando Transações de uma Conta
URL: /documentation/iaas/visibildade_de_caixa/get_transaction_reversals
---
### Request
ENDPOINT /cash_account/account/ACCOUNT_KEY/transactions
MÉTODO GET
### Response
STATUS 200
```json title='Response Body'
{
"data": [
{
"transaction_key": "ed585534-8c05-431d-b829-0dc7883b24ba",
"transaction_type": "outgoing_wire_transfer",
"transaction_status": "pending_conciliation",
"transaction_description": "Descrição do pagamento",
"amount": -70000,
"transaction_datetime": "2025-01-01T14:00:00Z",
"account_balance": 500000,
"transaction_data": {
"counter_part_account": {
"owner": {
"name": "Nome da Contraparte",
"document_number": "***.805.49*-**"
},
"account_digit": "8",
"account_branch": "1",
"account_number": "1234567",
"financial_institution": {
"code": "329",
"ispb": "32402502"
}
},
},
"account": {
"account_key": "9c1d0c18-01ea-4c32-a878-1c6391f9aa44",
"account_type": "checking_account",
"financial_institution": {
"ispb": "32402502",
"code": "329",
"name": "QI Sociedade de Crédito Direto"
},
"account_status": "open",
"account_number": "3289018",
"account_digit": "7",
"account_branch": "0001",
"accounting_identification": 1,
"balance": 500000,
"owner": {
"name": "FUNDO TESTE",
"document_number": "93.625.214/0001-34"
},
"owner_document_number": "93.625.214/0001-34",
"account_configuration": {
"pix": true,
"wire_transfer": true
},
"billings": []
}
},
{
"transaction_key": "16c9c463-266e-4e73-b87d-efc32aa6727a",
"transaction_type": "incoming_wire_transfer",
"transaction_status": "reconciled",
"transaction_description": "Descrição",
"amount": 300000,
"transaction_datetime": "2025-06-04T13:00:00Z",
"account_balance": 570000,
"transaction_data": {
"counter_part_account": {
"owner": {
"name": "FUNDO TESTE",
"document_number": "93.625.214/0001-34"
},
"account_digit": "8",
"account_branch": "73",
"account_number": "567567",
"financial_institution": {
"code": "341",
"ispb": "60701190",
}
},
},
"account": {
"account_key": "9c1d0c18-01ea-4c32-a878-1c6391f9aa44",
"account_type": "checking_account",
"financial_institution": {
"ispb": "32402502",
"code": "329",
"name": "QI Sociedade de Crédito Direto"
},
"account_status": "open",
"account_number": "3289018",
"account_digit": "7",
"account_branch": "0001",
"accounting_identification": 1,
"balance": 500000,
"owner": {
"name": "FUNDO TESTE",
"document_number": "93.625.214/0001-34"
},
"owner_document_number": "93.625.214/0001-34",
"account_configuration": {
"pix": true,
"wire_transfer": true
},
"billings": []
},
"conciliation_group": {
"description": "TRANSFERÊNCIA: CONTA COBRANÇA -> CONTA PRINCIPAL",
"conciliation_group_key": "1ac2921c-6c81-481b-8472-6c4126bba4bf",
"conciliation_group_datetime": "2025-01-01T13:28:58Z"
}
}
],
"limit": 10,
"page": 0,
"is_last_page": true
}
```
### Query Params
| Campo | Tipo | Descrição |
|---------------|--------|----------------------------|
| `status` | string | Status da transação |
| `start_date` | string | Data inicial de consulta |
| `end_date` | string | Data final de consulta |
| `page` | string | Número da página recuperada|
### Response Fields
| Campo | Tipo | Descrição |
|---------------|--------|--------------------------------------------------------|
| `data` | array | Lista de objetos de **[Transaction](#transaction)** |
| `limit` | int | Limite de objetos recuperados por página |
| `page` | int | Número da página recuperada |
| `is_last_page`| boolean| Informação que indica se a página recuperada é a última|
### Transaction
| Campo | Tipo | Descrição | Caracteres |
|-----------------------------|--------|---------------------------------------------------|------------|
| `transaction_key` | string | Chave única identificadora da transação | 36 |
| `transaction_type` | string | Tipo de transação | Até 50 |
| `transaction_status` | string | status da transação | Até 50 |
| `transaction_description` | string | Descrição da transação fornecida pelo banco | Até 255 |
| `amount` | bigint | Valor da transação vezes 100 (ex: R$1,00 == 100) | - |
| `transaction_datetime` | string | Data e hora da transação | ISO 8601 |
| `account_balance` | bigint | Saldo da conta após a transação | - |
| `transaction_data` | JSON | Objeto com informações adicionais da transação | - |
| `account` | JSON | Objeto da conta contendo a transação | - |
### Account
| Campo | Tipo | Descrição | Caracteres |
|-----------------------------|--------|-------------------------------------|------------|
| `account_key` | string | Chave única identificadora da conta | 36 |
| `account_type` | string | Tipo de conta | Até 50 |
| `financial_institution` | JSON | Objeto de instituição financeira | - |
| `account_status` | string | Status da conta | Até 50 |
| `account_number` | string | Número da conta | Até 50 |
| `account_digit` | string | Digito da conta | 1 |
| `account_branch` | string | Agência da conta | Até 50 |
| `accounting_identification` | int | Identificador ordinal da conta | - |
| `balance` | int | Saldo da conta no momento | - |
| `owner` | JSON | Objeto de proprietário | - |
| `owner_document_number` | string | Documento do proprietário | 14 ou 18 |
:::caution **Atenção**
O saldo é disponibilizado concatenando reais e centavos ex.: 1234 = R$ 12,34
:::
### Finacial institution
| Campo | Tipo | Descrição | Caracteres |
|--------|--------|---------------------------------------------------|------------|
| `ispb` | string | Identificador de Sistema de Pagamentos Brasileiro | 8 |
| `code` | string | Código da instituição financeira | 3 |
| `name` | string | Nome da instituição financeira | Até 255 |
### Owner
| Campo | Tipo | Descrição | Caracteres |
|-------------------|--------|---------------------------|------------|
| `name` | string | Nome do proprietário | até 255 |
| `document_number` | string | Documento do proprietário | 14 ou 18 |
### Conciliation Group
| Campo | Tipo | Descrição | Caracteres |
|-------------------------------|--------|------------------------------------------|------------|
| `description` | string | Descrição da conciliação da transação | Até 255 |
| `conciliation_group_key` | string | Chave única identificadora da conciliação| 36 |
| `conciliation_group_datetime` | string | data e horário da conciliação | ISO 8601 |
---
# Introdução a Documentação
URL: /documentation/introducao_api_reference
Essa documentação tem como objetivo descrever e guiar o desenvolvedor a utilizar nossa API Rest.
## Introdução
Somos a primeira instituição financeira a criar um modelo exclusivo de Bank-as-a-Service (BaaS) do Brasil. Nosso objetivo é ajudar qualquer Fintech/Gestora de Crédito ou empresa a ter acesso a serviços financeiros rápidos, ágeis e seguros, da maneira que quiser. Saiba mais em https://qitech.com.br.
## Ambientes (Hosts)
A QI Tech possui infraestruturas completamente separadas para os ambientes SANDBOX e PRODUÇÃO, sendo que o ambiente de sandbox apresenta valores monetários totalmente fictícios, somente o ambiente de Produção realiza transações financeiras validas.
O ambiente Sandbox foi criado para os desenvolvedores realizarem suas integrações, e quando estiverem prontos para entrada em produção, atualizarem apenas as variáveis Host e Access Token com os parâmetros do ambiente de Produção.
Alem da divisão por ambientes, ainda contamos com a segregação dos HOSTs relacionados a serviços financeiros, Serviços de analise e serviços da certificadora QI Tech conforme tabela abaixo:
| Serviço | Ambiente | Host |
|-|-|-|
| BaaS e LaaS | Produção | https://api-auth.qitech.app/ |
| BaaS e LaaS | Sandbox | https://api-auth.sandbox.qitech.app/ |
| CaaS | Produção | https://api.caas.qitech.app/ |
| CaaS | Sandbox | https://api.sandbox.caas.qitech.app/ |
| CertifiQI | Produção | https://api.certifiqi.com.br/ |
| CertifiQI | Sandbox | https://api.sandbox.certifiqi.com.br/ |
| Insurance | Produção | https://api.insurance.qitech.app/ |
| Insurance | Sandbox | https://api.sandbox.insurance.qitech.app/ |
:::danger Aviso Importante!
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.
:::
Os ambientes estão sempre na mesma versão, portanto quando ocorre uma atualização em Produção, a mesma atualização ocorre no ambiente Sandbox.
## Primeiros Passos
Para começar a integrar com as APIs da QI Tech, siga os passos abaixo:
1. [Criação de Perfil de Acesso](/documentation/primeiros_passos/inicio)
2. [Troca de Chaves](/documentation/primeiros_passos/troca_de_chaves)
3. [Teste de Autenticação](/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2)
4. [Configuração de Webhooks](/documentation/primeiros_passos/configurando_webhooks)
## Como essa documentação esta dividida?
Após realizar os primeiros passos presentes na unidade "Primeiros Passos" já é possível consumir os micro-serviços da QI Tech em ambiente de sandbox.
Essa documentação esta dividida por produtos, são eles:
- **Banking as a Service**
- **Lending as a Service**
- **Risk Solutions**
- **Investment as a Service**
- **Insurance as a Service**
## Mensagens de Erro
:::danger Atenção!
As mensagens de erro retornadas pela QI não devem ser mapeadas de forma restrita. Campos adicionais podem ser incluídos futuramente nas mensagens de erro das nossas APIs.
:::
---
# Bem Vindo à Seção de Manuais das API's da QI Tech
URL: /documentation/introducao_manuais
Esta seção é destinada à orientação dos diferentes casos de uso das APIs da QI Tech.
## Crédito Consignado
- **[INSS](/documentation/guides/INSS/intro)** — Crédito Novo, Refinanciamento e Portabilidade para beneficiários INSS
- **[SIAPE-SIGEPE](/documentation/siape/manual_siape)** — Crédito Novo para servidores públicos federais
- **[Consignado Privado](/documentation/manual_consignado_privado/manual_detalhamento_fluxo_ativo)** — Originação via Leilão ou Ativa, consultas, emissão e averbação
- **[Previdência Privada](/documentation/manual_previdencia_privada/manual_previdencia_privada_consulta)** — Consulta, Crédito Novo e Averbação para previdência privada
- **[Saque Aniversário FGTS](/documentation/manual_FGTS/manual_fgts)** — Originação e Consulta de Autorização
## Cartões
- **[Pré-pago](/documentation/manual_pre_pago/casos_uso)** — Casos de uso do QI Cartões Pré-pago
- **[Cartão Consignado INSS](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_emissao)** — Emissão, Acompanhamento, Webhooks, Documentos e Gestão de Endereço
- **[QI Fatura](/documentation/manual_qi_fatura/pix_parcelado)** — Experiência de cartão com PIX Parcelado
## Portabilidade
- **[Port Out](/documentation/manual_portabilidade/portabilidade_out)** — Portabilidade de crédito
- **[Evidências de Retenção](/documentation/manual_portabilidade/evidencias_de_retencao)** — Evidências para retenção de portabilidade
## Outros Produtos
- **[QI Sign](/documentation/manual_qi_sign/manual_qi_sign)** — Assinatura eletrônica
- **[BNPL E-commerce](/documentation/manual_bnpl_ecommerce/manual_bnpl_ecommerce)** — Buy Now Pay Later para e-commerce
- **[Negociação de Direitos Creditórios](/documentation/iaas/negociacao_recebiveis/manual_api)** — Negociação e cessão de recebíveis
- **[Crédito Clean](/documentation/manual_credito_clean/emissao/emissao)** — Crédito Clean
## Cessão
- **[Cessão](/documentation/manual_cessao/)** — Fluxo de cessão de direitos creditórios ao cessionário
## Conciliação
- **[Conciliação](/documentation/manual_conciliacao/)** — Conciliação de portabilidade, renegociação, refinanciamento e cancelamento
---
# Bem Vindo à Seção de Manuais das API's da QI Tech
URL: /documentation/introducao_operational_guides
Esta seção é destinada à orientação dos diferentes casos de uso das APIs da QI Tech.
---
# Manual Consignado da Aeronáutica
URL: /documentation/manual_aeronautica/manual_consignado
---
:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita.
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::
:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::
:::info Funcionamento AERONÁUTICA
O sistema de consignações da Aeronáutica, via API, funciona 24 horas por dia, todos dias da semana, inclusive feriados.
:::
## 1. Autorização
Antes do envio de qualquer requisição de Consignado do Exército (Consulta, Emissão da dívida, etc), é necessário fazer o upload do consentimento do militar autorizando a QI a proceder com a consulta, averbação e manutenção em folha de pagamento.
Para upload da autorização, seguir o passo a passo encontrado na sessão de [**Upload de Documentos**](../upload_de_documentos/)
O upload retornará uma chave única no campo de retorno "**document_key**" que deverá ser enviado no payload de requisição de Consulta de Margem Consignável em "**authorization_document_key**", confome melhor detalhado à seguir, no item **[3. Consulta de Margem Consignável.](#3-consulta-de-margem-consignável)**
## 2. Simulação de Cenários de Sucesso nas Consultas de Saldos, Consulta de Lista de Contratos e Averbações em Sandbox
Para fins de teste, temos um conjunto de dados que podem ser utilizados para simular os casos de sucesso em sandbox, são eles:
| document_number | registration_code | token | birthdate |
|-----------------|--------------------|----------------|-----------|
| 60221284630 | 18571 | abc123 |1954-09-08 |
| 57343241400 | 72893 | abc123 |1998-02-06 |
| 13212590696 | 15410 | abc123 |1959-11-14 |
Essas informações devem ser enviadas no **payload da requisição** no momento da simulação e o resultado será enviado por meio do webhook de sucesso correspondente.
## 3. Consulta de Margem Consignável {#3-consulta-de-margem-consignavel}
Em posse dos dados de **CPF**, **Matrícula do militar** e a **Chave do Documento de Autorização**, o parceiro integrador pode realizar a **consulta assíncrona** da margem consignável do militar através do seguinte endpoint:
### Request
ENDPOINT /airforce_payroll/balance
MÉTODO POST
Request Body
```json
{
"document_number": "45507529710",
"registration_code": "146254221",
"authorization_document_key": "f2bc2369-89ea-4a80-9f64-ba7b1566cd31",
}
```
:::info
O CPF deve ser informados em formato de texto, com no máximo 11 caracteres, sem ".", sem "-" e alinhado com zeros à esquerda.
A Matrícula também deve ser no formato de texto.
:::
#### Request Body Params
| Campo | Tipo | Descrição |
|------------------------------|--------|-------------------------------------------|
| `document_number` | string | CPF do militar. |
| `registration_code` | string | Matrícula do militar. |
| `authorization_document_key` | uuid | **document_key** do termo de autorização. |
### Sincronous Response
ENDPOINT /airforce_payroll/balance
STATUS 201
Response Body
```json
{
"balance_key": "81da8afb-e1b2-4215-8093-c4b5feab8a9f",
"status": "pending_search"
}
```
**Por ser assíncrono, os dados da consulta de margem do tomador serão retornados via webhook.**
#### Response Body Params
| Campo | Tipo | Descrição |
|------------------------------|--------|------------------------------------------------------------------------------------------------------------------------|
| `balance_key` | string | Chave de identificação da consulta de Margem Consignável. |
| `status` | enum | [Enumeradores de status de consulta de margem consignável abaixo.](#enumeradores-de-status-de-consulta-de-margem-consignável) |
#### Enumeradores de Status de Consulta de Margem Consignável {#enumeradores-de-status-de-consulta-de-margem-consignavel}
| Enumerador | Descrição |
|-------------------|-----------------------------------------------------------------------------|
| `pending_search` | Consulta de margem consignável pendente de resposta do sistema do exército. |
| `processed` | Consulta de margem consignável processada. |
:::info
O status ***'processed'*** refere-se apenas ao fato de que a requisição do saldo foi efetivamente eviada e processada, porém não diz respeito ao sucesso ou à falha da mesma, tal informação estará no payload enviado via **Webhook** explicado à seguir.
:::
### Consulta com sucesso
O webhook de sucesso será retornado da seguinte forma:
WEBHOOK_TYPE airforce_payroll.balance
Body
```json
{
"webhook_type": "airforce_payroll.balance.status_change",
"key": "81da8afb-e1b2-4215-8093-c4b5feab8a9f",
"event_datetime": "2023-05-28T08:43:29Z",
"status": "processed",
"data": {
"military_unit": "Aeronáutica Brasileira",
"military_branch": "IAE",
"category": "Ativo",
"name": "João da Silva",
"document_number": "12345678901",
"registration_code": "ABC123",
"balance": "15000.00",
"birth_date": "1980-01-01",
"grant_date": "2005-03-15",
"allowed_installment_numbers": 24
}
}
```
#### Response Body Params success
| Campo | Tipo | Descrição |
|------------------------------------|---------|----------------------------------------------------------------------------------|
| `webhook_type` | string | Tipo do webhook. |
| `key` | uuid | Chave de referência do webhook. Neste caso, se trata da **balance_key** |
| `event_datetime` | string | Data e hora do envio do webhook. |
| `status` | string | Status da consulta de margem consignável. |
| `data` | json | Campo que irá conter os dados referentes à consulta. |
| `data.military_unit` | string | Estabelecimento que o militar está cadastro no sistema eConsig. |
| `data.military_branch` | string | Orgão/organização militar que o militar está. |
| `data.category` | string | Categoria do militar. |
| `data.name` | string | Nome do militar. |
| `data.document_number` | string | CPF do militar. |
| `data.registration_code` | string | Matrícula do militar. |
| `data.balance` | string | Margem disponível para contratação de empréstimo consignado. |
| `data.birth_date` | string | Data de nascimento do militar. |
| `data.grant_date` | string | Data de admissão do militar. |
| `data.allowed_installment_numbers` | string | Número limite de parcelas de um empréstimo consignado para o militar consultado. |
### Consulta com falha
O webhook de falha será retornado da seguinte forma:
WEBHOOK_TYPE airforce_payroll.balance
Body
```json
{
"webhook_type": "airforce_payroll.balance.status_change",
"key": "81da8afb-e1b2-4215-8093-c4b5feab8a9f",
"event_datetime": "2023-05-28T08:43:29Z",
"status": "processed",
"data": {
"title": "insufficient_permission",
"description": "User Has insufficient permissions for this operation.",
"translation": "Usuario nao possui permissoes suficientes para essa operacao.",
"code": "ZP000329",
"extra_fields": {}
}
}
```
Cada tipo de erro **mapeado** possui um título, código e descrição mais detalhada. Caso ainda não tenha sido mapeado retornaremos no mesmo formato porém com o título ***unknown_response***. Salvo os campos idênticos, a tabela abaixo descreve com detalhes os parâmetros retornados.
#### Response body params failure
| Campo | Tipo | Descrição |
|---------------------------|--------|-------------------------------------------------------------------------------------------------------------------------|
| `data.title` | string |Título referente ao erro ocorrido. |
| `data.description` | string |Descrição detalhada em **inglês** do erro ocorrido. |
| `data.translation` | string |Tradução da decrição do erro ocorrido. |
| `data.code` | string |Código do erro recebido. **Os 3 últimos dígitos referem-se ao código de erro recebido pela Zetra.** (ex: ZP000***329***) |
| `data.extra_fields` | json |Campo destinado à possíveis atributos extras. |
---
### Requisição de uma Consulta de Margem Consignável
Caso o parceiro queira saber sobre o andamento de alguma entidade Balance criada, ele pode realizar uma requisição da mesma:
:::danger Atenção!
Recomendamos fortemente que utilizem o Webhook como referência nas informações da Consulta de Margem Consignável do tomador. Feature passível de remoção no futuro.
:::
#### Request
ENDPOINT /airforce_payroll/balance/[balance_key]
MÉTODO GET
#### Response
ENDPOINT /airforce_payroll/balance/[balance_key]
STATUS 200
Body
```json
{
"status": "processed",
"data": {
"military_unit": "Aeronáutica Brasileira",
"military_branch": "IAE",
"category": "Ativo",
"name": "João da Silva",
"document_number": "12345678901",
"registration_code": "ABC123",
"balance": "15000.00",
"birth_date": "1980-01-01",
"grant_date": "2005-03-15",
"allowed_installment_numbers": 24
}
}
```
## 4. Consulta da Lista de Contratos
Em posse dos dados de **CPF**, **Matrícula do militar** e **Token** do possível tomador, o parceiro integrador pode realizar a consulta da lista de contratos do militar disponíveis para compra através do seguinte endpoint:
### Request
ENDPOINT /airforce_payroll/portability_contracts_report
MÉTODO POST
Request Body
```json
{
"document_number": "45507529710",
"registration_code": "146254221",
"token": "abc1234"
}
```
:::info
O CPF deve ser informados em formato de texto, com no máximo 11 caracteres, sem ".", sem "-" e alinhado com zeros à esquerda. A Matrícula também deve ser no formato de texto.
:::
#### Request Body Params
| Campo | Tipo | Descrição |
|------------------------------|--------|-------------------------------------------|
| `document_number` | string | CPF do militar. |
| `registration_code` | string | Matrícula do militar. |
| `token` | string | Senha do militar. |
### Sincronous Response
ENDPOINT /airforce_payroll/portability_contracts_report
STATUS 201
Response Body
```json
{
"portability_contracts_report_key": "3e41a8afb-e1b2-4215-8093-c4b5feab529c" ,
"status": "pending_search"
}
```
**Por ser assíncrono, os dados da consulta da lista de contratos do tomador serão retornados via webhook.**
#### Response Body Params
| Campo | Tipo | Descrição |
|------------------------------------|--------|------------------------------------------------------------------------------------------------------------------------|
| `portability_contracts_report_key` | string | Chave de identificação da consulta da lista de contratos. |
| `status` | enum | [Enumeradores de status de consulta da lista de contratos.](#enumeradores-de-status-da-consulta-da-lista-de-contratos) |
#### Enumeradores de Status da Consulta da Lista de Contratos {#enumeradores-de-status-da-consulta-da-lista-de-contratos}
| Enumerador | Descrição |
|--------------------|-----------------------------------------------------------------------------|
| `pending_search` | Consulta da lista de contratos pendente de resposta do sistema do exército. |
| `processed` | Consulta da lista de contratos processada. |
:::info
O status ***'processed'*** refere-se apenas ao fato de que a requisição da consulta da lista de contratos foi efetivamente eviada e processada, porém não diz respeito ao sucesso ou à falha da mesma, tal informação estará no payload enviado via **Webhook** explicado à seguir.
:::
### Webhook da Consulta de Lista de Contratos
O webhook de sucesso será retornado da seguinte forma:
WEBHOOK_TYPE airforce_payroll.portability_contracts_report
Body
```json
{
"webhook_type": "airforce_payroll.portability_contracts_report.status_change",
"key": "3e41a8afb-e1b2-4215-8093-c4b5feab529c",
"event_datetime": "2023-05-28T08:43:29Z",
"status": "processed",
"data": {
"document_number": "45507529710",
"contracts" : [
{
"econsig_id": "2361529",
"consignatory": "BANCO XPTO",
"contract_date": "2022-01-03T15:01:57Z",
"installment_amount": 10.0,
"number_of_installments": 5,
"number_of_paid_installments": 1,
"contract_status":"in_progress"
},
{
"econsig_id": "2361529",
"consignatory": "BANCO XPTO",
"contract_date": "2022-01-03T15:01:57Z",
"installment_amount": 10.0,
"number_of_installments": 5,
"number_of_paid_installments": 1,
"contract_status":"in_progress"
}
]
}
}
```
#### Response Body Params
| Campo | Tipo | Descrição |
|---------------------------------------------------|---------|----------------------------------------------------------------------------------|
| `webhook_type` | string | Tipo do webhook. |
| `key` | uuid | Chave de referência do webhook. Neste caso, se trata da **balance_key** |
| `event_datetime` | string | Data e hora do envio do webhook. |
| `status` | string | Status da consulta de margem consignável. |
| `data` | json | Campo que irá conter os dados referentes à consulta. |
| `data.document_number` | string | CPF do militar. |
| `data.contracts` | array | Lista dos contratos e de suas respectivas informações. |
| `data.contracts.econsig_id` | string | Identificador único do contrato no sistema da Zetra. |
| `data.contracts.consignatory` | string | Consignatária do contrato. |
| `data.contracts.installment_amount` | float | Valor da parcela. |
| `data.contracts.number_of_installments` | int | Número total de parcelas do contrato. |
| `data.contracts.number_of_paid_installments` | int | Número de parcelas pagas até a vigência atual. |
| `data.contracts.contract_status` | string | Situação do contrato. |
As possíveis Situações de Contrato estão mapeadas aqui.
| Situações do Contrato | contract_status |
|-----------------------------------|------------------------------|
|"Aguard. Confirmação" | `waiting_confirmation` |
|"Suspensa Pelo Gestor." | `suspend_by_manager` |
|"Aguard. Liquidação" | `waiting_closure` |
|"Aguard. Liquidação Portabilidade" | `waiting_portability_closure`|
|"Aguard. Margem" | `waiting_balance` |
|"Encerrado por Exclusão" | `closed_by_exclusion` |
|"Aguard. Deferimento" | `waiting_approval` |
|"Indeferida" | `rejected` |
|"Deferida" | `accepted` |
|"Em Andamento" | `in_progress` |
|"Suspensa" | `suspended` |
|"Cancelada" | `canceled` |
|"Liquidada" | `settled` |
|"Concluído" | `completed` |
:::info
Estas situações de contrato referem-se também às possíveis situações dos contratos internos.
:::
### Requisição de uma Consulta de Lista de Contratos
Caso o parceiro queira saber sobre o andamento de uma Consulta de Lista de Contratos, ele pode realizar uma requisição da mesma:
:::danger Atenção!
Recomendamos fortemente que utilizem o Webhook como referência nas informações da Lista de Contratos do tomador. Feature passível de remoção no futuro.
:::
#### Request
ENDPOINT /airforce_payroll/portability_contracts_report/[portability_contracts_report_key]
MÉTODO GET
#### Response
ENDPOINT /airforce_payroll/portability_contracts_report/[portability_contracts_report_key]
STATUS 200
Body
```json
{
"status": "processed",
"data": {
"document_number": "45507529710",
"contracts" : [
{
"econsig_id": "2361529",
"consignatory": "BANCO XPTO",
"contract_date": "2022-01-03T15:01:57Z",
"installment_amount": 10.0,
"number_of_installments": 5,
"number_of_paid_installments": 1,
"contract_status":"in_progress"
},
{
"econsig_id": "2361529",
"consignatory": "BANCO XPTO",
"contract_date": "2022-01-03T15:01:57Z",
"installment_amount": 10.0,
"number_of_installments": 5,
"number_of_paid_installments": 1,
"contract_status":"in_progress"
}
]
}
}
```
## 5. Simulação da Operação de Crédito Pessoal
Primeiramente é preciso calcular o valor da operação de Crédtio Pessoal necessária para quitar a operação de crédito original.
O valor do saldo devedor da dívida original deve ser informado no campo _**disbursed_amount**_.
:::caution Aviso
A operação deve ser simulada com apenas 1 parcela, desembolso em **D0** e a parcela deve ter seu vencimento para **D+5 dias úteis**, contas a partir da data de desembolso (pagamento) da operação.
:::
### Request
ENDPOINT /debt_simulation
MÉTODO POST
```json title='Request Body'
{
"borrower": {
"person_type": "natural"
},
"financial": {
"disbursed_amount": 80492.95,
"monthly_interest_rate": 0.03,
"credit_operation_type": "ccb",
"disbursement_date": "2023-03-17",
"issue_date": "2023-03-17",
"fine_configuration": {
"contract_fine_rate": 0,
"interest_base": "workdays",
"monthly_rate": 0
},
"interest_grace_period": 0,
"interest_type": "pre_price_days",
"number_of_installments": 1,
"principal_grace_period": 0,
"first_due_date_delay": 5
}
}
```
---
## 6 .Simulação da Operação de Crédito Consignado da AERONÁUTICA
Nesta simulação os campos informados terão seus valores atribuidos da seguinte forma:
_**installment_face_value**_ = Valor da margem consignável
_**disbursement_date**_ = **D+5 dias úteis** do momento da simulação
_**due_balance**_ = **total_amount** da 1ª parcela retornada na simulação da Operação de Crédito Pessoal
_**original_deadline**_ = Prazo total em dias da Operação de Crédito Pessoal (5 dias)
### Request
ENDPOINT /debt_simulation
MÉTODO POST
```json title='Request Body'
{
"borrower": {
"person_type": "natural"
},
"financial": {
"first_due_date": "2023-06-10",
"installment_face_value": 100.0,
"disbursement_date": "2023-03-22",
"number_of_installments": 96,
"monthly_interest_rate": 0.0205,
"interest_type": "pre_price_days",
"fine_configuration": {
"monthly_rate": 0.01,
"interest_base": "calendar_days",
"contract_fine_rate": 0.02
},
"credit_operation_type": "ccb",
"interest_grace_period": 0,
"principal_grace_period": 0
},
"collaterals": [{
"collateral_type": "airforce_payroll"
}],
"refinanced_credit_operations": [
{
"due_balance": 1250.20,
"original_deadline": 120
}
]
}
```
O campo _**data.final_disbursement_amount**_ retornado na simulação será o valor do troco pago ao cliente.
---
### Consulta do valor de parcela da operação de Crédito Pessoal
#### Request
ENDPOINT /debt?key=[DEBT-KEY]&eval_present_value=True&calculate_delay=True&calculate_spread=False
MÉTODO GET
:::info Informação
A DEBT-KEY é a chave retornada na resposta da criação da operação (resposta do /debt)
:::
---
## 7. Criação da conta de titularidade do devedor
Antes da digitação das propostas é necessário abrir uma conta para o devedor na QI Tech.
A conta será utilizada para receber o desembolso da Operação de Crédito Pessoal, realizar os pagamentos do saldo devedor da dívida original em outro banco (via Boleto, TED ou Pix).
### Request
ENDPOINT /account
MÉTODO POST
```json title='Request Body'
{
"is_operation_account": true,
"account_owner": {
"address": {
"city": "São Paulo",
"complement": "s/c",
"neighborhood": "Pinheiros",
"number": "215",
"postal_code": "12345012",
"state": "SP",
"street": "Gilberto Sabino"
},
"birth_date": "1961-01-30",
"document_identification": "261a8fbc-d998-4dd7-8515-ddebb212ae27",
"is_pep": false,
"mother_name": "Nome da Mãe do Devedor",
"nationality": "brasileiro",
"email": "email@email.com",
"individual_document_number": "12345678911",
"name": "Nome do Devedor",
"phone": {
"area_code": "11",
"country_code": "055",
"number": "900000000"
},
"person_type": "natural"
}
}
```
| Parâmetro | Descrição |
|--------------------------------------------------------------|----------------------------------------------------|
| **account_owner** | Dados do devedor |
| **is_operation_account** | Indicativo de que a conta é uma conta de operação. |
### Response
ENDPOINT /account
MÉTODO POST
```json title='Response Body'
{
"data": {
"account_info": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "1234567",
"financial_institution_code": "329"
},
"account_owner": {
"document_number": "12345678911",
"name": "Nome do Devedor"
}
},
"event_datetime": "2023-03-21 12:30:24",
"key": "8ff1e73f-e87b-4641-99a6-3267030c6034",
"status": "account_pending_operation",
"webhook_type": "account"
}
```
:::info
Os dados de conta retornados no /account deverão ser utilizados como conta de desembolso da Operação de Crédito Pessoal
:::
### Erro 5xx ou Timeout
O fluxo não deve prosseguir enquanto a conta não estiver abertua com sucesso.
Para os casos de falha, deve ser checado se a conta de fato não foi aberta para o cliente, antes de uma possível retentativa de abertura.
É possível checar se a conta foi aberta para o cliente, listando as conta abertas para um determinado CPF.
#### Request
ENDPOINT /account
MÉTODO POST
PARAMETER owner_document_number, requester_key
| Parâmetro | Descrição |
|---------------------------|------------------------------------|
| **owner_document_number** | CPF do devedor |
| **requester_key** | É uma chave interna da integração. |
#### Response
STATUS 200
```json title='Response Body'
{
"data": [{
...
"account_branch": "0001",
...
"account_digit": "2",
...
"account_key": "f600a6a9-0845-454f-b25c-a6d108ea582e",
"account_name": "Default",
"account_number": "1467576",
"account_status": {
"created_at": "2019-10-11T18:58:31",
"enumerator": "opened",
"translation_path": "account.AccountStatus.opened"
},
...
"owner_document_number": "09080702000105",
"owner_name": "Nome do Devedor",
...
}],
"pagination": {
"current_page": 1,
"next_page": null,
"rows_per_page": 100,
"total_pages": 1,
"total_rows": 1
}
}
```
:::info Informação
No payload de resposta acima, estão listados apenas os campos relevantes para leitura.
:::
---
## 8. Emissão das Operações
- **Operação de Crédito Pessoal**: Deve ser emitida com desembolso em D0 e com apenas uma parcela com vencimento para **D+5 dias úteis** do desembolso.
:::danger Atenção
Para emissão da Operação de Crédito Pessoal o objeto "_**financial**_", deve ser enviado com exatamente as mesmas informações enviadas na sua simulação.
:::
:::info Informação
A Operação de Crédito Pessoal, só pode desembolsar em **dias úteis** e nos seguintes horários, à depender do meio de pagamento do saldo devedor da dívida original:
- **TED**: desembolso entre **6:30 e 17:15**
- **Boleto**: desembolso entre **7:00 e 22:00**
- **Pix**: qualquer horário (mas é recomendado o desembolso em horário comercial, pois caso uma operação seja desembolsada de madrugada, por exemplo, a entrada do Pix pode ser rejeitada por suspeitas de fraude)
:::
### Emissão da Operação de Crédito Pessoal
Para emitir a Operação de Crédito Pessoal, é necessário enviar a informação dos Boletos/TEDs/Pix que precisam ser pagos após o desembolso da operação.
:::caution Atenção
O parceiro deve gerar uma chave interna de identificação da operação e enviá-la na requisição de emissão de dívida no campo "_**requester_identifier_key**_"
:::
#### Exemplos Resquests
ENDPOINT /debt
MÉTODO POST
**Boleto**
```json title='Request Body'
{
"borrower": {
"name": "Nome do Devedor",
"email": "email@email.com",
"phone": {
"number": "900000000",
"area_code": "11",
"country_code": "055"
},
"address": {
"city": "São Paulo",
"state": "SP",
"number": "215",
"street": "Gilberto Sabino",
"complement": "s/c",
"postal_code": "12345012",
"neighborhood": "Pinheiros"
},
"role_type": "issuer",
"birth_date": "1969-05-01",
"mother_name": "Nome da Mãe do Devedor",
"person_type": "natural",
"individual_document_number": "12345678911",
"gender": "male",
"nationality": "brasileiro",
"is_pep": false,
"marital_status": "married"
},
"financial": {
"disbursed_amount": 80492.95,
"annual_interest_rate": 0.20983,
"credit_operation_type": "ccb",
"disbursement_date": "2023-03-17",
"issue_date": "2023-03-17",
"fine_configuration": {
"contract_fine_rate": 0,
"interest_base": "workdays",
"monthly_rate": 0
},
"interest_grace_period": 0,
"interest_type": "pre_price_days",
"number_of_installments": 1,
"principal_grace_period": 0,
"first_due_date_delay": 5
},
"simplified": true,
"additional_data": {
"debt_payment": [{
"bank_slip": [{
"digitable_line": "10495419967200010004900031456924592920008049295",
"amount": "80492,95",
"beneficiary": "CAIXA ECONÔMICA FEDERAL",
"due_date": "2023-03-17"
}],
"funds_transfer": [],
"pix": [],
"financial_institution_code_number": "623"
}],
"issuer_account": {
"account_digit": "0",
"account_branch": "1234",
"account_number": "123456",
"financial_institution_code_number": "104"
},
"total_af_amount": 86186.52
},
"requester_identifier_key": "7ac52492-61c0-4dd6-a414-b0bf940fb7ca",
"disbursement_bank_account": {
"bank_code": "329",
"account_digit": "3",
"branch_number": "0001",
"account_number": "1234567"
},
"after_disbursement_actions": [{
"action_data": {
"digitable_line": "10495419967200010004900031456924592920008049295"
},
"action_type": "bankslip_payment"
}],
"modality": {
"code": "0203"
}
}
```
**TED**
```json title='Request Body'
{
"borrower": {
"name": "Nome do Devedor",
"email": "email@email.com",
"phone": {
"number": "900000000",
"area_code": "11",
"country_code": "055"
},
"address": {
"city": "São Paulo",
"state": "SP",
"number": "215",
"street": "Gilberto Sabino",
"complement": "s/c",
"postal_code": "12345012",
"neighborhood": "Pinheiros"
},
"role_type": "issuer",
"birth_date": "1969-05-01",
"mother_name": "Nome da Mãe do Devedor",
"person_type": "natural",
"individual_document_number": "12345678911",
"gender": "male",
"nationality": "brasileiro",
"is_pep": false,
"marital_status": "married"
},
"financial": {
"disbursed_amount": 80492.95,
"annual_interest_rate": 0.20983,
"credit_operation_type": "ccb",
"disbursement_date": "2023-03-17",
"issue_date": "2023-03-17",
"fine_configuration": {
"contract_fine_rate": 0,
"interest_base": "workdays",
"monthly_rate": 0
},
"interest_grace_period": 0,
"interest_type": "pre_price_days",
"number_of_installments": 1,
"principal_grace_period": 0,
"first_due_date_delay": 5
},
"simplified": true,
"additional_data": {
"debt_payment": [{
"bank_slip": [],
"funds_transfer": [{
"amount": "4736,07",
"account_digit": "0",
"account_branch": "0897",
"account_number": "20001",
"financial_institution_code_number": "341"
}],
"pix": [],
"financial_institution_code_number": "341"
}],
"issuer_account": {
"account_digit": "0",
"account_branch": "0491",
"account_number": "100021100",
"financial_institution_code_number": "104"
},
"total_af_amount": 86186.52
},
"requester_identifier_key": "7ac52492-61c0-4dd6-a414-b0bf940fb7ca",
"disbursement_bank_account": {
"bank_code": "329",
"account_digit": "3",
"branch_number": "0001",
"account_number": "1234567"
},
"after_disbursement_actions": [{
"action_data": {
"destination": {
"name": "Nome Credor Original",
"account_digit": "0",
"account_branch": "0897",
"account_number": "20001",
"document_number": "87163234000138",
"financial_institution_code_number": "341"
},
"transaction_amount": 4736.07
},
"action_type": "funds_transfer"
}],
"modality": {
"code": "0203"
}
}
```
**Chave Pix**
```json title='Request Body'
{
"borrower": {
"name": "Nome do Devedor",
"email": "email@email.com",
"phone": {
"number": "900000000",
"area_code": "11",
"country_code": "055"
},
"address": {
"city": "São Paulo",
"state": "SP",
"number": "215",
"street": "Gilberto Sabino",
"complement": "s/c",
"postal_code": "12345012",
"neighborhood": "Pinheiros"
},
"role_type": "issuer",
"birth_date": "1969-05-01",
"mother_name": "Nome da Mãe do Devedor",
"person_type": "natural",
"individual_document_number": "12345678911",
"gender": "male",
"nationality": "brasileiro",
"is_pep": false,
"marital_status": "married"
},
"financial": {
"disbursed_amount": 80492.95,
"annual_interest_rate": 0.20983,
"credit_operation_type": "ccb",
"disbursement_date": "2023-03-17",
"issue_date": "2023-03-17",
"fine_configuration": {
"contract_fine_rate": 0,
"interest_base": "workdays",
"monthly_rate": 0
},
"interest_grace_period": 0,
"interest_type": "pre_price_days",
"number_of_installments": 1,
"principal_grace_period": 0,
"first_due_date_delay": 5
},
"simplified": true,
"additional_data": {
"debt_payment": [{
"bank_slip": [],
"funds_transfer": [],
"pix": [{
"amount": "4736,07",
"account_digit": "0",
"account_branch": "0897",
"account_number": "20001",
"financial_institution_code_number": "341",
"ispb": "60701190"
}],
"financial_institution_code_number": "341"
}],
"issuer_account": {
"account_digit": "0",
"account_branch": "0491",
"account_number": "100021100",
"financial_institution_code_number": "104"
},
"total_af_amount": 86186.52
},
"requester_identifier_key": "7ac52492-61c0-4dd6-a414-b0bf940fb7ca",
"disbursement_bank_account": {
"bank_code": "329",
"account_digit": "3",
"branch_number": "0001",
"account_number": "1234567"
},
"after_disbursement_actions": [{
"action_data": {
"pix_transfer_type": "key",
"pix_key": "cahvepix@credororiginal.com.br",
"transaction_amount": 4736.07
},
"action_type": "pix"
}],
"modality": {
"code": "0203"
}
}
```
**Pix Manual**
```json title='Request Body'
{
"borrower": {
"name": "Nome do Devedor",
"email": "email@email.com",
"phone": {
"number": "900000000",
"area_code": "11",
"country_code": "055"
},
"address": {
"city": "São Paulo",
"state": "SP",
"number": "215",
"street": "Gilberto Sabino",
"complement": "s/c",
"postal_code": "12345012",
"neighborhood": "Pinheiros"
},
"role_type": "issuer",
"birth_date": "1969-05-01",
"mother_name": "Nome da Mãe do Devedor",
"person_type": "natural",
"individual_document_number": "12345678911",
"gender": "male",
"nationality": "brasileiro",
"is_pep": false,
"marital_status": "married"
},
"financial": {
"disbursed_amount": 80492.95,
"annual_interest_rate": 0.20983,
"credit_operation_type": "ccb",
"disbursement_date": "2023-03-17",
"issue_date": "2023-03-17",
"fine_configuration": {
"contract_fine_rate": 0,
"interest_base": "workdays",
"monthly_rate": 0
},
"interest_grace_period": 0,
"interest_type": "pre_price_days",
"number_of_installments": 1,
"principal_grace_period": 0,
"first_due_date_delay": 5
},
"simplified": true,
"additional_data": {
"debt_payment": [{
"bank_slip": [],
"funds_transfer": [],
"pix": [{
"amount": "4736,07",
"account_digit": "0",
"account_branch": "0897",
"account_number": "20001",
"financial_institution_code_number": "341",
"ispb": "60701190"
}],
"financial_institution_code_number": "341"
}],
"issuer_account": {
"account_digit": "0",
"account_branch": "0491",
"account_number": "100021100",
"financial_institution_code_number": "104"
},
"total_af_amount": 86186.52
},
"requester_identifier_key": "7ac52492-61c0-4dd6-a414-b0bf940fb7ca",
"disbursement_bank_account": {
"bank_code": "329",
"account_digit": "3",
"branch_number": "0001",
"account_number": "1234567"
},
"after_disbursement_actions": [{
"action_data": {
"pix_transfer_type": "manual",
"target_account": {
"name": "Nome Credor Original",
"account_digit": "0",
"account_branch": "0897",
"account_number": "20001",
"document_number": "87163234000138",
"financial_institution_code_number": "341"
},
"transaction_amount": 4736.07
},
"action_type": "pix"
}],
"modality": {
"code": "0203"
}
}
```
**QrCode Pix**
```json title='Request Body'
{
"borrower": {
"name": "Nome do Devedor",
"email": "email@email.com",
"phone": {
"number": "900000000",
"area_code": "11",
"country_code": "055"
},
"address": {
"city": "São Paulo",
"state": "SP",
"number": "215",
"street": "Gilberto Sabino",
"complement": "s/c",
"postal_code": "12345012",
"neighborhood": "Pinheiros"
},
"role_type": "issuer",
"birth_date": "1969-05-01",
"mother_name": "Nome da Mãe do Devedor",
"person_type": "natural",
"individual_document_number": "12345678911",
"gender": "male",
"nationality": "brasileiro",
"is_pep": false,
"marital_status": "married"
},
"financial": {
"disbursed_amount": 80492.95,
"annual_interest_rate": 0.20983,
"credit_operation_type": "ccb",
"disbursement_date": "2023-03-17",
"issue_date": "2023-03-17",
"fine_configuration": {
"contract_fine_rate": 0,
"interest_base": "workdays",
"monthly_rate": 0
},
"interest_grace_period": 0,
"interest_type": "pre_price_days",
"number_of_installments": 1,
"principal_grace_period": 0,
"first_due_date_delay": 5
},
"simplified": true,
"additional_data": {
"debt_payment": [{
"bank_slip": [],
"funds_transfer": [],
"pix": [{
"amount": "4736,07",
"account_digit": "0",
"account_branch": "0897",
"account_number": "20001",
"financial_institution_code_number": "341",
"ispb": "60701190"
}],
"financial_institution_code_number": "341"
}],
"issuer_account": {
"account_digit": "0",
"account_branch": "0491",
"account_number": "100021100",
"financial_institution_code_number": "104"
},
"total_af_amount": 86186.52
},
"requester_identifier_key": "7ac52492-61c0-4dd6-a414-b0bf940fb7ca",
"disbursement_bank_account": {
"bank_code": "329",
"account_digit": "3",
"branch_number": "0001",
"account_number": "1234567"
},
"after_disbursement_actions": [{
"action_data": {
"pix_transfer_type": "qr_code",
"qr_code": "00020126870014br.gov.bcb.pix2565qrcode.qitech.app/bacen/cobv/4ec760c4-b950-4afd-af10-92c1bb7804015204000053039865802BR5925SECURITIZADORA DE CREDITO6009SAO PAULO61080540700362070503***63042FA4"
},
"action_type": "pix"
}],
"modality": {
"code": "0203"
}
}
```
#### Enumeradores Marital Status
| Enumerador | Descrição |
|--------------|---------------|
| **single** | Solteiro(a) |
| **married** | Casado(a) |
| **widower** | Viúvo(a) |
| **divorced** | Divorciado(a) |
#### Erro 5xx ou Timeout
Caso seja retornado algum 5xx ou Timeout na requisição, afim de certificar que a operação de fato não foi criada na QI, é recomendado que o parceiro realize uma consulta da operação que teve retorno 5xx ou timeout.
ENDPOINT /debt?requester_identifier_key=34427233-925d-416d-93eb-c7f5084e8359
MÉTODO GET
Caso o retorno do GET seja um 200, o parceiro não deve retentar a criação da operação e seguir o fluxo da operação.
Caso seja retornado um 404 - Not Found, o parceiro deve retentar a criação da operação.
STATUS 200
```json title='Response Body'
{
"data": {
"additional_iof": 307.166388,
"annual_cet": "60,4731%",
"assignment_amount": 80833.26,
"base_iof": 33.141637696905995,
"borrower": {
"document_number": "12345678911",
"name": "Nome do Devedor"
},
"cet": "4,0200%",
"collaterals": [],
"contract": {
"external_contract_key": "351eada5-a626-404c-a3a3-f91c123270ce",
"number": "0000000001/NDD",
"signature_information": [{
"signature_url": "https://sign.qitech.com.br/s/hNrwjda",
"signer_document_number": "12345678911",
"signer_email": "email@email.com",
"signer_external_key": "56d105f3-a7f6-4442-95e9-71f44d2ae5fc",
"signer_name": "Nome do Devedor",
"signer_role": "issuer"
}],
"urls": [
"https://storage.googleapis.com/live-doc-api/documents/45e5b9c0-0f56-40a8-aace-d206f72c164d/QISCD-NOME_DO_DEVEDOR-CCB-0001212121-20230317194512.pdf"
]
},
"contract_fee_amount": 0,
"contract_fees": [],
"external_contract_fee_amount": 0,
"external_contract_fees": [],
"installments": [{
"accrual_reference_date": null,
"additional_costs": [],
"advanced_paid_amount": 0,
"bank_slip_key": null,
"business_due_date": "2023-03-22",
"calendar_days": 5,
"digitable_line": null,
"due_date": "2023-03-22",
"due_interest": 0,
"due_principal": 80833.26,
"fine_amount": null,
"has_interest": true,
"installment_history": [],
"installment_key": "75460851-2e82-4e3d-a805-b3e55b6b31d4",
"installment_number": 1,
"installment_payment": [],
"installment_status": "created",
"installment_type": "principal",
"original_due_principal": 80833.26,
"original_pre_fixed_amount": 183.5073246195304,
"original_principal_amortization_amount": 80833.26267538047,
"original_total_amount": 81016.77,
"paid_amount": 0,
"paid_at": null,
"post_fixed_amount": 0,
"pre_fixed_amount": 183.5073246195304,
"principal_amortization_amount": 80833.26267538047,
"qr_code_key": null,
"qr_code_url": null,
"renegotiation_proposal_key": null,
"tax_amount": 33.141637696905995,
"total_accrual_amount": null,
"total_amount": 81016.77,
"total_paid_amount": 0,
"workdays": 3
}],
"iof_charge_method": "financed",
"issue_amount": 80833.26,
"net_external_contract_fee_amount": 0,
"number_of_installments": 1,
"prefixed_interest_rate": {
"annual_rate": 0.20983,
"created_at": "2023-03-17T19:45:11",
"daily_rate": 0.00075616,
"interest_base": "workdays",
"monthly_rate": 0.01599997
},
"requester_identifier_key": "34427233-925d-416d-93eb-c7f5084e8359",
"total_iof": 340.31,
"total_pre_fixed_amount": 183.5073246195304
},
"event_datetime": "2023-03-17 19:45:19",
"key": "052fe83c-37f6-4339-a831-127b50566745",
"status": "waiting_signature",
"webhook_type": "debt"
}
```
:::info Informação
O campo "key" da resposta de criação da operação é a **DEBT-KEY**, que é a chave única da operação dentro da QI.
:::
#### Assinatura
#### Autorizar desembolso
Após assinatura da operação, é necessário autorizar a operação para desembolso.
ENDPOINT /debt/ [DEBT-KEY] /allow_disbursement
MÉTODO POST
```json title='Request Body'
{
"allow_disbursement": true
}
```
#### Desembolso
Após ser assinada e autorizada para desembolso, a operação seguirá automaticamente para esteira de desembolso.
Após o desembolso ser processado o parceiro receberá o seguinte webhook:
#### Sucesso no desembolso
WEBHOOK_TYPE debt
STATUS Disbursed
```json title='Webhook Body'
{
"key": "052fe83c-37f6-4339-a831-127b50566745",
"data": {
"installments": [{
"due_date": "2023-03-22",
"total_amount": 81016.77,
"installment_key": "75460851-2e82-4e3d-a805-b3e55b6b31d4",
"pre_fixed_amount": 183.5073246195304,
"principal_amortization_amount": 80833.26267538047
}],
"ted_receipt_list": []
},
"status": "disbursed",
"webhook_type": "debt",
"event_datetime": "2023-03-17 13:20:40"
}
```
#### Ações pós-desembolso
Após o desembolso da Operação de Crédito Pessoal na conta do devedor criada na QI, serão executados os pagamentos de boleto/TED/Pix referente à quitação do saldo devedor da dívida original do devedor (ações pós-desembolso)
#### Sucesso
WEBHOOK_TYPE after_disbursement_action_update
STATUS Success
**Boleto**
```json title='Webhook Body'
{
"key": "3bce3113-3644-4491-b87a-fe6551edff70",
"data": {
"status": "done",
"action_key": "d25097e2-09f1-47fc-8b7f-d1988b1a7669",
"error_data": null,
"action_data": {
"digitable_line": "10495419967200010004900031456924592920008049295"
},
"action_type": "bankslip_payment",
"execution_data": {
"bank_slip": {
"payer": {
"name": "Nome do Devedor",
"document_number": "12345678911",
"document_number_formatted": "123.456.789-11"
},
"beneficiary": {
"name": "CAIXA ECONÔMICA FEDERAL",
"document_number": "00360305000104",
"document_number_formatted": "00.360.305/0001-04"
},
"payment_key": "500a496e-4cca-4b12-9dc8-254932ebbcac",
"payment_date": "2023-03-08",
"digitable_line": "10495419967200010004900031456924592920008049295",
"expiration_date": "2023-03-10",
"payment_date_formatted": "08/03/2023",
"expiration_date_formatted": "10/03/2023",
"financial_institution_name": "CAIXA ECONÔMICA FEDERAL",
"financial_institution_compe_number": "104"
},
"origin_key": "dfac205a-bdef-4820-8608-2dc81d9e10d4",
"transacted_at": "2023-03-08 16:07:58",
"source_account": {
"owner_name": "Nome do Devedor",
"account_digit": "3",
"account_branch": "0001",
"account_number": "1234567",
"owner_document_number": "12345678911",
"financial_institution_name": "QI SCD S.A.",
"owner_document_number_formatted": "123.456.789-11",
"financial_institution_compe_number": 329
},
"source_subtype": "bank_slip_payment",
"transaction_key": "86a4320d-a69d-4c14-8300-9a6f22d35fcb",
"transacted_at_br": "2023-03-08 13:07:58",
"pdf_encoded_string": "\",
"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"
}
```
#### Erro na ação pós-desembolso
Em caso de erro no pagamento da ação pós-desembolso, o parceiro será notificado através do seguinte webhook:
WEBHOOK_TYPE after_disbursement_action_update
STATUS Error
**Boleto**
```json title='Webhook Body'
{
"key": "e358e7e3-17b8-4aab-9da1-92f6b78dea00",
"data": {
"status": "error",
"action_key": "e2495e5a-df32-4826-b6f0-419014d3c35a",
"error_data": {
"error_code": "QIT000007",
"description": "Account blocked balance cannot be negative."
},
"action_data": {
"digitable_line": "10495419967200010004900031456924592920008049295"
},
"action_type": "bankslip_payment",
"execution_data": null
},
"webhook_type": "after_disbursement_action_update",
"event_datetime": "2023-03-22 12:06:38"
}
```
**TED**
```json title='Webhook Body'
{
"key": "e358e7e3-17b8-4aab-9da1-92f6b78dea00",
"data": {
"status": "error",
"action_key": "e2495e5a-df32-4826-b6f0-419014d3c35a",
"error_data": {
"error_code": "QIT000007",
"description": "Account blocked balance cannot be negative."
},
"action_data": {
"destination": {
"name": "Nome Credor Original",
"account_digit": "0",
"account_branch": "0897",
"account_number": "20001",
"document_number": "87163234000138",
"financial_institution_code_number": "341"
},
"transaction_amount": 1000
},
"action_type": "funds_transfer",
"execution_data": null
},
"webhook_type": "after_disbursement_action_update",
"event_datetime": "2023-03-22 12:06:38"
}
```
#### Estorno da TED da ação pós-desembolso
Caso a TED realizada na ação pós-desembolso seja devolvida pela instituição financeira destinatária, o parceiro será notificado através do seguinte webhook:
WEBHOOK_TYPE after_disbursement_action_update
STATUS Refused
```json title='Webhook Body'
{
"key": "f4b5c36a-2aa1-4865-9678-e5a6fa585845",
"data": {
"status": "refused",
"action_key": "cf3b8809-36dc-4574-8763-3600e413cf5c",
"error_data": {
"code": "agencia_conta_invalida",
"description": "Agência ou Conta Destinatária do Crédito Inválida"
},
"action_data": {
"destination": {
"name": "SILVANA RAMOS DOS SANTOS",
"account_digit": "1",
"account_branch": "0150",
"account_number": "301771620",
"document_number": "30874011884",
"financial_institution_code_number": "237"
},
"transaction_amount": 3200
},
"action_type": "funds_transfer",
"action_amount": 3200.0
},
"webhook_type": "after_disbursement_action_update",
"event_datetime": "2023-03-23 14:46:39"
}
```
#### Retentar ação pós-desembolso com falha
Caso ocorra um erro/estorno no pagamento da ação pós-desembolso, ela pode ser retentada através do seguinte endpoint [/baas/action/**[ACTION-KEY]**](/documentation/emissao_de_divida/reprocessar_acao_pos_desembolso)
### Emissão da Operação de Crédito Consignado da Aeronáutica
A Operação de Crédito Consignado do Exército deve quitar a Operação de Crédito Pessoal e liberar (caso exista) o troco para o cliente
#### Request
ENDPOINT /debt
MÉTODO POST
**Digitação Portabilidade(s)**
```json title='Request Body'
{
"borrower": {
"name": "Nome do Devedor",
"email": "email@email.com",
"phone": {
"number": "900000000",
"area_code": "11",
"country_code": "055"
},
"address": {
"city": "São Paulo",
"state": "SP",
"number": "215",
"street": "Gilberto Sabino",
"complement": "s/c",
"postal_code": "12345012",
"neighborhood": "Pinheiros"
},
"role_type": "issuer",
"birth_date": "1969-05-01",
"mother_name": "Nome da Mãe do Devedor",
"person_type": "natural",
"individual_document_number": "12345678911",
"gender": "male",
"nationality": "brasileiro",
"is_pep": false,
"marital_status": "married"
},
"financial": {
"first_due_date": "2023-05-07",
"installment_face_value": 100.0,
"disbursement_date": "2023-03-22",
"limit_days_to_disburse": 3,
"number_of_installments": 72,
"monthly_interest_rate": 0.017,
"interest_type": "pre_price_days",
"fine_configuration": {
"monthly_rate": 0.01,
"interest_base": "calendar_days",
"contract_fine_rate": 0.02
},
"credit_operation_type": "ccb",
"interest_grace_period": 0,
"principal_grace_period": 0
},
"simplified": true,
"collaterals": [{
"percentage": 1,
"collateral_data": {
"reservation_type": "portability",
"portability_data":{
"token":"hw342y1h24",
"origin_econsig_ids": [
"2016587",
"2016588",
"2016589",
]
},
"registration_code": "12345678",
"reservation_method": "creation"
},
"collateral_type": "airforce_payroll"
}],
"requester_identifier_key": "7e000c2d-d381-470e-b233-416097504866",
"disbursement_bank_account": {
"bank_code": "341",
"account_digit": "3",
"branch_number": "1234",
"account_number": "1234567"
},
"purchaser_document_number": "32402502000135",
"modality": {
"code": "0202"
},
"refinanced_credit_operations": [
{
"operation_key": "d2fd3f63-3d11-42a8-ab5c-9a84b5c58b6c"
}
]
}
```
**Digitação Margem Livre**
```json title='Request Body'
{
"borrower": {
"name": "Nome do Devedor",
"email": "email@email.com",
"phone": {
"number": "900000000",
"area_code": "11",
"country_code": "055"
},
"address": {
"city": "São Paulo",
"state": "SP",
"number": "215",
"street": "Gilberto Sabino",
"complement": "s/c",
"postal_code": "12345012",
"neighborhood": "Pinheiros"
},
"role_type": "issuer",
"birth_date": "1969-05-01",
"mother_name": "Nome da Mãe do Devedor",
"person_type": "natural",
"individual_document_number": "12345678911",
"gender": "male",
"nationality": "brasileiro",
"is_pep": false,
"marital_status": "married"
},
"financial": {
"first_due_date": "2023-05-07",
"installment_face_value": 100.0,
"disbursement_date": "2023-03-22",
"limit_days_to_disburse": 3,
"number_of_installments": 72,
"monthly_interest_rate": 0.017,
"interest_type": "pre_price_days",
"fine_configuration": {
"monthly_rate": 0.01,
"interest_base": "calendar_days",
"contract_fine_rate": 0.02
},
"credit_operation_type": "ccb",
"interest_grace_period": 0,
"principal_grace_period": 0
},
"simplified": true,
"collaterals": [{
"percentage": 1,
"collateral_data": {
"reservation_type": "new_credit",
"registration_code": "123456789",
"reservation_method": "creation"
},
"collateral_type": "airforce_payroll"
}],
"requester_identifier_key": "7e000c2d-d381-470e-b233-416097504866",
"disbursement_bank_account": {
"bank_code": "341",
"account_digit": "3",
"branch_number": "1234",
"account_number": "1234567"
},
"purchaser_document_number": "32402502000135",
"modality": {
"code": "0202"
},
"refinanced_credit_operations": [
{
"operation_key": "d2fd3f63-3d11-42a8-ab5c-9a84b5c58b6c"
}
]
}
```
**Digitação Refinanciamento**
```json title='Request Body'
{
"borrower": {
"name": "Nome do Devedor",
"email": "email@email.com",
"phone": {
"number": "900000000",
"area_code": "11",
"country_code": "055"
},
"address": {
"city": "São Paulo",
"state": "SP",
"number": "215",
"street": "Gilberto Sabino",
"complement": "s/c",
"postal_code": "12345012",
"neighborhood": "Pinheiros"
},
"role_type": "issuer",
"birth_date": "1969-05-01",
"mother_name": "Nome da Mãe do Devedor",
"person_type": "natural",
"individual_document_number": "12345678911",
"gender": "male",
"nationality": "brasileiro",
"is_pep": false,
"marital_status": "married"
},
"financial": {
"first_due_date": "2023-05-07",
"installment_face_value": 100.0,
"disbursement_date": "2023-03-22",
"limit_days_to_disburse": 3,
"number_of_installments": 72,
"monthly_interest_rate": 0.017,
"interest_type": "pre_price_days",
"fine_configuration": {
"monthly_rate": 0.01,
"interest_base": "calendar_days",
"contract_fine_rate": 0.02
},
"credit_operation_type": "ccb",
"interest_grace_period": 0,
"principal_grace_period": 0
},
"simplified": true,
"collaterals": [{
"percentage": 1,
"collateral_data": {
"reservation_type": "refinancing",
"registration_code": "123456789",
"reservation_method": "issuing"
},
"collateral_type": "airforce_payroll"
}],
"requester_identifier_key": "7e000c2d-d381-470e-b233-416097504866",
"disbursement_bank_account": {
"bank_code": "341",
"account_digit": "3",
"branch_number": "1234",
"account_number": "1234567"
},
"purchaser_document_number": "32402502000135",
"modality": {
"code": "0202"
},
"refinanced_credit_operations": [
{
"operation_key": "d2fd3f63-3d11-42a8-ab5c-9a84b5c58b6c"
}
]
}
```
### Detalhamento de campos no objeto collateral_data
| Campo | Descrição | Valores |
|-----------------------|-----------------------------------------------|-------------------------------------------------------|
| reservation_type | Tipo da reserva | [Enumeradores](#reservation_type_enumerator) |
| registration_code | Matrícula do militar | 123456789 |
| reservation_method | Determina quando deve-se iniciar a tentativa de averbação do consignado, seja no momento da criação da operação de crédito ou no momento da emissão da mesma. | [Enumeradores](#reservation_method_enumerator) |
| portability_data | Dados de portabilidade | [Objeto de Portabilidade](#portability_data_object) |
### Tabela de tipos de reserva {#reservation_type_enumerator}
| Enumerador | Descrição |
|-------------|-----------------|
| new_credit | Crédito Novo |
| portability | Portabilidade |
| refinancing | Refinanciamento |
### Tabela de metodos de criação de reserva {#reservation_method_enumerator}
:::caution Atenção
Campo muito importante, pois ele determina diretamente quando o pedido de intensão de reserva na Zetra será feito.
:::
| Enumerator | Descrição |
|---------------|-----------------------------------------------------------------------------------------------------------------------|
| creation | A tentativa de averbação começará quando a operação de crédito for criada. |
| issuing | A tentativa de averbação começará quando a operação de crédito for emitida, ou seja, após a formalização da mesma. |
### Detalhamento de campos no objeto portability_data {#portability_data_object}
| Campo | Descrição | Valores |
|-----------------------|-----------------------------------------------------------|-------------------------------|
| token | Senha fornecida pelo militar | 1234abcd |
| origin_econsig_id | Código identificador de contrato da Zetra | 1234567 |
| origin_econsig_ids | Lista de códigos identificadores de contratos da Zetra | [1234567, 1234568, 1234569] |
#### Response
STATUS 200
```json title='Response Body'
{
"data": {
"borrower": {
"document_number": "12345678911",
"name": "Nome do Devedor",
"related_party_key": "1fe936e7-0917-4c3d-9206-87958254fa1d"
},
"collaterals": [{
"absolute_amount": null,
"collateral_constituted": false,
"collateral_data": {
"reservation_type": "new_credit",
"registration_code": "123456789"
},
"collateral_key": "c6006572-d66a-45f6-862d-4ecb5b9b5d2d",
"collateral_type": "airforce_payroll",
"created_at": "2023-03-17T20:56:09.200482",
"external_key": "1c736cd8-a4c7-43d4-8abd-c00ed0cd6450",
"percentage": 1,
"updated_at": "2023-03-17T20:56:09.200474"
}],
"contract": {
"number": "0000000003/NDD",
"signature_information": [{
"signature_url": null,
"signer_document_number": "12345678911",
"signer_email": "email@email.com",
"signer_external_key": null,
"signer_name": "Nome do Devedor",
"signer_role": "issuer"
}],
"urls": [
"https://storage.googleapis.com/live-doc-api/documents/ae66d0cd-1054-4ff5-b1d6-e03aaaa2ff1b/QISCD-NOME_DO_DEVEDOR-CCB-0000000002-20230317183044.pdf"
]
},
"disbursement_options": [{
"additional_iof": 24.220242,
"annual_cet": "26.1457%",
"assignment_amount": 3205.12,
"base_iof": 176.6603785598479778,
"cet": "1,9544%",
"contract_fee_amount": 17.68,
"contract_fees": [{
"amount": 17.68,
"amount_type": "absolute",
"fee_amount": 17.68,
"fee_type": "spread_cip_cost"
}],
"disbursement_date": "2023-03-22",
"external_contract_fee_amount": 0,
"external_contract_fees": [],
"first_due_date": "2023-05-07",
"installments": [{
"additional_costs": [],
"business_due_date": "2022-05-08",
"calendar_days": 34,
"due_date": "2023-05-07",
"due_interest": 0,
"due_principal": 3187.44,
"fine_amount": null,
"has_interest": true,
"installment_number": 1,
"installment_status": null,
"installment_type": null,
"post_fixed_amount": 0,
"pre_fixed_amount": 64.20069301315790,
"principal_amortization_amount": 35.79930698684210,
"tax_amount": 0.10014353287723266,
"total_amount": 100,
"workdays": 23
},
...
x 96
],
"issue_amount": 3187.44,
"net_external_contract_fee_amount": 0,
"total_iof": 100.44,
"total_pre_fixed_amount": 3225.1656904289435
},
...
x 15
],
"iof_charge_method": "financed",
"requester_identifier_key": "f7fa079e-e02f-469f-a9ba-7a550f8f665f"
},
"event_datetime": "2023-03-17 13:54:58",
"key": "23c89acf-b11b-4988-b738-a0f5ba238c33",
"status": "waiting_signature",
"webhook_type": "debt"
}
```
#### Averbação
Após a criação da Operação de Crédito Consignado do EXÉRCITO, a QI iniciará o processo de averbação da operação.
O processo de tentativa de averbação inicia no momento da criação da operação, e será retentado até a última data de opção de desembolso da operação.
A após a conclusão da averbação da margem consignável do exército, a QI notificará o parceiro através do seguinte webhook:
WEBHOOK_TYPE credit_operation.collateral
STATUS Success
```json title='Webhook Body'
{
"key": "23c89acf-b11b-4988-b738-a0f5ba238c33",
"data": {
"collateral_type": "airforce_payroll",
"collateral_constituted": true
},
"event_time": "2022-10-31 15:23:46",
"webhook_type": "credit_operation.collateral"
}
```
Caso o token informado não seja válido, enviaremos o seguinte webhook. Esse webhook também será enviado caso o token informado já tenha sido utilizado e seja necessário um novo.
WEBHOOK_TYPE credit_operation.collateral
STATUS Pending Valid Token
```json title='Webhook Body'
{
"key": "23c89acf-b11b-4988-b738-a0f5ba238c33",
"data": {
"collateral_type": "airforce_payroll",
"collateral_data": {
"reservation_status": "pending_valid_token",
"cancel_reason": "invalid_token",
},
"collateral_constituted": false,
},
"event_time": "2022-10-31 15:23:46",
"webhook_type": "credit_operation.collateral"
}
```
#### Resposta que ocasionam cancelamento automático
Dependendo da resposta da Zetra, a operação será cancelada automaticamente.
Quando isso ocorrer enviaremos um webhook no formato abaixo, o motivo do cancelamento é informado no campo "cancel_reason"
WEBHOOK_TYPE credit_operation.collateral
STATUS Canceled
```json title='Webhook Body'
{
"data": {
"cancel_reason": "Contrato de origem não encontrato.",
"cancel_reason_enumerator": "airforce_payroll_portability_not_found"
},
"event_datetime": "2023-10-10 15:45:21",
"key": "\",
"status": "canceled",
"webhook_type": "debt"
}
```
#### Tabela de enumeradores
| Enumerador | Descrição | Código da Zetra |
|-----------------------------------------------|---------------------------------------|------------------|
| airforce_payroll_military_not_found | Militar não encontrado. | 293 |
| airforce_payroll_portability_not_found | Contrato de origem não encontrato. | 294 |
| airforce_payroll_consignable_margin_exceeded | Margem disponível excedida. | 359 |
#### Expiração da Portabilidade
Após 10 dias, a Zetra cancela os pedidos de portabilidades que estão aguardando confirmação.
Desta forma, para reiniciar o fluxo de portabilidade, faz-se necessário um novo token válido. Caso exista um novo token válido, a proposta retorna para o passo de intenção de portabilidade (status da reserva: pending_reservation). No entanto, caso não exista um token válido, geralmente porque o token enviado já foi utilizado na intenção de portabilidade anterior, a proposta é atualizada para o status de pending_valid_token, aguardando o envio de um novo token. Com o envio de um novo token válido, a proposta segue normalmente o fluxo de intenção de portabilidade e confirmação.
Para informar a situação será enviado o seguinte webhook:
WEBHOOK_TYPE credit_operation.collateral
STATUS Pending Reservation/Pending Valid Token
```json title='Webhook Body'
{
"key": "23c89acf-b11b-4988-b738-a0f5ba238c33",
"data": {
"collateral_type": "airforce_payroll",
"collateral_data": {
"reservation_status": "pending_reservation" ou "pending_valid_token",
"cancel_reason": "expired_portability",
},
},
"event_time": "2022-10-31 15:23:46",
"webhook_type": "credit_operation.collateral"
}
```
## 9. Envio de novo Token de Portabilidade
O token de portabilidade é de uso único, portanto, é necessário que um novo token seja enviado quando o anterior for utilizado ou no caso de token inválido.
A forma de envio é uma chamada simples:
### Request
ENDPOINT /debt/[DEBT-KEY]/collateral
MÉTODO PATCH
Request Body
```json
{
"portability_data": {
"token": "12345678"
}
}
```
### Casos de sucesso
ENDPOINT /debt/[DEBT-KEY]/collateral
STATUS 204
Response Body - No content
### Caso de erro
:::info
Somente o token deverá ser enviado nessa requisição, caso contrário o processo retornará um erro
:::
#### Response
ENDPOINT /debt/[DEBT-KEY]/collateral
STATUS 400
Response Body
```json
{
"title": "Bad Request",
"description": "Additional properties are not allowed ( was unexpected)",
"translation": "Schema Inválido",
"code": "QIT000001"
}
```
## 10. Cancelamento e Desaverbação:
Para realizar o cancelamento definitivo de uma operação, com a desaverbação da margem consignável, deve ser utilizado o seguinte endpoint:
:::caution Atenção
Vale ressaltar que o processo de desaverbação é assíncrono, ou seja, o cancelamento da operação de crédito, NÃO signifca necessáriamente que a desaverbação foi concluída. Para consultar o status da desaverbação vide [Recuperar resposta da última request](#recuperar-ultima-request)".
:::
:::caution Atenção
O cancelamento definitivo também pode ocorrer de forma automática, isso acontece quando uma operação está no status "canceled" por mais de 7 dias.
:::
### Request
ENDPOINT /debt/[DEBT-KEY]/cancel_permanently
MÉTODO POST
#### Cancelamento da operação com sucesso:
Após a conclusão do cancelamento da operação, o parceiro receberá o seguinte webhook:
WEBHOOK_TYPE debt
STATUS Canceled Permanently
Body
```json
{
"key": "\",
"data": {},
"status": "canceled_permanently",
"webhook_type": "debt",
"event_datetime": "2022-11-01 03:46:31"
}
```
#### Desaverbação com sucesso
Após a conclusão da desaverbação, o parceiro receberá o seguinte webhook:
incluímos esse webhook de confirmação que a reserva foi desaverbada. Só existe em exército por enquanto. Como ainda não temos o last_response pro get /collateral, esse webhook seria importante pro cliente saber se foi desaverbada.
Se achar que pode gerar confusão, a gte remove.
Seria a mesma ideia de webhook do pending_consent etc. -->
WEBHOOK_TYPE debt
STATUS Canceled Permanently
Body
```json
{
"key": "\",
"data": {
"collateral_data": {
"reservation_status": "deleted"
},
"collateral_type": "airforce_payroll",
"collateral_constituted": false
},
"event_datetime": "2022-11-01 03:46:31",
"webhook_type": "credit_operation.collateral",
"event_datetime": "2022-11-01 03:46:31"
}
```
## 11. Recuperar resposta da última Request {#recuperar-ultima-request}
O ***last_response*** é uma forma de mapear, de forma simples e objetiva, a resposta da comunicação entre a QI e a Zetra, possibilitando saber quando essa requisição foi feita e qual o retorno obtido (através de um enumerador).
Cada enumerador tem uma descrição detalhada. Podemos conferir abaixo, com mais detalhes, como serão apresentados os dados do last response.
### Casos de sucesso
#### Request
ENDPOINT /debt/[DEBT-KEY]/collateral
MÉTODO GET
#### Response
ENDPOINT /debt/[DEBT-KEY]/collateral
STATUS 200
Response Body
```json
{
"collateral_constituted": true,
"collateral_type": "airforce_payroll",
"updated_at": "2023-05-24 19:13:02",
"collateral_data": {
"status": "reserved",
"last_response": {
"success": [
{
"enumerator": "succesfully_reserved"
}
]
},
"last_response_event_datetime": "2023-05-22T19:13:02Z"
}
}
```
Response Body Portability or Refin
```json
{
"collateral_constituted": true,
"collateral_type": "airforce_payroll",
"collateral_data": {
"status": "reserved",
"last_response": {
"success": [
{
"enumerator": "successfully_reserved"
}
]
},
"last_response_event_datetime": "2023-08-09T19:25:09Z",
"portability_data": {
"origin_econsig_id": "2016587",
"token": "123456"
}
}
}
```
#### Tabela de enumeradores
| Enumerador | Descrição | Detalhes | Status da reserva |
|-----------------------------------|----------------------------------|--------------------------------------------------------------------| ---------------------|
| successfully_accepted | Reservation request accepted | O pedido de averbação foi aceito e está aguardando confirmação | pending_confirmation |
| successfully_reserved | Reservation made successfully | A reserva foi averbada com sucesso | reserved |
| successfully_deleted | Reservation successfully deleted | A reserva foi desaverbada com sucesso | deleted |
### Casos de erro
#### Request
ENDPOINT /debt/[DEBT-KEY]/collateral
MÉTODO GET
#### Response
ENDPOINT /debt/[DEBT-KEY]/collateral
STATUS 200
Response Body
```json
{
"collateral_constituted": false,
"collateral_type": "airforce_payroll",
"updated_at": "2023-05-24 19:13:02",
"collateral_data": {
"status": "pending_reservation",
"last_response": {
"errors": [
{
"enumerator": "invalid_portability_token"
}
]
},
"last_response_event_datetime": "2023-05-22T19:13:02Z"
}
}
```
#### Tabela de enumeradores
| Enumerador | Descrição | Ação QI | Código correspondente da Zetra |
|-----------------------------|-------------------------------------------|---------|---------------------------------|
| waiting_confirmation | Waiting Confirmation on Portability | retry | |
| communication_error | Communication Error with Zetra | retry | 241 |
| consignable_margin_excceded | Exceeded consignable margin | retry | 359 |
## 12. Informe de Saldo Devedor
O informe de saldo devedor acontece no 5º dia útil após o dia da solicitação, e todos os contratos informados são enviados pelo webhook com as seguintes informações:
WEBHOOK_TYPE airforce_payroll.due_balance.status_change
STATUS processed
Response Body
```json
{
"webhook_type": "airforce_payroll.due_balance.status_change",
"status": "processed",
"event_datetime": "2024-03-12T19:23:12Z",
"data":{
"contract_number": "0000086715/TA",
"payment_amount": 284.28,
"balance_limit_date": "2024-03-12"
}
}
```
---
# Homologation Roadmap - BNPL
URL: /documentation/manual_bnpl_ecommerce/manual_bnpl
## Summary
This document guides clients through integrating Buy Now Pay Later (BNPL) with the QI Tech platform. It outlines the essential steps and provides answers to common questions.
## 1. Document Inquiry
The document inquiry can be performed using the following request:
### Request Body Upload
ENDPOINT /document/[document_key]/url
METHOD GET
Testar no Playground
### Path Params
| Field | Description |
|--------------- |------------------------------------------|
| `document_key` | Unique document key |
:::caution Attention
The document URL will be generated with an expiration period of 10 minutes.
:::
Response Body
```json
{
"document_key": "8a1e62f3-7add-4240-a51d-e0f1a2f421fa",
"document_url": "expirable_url",
"signed_document_url": "expirable_url",
"expiration_datetime": "2024-05-01T01:00:00.000Z"
}
```
## 2. Document upload
To receive the document_key for the debt issuance documents, you must upload them using the following request:
### Request Body Upload
ENDPOINT /upload
METHOD POST
Testar no Playground
Response Body
```json
{
"document_key": "cfbc8469-89ea-4a80-9f64-ba7b1566c68b",
"document_md5": "cd451103fa512frc98ce684d3896698c"
}
```
:::caution Atenção
Remember to save the **document_key**, as this key is required to query the document.
:::
### API call example
Example for uploading an image from a URL.
**Python**
```python
import jwt
import hashlib
import requests
from requests_toolbelt.multipart.encoder import MultipartEncoder
import json
from datetime import datetime
BASE_URL = "https://api-auth.sandbox.qitech.app"
API_KEY = "4c268c0a-53ff-429b-92b6-47ef98a6d89a" # This key is an example; please use your own key.
CLIENT_PRIVATE_KEY = ''''
-----BEGIN EC PRIVATE KEY-----
MIHbAgEBBEHh1hIeOPE5XNNhn6bxRAmVswsPZ0wZCmzVvP8Tl/LZK9ofVmRVGzll
srU1uezJEyHKYdOHrE2p52xUj+pHzjJvb6AHBgUrgQQAI6GBiQOBhgAEAAofUz1J
hBSOyGHLsnV9Sz0DSWmhl7U+ljqbfa8PKVFWSV3w16I1v2zME5/UzUhHn1gWsjnv
7/ekcLLAQbvqMPNXAfjIhFXLAPzqbB9iCuVua1v0Vgy52rBemOWrJka/Ws2bnKR8
h1N1OxOYeYr6C2jqMygBLktKMAs+282CEiEb4bIv
-----END EC PRIVATE KEY-----
''' # This key is an example; please use your own key.
def get_document(url):
try:
response = requests.get(url)
return response.content
except Exception as error:
print("Error fetching document:", error)
raise
def upload_document(array_buffer):
endpointeger= "/upload"
method = "POST"
timestamp = datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
md5_hash = hashlib.md5(array_buffer).hexdigest()
jwt_header = {
"typ": "JWT",
"alg": "ES512",
}
jwt_body = {
"payload_md5": md5_hash,
"timestamp": timestamp,
"method": method,
"uri": endpoint,
}
encoded_header_token = jwt.encode(jwt_body, CLIENT_PRIVATE_KEY, algorithm="ES512", headers=jwt_header)
signed_header = {
"Authorization": encoded_header_token,
"API-CLIENT-KEY": API_KEY,
"Content-Type": "multipart/form-data",
}
url = f"{BASE_URL}{endpoint}"
multipart_data = MultipartEncoder(
fields={'file': ('image.jpeg', array_buffer, 'image/jpeg')}
)
signed_header['Content-Type'] = multipart_data.content_type
try:
response = requests.post(url, headers=signed_header, data=multipart_data)
response_data = response.json()
document_key = response_data.get('document_key')
print(f'Response data is: {response_data} and document_key is: {document_key}')
return document_key
except Exception as error:
print('Error:', error)
raise
def main():
file_url = "{FILE_URL}"
document_buffer = get_document(file_url)
document_key = upload_document(document_buffer)
print("document_key is", document_key)
if __name__ == "__main__":
main()
```
**Node.js**
```js
const jwt = require('jsonwebtoken')
const crypto = require('crypto')
const axios = require('axios')
const FormData = require('form-data')
const fs = require('fs')
const fetch = require('node-fetch')
async function getDocument(url) {
try {
const response = await axios.get(url, { responseType: 'arraybuffer' })
return response.data
} catch (error) {
console.error('Error fetching document:', error)
throw error
}
}
async function uploadDocument(arrayBuffer) {
const endpointeger= '/upload'
const method = 'POST'
const timestamp = new Date().toISOString()
const md5_hash = crypto.createHash('md5').update(arrayBuffer).digest('hex')
const client_private_key = `-----BEGIN EC PRIVATE KEY-----
MIHbAgEBBEHh1hIeOPE5XNNhn6bxRAmVswsPZ0wZCmzVvP8Tl/LZK9ofVmRVGzll
srU1uezJEyHKYdOHrE2p52xUj+pHzjJvb6AHBgUrgQQAI6GBiQOBhgAEAAofUz1J
hBSOyGHLsnV9Sz0DSWmhl7U+ljqbfa8PKVFWSV3w16I1v2zME5/UzUhHn1gWsjnv
7/ekcLLAQbvqMPNXAfjIhFXLAPzqbB9iCuVua1v0Vgy52rBemOWrJka/Ws2bnKR8
h1N1OxOYeYr6C2jqMygBLktKMAs+282CEiEb4bIv
-----END EC PRIVATE KEY-----`; // This key is an example; please use your own key.
const api_key = '4c268c0a-53ff-429b-92b6-47ef98a6d89a' // This key is an example; please use your own key.
try {
const jwt_header = {
typ: 'JWT',
alg: 'ES512',
}
const jwt_body = {
payload_md5: md5_hash,
timestamp: timestamp,
method: method,
uri: endpoint,
}
const encoded_header_token = jwt.sign(jwt_body, client_private_key, {
algorithm: 'ES512',
header: jwt_header,
})
const signed_header = {
AUTHORIZATION: encoded_header_token,
'API-CLIENT-KEY': api_key,
'Content-Type': 'multipart/form-data',
}
const url = `${base_url}${endpoint}`
const formData = new FormData()
formData.append('file', Buffer.from(arrayBuffer), {
filename: 'image.jpeg',
})
fetch(url, {
method: 'POST',
headers: signed_header,
body: formData,
})
.then(data => {
console.log('Response data is: ' + data)
return data.document_key
})
.catch(error => {
console.log('Error: ' + error)
})
} catch (error) {
console.error('Error:', error)
}
}
async function main() {
const fileUrl = ''
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 |
---
# Manual CertifiQI
URL: /documentation/manual_certifiqi/dc37cf4f-adad-45c5-9251-9c957fb9ce8e
## Request
ENDPOINT /document
MÉTODO POST
Request Body
```json
{
"file_name": "nome.pdf",
"document_type": "ccb",
"document_identifier": "jfkjkd",
"endorsement_page": true,
"endorser_name": "NOME ENDOSSANTE",
"endorser_document_number": "CNPM ENDOSSANTE",
"receiver_name": "NOME ENDOSSATÁRIO",
"receiver_document_number": "CNPJ ENDOSSATÁRIO",
"control_number": "123456789"
}
```
O método POST /document deve ser utilizado para enviar os documentos (PDF ou CNAB) e vincular a um grupo de documentos.
Deverão ser enviados os seguintes dados no form-data da request:
- file - documento no formato pdf.
:::caution **Retorno desta request**
O retorno desta request deverá ser enviado posteriormente na request POST /batch_group. Depois de enviado junto com o batch_group não há necessidade de salvar esta informação.
:::
## Response
STATUS 200
Response Body
```json
{
"control_number": null,
"document_key": "45e781b8-7275-48e6-8719-b4d232b2828a",
"file_size": 281195,
"name": "ml1258-00822_22_carlos_cesar_consolaro_20221222095624158505.pdf",
"url": "https://storage.googleapis.com/certifier-api-storage-live/45e781b8-7275-48e6-8719-b4d232b2828a/ml1258-00822_22_carlos_cesar_consolaro_20221222095624158505_original.pdf"
}
```
## Definições
### Objeto Request Body
| Campo | Tipo | Descrição | Máx. Caract. |
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **file_name** * | string | Nome do arquivo que será enviado. | - |
| **document_type** * | string | Tipo do documento que será enviado. | - |
| **document_identifier** * | string | Identificador do documento do sistema do parceiro. | - |
| **endorsement_page** * | booleano | Indica se um endosso deve ser gerado para o documento. | - |
| **endorser_name** * | string | nome do endossante. | - |
| **endorser_document_number** * | string | Numero de documento do endossante. | - |
| **receiver_name** * | string | Nome do recebedor. | - |
| **receiver_document_number** * | string | Número de documento do recebedor. | - |
| **control_number** | string | Campo opcional indicando o numero de controle da cessão, fornecido pela QI Tech quando a cessão é realizada pela pela mesma. | 36 |
## Request
ENDPOINT /batch_group
MÉTODO POST
Request Body
```json
{
"client_key": "eb4d4f62-f209-47aa-bb99-24d4e056ae11",
"name": "Endosso",
"main_related_party": "MACACO LOCO LTDA",
"batches": [{
"documents": [
{
"control_number": null,
"document_key": "45e781b8-7275-48e6-8719-b4d232b2828a",
"file_size": 281195,
"name": "ml1258-00822_22_macaco_loco_20221222095624158505.pdf",
"url": "https://storage.googleapis.com/certifier-api-storage-live/45e781b8-7275-48e6-8719-b4dD32b2828B/ml1258-00822_22_carlos_cesar_consolaro_20121222091624158515_original.pdf"
}
],
"related_parties": [
{
"document_number": "00000000000000",
"name": "MACACO LOCO LTDA",
"role": "endorser"
}
],
"document_type": "endorsement",
"name": "Endosso",
"signature_type": "cades"
}],
"total_value": 0,
"send_emails": true,
"send_to_fund_administrator": false,
"requester_identifier": null
}
```
O método POST /batch_group deve ser utilizado para enviar todos os documentos e os assinantes
do evento para assinatura. Os dados que devem ser enviados no body da request estão disponíveis em Criar 'batch group.
## Response
STATUS 200
Response Body
```json
{
"batch_group_key": "6ab44a69-7089-4951-a27a-d58c4136ac11",
"name": "Endosso",
"main_related_party": "MACACO LOCO LTDA",
"number_of_documents": 131,
"total_value": 0.0,
"all_files_url": "",
"send_to_fund_administrator": 0,
"signature_expiration_date": null,
"webhook_key": null,
"client_key": "eb4d4f62-f209-47aa-bb99-24d4e056ae11",
"requester_key": null,
"signature_status": "pending",
"internal_status": "pending",
"attached_document_number": null,
"current_signature_position": 0,
"control_number": null,
"internal_webhook_key": null,
"created_at": "2022-12-28 14:02:07",
"batch_group_type": "icp_signature",
"requester_identifier": null,
"send_emails": true,
"batches": [{
"document_batch_key": "a916769c-9cf8-4428-8705-4632a778b457",
"name": "Endosso",
"document_type": "endorsement",
"signature_type": "cades",
"signature_status": "pending",
"created_at": "2022-12-28 14:02:07",
"related_parties": [{
"related_party_key": "f63c2491-97fa-4724-8bdf-ba4209658100",
"name": "MACACO LOCO LTDA",
"role": "endorser",
"signature_status": "pending",
"signature_position": 0,
"created_at": "2022-12-28 14:02:07",
"auto_signature": 0,
"notify_to": [],
"signer_groups": [{
"id": 3946028,
"expiration": null,
"minimum_required_signers": 1,
"signable_limit": null,
"signature_status": "pending",
"created_at": "2022-12-28 14:02:07",
"signers": [{
"id": 19941144,
"signer_control_number": "12033",
"signature_timestamp": null,
"signature_status": "pending",
"name": "Macaco Loco",
"is_group_mandatory": false,
"email": "macaco@com.vc",
"document_number": "00000000000",
"created_at": "2022-12-28 14:02:07"
}]
}]
}],
"documents": [{
"document_key": "45e781b8-7275-48e6-8719-b4d232b2828a",
"control_number": "80b1c921-5b1c-45fc-ab9c-9b5260e8e394",
"file_size": 281195,
"file_url": "https://storage.googleapis.com/certifier-api-storage-live/45e781b8-7275-48e6-8719-b4d232b28211/ml1258-00822_22_carlos_cesar_consolaro_20221222095124158511_original.pdf",
"name": "ml1258-00822_22_macaco_loco_20221222095624158511.pdf",
"original_file_url": "https://storage.googleapis.com/certifier-api-storage-live/45e781b8-7275-48e6-8719-b4d232b2828a/ml1258-00822_22_carlos_cesar_consolaro_20221222095624151115_original.pdf",
"status": "pending",
"signed_file_url": null,
"created_at": "2022-12-28 14:02:07",
"signatures": []
}]
}],
"watcher_clients": []
}
```
## Definições
### Objeto Request Body
| Campo | Tipo | Descrição | Máx. Caract. |
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **client_key** * | string | uuid representando a chave do parceiro. | - |
| **name** * | string | Nome dado ao grupo de documentos que será enviado. | - |
| **main_related_party** * | string | Nome da principal parte relacionada para assinar o evento (porém é um campo livre). | - |
| **batches** * | array of objects | Lista de diferentes tipos de documentos. | - |
| **total_value** * | float | Valor total dos documentos do evento. | - |
| **send_emails** * | boolean |Indica se os e-mails de assinatura devem ser enviados para este evento de assinatura. | - |
| **send_to_fund_administrator** * | boolean | Indica se o evento deve ser enviado para o FROMTIS caso o administrador do fundo o utilize. | - |
| **requester_identifier** * | string | Identificador do evento fornecido pelo parceiro.
### BATCHES OBJECT
| Campo | Tipo | Descrição | Máx. Caract. |
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **related_parties** * | array of objects | Partes relacionadas que assinam este batch. | - |
| **documents** * | array of objects | lista de documentos enviados no POST /document. | - |
| **name** * | string | NNome do arquivo. | - |
| **signature_type** * | string | Tipo de assinatura. | - |
| **document_type** * | string | Tipo de documento. | - |
### RELATED PARTIES OBJECT
| Campo | Tipo | Descrição | Máx. Caract. |
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **role** * | string | Cargo. | - |
| **name** * | string | Nome da Empresa. | - |
| **document_number** * | string | numero de documento do assinante. | - |
## Request
ENDPOINT /batch_group/ BATCH_GROUP_KEY /send_to_signature
MÉTODO POST
### Path Params
| Campo | Descrição |
|---|---|
| **batch_group_key** * | Chave única de identificação do evento de assinatura. |
O método POST /batch_group/ BATCH_GROUP_KEY /send_to_signature" finaliza o grupo de documentos e envia o lote para assinatura.
---
# Cessão
URL: /documentation/manual_cessao/
Este manual descreve o fluxo de Cessão de Direitos Creditórios operado pela QI Tech, desde a originação do ativo até o repasse ao originador.
## Visão Geral
:::info
O fluxo descrito nesta página se refere ao caso de CCB (Cédula de Crédito Bancário).
:::
O Originador origina os ativos utilizando o balanço da QI Tech para realizar o desembolso. A partir daí, o fluxo segue três grandes blocos:
```mermaid
graph LR
O[Originação do Ativo] --> D[Desembolso Pré-Cessão
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: /documentation/manual_conciliacao/
Este manual descreve o processo de conciliação de CCBs já cedidas ao cessionário (fundo), utilizado sempre que um evento altera a posição de uma operação cedida.
## Tipos de Conciliação
Existem conciliações para os seguintes eventos:
- Portabilidade
- Renegociação
- Refinanciamento
- Cancelamento
## Fluxo de Conciliação
Nesses casos, a QI Tech:
1. Envia um arquivo de baixa para o SFTP/Bucket combinado com o cessionário, com o nome de arquivo acordado entre as partes.
2. Envia uma transferência atrelada ao evento para a conta do fundo vinculado à operação.
## Contatos de Suporte
| Time | Contato |
|---|---|
| Tesouraria | suporte.cessao@qitech.com.br / suporte.conciliacao@qitech.com.br |
---
# Manual Consignado Privado - Contratos Legados
URL: /documentation/manual_consignado_privado/manual_contratos_legados
:::caution API em desenvolvimento
A API ainda está em fase de desenvolvimento, sendo assim, este manual esta sujeito a alterações.
:::
A renegociação de um contrato legado é feita a partir da criação de uma nova dívida, com os dados do contrato legado informados no campo *collateral_data*.
Para verificar os contratos legados que foram incluídos no sistema, deve-se realizar uma consulta aos empréstimos legados.
Em caso de não encontrar, favor entrar em contato com o suporte para solicitar a inclusão.
Devido à regra de negócio do Consignado Privado, atualmente o trabalhador pode ter apenas um contrato ativo.
Portanto, caso o trabalhador possua mais de um contrato legado, somente um deles poderá ser renegociado.
Da mesma forma, caso o trabalhador possua um contrato ativo, não será possível criar uma renegociação para o mesmo.
O fluxo de criação da dívida e de assinatura é o mesmo utilizado para a criação de um crédito novo. A diferença está na averbação da dívida, que é feita automaticamente pelo sistema após a assinatura do contrato, não necessitando de aprovação manual e não sendo necessária a consulta ao SCR.
## 1 - Consulta de empréstimos legados
**GET**
/private_payroll/legacy_contracts
Testar no Playground
### Query Parameters
| Parâmetro | Tipo | Obrigatório | Descrição | Valor Padrão |
|-----------------|---------|-------------|------------------------------------|--------------|
| page | integer | Não | Número da página a ser retornada | 1 |
| page_size | integer | Não | Quantidade de registros por página | 100 |
| document_number | string | Não | CPF do cliente sem pontuação | N/A |
:::info
A paginação é baseada em um, portanto a primeira página é a página 1.
:::
### Response
STATUS
**200** OK
```json
{
"data": [
{
"legacy_contract_key": "123e4567-e89b-12d3-a456-426614174000",
"document_number": "29883927061",
"contract_number": "1234567890",
"legacy_contract_data": {
"cet": 0.0637,
"due_balance": 1935,
"total_amount": 2405.76,
"contract_type": "consigned_loan",
"interest_rate": 0.0409,
"period_amount": 129.33,
"contract_end_date": "2026-10-05",
"number_of_periods": 36,
"contract_start_date": "2023-10-06",
"registration_number": "11841",
"number_of_paid_periods": 17,
"employer_document_number": "43028211000145"
},
"status": "active"
}
],
"pagination": {
"current_page": 1,
"next_page": 2,
"rows_per_page": 100,
"total_pages": 1,
"total_rows": 1
}
}
```
### Response Body
A resposta paginada é composta por um array de contratos (*data*) e um objeto de paginação (*pagination*).
#### Lista de contratos
Descrição dos itens do array *data*:
| Parâmetro | Tipo | Obrigatório | Descrição |
|----------------------|---------|-------------|----------------------------------------|
| legacy_contract_key | string | Sim | Identificador único do contrato legado |
| document_number | string | Sim | CPF do cliente |
| contract_number | string | Sim | Número do contrato |
| legacy_contract_data | object | Sim | Dados do contrato legado |
| status | string | Sim | Status do contrato |
#### Dados do contrato legado
Dados contidos no objeto *legacy_contract_data*:
| Parâmetro | Tipo | Obrigatório | Descrição |
|--------------------------|---------|-------------|-----------------------------|
| cet | decimal | Sim | Custo Efetivo Total |
| due_balance | decimal | Sim | Saldo devedor |
| total_amount | decimal | Sim | Valor total do contrato |
| contract_type | string | Sim | Tipo do contrato |
| interest_rate | decimal | Sim | Taxa de juros |
| period_amount | decimal | Sim | Valor da parcela |
| contract_end_date | string | Sim | Data de término do contrato |
| number_of_periods | integer | Sim | Número total de parcelas |
| contract_start_date | string | Sim | Data de início do contrato |
| registration_number | string | Sim | Matrícula do funcionário |
| number_of_paid_periods | integer | Sim | Número de parcelas pagas |
| employer_document_number | string | Sim | CNPJ do empregador |
#### Dados de paginação
Dados contidos no objeto *pagination*:
| Parâmetro | Tipo | Obrigatório | Descrição |
|---------------|---------|-------------|------------------------------------|
| current_page | integer | Sim | Página atual |
| next_page | integer | Sim | Próxima página |
| rows_per_page | integer | Sim | Quantidade de registros por página |
| total_pages | integer | Sim | Total de páginas |
| total_rows | integer | Sim | Total de registros |
## 2 - Exclusão de Contrato Legado
A exclusão de um contrato legado é realizada pelo seguinte endpoint:
**DELETE**
/private_payroll/legacy_contract/ contract_number
Testar no Playground
Onde o path parameter "contract_number" deve ser o contrato a ser excluído, em formato de string.
### Response
Em caso de sucesso será retornada a resposta:
STATUS
**200** OK
Enquanto no caso em que o contrato legado apontado não exista será retornado um erro de NotFound, com código de erro "PRP000079".
STATUS
**404** NOT FOUND
## 3 - Criação da renegociação
A renegociação de um contrato legado é realizada através da criação de uma dívida similar à criação de um crédito novo, com a diferença de que os dados do contrato legado deverão ser informados no campo *collateral_data* como exemplificado abaixo:
**POST**
/debt
Testar no Playground
```json
{
"simplified": true,
"requester_identifier_key": "05a9c4cc-39d5-48fe-ab47-8f1b37d8bffb",
"purchaser_document_number": "30620610000159",
"borrower": {
"role_type": "issuer",
"person_type": "natural",
"name": "EXEMPLO",
"email": "exemplo@exemplo.com",
"individual_document_number": "48674911013",
"birth_date": "1991-01-01",
"mother_name": "MÃE DO EXEMPLO",
"phone": {
"country_code": "55",
"area_code": "11",
"number": "999999999"
},
"address": {
"street": "RUA EXEMPLO",
"number": "123",
"complement": "APTO 123",
"neighborhood": "BAIRRO EXEMPLO",
"postal_code": "12345678",
"city": "SÃO PAULO",
"state": "SP"
},
},
"disbursement_bank_accounts": [
{
"name": "EXEMPLO",
"document_number": "48674911013",
"pix_transfer_type": "key",
"pix_key": "pix03@pix03.com",
"amount_receivable": 2000
},
{
"name": "Cel-lep Ensino De Idiomas S.a.",
"document_number": "10772420000140",
"digitable_line": "32990001039000210987502864982109595090000063958",
"amount_receivable": 639.58
}
],
"financial": {
"credit_operation_type": "ccb",
"interest_type": "pre_price_days",
"interest_grace_period": 0,
"principal_grace_period": 0,
"limit_days_to_disburse": 1,
"number_of_installments": 12,
"installment_face_value": 250,
"disbursement_date": "2025-05-12",
"disbursed_amount": 2639.58,
"first_due_date": "2025-07-28",
"fine_configuration": {
"interest_base": "calendar_days",
"contract_fine_rate": 0.02,
"monthly_rate": 0.01
},
},
"collaterals": [
{
"percentage": 1,
"collateral_type": "private_payroll",
"collateral_data": {
"registration_number": "g7D1IFvUmq2s7zE9UVsV0HQwfcbHj",
"employer_document_number": "60518978000171",
"operation_category": "legacy_contract_refinancing",
"legacy_contract_numbers": ["0000001523EMP"],
}
}
]
}
```
:::info
Caso tenha um representante legal, deverá ser informado no campo *related_parties* como exemplificado no exemplo de crédito novo.
```json
{
"related_parties": [
{
"role_type": "issuer_legal_representative",
"person_type": "natural",
"name": "REPRESENTANTE EXEMPLO",
"email": "representante.exemplo@exemplo.com",
"individual_document_number": "79795844067",
"birth_date": "1970-04-20",
"mother_name": "MÃE DO REPRESENTANTE",
"phone": {
"country_code": "55",
"area_code": "11",
"number": "999999999"
},
"address": {
"street": "RUA EXEMPLO",
"number": "123",
"complement": "APTO 123",
"neighborhood": "BAIRRO EXEMPLO",
"postal_code": "12345678",
"city": "SÃO PAULO",
"state": "SP"
}
}
]
}
```
:::
### Response
STATUS
**201** Created
```json title="Response Body"
{
"webhook_type": "debt",
"key": "",
"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"
}
}
]
}
}
```
---
# Seguro
URL: /documentation/manual_consignado_privado/manual_seguro
**Este manual passa pelas etapas do fluxo de emissão de crédito consignado privado atrelado à contratação de seguro.**
## 1. Simulação e emissão da dívida
Para simular e emitir uma dívida atrelada à emissão de um seguro, deve-se adicionar um objeto à lista de rebates dentro do objeto finantial.
:::warning Seleção do Produto
O enumerador _description_ é utilizado para definir o tipo de produto de seguro que será emitido, isto interfere diretamente no valor do prêmio e nas coberturas. Consulte a equipe de operações para saber quais enumeradores devem ser utilizados na sua integração.
:::
```json title='Objeto Rebate'
{
"rebates": [
{
"fee_type": "insurance_premium_qi",
"description": "insurance_premium_description"
}
]
}
```
### Exemplo de payload de simulação
POST /debt
request_body
```json
{
"borrower": {
"person_type": "natural"
},
"financial": {
"first_due_date": "2024-12-07",
"installment_face_value": 100,
"disbursement_date": "2024-11-05",
"limit_days_to_disburse": 3,
"number_of_installments": 4,
"monthly_interest_rate": 0.018,
"interest_type": "pre_price_days",
"fine_configuration": {
"monthly_rate": 0.01,
"interest_base": "calendar_days",
"contract_fine_rate": 0.02
},
"credit_operation_type": "ccb",
"interest_grace_period": 0,
"principal_grace_period": 0,
"rebates": [
{
"fee_type": "insurance_premium_qi",
"description": "insurance_premium_description"
}
]
}
}
```
### Exemplo payload de emissão
POST /debt_simulation
request_body
```json
{
"borrower": {
"name": "Nome devedor",
"email":"email.devedor@gmail.com",
"phone": {
"number": "999538380",
"area_code": "84",
"country_code": "055"
},
"gender": "female",
"political_exposition": "not_exposed",
"address": {
"city": "Natal",
"state": "RN",
"number": "1984",
"street": "Rua",
"complement": "complemento",
"postal_code": "59065720",
"neighborhood": "bairro"
},
"role_type": "issuer",
"birth_date": "1959-07-08",
"mother_name": "NOME DA MAE",
"nationality": "Brasileiro",
"person_type": "natural",
"marital_status": "single",
"attached_documents_list": [],
"individual_document_number": "14471835092",
"document_identification_date": "2015-10-02",
"document_identification_type": "rg",
"document_identification_number": "003709888"
},
"financial": {
"interest_type": "pre_price_days",
"first_due_date": "2023-09-21",
"disbursement_date": "2024-11-07",
"fine_configuration": {
"monthly_rate": 0.0166,
"interest_base": "calendar_days",
"contract_fine_rate": 0
},
"credit_operation_type": "ccb",
"interest_grace_period": 0,
"monthly_interest_rate": 0.0166,
"installment_face_value": 101.84,
"limit_days_to_disburse": 7,
"number_of_installments": 10,
"principal_grace_period": 0,
"rebates": [ // Opcional
{
"fee_type": "insurance_premium_qi",
"description": "insurance_premium_description"
}
]
},
"simplified": true,
"collaterals": [
{
"percentage": 1,
"collateral_type": "private_payroll",
"collateral_data": {
"employer_document_number": "07940839000159",
"registration_number": "99999999999-A"
}
}
],
"additional_data": {
"contract": {
"contract_number": "TST0000644799"
}
},
"purchaser_document_number": "32402502000135",
"disbursement_bank_accounts": [
{
"name": "NOME DEVEDOR",
"bank_code": "001",
"account_digit": "0",
"branch_number": "2874",
"account_number": "000057555",
"document_number": "14471835092",
"transfer_method": "pix",
"percentage_receivable": 100
}
]
}
```
## 2. Formalização
Durante o fluxo de formalização da dívida no QI Sign, serão apresentadas algumas telas para garantir a ciência e o consentimento do tomador em relação à contratação do seguro.
:::warning OPT-OUT
É possível que o tomador decida abandonar a contratação do seguro e seguir somente com a contratação do crédito, neste caso o valor que seria destinado ao prêmio do seguro também será desembolsado na conta do tomador.
:::
Junto ao webhook de formalização do crédito, será enviado um evento informando se o seguro foi aceito ou rejeitado no fluxo de formalização.
WEBHOOK_TYPE insurance_premium.status_change
Webhook Body
**Operação formalizada com seguro**
```json
{
"data": {
"credit_operation_key": "5ae2c008-44c1-4435-bbfa-094a4b11d962"
},
"event_datetime": "2023-03-03 22:39:39",
"key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
"status": "accepted",
"webhook_type": "insurance_premium.status_change"
}
```
**Operação formalizada sem seguro**
```json
{
"data": {
"credit_operation_key": "5ae2c008-44c1-4435-bbfa-094a4b11d962",
"rejection_reason": "insurance_rejected"
},
"event_datetime": "2023-03-03 22:39:39",
"key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
"status": "rejected",
"webhook_type": "insurance_premium.status_change"
}
```
## 3. Emissão do seguro
Após o sucesso no desembolso, será realizada a transferência do valor do prêmio e a emissão do seguro, para acompanhamento do status do seguro deve-se monitorar o seguinte webhook.
WEBHOOK_TYPE insurance_premium.status_change
Webhook Body
**Seguro emitido**
```json
{
"data": {
"credit_operation_key": "5ae2c008-44c1-4435-bbfa-094a4b11d962",
"insurance_policy_document_key": "9990ce22-aeac-4728-82da-d1f22c33873f",
"insurance_date": "2024-09-11",
"term_start_date": "2024-09-11",
"term_end_date": "2025-09-11",
"insurance_amount": 1600,
"operation_amount": 6400,
"covers": [
{
"cover_amount": 200,
"cover_type": "permanent_disability",
"cover_prize_amount": 572.82
},
{
"cover_amount": 100,
"cover_type": "accidental_death",
"cover_prize_amount": 572.82
},
{
"capitalcover_amount_segurado": 300,
"cover_type": "unemployment",
"cover_prize_amount": 572.82
}
],
"policy_number": "1098200000008",
"prize_number": "3907",
"insurance_premium_net_amount": 1145.63,
"iof_amount": 4.37
},
"event_datetime": "2023-03-03 22:39:39",
"key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
"status": "active",
"webhook_type": "insurance_premium.status_change"
}
```
**Seguro cancelado**
```json
{
"key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
"data": {
"cancel_reason": "reversed_operation",
"credit_operation_key": "2fbd6613-3228-5gdg-9377-93db394bf2d4"
},
"status": "canceled",
"webhook_type": "insurance_premium.status_change",
"event_datetime": "2023-03-03 22:39:39"
}
```
:::info Cancelamento do seguro
Para verificar os possíveis motivos de cancelamento do seguro, consulte a tabela [Motivo de cancelamento](#cancel-insurance).
:::
:::danger Envio obrigatório do bilhete ao tomador
É obrigatório que o pdf do bilhete seja enviado ao tomador após a emissão do seguro, o documento pode ser consultado através da **[consulta de documentos](../upload_de_documentos/consulta_documents)** utilizando a *insurance_policy_document_key* informada no webhook de emissão do seguro.
:::
:::info Testes em Sandbox
Para testar o cancelamento do seguro pode-se utilizar o seguinte endpoint:
POST /mock/insurance_premium/ [INSURANCE-PREMIUM-KEY] /cancel
:::
### Consulta de seguro
Para ativamente consultar as informações de um seguro pode-se utilizar o seguinte endpoint.
GET /debt/ [DEBT-KEY] /insurance_premium/ [INSURANCE-PREMIUM-KEY]
STATUS 200
Response Body
```json
{
"insurance_premium_key": "e4fe84e3-cc71-481b-87ea-8a07f7d69079",
"status": "active",
"credit_operation_key": "5ae2c008-44c1-4435-bbfa-094a4b11d962",
"disbursement_key": "bd0ea133-ff47-4a21-a3e6-24186e5e2fc1",
"contract_number": "4069550961/QIT",
"requester_key": "1040ce22-aeac-4728-82da-d1f22c33873f",
"insurance_policy_document_key": "9990ce22-aeac-4728-82da-d1f22c33873f",
"insurance_date": "2024-09-11",
"term_start_date": "2024-09-11",
"term_end_date": "2025-09-11",
"insurance_amount": 1600,
"operation_amount": 6400,
"customer": {
"customer_key": "cd587fa8-3abd-4023-99ab-957df60933a5",
"document_number": "08556878350",
"name": "Wilker Oliveiraço",
"birth_date": "1998-03-21",
"gender": "male",
"email": "urich.oliveira@yopmail.com",
"phone": {
"country_code": "55",
"area_code": "11",
"number": "966931427"
},
"address": {
"postal_code": "56821686",
"state": "CE",
"city": "Ceará",
"neighborhood": "Marmiteiros",
"street": "Conjunto João Gabriel da Mata",
"number": "95",
"complement": ""
}
},
"covers": [
{
"cover_amount": 300,
"cover_type": "permanent_disability",
"cover_prize_amount": 572.82
},
{
"cover_amount": 300,
"cover_type": "accidental_death",
"cover_prize_amount": 572.82
},
{
"cover_amount": 300,
"cover_type": "unemployment",
"cover_prize_amount": 572.82
}
],
"policy_number": "1098200000008",
"prize_number": "3907",
"insurance_premium_net_amount": 1145.63,
"iof_amount": 4.37
}
```
## Anexos
---
### Motivo de rejeição {#rejection_reason}
| Enumerador | Descrição |
|------------------------------------------ |-------------------------------------------------------|
| **insurance_rejected** | seguro rejeitado |
### Motivo de cancelamento {#cancel-insurance}
| Enumerador | Descrição |
|------------------------------------------ |-------------------------------------------------------|
| reversed_operation | Operação revertida e seguro cancelados|
| cover_limit_amount_exceeded | Somente o seguro foi cancelado. Algum limite de cobertura foi ultrapassado e não foi possível a emissão do seguro|
| insurance_premium_cancel | Somente o seguro foi cancelado. Cancelamento do tomador direto com a seguradora|
---
# Manual Consignado Privado - Tombamento do Legado
URL: /documentation/manual_consignado_privado/manual_tombamento_legado
:::caution API em desenvolvimento
A API ainda está em fase de desenvolvimento, sendo assim, este manual esta sujeito a alterações.
:::
## 1 - Pré requisitos
Para tombar um contrato para o novo modelo do empréstimo consignado, é necessário que este tenha sido informado previamente e esteja no status "active", caso ainda haja algum contrato legado que não foi informado ou que não esteja no status correto, favor informar o time de operações com urgência, no [manual de contratos legados](./manual_contratos_legados) está a documentação para consultar os contratos informados.
Além disso, por determinação da DATAPREV, é necessário que o tomador ainda esteja empregado no mesmo vínculo do contrato informado. É possível consultar os vínculos ativos do tomador sem enviar um termo de autorização utilizando a chamada abaixo (será validado se existe um contrato legado ativo para o mesmo CPF):
## 2 - Consulta de vínculos empregatícios para tombamento:
A consulta de vínculos empregatícios é uma operação assíncrona. Ao enviar a requisição, a QI Tech processará a consulta em background e retornará o resultado através de um webhook quando finalizada.
O webhook será enviado para a URL configurada no seu ambiente.
Para consultar os vínculos ativos de um tomador que possui um contrato legado ativo, deverá ser feita uma consulta de vínculos utilizando o mesmo endpoint do fluxo de emissão adicionando um campo extra na raiz do payload da requisição.
**POST**
/private_payroll/employment_relationships_inquiry
Testar no Playground
### Request
**Request Body**
```json
{
"document_number" : "",
"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
Retorno da consulta dos vínculos empregatícios:
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 - Chamada de tombamento do contrato legado:
:::warning Atenção!
Os campos de nome do tomador, documento do empregador e número de registro do vínculo devem ser preenchidos com os dados retornados na consulta de vínculos, caso contrário, a DATAPREV retornará erro na averbação.
:::
:::warning Atenção!
Caso tenha sido cobrada uma tarifa de cadastro (TAC) na operação original, o valor desta tarifa será calculado pela diferença entre o valor de emissão e a somatória do valor desembolsado com o valor de iof.
:::
TOMBAMENTO
### Request
**POST**
/credit_operation/external
Testar no Playground
**Contrato legado emitido externamente**
```json title='Request Body'
{
"requester_identifier_key": "d6a931e8-1655-479e-97a8-df8b426f49a0",
"borrower": {
"name": "Nome devedor",
"role_type": "issuer",
"person_type": "natural",
"individual_document_number": "14471835092",
},
"collaterals": [
{
"percentage": 1,
"collateral_type": "private_payroll",
"collateral_data": {
"legacy_contract_number": "109230148",
"operation_category": "legacy_contract_rollover",
"employer_document_number": "07940839000159",
"registration_number": "99999999999-A",
},
}
],
"control_number": "CTRL-2025-0001",
"purchaser_document_number": "32402502000135",
"disbursement_bank_account": {
"name": "NOME DEVEDOR",
"bank_code": "001",
"account_digit": "0",
"branch_number": "2874",
"account_number": "000057555",
"document_number": "14471835092",
"transfer_method": "pix",
"percentage_receivable": 100,
},
"financial": {
"interest_type": "pre_price_days",
"disbursement_date": "2024-11-07",
"fine_configuration": {
"monthly_rate": 0.0186,
"interest_base": "calendar_days_365",
"contract_fine_rate": 0,
},
"monthly_interest_rate": 0.04,
"credit_operation_type": "ccb",
"principal_grace_period": 0,
"interest_grace_period": 0,
"total_iof": 50,
"amount": 700,
"disbursed_amount": 500,
"monthly_cet": 0.015,
"annual_cet": 31.81,
"installment_face_value": 82.57,
"installments" : [
{
"due_date":"2025-04-07",
"control_number": "CTRL-2025-1001",
"status": "paid"
},
{
"due_date":"2025-05-07",
"control_number": "CTRL-2025-1002",
"status": "paid"
},
{
"due_date":"2025-06-07",
"control_number": "CTRL-2025-1003",
"status": "opened"
},
{
"due_date":"2025-08-07",
"due_balance": 11.20,
"control_number": "CTRL-2025-1004",
"status": "paid_partial"
},
{
"due_date":"2025-09-07",
"control_number": "CTRL-2025-1005",
"status": "opened"
},
{
"due_date":"2025-10-07",
"control_number": "CTRL-2025-1006",
"status": "opened"
},
{
"due_date":"2025-11-07",
"due_balance": 70.09,
"control_number": "CTRL-2025-1007",
"status": "paid_partial"
}
]
},
}
```
:::warning Atenção!
Todas as parcelas devem ser informadas, mesmo que já tenham sido pagas. Os status das parcelas devem ser informados conforme a descrição abaixo.
:::
#### Descrição dos Status
| Status | Descrição |
|--------|-----------|
| `opened` | Parcela em aberto |
| `paid_partial` | Parcela parcialmente paga |
| `paid` | Parcela totalmente paga |
| `overdue` | Parcela vencida e não paga |
### Response
STATUS
**201** Created
**Response Body**
```json
{
"issue_date": "2024-11-07",
"issuer_name": "Nome Devedor",
"disbursement_start_date": "2024-11-07",
"credit_operation_status_enumerator": "opened",
"original_total_iof": null,
"origin_key": "",
"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: /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: /documentation/manual_emissao_pj_signed_debt/emissao_signed_debt_pj
Este endpoint realiza a emissão da dívida para uma **pessoa jurídica** e processa a assinatura do contrato via opt-in em uma única chamada. O desembolso ocorre na data informada no campo `disbursement_date`, que pode ser diferente da data de emissão.
Não é necessário realizar o cadastro prévio do tomador: basta fornecer os dados cadastrais da empresa e de seus representantes legais no momento da requisição de emissão.
:::info Pré-requisito — upload de documentos
Os documentos da empresa e dos representantes (estatuto/contrato social, documentos de identificação, etc.) devem ser enviados previamente via [upload de documentos](../upload_de_documentos/upload_de_documentos). Cada upload retorna uma `document_key` (UUID), que deve ser referenciada nos campos correspondentes do request.
:::
:::danger Atenção — Onboarding e Antifraude
A QI Tech oferece uma solução de Onboarding de novos clientes e Antifraude.
[Confira aqui a documentação das APIs deste serviço.](https://www.zaig.com.br/en/devcenter.html)
Para receber uma cotação, entre em contato com nosso time comercial: comercial@qitech.com.br ou (11) 3522-1301
:::
O formato de assinatura do header e do body desta requisição é descrito em detalhes [aqui](../primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2).
## Simulação de dívida
Antes de emitir, é possível **simular** os valores da operação de crédito. A simulação segue o mesmo padrão da emissão, porém **não exige** os dados cadastrais do tomador nem a conta de desembolso — basta informar `borrower.person_type` (`legal` para PJ) e o objeto `financial`. O exemplo abaixo simula com base no **valor desembolsado** (`disbursed_amount` + `number_of_installments`).
ENDPOINT /debt_simulation
MÉTODO POST
### Request
Request Body
```json
{
"borrower": {
"person_type": "legal"
},
"financial": {
"interest_type": "pre_price_days",
"disbursement_date": "2026-04-07",
"fine_configuration": {
"monthly_rate": 0.01,
"interest_base": "calendar_days",
"contract_fine_rate": 0.02
},
"disbursed_amount": 10000,
"monthly_interest_rate": 0.03,
"credit_operation_type": "ccb",
"interest_grace_period": 0,
"number_of_installments": 2,
"principal_grace_period": 0
}
}
```
#### Campos do Request
| Campo | Tipo | Descrição |
|---|---|---|
| borrower.person_type* | enum | Natureza jurídica do tomador — usar `legal` para PJ |
| financial.interest_type* | enum | Método de amortização — **[Enumerador Interest Type](#enumerador-interest-type)** |
| financial.credit_operation_type* | enum | Tipo do contrato de crédito — **[Enumerador Credit Operation Type](#enumerador-credit-operation-type)** |
| financial.disbursed_amount* | float | Valor desembolsado da operação |
| financial.monthly_interest_rate* | float | Taxa de juros mensal pré-fixada (em decimal) |
| financial.number_of_installments* | int | Número de parcelas |
| financial.disbursement_date | date | Data do desembolso (YYYY-MM-DD) |
| financial.interest_grace_period | int | Carência de juros (em meses) |
| financial.principal_grace_period | int | Carência do principal (em meses) |
| financial.fine_configuration | object | Configuração de multa e mora — **[Objeto Fine Configuration](#objeto-fine-configuration)** |
### Response
Response Body
```json
{
"type": "debt",
"key": "bf84379c-d4cf-4f16-a63c-865c129e6fce",
"status": "finished",
"event_datetime": "2026-04-07 23:59:28",
"data": {
"interest_type": "pre_price_days",
"credit_operation_type": "ccb",
"interest_grace_period": 0,
"principal_grace_period": 0,
"prefixed_interest_rate": {
"interest_base": "calendar_days",
"annual_rate": 0.42576089,
"monthly_rate": 0.03,
"daily_rate": 0.00097227
},
"issue_date": "2026-04-07",
"number_of_installments": 2,
"final_disbursement_amount": 10000,
"total_pre_fixed_amount": 453.94,
"iof_amount": 51.07,
"cet": 0.0335,
"annual_cet": 0.4851,
"disbursement_date": "2026-04-07",
"issue_amount": 10076.2,
"disbursed_issue_amount": 10000,
"assignment_amount": 10106.4,
"installments": [
{
"calendar_days": 30,
"workdays": 20,
"business_due_date": "2026-05-07",
"due_date": "2026-05-07",
"due_principal": 10076.2,
"has_interest": true,
"post_fixed_amount": 0,
"pre_fixed_amount": 52.4,
"tax_amount": 12.49,
"total_amount": 5226.97,
"principal_amortization_amount": 5174.57,
"installment_number": 1
},
{
"calendar_days": 31,
"workdays": 20,
"business_due_date": "2026-06-08",
"due_date": "2026-06-07",
"due_principal": 4901.63,
"has_interest": true,
"post_fixed_amount": 0,
"pre_fixed_amount": 27.76,
"tax_amount": 26.09,
"total_amount": 5226.97,
"principal_amortization_amount": 4901.63,
"installment_number": 2
}
]
}
}
```
#### Campos do Response
A simulação não gera dívida nem retorna **DEBT-KEY**: o campo `key` é apenas o identificador da simulação e o `status` é `finished`. Os valores ficam dentro de `data`.
| Campo | Tipo | Descrição |
|---|---|---|
| disbursed_issue_amount | float | Valor desembolsado informado na simulação |
| final_disbursement_amount | float | Valor efetivamente desembolsado para o tomador |
| issue_amount | float | Valor de emissão/nominal da operação |
| assignment_amount | float | Valor de aquisição (cessão) da operação |
| cet | float | Custo Efetivo Total mensal (em decimal) |
| annual_cet | float | Custo Efetivo Total anual (em decimal) |
| iof_amount | float | Valor total do IOF |
| total_pre_fixed_amount | float | Total de juros pré-fixados da operação |
| prefixed_interest_rate | object | Taxa de juros nominal (anual, diária, mensal e base de cálculo) |
| installments | array | Parcelas simuladas (data, valor, amortização, juros e IOF de cada parcela) |
## Emissão de dívida
ENDPOINT /signed_debt
MÉTODO POST
Testar no Playground
### Request
#### Payload recomendado (PJ + PIX)
Este é o corpo recomendado para emitir uma dívida de pessoa jurídica com desembolso via PIX. Além dos dados cadastrais, ele inclui a **evidência de assinatura (opt-in)** em `additional_data.contract.signatures`, que é necessária para a emissão ser concluída com sucesso.
```json
{
"borrower": {
"person_type": "legal",
"name": "RAZAO SOCIAL EMPRESA",
"phone": { "country_code": "055", "area_code": "11", "number": "991112222" },
"address": {
"street": "Rua Gilberto Sabino",
"number": "215",
"neighborhood": "Pinheiros",
"city": "São Paulo",
"state": "SP",
"postal_code": "05425020"
},
"company_document_number": "80282008000127",
"company_statute": "2d9b7271-8dfd-43d5-9aee-d2814b98cb9e",
"company_representatives": [
{
"person_type": "natural",
"name": "NOME DO REPRESENTANTE",
"phone": { "country_code": "055", "area_code": "11", "number": "990121234" },
"address": {
"street": "Rua Gilberto Sabino",
"number": "215",
"neighborhood": "Pinheiros",
"city": "São Paulo",
"state": "SP",
"postal_code": "05425020"
},
"is_pep": false,
"individual_document_number": "31057466093"
}
]
},
"financial": {
"disbursed_amount": 10000,
"interest_type": "pre_price_days",
"credit_operation_type": "ccb",
"number_of_installments": 1,
"interest_grace_period": 0,
"principal_grace_period": 0,
"monthly_interest_rate": 0.03,
"disbursement_date": "2026-06-23",
"first_due_date": "2026-07-23",
"fine_configuration": {
"contract_fine_rate": 0.02,
"monthly_rate": 0.01,
"interest_base": "calendar_days_365"
}
},
"additional_data": {
"contract": {
"contract_number": "STN92924220",
"signatures": [
{
"signer": {
"name": "NOME DO REPRESENTANTE",
"email": "representante@test.com",
"document_number": "32402502000135",
"phone": { "country_code": "011", "area_code": "55", "number": "991112222" }
},
"signature": {
"ip_address": "192.168.1.1",
"signature_file": {
"file_type": "pdf",
"file_url": "https://qitech.com.br/signature.pdf"
}
}
}
]
}
},
"disbursement_bank_accounts": [
{
"pix_key": "2f205c99-3161-4120-badd-854039d12de6",
"pix_transfer_type": "key"
}
],
"purchaser_document_number": "32402502000135",
"requester_identifier_key": "3eb8d228-ed17-4352-a081-1d1f3a35334c",
"simplified": true
}
```
:::info Observações importantes
- O bloco `additional_data.contract.signatures` (opt-in) é **necessário** para a emissão. Enviar `additional_data` vazio (`{}`) faz a emissão falhar.
- Envie `simplified: true` para utilizar o fluxo simplificado de emissão.
- `monthly_interest_rate` e `disbursement_bank_accounts` são obrigatórios: sem a taxa o cálculo pré-fixado não é possível, e sem a conta não há desembolso.
- `financial.first_due_date` define a data de vencimento da primeira parcela; junto com `disbursement_date`, determina a agenda de pagamento.
- `postal_code` deve ter **8 dígitos, sem traço**.
- `company_representatives[].address` é **obrigatório**.
- `interest_grace_period` e `principal_grace_period` são **obrigatórios** neste modo (use `0` quando não houver carência).
:::
O exemplo completo abaixo inclui também os campos cadastrais adicionais da empresa (`company_type`, `cnae_code`, `foundation_date`, `trading_name`) e dos representantes.
Request Body
**Valor líquido**
```json
{
"borrower": {
"name": "RAZAO SOCIAL EMPRESA",
"email": "emailempresa@email.com",
"phone": {
"number": "991112222",
"area_code": "11",
"country_code": "055"
},
"is_pep": false,
"address": {
"city": "São Paulo",
"state": "SP",
"number": "215",
"street": "Rua Gilberto Sabino",
"complement": "3 andar",
"postal_code": "05425020",
"neighborhood": "Pinheiros"
},
"cnae_code": "6822-6/00",
"role_type": "issuer",
"person_type": "legal",
"company_type": "ltda",
"trading_name": "NOME FANTASIA DA EMPRESA",
"foundation_date": "2019-07-05",
"attached_documents_list": [],
"company_document_number": "80282008000127",
"company_statute": "aa28e598-55e2-40f1-8884-671772c541a1",
"company_representatives": [
{
"name": "NOME DO REPRESENTANTE",
"email": "nomedorepresentante@email.com",
"phone": {
"number": "990121234",
"area_code": "11",
"country_code": "055"
},
"is_pep": false,
"final_beneficiary": true,
"address": {
"city": "São Paulo",
"state": "SP",
"number": "215",
"street": "Rua Gilberto Sabino",
"complement": "3 andar",
"postal_code": "05425020",
"neighborhood": "Pinheiros"
},
"role_type": "company_representative",
"birth_date": "1993-09-10",
"profession": "DIRETOR",
"mother_name": "NOME DA MAE DO REPRESENTANTE",
"nationality": "BRASILEIRO",
"person_type": "natural",
"marital_status": "single",
"attached_documents_list": [],
"individual_document_number": "31057466093",
"document_identification_number": "20202020200"
}
]
},
"financial": {
"interest_type": "pre_price_days",
"disbursement_date": "2026-04-07",
"first_due_date": "2026-05-07",
"fine_configuration": {
"monthly_rate": 0.01,
"interest_base": "calendar_days",
"contract_fine_rate": 0.02
},
"disbursed_amount": 10000,
"monthly_interest_rate": 0.03,
"credit_operation_type": "ccb",
"interest_grace_period": 0,
"number_of_installments": 2,
"principal_grace_period": 0
},
"additional_data": {
"contract": {
"contract_number": "DWF1761222116",
"signatures": [
{
"signer": {
"name": "NOME DO REPRESENTANTE",
"email": "nomedorepresentante@email.com",
"phone": {
"number": "990121234",
"area_code": "11",
"country_code": "055"
},
"document_number": "31057466093"
},
"signature": {
"timestamp": "28-01-2026 06:36:35",
"ip_address": "192.168.1.1",
"signature_file": {
"file_url": "https://qitech.com.br/signature.pdf",
"file_type": "pdf"
}
}
}
]
}
},
"requester_identifier_key": "d1905ef5-19df-4183-bf0e-802b8229933c",
"purchaser_document_number": "32402502000135",
"disbursement_bank_accounts": [
{
"document_number": "31233261000185",
"name": "Fornecedor",
"pix_key": "2f205c99-3161-4120-badd-854039d12de6",
"pix_transfer_type": "key"
}
],
"simplified": true
}
```
#### Detalhes do Request Body
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| **borrower*** | object | Objeto do tomador pessoa jurídica — a empresa devedora da operação de crédito | **[Objeto Borrower](#objeto-borrower)** |
| **financial*** | object | Contém todos os detalhes financeiros e parâmetros de cálculo da operação | **[Objeto Financial](#objeto-financial)** |
| **additional_data*** ⚠ | object | Dados adicionais do contrato. Deve conter `contract.signatures` (opt-in) para a emissão ser concluída — enviar vazio (`{}`) faz a emissão falhar | **[Objeto Additional Data](#objeto-additional-data)** |
| **disbursement_bank_accounts** ⚠ | array | Dados de desembolso via PIX. Não exigido pelo schema, mas **operacionalmente obrigatório** (sem ele não há desembolso) | **[Objeto Disbursement Bank Account](#objeto-disbursement-bank-account)** |
| **simplified** | boolean | Utiliza o fluxo simplificado de emissão. Envie `true` | - |
| **purchaser_document_number** | string | CNPJ do cessionário — o comprador da operação de crédito (FIDC) | 14 |
| **requester_identifier_key** | string | Chave identificadora única do solicitante | UUID |
:::note Legenda
**\*** campo obrigatório no schema · **⚠** exigido na prática para concluir a emissão · sem marcação: opcional.
:::
#### Objeto Borrower
O `borrower` representa a pessoa jurídica tomadora. Por isso o campo `person_type` deve conter **sempre** o valor `legal`.
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| name* | string | Razão social da empresa | 100 |
| trading_name* | string | Nome fantasia da empresa | 100 |
| email | string | E-mail institucional da empresa | 254 |
| phone* | object | Telefone da empresa | **[Objeto Phone](#objeto-phone)** |
| is_pep | boolean | Indicador de Pessoa Politicamente Exposta | - |
| address* | object | Endereço da empresa | **[Objeto Address](#objeto-address)** |
| role_type | string | Papel do tomador na operação — default: `issuer` | - |
| person_type* | string | Classificação da pessoa — deve ser sempre `legal` | 5 |
| company_type* | enum | Tipo da empresa | **[Enumerador Company Type](#enumerador-company-type)** |
| company_document_number* | string | CNPJ da empresa — somente números | 14 |
| cnae_code* | string | Classificação Nacional de Atividades Econômicas | - |
| foundation_date* | date | Data de abertura da empresa (Formato: "YYYY-MM-DD") | 10 |
| company_statute* | string | `document_key` do PDF do contrato social/estatuto da empresa (enviado previamente) | UUID |
| directors_election_minute | string | `document_key` do PDF da ata de eleição (recomendado para `company_type` igual a `sa`; não é forçado pelo schema) | UUID |
| attached_documents_list | array | Lista de documentos anexados da empresa | - |
| company_representatives* | array | Lista de representantes legais da empresa | **[Objeto Company Representatives](#objeto-company-representatives)** |
#### Objeto Company Representatives
Lista dos representantes legais da empresa. O representante que assina o contrato deve também constar no array `signatures` em [Objeto Contract](#objeto-contract).
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| person_type* | string | Identificador do tipo de pessoa — deve ser `natural` | 7 |
| name* | string | Nome completo do representante | 100 |
| birth_date* | date | Data de nascimento (Formato: "YYYY-MM-DD") | 10 |
| is_pep* | boolean | Declaração se o representante é PEP | - |
| individual_document_number* | string | CPF do representante — somente números | 11 |
| phone* | object | Telefone do representante | **[Objeto Phone](#objeto-phone)** |
| address* | object | Endereço do representante | **[Objeto Address](#objeto-address)** |
| mother_name | string | Nome da mãe do representante | 100 |
| profession | string | Profissão do representante | 64 |
| nationality | string | Nacionalidade do representante | 50 |
| marital_status | string | Estado civil do representante | - |
| property_system | string | Regime de bens (recomendado para `marital_status` igual a `married`; não é forçado pelo schema) | **[Enumerador Property System](#enumerador-property-system)** |
| wedding_certificate | string | `document_key` do PDF da certidão de casamento (`null` se solteiro) | UUID |
| spouse | object | Dados do cônjuge (`null` se solteiro; não é forçado pelo schema) | **[Objeto Spouse](#objeto-spouse)** |
| final_beneficiary | boolean | Declaração se o representante é beneficiário final da empresa | - |
| document_identification | string | `document_key` do PDF do documento de identificação com foto (RG ou CNH) | UUID |
| document_identification_back | string | `document_key` do PDF do verso do documento de identificação | UUID |
| document_identification_type | string | Tipo do documento de identificação enviado | - |
| document_identification_number | string | Número do documento de identificação enviado | 16 |
| email | string | E-mail do representante | 254 |
| role_type | string | Papel na operação — default: `company_representative` | - |
| proof_of_residence | string | `document_key` do PDF do comprovante de endereço (enviado previamente) | UUID |
#### Objeto Spouse
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| person_type* | string | Identificador do tipo de pessoa — deve ser `natural` | 7 |
| name* | string | Nome completo do cônjuge | 100 |
| mother_name* | string | Nome da mãe do cônjuge | 100 |
| birth_date* | date | Data de nascimento (Formato: "YYYY-MM-DD") | 10 |
| profession* | string | Profissão do cônjuge | 64 |
| is_pep* | boolean | Declaração se o cônjuge é PEP | - |
| individual_document_number* | string | CPF do cônjuge — somente números | 11 |
| document_identification_number* | string | Número do documento de identificação do cônjuge | 16 |
| email* | string | E-mail do cônjuge | 254 |
| phone* | object | Telefone do cônjuge | **[Objeto Phone](#objeto-phone)** |
| address | object | Endereço do cônjuge | **[Objeto Address](#objeto-address)** |
#### Objeto Address
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| city* | string | Nome da cidade | 100 |
| state* | string | Sigla do estado (duas letras maiúsculas) | 2 |
| number* | string | Número do logradouro | 10 |
| street* | string | Nome do logradouro | 100 |
| complement | string | Complemento do endereço (texto livre) | 100 |
| postal_code* | string | CEP — somente números | 8 |
| neighborhood* | string | Nome do bairro | 100 |
#### Objeto Phone
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| number* | string | Número do telefone | 10 |
| area_code* | string | Código de área (DDD) | 2 |
| country_code* | string | Código internacional (ex: "055") | 3 |
#### Objeto Financial
Nesta modalidade, o valor da operação é definido pelo **valor líquido** a ser desembolsado (`disbursed_amount`), em conjunto com a taxa de juros (`monthly_interest_rate`) e o número de parcelas (`number_of_installments`). A partir desses dados, o sistema calcula o valor de cada parcela.
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| interest_type* | string | Método de amortização | **[Enumerador Interest Type](#enumerador-interest-type)** |
| fine_configuration* | object | Configuração de multa e mora | **[Objeto Fine Configuration](#objeto-fine-configuration)** |
| disbursed_amount* | float | Valor líquido a ser desembolsado | 15,2 |
| credit_operation_type* | string | Tipo da operação de crédito | **[Enumerador Credit Operation Type](#enumerador-credit-operation-type)** |
| number_of_installments* | integer | Número de parcelas | 3 |
| interest_grace_period* | integer | Período de carência de juros (em meses) — use `0` quando não houver | 3 |
| principal_grace_period* | integer | Período de carência do principal (em meses) — use `0` quando não houver | 3 |
| monthly_interest_rate ⚠ | float | Taxa de juros mensal (em decimal). Não exigida pelo schema, mas **necessária** para o cálculo pré-fixado (`interest_type` `pre_*`) | 10,6 |
| disbursement_date | string | Data de desembolso (YYYY-MM-DD). Se omitida, assume a data de emissão | 10 |
| first_due_date | string | Data de vencimento da primeira parcela (YYYY-MM-DD) | 10 |
#### Objeto Fine Configuration
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| monthly_rate* | float | Taxa de mora mensal (alternativamente, informe `daily_rate` ou `annual_rate`) | 10,6 |
| interest_base* | string | Base de cálculo da mora | **[Enumerador Interest Base](#enumerador-interest-base)** |
| contract_fine_rate* | float | Taxa de multa contratual | 10,6 |
#### Objeto Disbursement Bank Account
O desembolso desta operação é realizado via **chave PIX**. Informe os dados do recebedor do desembolso no array `disbursement_bank_accounts`.
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| pix_key* | string | Chave PIX para a qual o desembolso será realizado | - |
| pix_transfer_type* | string | Tipo de transferência PIX — utilizar `key` para transferência via chave | - |
| document_number | string | CPF/CNPJ do titular da chave PIX. Obrigatório apenas quando há **mais de uma conta** de desembolso | 14 |
| name | string | Nome do titular da chave PIX. Obrigatório apenas quando há **mais de uma conta** de desembolso | 50 |
| percentage_receivable | float | Percentual do desembolso para esta conta. Obrigatório com **múltiplas contas** (a soma deve ser 100) | 3 |
#### Objeto Additional Data
A chave `additional_data` é obrigatória e deve conter o bloco `contract` com a evidência de assinatura (opt-in) em `signatures`. Enviar `additional_data` vazio (`{}`) faz a emissão **falhar**.
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| contract* | object | Dados do contrato | **[Objeto Contract](#objeto-contract)** |
#### Objeto Contract
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| contract_number* | string | Número identificador único do contrato | 20 |
| signatures* | array | Lista de objetos de evidência de assinatura digital (Opt-in) dos representantes legais | **[Objeto Signature](#objeto-signature)** |
#### Objeto Signature
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| signer* | object | Dados de identificação do assinante (representante legal) | **[Objeto Signer](#objeto-signer)** |
| signature* | object | Dados de evidência da assinatura digital | **[Objeto Signature Details](#objeto-signature-details)** |
#### Objeto Signer
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| name* | string | Nome completo do assinante | 255 |
| document_number* | string | CPF do assinante | 11 |
| email | string | E-mail do assinante | 100 |
| phone | object | Telefone do assinante | **[Objeto Phone](#objeto-phone)** |
#### Objeto Signature Details
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| ip_address* | string | Endereço IP utilizado na assinatura | 45 |
| timestamp* | string | Data e hora da assinatura | 24 |
| signature_file* | object | Arquivo da assinatura digital | **[Objeto Signature File](#objeto-signature-file)** |
#### Objeto Signature File
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| file_url* | string | Link direto para o documento do contrato assinado (PDF) | 2048 |
| file_type* | string | Formato do arquivo de assinatura (ex: "pdf") | 4 |
### Response
A resposta à requisição de emissão retornará o plano de pagamento e uma **DEBT-KEY**, que é o identificador da dívida na QI SCD.
STATUS 201
Response Body
```json
{
"webhook_type": "debt",
"key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c",
"status": "issued",
"event_datetime": "2026-04-07 23:59:28",
"data": {
"borrower": {
"name": "RAZAO SOCIAL EMPRESA",
"document_number": "80282008000127",
"related_party_key": "24fac77e-7782-4f72-b31a-daee288e34ed"
},
"contract": {
"document_key": null,
"number": "DWF1761222116",
"urls": [],
"signature_information": [
{
"signer_name": "NOME DO REPRESENTANTE",
"signer_document_number": "31057466093",
"signer_role": "issuer",
"signer_email": null,
"signer_external_key": null,
"signature_url": null
}
]
},
"requester_identifier_key": "d1905ef5-19df-4183-bf0e-802b8229933c",
"iof_charge_method": "financed",
"collaterals": [],
"contract_fees": [
{
"fee_type": "spread",
"fee_amount": 30.2
}
],
"external_contract_fees": [
{
"fee_type": "tac",
"fee_amount": 0,
"tax_amount": 0,
"net_fee_amount": 0
}
],
"external_contract_fee_amount": 0,
"net_external_contract_fee_amount": 0,
"contract_fee_amount": 30.2,
"issue_amount": 10076.2,
"assignment_amount": 10106.4,
"cet": "3,3500%",
"annual_cet": "48,5100%",
"number_of_installments": 2,
"base_iof": 12.49,
"additional_iof": 38.58,
"total_iof": 51.07,
"ipoc_code": "324025020203180282008000127DWF1761222116",
"prefixed_interest_rate": {
"annual_rate": 0.42576089,
"created_at": "2026-04-07T23:59:22",
"daily_rate": 0.00097227,
"interest_base": "calendar_days",
"monthly_rate": 0.03
},
"installments": [
{
"accrual_reference_date": null,
"additional_costs": [],
"advanced_paid_amount": 0,
"bank_slip_key": null,
"business_due_date": "2026-05-07",
"calendar_days": 30,
"digitable_line": null,
"due_date": "2026-05-07",
"due_interest": 0,
"due_principal": 10076.2,
"fine_amount": null,
"has_interest": true,
"installment_history": [],
"installment_key": "1dea396f-beb1-4df3-9822-35800b4c095a",
"installment_number": 1,
"installment_payment": [],
"installment_status": "created",
"installment_type": "principal",
"paid_amount": 0,
"paid_at": null,
"post_fixed_amount": 0,
"qr_code_key": null,
"qr_code_url": null,
"renegotiation_proposal_key": null,
"total_amount": 5226.97,
"total_paid_amount": 0,
"workdays": 20
},
{
"accrual_reference_date": null,
"additional_costs": [],
"advanced_paid_amount": 0,
"bank_slip_key": null,
"business_due_date": "2026-06-08",
"calendar_days": 31,
"digitable_line": null,
"due_date": "2026-06-07",
"due_interest": 0,
"fine_amount": null,
"has_interest": true,
"installment_history": [],
"installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999",
"installment_number": 2,
"installment_payment": [],
"installment_status": "created",
"installment_type": "principal",
"paid_amount": 0,
"paid_at": null,
"post_fixed_amount": 0,
"qr_code_key": null,
"qr_code_url": null,
"renegotiation_proposal_key": null,
"total_amount": 5226.97,
"total_paid_amount": 0,
"workdays": 20
}
],
"total_pre_fixed_amount": 453.94
}
}
```
:::caution Atenção
Lembre-se de salvar a **DEBT-KEY** retornada, pois ela será necessária para consultas, renegociações e estornos da operação.
:::
#### Detalhes do Response Body
| Campo | Tipo | Descrição |
|---|---|---|
| **webhook_type** | string | Identificador do tipo de evento |
| **key** | string | DEBT-KEY — identificador único da dívida na QI SCD (UUID) |
| **status** | string | Status atual da dívida — veja os [status de uma dívida](../emissao_de_divida/status_de_uma_divida) |
| **event_datetime** | string | Data e hora do evento |
| **data** | object | **[Objeto Data](#objeto-data)** — Dados da operação |
#### Objeto Data
| Campo | Tipo | Descrição |
|---|---|---|
| **borrower** | object | Dados do tomador (razão social, CNPJ e `related_party_key`) |
| **contract** | object | Dados do contrato, incluindo informações de assinatura |
| **requester_identifier_key** | string | Chave identificadora do solicitante (UUID) |
| **iof_charge_method** | string | Método de cobrança do IOF — sempre "financed" |
| **collaterals** | array | Lista de garantias da operação |
| **contract_fees** | array | Taxas QI Tech cobradas na operação |
| **external_contract_fees** | array | Taxas externas cobradas na operação |
| **contract_fee_amount** | float | Valor total das taxas QI Tech |
| **issue_amount** | float | Valor nominal da operação de crédito |
| **assignment_amount** | float | Valor de cessão da operação de crédito |
| **cet** | string | Custo Efetivo Total mensal |
| **annual_cet** | string | Custo Efetivo Total anual |
| **number_of_installments** | integer | Número de parcelas |
| **base_iof** | float | Valor base do IOF |
| **additional_iof** | float | Valor adicional do IOF |
| **total_iof** | float | Valor total do IOF |
| **ipoc_code** | string | Código de registro de crédito brasileiro gerado pela QI Tech |
| **prefixed_interest_rate** | object | Taxa de juros nominal (anual, diária, mensal e base de cálculo) |
| **installments** | array | Parcelas da operação |
| **total_pre_fixed_amount** | float | Valor total dos juros pré-fixados de todas as parcelas |
## Webhooks
Durante o ciclo de vida da operação, a QI Tech envia webhooks para a URL configurada. Abaixo estão os eventos relevantes para este fluxo.
:::info Informação
O timeout para resposta dos nossos webhooks é de 5 segundos.
:::
:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeados de forma restrita. Campos adicionais podem ser incluídos aos payloads retornados.
:::
### Webhook de documento gerado
Enviado quando o contrato da operação é gerado. Traz a `document_key` e as URLs do documento (incluindo a versão assinada).
Response Body
```json
{
"key": "cc91aac2-8d15-4349-b155-7c23080c61e8",
"data": {
"contract": {
"urls": [
"https://storage.googleapis.com/live-doc-api/documents/50711223-dfe2-4ed6-9c41-42d68638cfff.pdf"
]
},
"document_key": "50711223-dfe2-4ed6-9c41-42d68638cfff",
"signed_contract_url": "https://storage.googleapis.com/live-doc-api/documents/_signed.pdf"
},
"status": "generated_document",
"webhook_type": "debt",
"event_datetime": "2026-03-24 08:27:11"
}
```
### Webhook de desembolso
Enviado quando o desembolso da operação é realizado (`status: disbursed`). Traz a agenda de parcelas e os comprovantes de transferência (`ted_receipt_list`).
Response Body
```json
{
"key": "bb81d525s-aa4b-4ddf-81d6-aa4b41fd04nb",
"data": {
"installments": [
{
"due_date": "2025-11-24",
"total_amount": 8304.16,
"installment_key": "7ec2f4d-b21e-4bd5-ahs6-60e998267249",
"pre_fixed_amount": 2475.77421509,
"installment_number": 1,
"principal_amortization_amount": 5828.23857532
},
{
"due_date": "2025-12-22",
"total_amount": 8304.16,
"installment_key": "54g37d78-a9a9-bf82-9f8e-fd3ba123797a",
"pre_fixed_amount": 2001.06342502,
"installment_number": 2,
"principal_amortization_amount": 6303.43346322
}
],
"ted_receipt_list": [
{
"fee": 0,
"url": "https://storage.storage.com/sandbox-doc-api/documents/f9as9329-22bd-4dbg-91a2-f2sdgeth4h04/fheth459-bhrf-4hrt-9hra-fdsfsgehth42.pdf",
"amount": 123456.0,
"origin": {
"name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
"type": "payment_account",
"branch": "0001",
"document": "32402502000777",
"bank_code": "329",
"account_key": "5d068423-7774-49e4-b15b-7741238df5a8",
"branch_digit": null,
"account_digit": "5",
"account_branch": "0001",
"account_number": "00002",
"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A."
},
"timestamp": "2025-10-26T17:00:51",
"description": "60701190 8615 22110-2 96969879003 - Fornecedor",
"destination": {
"name": "Fornecedor",
"type": "checking_account",
"branch": "8612",
"purpose": "Crédito PIX em Conta",
"document": "31233261000185",
"bank_ispb": "60111190",
"branch_digit": null,
"account_digit": "2",
"account_number": "44110",
"financial_institution_name": "BANCO S.A."
},
"end_to_end_id": "E32402402200510221300gNgeefVNtVr",
"transaction_key": "25044504-1902-412a-a445-23b813bee6c1",
"origin_transaction_key": "542224ea-b5ea-49ff-b7b7-673b81af387b"
}
],
"requester_identifier_key": null
},
"status": "disbursed",
"webhook_type": "debt",
"event_datetime": "2025-10-26 17:00:52"
}
```
### Webhook de cancelamento
Enviado quando a operação é cancelada (`status: canceled`). O campo `cancel_reason_enumerator` indica o motivo.
Response Body
```json
{
"webhook_type": "debt",
"key": "27a099df-4688-43cb-87fa-515b1cf343a5",
"event_datetime": "2022-09-27 07:03:49",
"data": {
"cancel_reason": "Operacao cancelada manualmente",
"cancel_reason_enumerator": "manual"
},
"status": "canceled"
}
```
#### Motivos de cancelamento
| cancel_reason_enumerator | Descrição |
|---|---|
| disbursing_error | Operação cancelada por erro no momento do desembolso. |
| waiting_signature | Operação cancelada por falta de assinatura. |
| is_portability | A operação foi cancelada pois é uma portabilidade que não foi concluída. |
| not_collateral_constituted | A operação foi cancelada pois as garantias não foram constituídas. |
| entry_not_paid | A operação foi cancelada pois a entrada não foi paga. |
| not_assigned | Operação cancelada porque o processo de cessão não foi realizado. |
| pix_max_retry | Operação cancelada pois o banco recebedor não conseguiu receber o desembolso. |
| lack_of_resource | Operação cancelada por falta de recurso. |
| manual | Operação cancelada manualmente. |
| kyc_not_accepted | Operação cancelada pois não foi aprovada no compliance. |
| not_collateral_fgts | Operação cancelada por erro com FGTS. |
| agencia_conta_invalida | Agência ou conta destinatária do crédito inválida. |
| invalid_account | Número da conta de destino é inexistente ou inválido. |
| invalid_document_number | CPF/CNPJ da conta de destino está incorreto. |
| unsupported_transaction | A conta de destino não suporta este tipo de transação. |
| bank_slip_payment | Operação cancelada por erro no pagamento do boleto. |
| bank_slip_paid | Operação cancelada pois o boleto já está pago. |
| bank_slip_written_off | Operação cancelada pois o boleto já está baixado. |
| invalid_ispb | Número ISPB é inválido ou inexistente. |
| rejected_payment | Ordem de pagamento foi rejeitada pelo banco recebedor. |
| disbursed_amount_refunded | Operação cancelada devido à devolução do valor de desembolso. |
# Enumeradores
### Enumerador _Company Type_
| Enumerador | Descrição |
|---|---|
| **ltda** | Sociedade Limitada |
| **sa** | Sociedade Anônima |
| **micro_enterprise** | Microempresa |
| **freelancer** | Profissional autônomo |
### Enumerador _Property System_
| Enumerador | Descrição |
|---|---|
| **total_communion_of_goods** | Comunhão total de bens |
| **partial_communion_of_goods** | Comunhão parcial de bens |
| **final_participation_of_acquisitions** | Participação final nos aquestos |
| **compulsory_separation_of_goods** | Separação obrigatória de bens |
### Enumerador _Interest Type_
| Enumerador | Descrição |
|---|---|
| **pre_price_days** | Amortização Price (parcelas iguais) com juros pré-fixado ao dia |
| **pre_price** | Amortização Price (parcelas iguais) com juros pré-fixado em períodos fixos (30 dias) |
| **pre_sac** | Amortização SAC (amortização constante) com juros pré-fixado ao dia |
| **post_sac** | Amortização SAC com juros pré-fixado + indexador pós-fixado (cdi, ipca ou igpm) ao dia |
| **post_price** | Amortização Price com juros pré-fixado + indexador pós-fixado em períodos fixos (30 dias) |
| **post_price_days** | Amortização Price com juros pré-fixado + indexador pós-fixado ao dia |
### Enumerador _Credit Operation Type_
| Enumerador | Descrição |
|---|---|
| **ccb** | Cédula de Crédito Bancário |
| **cce** | Cédula de Crédito à Exportação |
| **cci** | Cédula de Crédito Imobiliário |
| **nce** | Nota de Crédito à Exportação |
| **ncom** | Nota Comercial |
### Enumerador _Interest Base_
| Enumerador | Descrição |
|---|---|
| **workdays** | Cálculo de juros em dias úteis considerando um ano de 252 dias |
| **calendar_days** | Cálculo de juros em dias corridos considerando um ano de 360 dias |
| **calendar_days_365** | Cálculo de juros em dias corridos considerando um ano de 365 dias |
## Decodificação de QR Code
### Request
ENDPOINT pix/decode_qrcode_payload
MÉTODO POST
Testar no Playground
Request Body
```json
{
"qr_code_type": "dynamic_instant",
"qr_code_payload": "00020101021226850014br.gov.bcb.pix2563qrcodepix.bb.com.br/pix/v2/d373e385-dfe7-49f6-b9ec-14ba60a9b8285204000053039865802BR5925TESTE62070503***63047B7D",
"pix_key": "teste.cobrancapix@gmail.com.br",
"receiver_conciliation_id": "fgnb4NTt7pOUBGfrcporERwVVqr0f8PWRfK",
"amount": "9367.61",
"status": "ATIVA"
}
```
### Response Body
| Campo | Tipo | Descrição | Disponível |
|-----------------------------|--------|-------------------------------------------------------------------------|--------------------|
| `qr_code_type` | string | Tipo do QR Code: static, dynamic_instant ou dynamic_term. | Todos |
| `qr_code_payload` | string | Payload EMV original recebido na requisição. | Todos |
| `pix_key` | string | Chave Pix do recebedor extraída do payload do QR Code. | Todos |
| `transfer_amount` | string | Valor da transferência, quando especificado no QR Code. | `static` |
| `additional_data` | string | Dados adicionais contidos no QR Code estático. | `static` |
| `receiver_conciliation_id` | string | Identificador de conciliação do recebedor (txid). | `dynamic_*` |
| `amount` | string | Valor original da cobrança. | `dynamic_*` |
| `status` | string | Status da cobrança dinâmica. | `dynamic_*` |
### :::info Status
Para QR Codes dinâmicos, o status do QR Code é retornado de acordo com a tabela de enumeração abaixo.
### Erros
Response Body: QR Code estático
QR Code com formato inválido
```json
{
"data": "{\"title\": \"Invalid Qr Code Format\", \"description\": \"The Qr Code format is invalid, please enter a valid Qr Code\", \"translation\": \"O formato do Qr Code é inválido, por favor insira um Qr Code válido\", \"extra_fields\": {}, \"code\": \"PXT000070\"}"
}
```
Tipo de QR Code não identificado no payload
```json
{
"data": "{\"title\": \"Invalid Qr Code Type\", \"description\": \"The Qr Code payload given did not provide a propper Qr Code type\", \"translation\": \"O payload de QR Code fornecido não contêm um tipo de Qr Code Válido\", \"extra_fields\": {}, \"code\": \"PXT000071\"}"
}
```
Response Body
```json
{
"data": "{\"title\": \"Error in Qr Code Payload Request\", \"description\": \"An error occurred while requesting the qr code payload to the registry institution\", \"translation\": \"Um erro ocorreu durante a requisição do payload do qr code para a instituição de registro\", \"extra_fields\": {}, \"code\": \"PXT000069\"}"
}
```
# Análise de Risco
:::caution Versão preliminar
Esta é a primeira versão da documentação do Análise de Risco e pode sofrer pequenas alterações. Recomendamos acompanhar esta página para futuras atualizações.
:::
O endpoint de **Análise de Risco** permite realizar uma análise de crédito completa para o tomador, combinando onboarding, análise de crédito e consulta de dados do trabalhador do consignado privado em uma única requisição.
A operação é **assíncrona**: ao enviar a requisição, a API retorna uma resposta síncrona com o status `pending_inquiry`. O resultado final da análise é entregue via **webhook** quando o processamento é concluído.
:::info Fluxo
1. O cliente envia um `POST` para `/lending_analysis` com os dados do tomador e as consultas desejadas.
2. A API retorna uma resposta síncrona com a `lending_analysis_key` e status `pending_inquiry`.
3. Ao finalizar o processamento, a API envia um webhook com o resultado completo da análise.
:::
:::info Endpoints disponíveis
Além do `POST /lending_analysis` descrito abaixo, a API expõe duas consultas auxiliares:
- [Consulta de elegibilidade](#consulta-de-elegibilidade) — `GET /lending_analysis` para verificar se o tomador já tem análise ativa antes de criar uma nova.
- [Consulta de status da análise](#consulta-de-status-da-análise) — `GET /lending_analysis/{lending_analysis_key}` para acompanhar o estado da análise via polling, como alternativa ao webhook.
:::
---
## Request
ENDPOINT /lending_analysis
MÉTODO POST
Request Body
```json
{
"request_identifier_key": "12345678901",
"document_number": "46276658812",
"lending_analysis_type": "private_payroll",
"purchaser_document_number": "12345678000199",
"private_payroll": {
"employer_document_number": "12345678000199",
"registration_number": "12345678901"
},
"authorization_term": {
"legal_representative_document_number": "98765432100",
"signature": {
"signer": {
"document_number": "46276658812",
"name": "João da Silva",
"email": "joao.silva@email.com",
"phone": {
"number": "912345678",
"area_code": "11",
"country_code": "55"
}
},
"authentication_type": "opt_in",
"authenticity": {
"timestamp": "2026-03-12T10:00:00Z",
"ip_address": "192.168.1.100",
"fingerprint": {},
"session_id": "3571e292-3a83-4011-904d-20ee963022ef"
}
}
},
"analysis_data": {
"name": "João da Silva"
}
}
```
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `request_identifier_key` | string | Chave idempotente da requisição. Deve ser única por análise. | - |
| `document_number` | string | CPF do tomador (apenas dígitos). | 11 |
| `lending_analysis_type` | string | Tipo da análise de crédito. | **[Enumeradores Análise de Risco Type](#enumeradores-lending-analysis-type)** |
| `purchaser_document_number` | string | CNPJ do comprador/cessionário. (opcional) | 14 |
| `private_payroll` | object | Dados do consignado privado do tomador. | **[Private Payroll Object](#private-payroll-object)** |
| `authorization_term` | object | Termo de autorização do tomador. | **[Authorization Term Object](#authorization-term-object)** |
| `analysis_data` | object | Dados adicionais do tomador para a análise. | **[Analysis Data Object](#analysis-data-object)** |
### Private Payroll Object
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `employer_document_number` | string | CNPJ do empregador. | 14 |
| `registration_number` | string | Número de matrícula do trabalhador. | - |
### Authorization Term Object
:::caution Atenção
Nos casos em que houver representante legal, é necessário preencher o campo `legal_representative_document_number` com o CPF do representante legal, e os dados do objeto `signer` devem ser preenchidos com os dados do representante.
:::
> Para mais informações sobre o objeto `authorization_term`, consulte a documentação oficial:
> [Consultas do Trabalhador - Consulta de Dados do Trabalhador](https://docs.qitech.com.br/documentation/manual_consignado_privado/manual_consultas_trabalhador)
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `legal_representative_document_number` | string | CPF do representante legal (obrigatório apenas quando houver representante legal). | 11 |
| `signature.signer.document_number` | string | CPF do assinante. | 11 |
| `signature.signer.name` | string | Nome do assinante. | - |
| `signature.signer.email` | string | Email do assinante. (opcional) | - |
| `signature.signer.phone.number` | string | Número de telefone do assinante. (opcional) | - |
| `signature.signer.phone.area_code` | string | DDD do assinante. (opcional) | 2 |
| `signature.signer.phone.country_code` | string | Código do país (ex: `"55"`). (opcional) | 3 |
| `signature.authentication_type` | string | Tipo de autenticação. Deve ser `"opt_in"`. | - |
| `signature.authenticity.timestamp` | string | Data e hora do aceite (formato ISO 8601: `2026-03-12T10:00:00Z`). | - |
| `signature.authenticity.ip_address` | string | IP da sessão do usuário (IPv4 ou IPv6). | - |
| `signature.authenticity.fingerprint` | object | Evidências adicionais de rastreabilidade (pode ser objeto vazio `{}`). | - |
| `signature.authenticity.session_id` | string | Identificador da sessão do usuário (min. 10, máx. 50 caracteres). | 50 |
### Analysis Data Object
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `name` | string | Nome do tomador. (opcional) | - |
---
## Response
STATUS 202
Response Body
```json
{
"analysis_status": "pending_inquiry",
"lending_analysis_key": "06666318-c9e9-416b-ae2f-460355a3d8e8"
}
```
| Campo | Tipo | Descrição |
|---|---|---|
| `analysis_status` | string | Status atual da análise. Retorna `pending_inquiry` na resposta síncrona. |
| `lending_analysis_key` | string | Chave UUID da análise, utilizada para correlacionar com o webhook. |
---
STATUS 400
Response Body
```json
{
"title": "Bad Request",
"description": "Invalid or missing required fields in the request body. Check 'document_number', 'lending_analysis_type', 'private_payroll', and 'authorization_term'.",
"translation": "Campos obrigatórios ausentes ou inválidos no corpo da requisição. Verifique 'document_number', 'lending_analysis_type', 'private_payroll' e 'authorization_term'.",
"extra_fields": {},
"code": "LAS000001"
}
```
---
STATUS 409
Retornado quando o campo `request_identifier_key` já foi utilizado em uma requisição anterior.
Response Body
```json
{
"title": "Conflict",
"description": "A lending analysis with the provided 'request_identifier_key' already exists. Each analysis must use a unique identifier.",
"translation": "Já existe uma análise de crédito com o 'request_identifier_key' informado. Cada análise deve utilizar um identificador único.",
"extra_fields": {
"existing_lending_analysis_key": "06666318-c9e9-416b-ae2f-460355a3d8e8"
},
"code": "LAS000002"
}
```
---
## Consulta de elegibilidade
Verifica se o tomador possui uma análise ativa (não expirada) para um determinado produto. Se não houver, indica que uma nova análise pode ser criada com `POST /lending_analysis`.
ENDPOINT /lending_analysis
MÉTODO GET
### Query Params
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `document_number` | string | CPF do tomador (apenas dígitos). | 11 |
| `product_name` | string | Nome do produto. Atualmente o único valor aceito é `private_payroll`. | - |
| `purchaser_document_number` | string | CNPJ do comprador/cessionário. (opcional) | 14 |
### Exemplo de chamada
```
GET /lending_analysis?document_number=46276658812&product_name=private_payroll
```
---
### Response — Tomador com análise ativa
STATUS 200
Response Body
```json
{
"lending_analysis_key": "06666318-c9e9-416b-ae2f-460355a3d8e8",
"analysis_status": "approved",
"expires_at": "2026-03-17T10:00:00Z"
}
```
| Campo | Tipo | Descrição |
|---|---|---|
| `lending_analysis_key` | string | Chave UUID da análise ativa do tomador. |
| `analysis_status` | string | Status atual da análise. Veja **[Status da análise](#status-da-análise)**. |
| `expires_at` | string | Data e hora (ISO 8601) em que a análise expira. Após essa data, o tomador volta a ser elegível para uma nova análise. |
---
### Response — Tomador sem análise ativa
STATUS 404
Retornado quando não existe análise ativa para o tomador na combinação informada. O cliente pode prosseguir com `POST /lending_analysis` para iniciar uma nova análise (desde que exista uma `AnalysisConfiguration` ativa para o mesmo `requester_key`, produto e `purchaser_document_number`).
Response Body
```json
{
"code": "LAS000009",
"title": "No active lending analysis found",
"description": "No active lending analysis found for product_name=, purchaser_document_number=. The borrower has no active analysis for the given product.",
"translation": "Nenhuma analise de credito ativa encontrada para product_name=