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. A fase de habilitação da auto-assinatura (Fase 2) depende de novo desenvolvimento do lado da QI Tech. 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 auto-assinatura só é configurada após a aprovação do cadastro do emissor. O termo de adesão que a autoriza é assinado dentro do pacote da primeira emissão. A partir da segunda emissão, a assinatura do lado do emissor é totalmente automática. A Fase 2 é, portanto, um portão único por emissor, e não uma etapa por operação.

---

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 representante é 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 é a nova funcionalidade que viabiliza o fluxo automatizado. Ela ocorre uma única vez por emissor, após a aprovação do cadastro do emissor, e resulta em um certificado privado da QI Tech com escopo exclusivo aos documentos de NC desta integração.

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, com biometria de reconhecimento facial, pelo representante cadastrado em CED0006.

Quando é assinado. O termo é incluído no pacote da primeira emissão. A primeira operação, portanto, ainda possui uma etapa de assinatura humana; a partir da segunda operação, a assinatura do lado do emissor é totalmente automática.

Código	Etapa	Descrição	Documentação	Pré-requisito	Status
ASG0001*	Consultar elegibilidade para auto-assinatura	Ler o bloco signature_configuration do emissor para confirmar que ele está aprovado e elegível à habilitação de auto-assinatura	Documentação (pendente de publicação)	CED0011 ou CED1003	🆕
ASG0002*	Solicitar habilitação de auto-assinatura	Solicitar a habilitação para um emissor aprovado, indicando o grupo de assinantes e o representante que assinará o termo de adesão. Retorna uma auto_signature_key no status pending_agreement	Documentação (pendente de publicação)	ASG0001, CED0006	🆕
ASG0003*	Consultar link de assinatura do termo de adesão	Consultar o link pelo qual o representante assina o termo de adesão com reconhecimento facial. Na primeira emissão, esse link é entregue como parte do pacote de assinatura da operação	Documentação (pendente de publicação)	ASG0002	🆕
ASG0004*	Webhook — termo de adesão assinado	Receber o webhook que confirma que o termo de adesão foi assinado e validado	Documentação (pendente de publicação)	CAB0003, ASG0003	🆕
ASG0005	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 via API está no roadmap e não bloqueia o go-live	—	ASG0004	⚙️ 🆕
ASG0006*	Consultar status da auto-assinatura	Consultar a habilitação pela auto_signature_key ou pela issuer_key e confirmar a transição para active. Nenhuma NC pode depender da assinatura automática antes de esse status ser atingido	Documentação (pendente de publicação)	ASG0002	🆕
ASG0007*	Webhook — auto-assinatura ativa	Receber o webhook que sinaliza que o certificado está disponível e o emissor está habilitado para assinatura automática	Documentação (pendente de publicação)	CAB0003, ASG0005	🆕
ASG0008	Consultar termo de adesão assinado	Consultar o documento do termo de adesão assinado para registro e trilha de auditoria do próprio integrador	Documentação (pendente de publicação)	ASG0004	🆕
ASG0009	Revogar auto-assinatura	Revogar a habilitação e o certificado associado — necessário quando o representante muda, quando o grupo de assinantes é alterado ou a pedido do emissor. Após a revogação, as emissões voltam ao fluxo de assinatura manual até que a Fase 2 seja repetida	Documentação (pendente de publicação)	ASG0006	🆕

5.1 Máquina de status da habilitação

Status	Significado	Comportamento de assinatura de uma nova NC
not_requested	Emissor aprovado, mas nunca submetido à habilitação	Assinatura manual (QI SIGN)
pending_agreement	Habilitação solicitada; termo de adesão ainda não assinado	Assinatura manual — o termo viaja no pacote desta operação
pending_certificate	Termo assinado; certificado em emissão pela QI Tech	Assinatura manual — segurar novas emissões até active
active	Certificado liberado na CertifiQI	Automática
revoked	Habilitação revogada	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 active e o fallback do QI SIGN (COM0015 / COM0016) em todos os demais status. Uma integração que assume active vai quebrar na primeira emissão de todo emissor novo.

---

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	✅

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

Código	Etapa	Descrição	Documentação	Pré-requisito	Status
COM0020*	Aprovação automática	Com a auto-assinatura ativa 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	✅

7.3 Assinatura — fallback manual (QI SIGN)

Obrigatório para a primeira emissão de cada emissor — que carrega o termo de adesão — e para qualquer emissor cujo status de habilitação não seja active.

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.

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*	Iniciar pagamento a terceiros	Disparar o pagamento da conta de liquidação do emissor para o fornecedor via API de BaaS. Estimativa de 4 semanas de desenvolvimento	Documentação (pendente de publicação)	PAY0002	🆕
PAY0004*	Consultar status do pagamento	Consultar o status de um pagamento pela sua chave única	Documentação (a confirmar)	PAY0003	🆕
PAY0005*	Webhook — pagamento liquidado	Receber o webhook que confirma que o fornecedor foi pago	Documentação (a confirmar)	CAB0003, PAY0003	🆕

Escopo da fase 1

Uma NC por pagamento. O split de pagamento — uma nota financiando vários pagamentos a fornecedores — não é suportado nesta fase e está previsto para a fase 2 do projeto. O integrador deve modelar suas requisições de acordo: uma operação, um beneficiário.

---

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 — habilita a solicitação da Fase 2
Termo de adesão assinado	2	Início da emissão do certificado
Auto-assinatura ativa	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: Pix/QR code ou boleto. Pix/QR é direto; boleto exige um desenvolvimento significativamente maior	Cliente + QI Tech	Dimensiona o desenvolvimento da Fase 6
3	Pagamento a terceiros a partir da conta de liquidação — estimativa de 4 semanas de desenvolvimento	QI Tech	Bloqueia a Fase 6
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) e do comportamento de aprovação/assinatura automática (COM0020–COM0022)	QI Tech	Bloqueia a homologação da Fase 2
6	Split de pagamento confirmado como escopo da fase 2	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

---

12. Mapeamento de erros

Os erros originados das APIs de emissor, investidor e nota comercial estão catalogados no Catálogo de Erros.

Os erros específicos de auto-assinatura — tentativa de emissão com a habilitação fora de active, certificado revogado, 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 os endpoints ASG forem publicados.