Roteiro de Integração — API de Escrituração de Notas Comerciais (NC) com Auto-Assinatura

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.

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

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

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	—	✅
CAB0002*	Teste de autenticação	Após o recebimento da chave de API, realizar os testes de autenticação de chamada	Documentação Documentação	CAB0001	✅
CAB0003*	Configuração de webhooks	Configurar a URL para a qual a QI Tech enviará os webhooks	Documentação Documentação Documentação	CAB0001, CAB0002	✅

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

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	CAB0002	✅
CED1002*	Listar emissores cadastrados	Listar os emissores cadastrados, filtrando por CNPJ ou nome	Documentação	CED1001	✅
CED1003*	Detalhes do emissor	Consultar os detalhes de um emissor cadastrado pela `issuer_key`	Documentação	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	CAB0002	✅
CED0002*	Upload / remoção de documentos do emissor	Anexar e remover documentos associados a um emissor cadastrado	Documentação Documentação	CED0001	✅
CED0003*	Cadastro / remoção de representantes do emissor	Adicionar e remover representantes associados a um emissor cadastrado	Documentação Documentação	CED0001	✅
CED0004*	Upload / remoção de documentos de representantes	Anexar e remover documentos associados a um representante de um emissor cadastrado	Documentação Documentação	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 Documentação	CED0001	✅
CED0006*	Cadastro / remoção de grupos de assinantes do emissor	Adicionar e remover grupos de assinantes associados a um emissor cadastrado	Documentação Documentação	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 Documentação	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	CED0001 → CED0007	✅
CED0009*	Alteração do cadastro do emissor	Reabrir o emissor para edição	Documentação	CED0001 → CED0007	✅
CED0010*	Listar emissores cadastrados	Listar os emissores cadastrados, filtrando por CNPJ ou nome	Documentação	CED0001	✅
CED0011*	Detalhes do emissor	Consultar os detalhes de um emissor cadastrado pela `issuer_key`	Documentação	CED0001	✅

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	—	⚙️
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	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	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	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	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	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	⚙️

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)

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

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	CAB0002	✅
INV1002*	Detalhes do investidor	Consultar os detalhes de um investidor cadastrado pela `investor_key`	Documentação	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	CAB0002	✅
INV0002*	Upload / remoção de documentos do investidor	Anexar e remover documentos associados a um investidor cadastrado	Documentação Documentação	INV0001	✅
INV0003*	Cadastro / remoção de representantes do investidor	Adicionar e remover representantes associados a um investidor cadastrado	Documentação Documentação	INV0001	✅
INV0004*	Upload / remoção de documentos de representantes	Anexar e remover documentos associados a um representante de um investidor cadastrado	Documentação Documentação	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 Documentação	INV0001	✅
INV0006*	Cadastro / remoção de grupos de assinantes do investidor	Adicionar e remover grupos de assinantes associados a um investidor cadastrado	Documentação Documentação	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 Documentação	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	INV0001 → INV0007	✅
INV0009*	Alteração do cadastro do investidor	Reabrir o investidor para edição	Documentação	INV0001 → INV0007	✅
INV0010*	Listar investidores cadastrados	Listar os fundos cadastrados, filtrando por CNPJ ou nome	Documentação	INV0001	✅
INV0011*	Detalhes do investidor	Consultar os detalhes de um investidor cadastrado pela `investor_key`	Documentação	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	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	COM0001, CED0011/CED1003, INV1002	✅
COM0003*	Cadastro / remoção de partes relacionadas	Adicionar e remover partes relacionadas a uma operação	Documentação	COM0002	✅
COM0004*	Upload / remoção de documentos de representantes de partes relacionadas	Anexar e remover documentos associados a representantes de partes relacionadas	Documentação	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	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	COM0002	✅
COM0007*	Alterar template do Termo Constitutivo	Alterar o template do Termo Constitutivo utilizado por uma operação	Documentação	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	COM0002	✅
COM0009*	Cadastro de garantias	Adicionar garantias associadas a uma operação	Documentação	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	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	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	COM0002	✅
COM0013*	Consulta de operações por filtro	Consultar operações de nota comercial utilizando filtros opcionais	Documentação	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	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	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	COM0002	⚙️ 🆕

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 (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 (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	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	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	COM0002, ASG0006	⚙️ 🆕

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	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	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	COM0022	✅
INT0002*	Consulta de subscrição	Consultar uma subscrição em andamento	Documentação	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	INT0001, INT0002	✅
INT0004	Cancelamento de subscrição	Cancelar uma subscrição — útil quando a data de subscrição precisa ser deslocada	Documentação	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	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	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	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	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	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	TFI0002	✅

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

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

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

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

{
    "key": "<ACCOUNT-KEY>",
    "data": {
        "amount": 150000.00,
        "origin": {
            "name": "Conta de Origem",
            "branch": "0001",
            "document": "32402502000135",
            "account_key": "5d068423-6094-49e4-b15b-7740038295a8",
            "account_digit": "5",
            "account_number": "00002"
        },
        "timestamp": "2022-09-02T21:36:33.446120",
        "destination": {
            "name": "Conta de Liquidação WL",
            "branch": "0001",
            "document": "09080702000105",
            "account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
            "account_digit": "2",
            "account_number": "2359934"
        },
        "reference_key": "983b4a28-7de6-4e71-97ef-60fb50c7b013",
        "reference_type": "movement_request",
        "account_balance": 150000.00,
        "source_sub_type": "internal_funds_transfer",
        "transaction_key": "46804f32-101e-4702-8fbc-c2dbc4c2caec",
        "source_sub_type_str": "Transferência Interna"
    },
    "datetime": "2022-09-02T21:36:33.446120",
    "webhook_type": "account_transaction"
}

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 (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	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	PAY0002, COM0024	⚙️ 🆕
PAY0004*	Consultar status do pagamento	Consultar o status do desembolso pela chave da transação na conta de liquidação	Documentação	PAY0003	🆕
PAY0005*	Webhook — pagamento liquidado	Receber o webhook que confirma que o fornecedor foi pago	Documentação (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.

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.

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

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.

1. Escopo e fases​

2. Fluxo ponta a ponta​

3. Fase 0 — Cadastro e autenticação na API​

4. Fase 1 — Homologação do emissor​

4.1 Fase 1A — Emissor cadastrado no sistema de cedentes da QI Tech​

4.2 Fase 1B — Emissor cadastrado pelo sistema​

5. Fase 2 — Habilitação da auto-assinatura ✅​

5.1 Máquina de status da habilitação​

6. Fase 3 — Homologação do investidor​

6.1 Investidores cadastrados durante o setup — caminho recomendado​

6.2 Investidores cadastrados pelo sistema — apenas se não forem utilizados fundos fixos​

7. Fase 4 — Emissão da NC​

7.1 Criação da operação​

7.2 Assinatura — caminho automático (emissor com auto-assinatura enabled) 🆕​

7.3 Assinatura — fallback manual (QI SIGN)​

8. Fase 5 — Subscrição e integralização​

9. Fase 6 — Transferência de recursos e pagamento 🆕​

9.1 Perna 1 — Transferência para a conta de liquidação da WL 🆕​

TFI0002 — Comandar a transferência interna​

TFI0004 — Webhook de confirmação do crédito​

9.2 Perna 2 — Pagamento ao fornecedor 🆕​

Trilhas disponíveis​

10. Resumo dos webhooks​

11. Pontos em aberto a serem fechados antes do go-live​

12. Mapeamento de erros​

1. Escopo e fases

2. Fluxo ponta a ponta

3. Fase 0 — Cadastro e autenticação na API

4. Fase 1 — Homologação do emissor

4.1 Fase 1A — Emissor cadastrado no sistema de cedentes da QI Tech

4.2 Fase 1B — Emissor cadastrado pelo sistema

5. Fase 2 — Habilitação da auto-assinatura ✅

5.1 Máquina de status da habilitação

6. Fase 3 — Homologação do investidor

6.1 Investidores cadastrados durante o setup — caminho recomendado

6.2 Investidores cadastrados pelo sistema — apenas se não forem utilizados fundos fixos

7. Fase 4 — Emissão da NC

7.1 Criação da operação

7.2 Assinatura — caminho automático (emissor com auto-assinatura `enabled`) 🆕

7.3 Assinatura — fallback manual (QI SIGN)

8. Fase 5 — Subscrição e integralização

9. Fase 6 — Transferência de recursos e pagamento 🆕

9.1 Perna 1 — Transferência para a conta de liquidação da WL 🆕

TFI0002 — Comandar a transferência interna

TFI0004 — Webhook de confirmação do crédito

9.2 Perna 2 — Pagamento ao fornecedor 🆕

Trilhas disponíveis

10. Resumo dos webhooks

11. Pontos em aberto a serem fechados antes do go-live

12. Mapeamento de erros