Manual Cartão Consignado - Acompanhamento

Navegação

Emissão (anterior)
Webhooks (próximo)

API em desenvolvimento

A API ainda está em fase de desenvolvimento, sendo assim, este manual esta sujeito a alterações.

1. Consulta da reserva do cartão consignado

Consulta os detalhes de uma reserva específica através de sua chave (payroll_card_reservation_key) ou da chave da requisição (request_control_key). Retorna um único objeto contendo os detalhes da reserva.

GET

/payroll_card_reservation/social_security/[PAYROLL-CARD-RESERVATION-KEY]

Testar no Playground

GET

/payroll_card_reservation/social_security/request_control_key/[REQUEST-CONTROL-KEY]

Testar no Playground

Query Params

Query Params

Campo	Tipo	Descrição
retrieve_document_urls	bool	Se as URLs de certos documentos devem ser retornadas. Definido como False como padrão.

Parâmetro retrieve_document_urls

Ativar esse parâmetro pode causar latências na requisição. Utilizar apenas quando necessário.

Atualmente, apenas o campo benefit.policy_document_url é impactado por esse parâmetro, mas outros campos de url (como attached_documents.document_url e attached_documents.signature_url) serão atualizados para depender desse parâmetro.

Os campos impactados (tanto atualmente quanto no futuro) estão demarcados por (*).

Response

Response Body

{
  "request_control_key": "550e8400-e29b-41d4-a716-446655440000",
  "payroll_card_reservation_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "payroll_card_reservation_status": "pending_document_generation",
  "card_holder_document_number": "12345678901",
  "identifier_number": "1234567890",
  "total_limit_amount": 8000.00,
  "reservation_amount": 250.00,
  "reservation_contract_number": "PCR0123456789",
  "wallet_key": null,
  "payroll_card_type": "social_security_payroll_card",
  "signature_url": "https://sandbox.sign.qitech.com.br/s/teste",
  "signature_data": {
      "document_similarity_score": 1,
      "similarity_score": 0.75,
      "biometry_analysis_reference": "internal",
  },
  "withdrawal": {
    "withdrawal_key": "b2c3d4e5-f6g7-8901-bcde-f23456789012",
    "withdrawal_amount": 5600.00,
    "withdrawal_status": "waiting_signature",
    "contract_number": "PCR12345678",
    "disbursement_date": "2025-08-08",
    "withdrawal_data": {
      "disbursement_options": [
        {
          "disbursement_date": "2025-08-08",
          "cet": 0.0262,
          "annual_cet": 0.3643,
          "issue_amount": 5827.36,
          "prefixed_interest_rate": {
            "daily_rate": 0.0008104046,
            "interest_base": "calendar_days",
            "monthly_rate": 0.0246,
            "annual_rate": 0.3386043084
          },
          "installments": [
            {
              "total_amount": 152.5,
              "due_date": "2025-10-10",
              "installment_number": 1
            },
            {
              "total_amount": 152.5,
              "due_date": "2025-11-10",
              "installment_number": 2
            },
            {
              "total_amount": 152.5,
              "due_date": "2025-12-10",
              "installment_number": 3
            }
          ]
        }
      ]
    }
  },
  "payroll_card": {
    "payroll_card_key": "c3d4e5f6-g7h8-9012-cdef-345678901234",
    "payroll_card_status": "pending_issuance",
    "card_limit": 2400.00,
    "card_issuance_entry_amount": 17.28
  },
  "attached_documents": [
    {
      "document_key": "d4e5f6g7-h8i9-0123-defg-456789012345",
      "document_batch_key": "e5f6g7h8-i9j0-1234-efgh-567890123456",
      "document_type": "withdrawal_operation_term",
      "document_certifier": "qi_sign",
      "document_status": "pending_generation",
      "document_url": null,
      "signature_url": null,
    },
    {
      "document_key": "f6g7h8i9-j0k1-2345-fghi-678901234567",
      "document_batch_key": "e5f6g7h8-i9j0-1234-efgh-567890123456",
      "document_type": "payroll_card_term",
      "document_certifier": "qi_sign",
      "document_status": "pending_generation",
      "document_url": null,
      "signature_url": null,
    },
    {
      "document_key": "925c0a62-ef98-4891-909b-9955a87ccefb",
      "document_batch_key": "e5f6g7h8-i9j0-1234-efgh-567890123456",
      "document_type": "payroll_card_consent_term",
      "document_certifier": "qi_sign",
      "document_status": "pending_generation",
      "document_url": null,
      "signature_url": null,
    }
  ],
  "benefit": {
    "benefit_key": "0b80d313-2ade-4a28-be58-38b9219c2b8c",
    "card_insurance_key": "0151934c-b219-458f-98a3-8b0f85c70307",
    "status": "active",
    "due_date": "2036-02-18",
    "policy_document_key": "6363eb63-2e85-4786-bc03-8c1ddd8e2be2",
    "policy_document_url": "https://example.com/policy.pdf"
  }
}

Response Body Details

Campo	Tipo	Descrição
request_control_key	string	Chave de identificação da requisição
payroll_card_reservation_key	string	Chave da reserva do cartão consignado
payroll_card_reservation_status	string	Status da reserva do cartão consignado
card_holder_document_number	string	CPF do portador do cartão
identifier_number	string	Número identificador da operação
reservation_amount	number	Valor da reserva do cartão consignado
reservation_contract_number	string	Número do contrato de averbação na Dataprev
withdrawal	object	Dados do saque
payroll_card	object	Dados do cartão consignado
attached_documents	array	Lista de documentos anexados
payroll_card_type	string	Tipo do cartão (`social_security_benefit_card` ou `social_security_payroll_card`)
wallet_key	string	Chave única da wallet criada (UUID4)
signature_url	string	URL de assinatura do contrato da reserva (Apenas presente no payload após geração do link de assiantura)
signature_data	object	Dados biométricos coletados na assinatura (Apenas presente no payload após assinatura dos documentos)
benefit	object	Dados do seguro/benefício associado ao cartão (Apenas presente no payload após emissão do cartão)

Payload withdrawal

Campo	Tipo	Descrição
withdrawal_key	string	Chave única do saque
contract_number	string	Número do contrato da CCB de saque
withdrawal_amount	number	Valor de desembolso calculado para CCB de saque
disbursement_date	date	Data de desembolso da operação
withdrawal_status	string	Status do saque
withdrawal_data	object	Dados detalhados do saque

Payload withdrawal_data

Campo	Tipo	Descrição
prefixed_interest_rate	object	Taxa de juros prefixada
disbursement_options	array	Opções de desembolso disponíveis

Payload prefixed_interest_rate

Campo	Tipo	Descrição
daily_rate	number	Taxa diária
interest_base	string	Base de cálculo dos juros
monthly_rate	number	Taxa mensal
annual_rate	number	Taxa anual

Payload disbursement_options

Campo	Tipo	Descrição
disbursement_date	string	Data do desembolso
cet	number	Custo Efetivo Total mensal
annual_cet	number	Custo Efetivo Total anual
total_iof	number	Valor total de IOF
disbursed_issue_amount	number	Valor de desembolso
issue_amount	number	Valor de emissão
installments	array	Lista de parcelas

Payload installments

Campo	Tipo	Descrição
total_amount	number	Valor total da parcela
due_date	string	Data de vencimento
installment_number	number	Número da parcela

Payload payroll_card

Campo	Tipo	Descrição
payroll_card_key	string	Chave única do cartão consignado
payroll_card_status	string	Status do cartão consignado
card_limit	number	Limite total calculado para o cartão
card_issuance_entry_amount	number	Valor da Taxa de emissão do cartão

Payload attached_documents

Campo	Tipo	Descrição
document_key	string	Chave única do documento
document_batch_key	string	Chave do lote de documentos
document_type	string	Tipo do documento
document_certifier	string	Certificadora do documento
document_status	string	Status do documento
document_url (*)	string	URL do documento
signature_url (*)	string	URL da assinatura

Payload signature_data

Campo	Tipo	Descrição
document_similarity_score	number	Nota de similiaridade biométrica entre o assinante e o documento enviado (0-1)
similarity_score	number	Nota de similiaridade biométrica entre o assinante e a referência encontrada na base de rostos (0-1)
biometry_analysis_reference	string	Base de origem do rosto utilizado para o calculo da nota de similaridade biométrica

Payload benefit

Campo	Tipo	Descrição
benefit_key	string	Chave única do benefício (UUID)
status	string	Status da emissão do Seguro (`created`, `pending_emission`, `active`, `canceled` ou `inactive`)
policy_document_key	string	Chave única do documento da apólice (UUID)
policy_document_url (*)	string	URL do documento de apólice do seguro

2. Consulta de reservas do cartão consignado por CPF

Consulta as reservas ativas de um determinado CPF. Retorna uma lista de objetos dentro da propriedade payroll_card_reservations.

GET

/payroll_card_reservation/social_security/card_holder_document_number/[CARD-HOLDER-DOCUMENT-NUMBER]

Testar no Playground

Response

Response Body

{
   "payroll_card_reservations": [
      {
        "request_control_key": "d3bc353e-d612-4029-9d77-4dca9171c3b5",
        "payroll_card_reservation_key": "5fb9d810-be74-4d26-959d-c75d10834e93",
        "payroll_card_reservation_status": "card_issued",
        "card_holder_document_number": "12345678901",
        "identifier_number": "1234567890",
        "total_limit_amount": 8000.00,
        "reservation_amount": 250.00,
        "reservation_contract_number": "PCR0123456789",
        "wallet_key": "298e4d37-0f20-4aed-ad66-016f8487afba",
        "payroll_card_type": "social_security_payroll_card",
        "card_holder": {
          "email": "joao.teste@example.com",
          "phone": {
            "number": "352141677",
            "area_code": "11",
            "country_code": "055"
          },
          "address": {
            "city": "Belo Horizonte",
            "state": "MG",
            "number": "7889",
            "street": "Rua Santos",
            "complement": "Apto 243",
            "postal_code": "30112000",
            "neighborhood": "Centro"
          }
        },
        "attached_documents": [
          {
              "document_key": "910e8de5-16af-4bc5-8ee1-4a0652ca0cbf",
              "document_type": "withdrawal_operation_term",
              "document_certifier": "qi_sign",
              "document_status": "signed",
              "document_batch_key": "f28bf87a-11cd-4d89-89c0-19229a1b31a7",
              "document_url": "https://storage.googleapis.com/example_document.pdf",
              "signature_url": "https://storage.googleapis.com/example_document_signed.pdf",
          },
          {
              "document_key": "332017f4-a0d6-463a-8557-e925a9485251",
              "document_type": "payroll_card_term",
              "document_certifier": "qi_sign",
              "document_status": "signed",
              "document_batch_key": "f28bf87a-11cd-4d89-89c0-19229a1b31a7",
              "document_url": "https://storage.googleapis.com/example_document.pdf",
              "signature_url": "https://storage.googleapis.com/example_document_signed.pdf",
          },
          {
              "document_key": "b098074a-7cba-4b67-81e1-8d587185504b",
              "document_type": "payroll_card_consent_term",
              "document_certifier": "qi_sign",
              "document_status": "signed",
              "document_batch_key": "f28bf87a-11cd-4d89-89c0-19229a1b31a7",
              "document_url": "https://storage.googleapis.com/example_document.pdf",
              "signature_url": "https://storage.googleapis.com/example_document_signed.pdf",
          },
          {
              "document_key": "b1c3e915-6707-49f5-85a9-398ef997fdad",
              "document_type": "selfie",
              "document_certifier": "qi_sign",
              "document_status": "generated",
              "document_url": "https://storage.googleapis.com/selfie.jpeg"
          },
          {
              "document_key": "5769a335-a2ac-4913-a742-38b9d1e4abd2",
              "document_type": "document_identification",
              "document_certifier": "qi_sign",
              "document_status": "generated",
              "document_url": "https://storage.googleapis.com/cnh.jpeg"
          },
          {
              "document_key": "75577d34-4ebd-4488-aca8-b064e603c973",
              "document_type": "document_identification_back",
              "document_certifier": "qi_sign",
              "document_status": "generated",
              "document_url": "https://storage.googleapis.com/cnh_back.jpeg"
          },
          {
              "document_key": "2fc216c6-5d1c-4713-b70b-6e1f75f8bb17",
              "document_type": "payroll_card_confirmation_video",
              "document_certifier": "electronic_client_side",
              "document_status": "generated",
              "document_url": "https://storage.googleapis.com/video.mp4"
          }
        ],
      },
      {
        "request_control_key": "d3bc353e-d612-4029-9d77-4dca9171c3b5",
        "payroll_card_reservation_key": "5fb9d810-be74-4d26-959d-c75d10834e93",
        "payroll_card_reservation_status": "pending_withdrawal_disbursement",
        "card_holder_document_number": "12345678901",
        "identifier_number": "1234567890",
        "total_limit_amount": 8000.00,
        "reservation_amount": 250.00,
        "reservation_contract_number": "PCR0123456789",
        "wallet_key": "298e4d37-0f20-4aed-ad66-016f8487afba",
        "payroll_card_type": "social_security_payroll_card",
        "card_holder": {
          "email": "joao.teste@example.com",
          "phone": {
            "number": "352141677",
            "area_code": "11",
            "country_code": "055"
          },
          "address": {
            "city": "Belo Horizonte",
            "state": "MG",
            "number": "7889",
            "street": "Rua Santos",
            "complement": "Apto 243",
            "postal_code": "30112000",
            "neighborhood": "Centro"
          }
        },
        "attached_documents": [
          {
              "document_key": "910e8de5-16af-4bc5-8ee1-4a0652ca0cbf",
              "document_type": "withdrawal_operation_term",
              "document_certifier": "qi_sign",
              "document_status": "signed",
              "document_batch_key": "f28bf87a-11cd-4d89-89c0-19229a1b31a7",
              "document_url": "https://storage.googleapis.com/example_document.pdf",
              "signature_url": "https://storage.googleapis.com/example_document_signed.pdf",
          },
          {
              "document_key": "332017f4-a0d6-463a-8557-e925a9485251",
              "document_type": "payroll_card_term",
              "document_certifier": "qi_sign",
              "document_status": "signed",
              "document_batch_key": "f28bf87a-11cd-4d89-89c0-19229a1b31a7",
              "document_url": "https://storage.googleapis.com/example_document.pdf",
              "signature_url": "https://storage.googleapis.com/example_document_signed.pdf",
          },
          {
              "document_key": "87c23417-c342-4cc7-81b6-81185b6012ce",
              "document_type": "payroll_card_consent_term",
              "document_certifier": "qi_sign",
              "document_status": "signed",
              "document_batch_key": "f28bf87a-11cd-4d89-89c0-19229a1b31a7",
              "document_url": "https://storage.googleapis.com/example_document.pdf",
              "signature_url": "https://storage.googleapis.com/example_document_signed.pdf",
          },
          {
              "document_key": "b1c3e915-6707-49f5-85a9-398ef997fdad",
              "document_type": "selfie",
              "document_certifier": "qi_sign",
              "document_status": "generated",
              "document_url": "https://storage.googleapis.com/selfie.jpeg"
          },
          {
              "document_key": "5769a335-a2ac-4913-a742-38b9d1e4abd2",
              "document_type": "document_identification",
              "document_certifier": "qi_sign",
              "document_status": "generated",
              "document_url": "https://storage.googleapis.com/cnh.jpeg"
          },
          {
              "document_key": "75577d34-4ebd-4488-aca8-b064e603c973",
              "document_type": "document_identification_back",
              "document_certifier": "qi_sign",
              "document_status": "generated",
              "document_url": "https://storage.googleapis.com/cnh_back.jpeg"
          },
          {
              "document_key": "b574b555-e3c9-402a-a869-c4bc27751be8",
              "document_type": "payroll_card_confirmation_video",
              "document_certifier": "electronic_client_side",
              "document_status": "generated",
              "document_url": "https://storage.googleapis.com/video.mp4"
          }
        ],
      }
   ]
}

3. Máquinas de Status

Payroll Card Reservation

A entidade Payroll Card Reservation possui os seguintes status e transições:

Descrição dos Status

Status	Descrição
`pending_document_generation`	Aguardando geração dos documentos para assinatura
`pending_onboarding`	Aguardando processo de onboarding e KYC
`pending_collateral_reservation`	Aguardando reserva do colateral
`pending_additional_documents_submission`	Margem averbada. Aguardando envio do vídeo de confirmação
`pending_additional_documents_validation`	Aguardando validação do video de confirmação
`pending_withdrawal_disbursement`	Aguardando desembolso da operação de saque
`pending_card_issuance`	Aguardando criação da wallet e emissão do cartão
`card_issued`	Cartão criado e ativo
`canceled`	Operação cancelada

Withdrawal

A entidade Withdrawal possui os seguintes status e transições:

Descrição dos Status

Status	Descrição
`pending_signature`	Aguardando assinatura dos termos
`pending_disbursement`	Aguardando desembolso da operação de saque
`opened`	Desembolso realizado e operação ativa
`canceled`	Operação cancelada

Benefit

A entidade Benefit possui os seguintes status e transições:

Descrição dos Status

Status	Descrição
`created`	Seguro em procesasmento
`pending_emission`	Aguardando emissão do seguro
`active`	Seguro emitido e ativo
`canceled`	Seguro cancelado
`inactive`	Seguro expirado ou inativo

4. Cancelamento da reserva

Permite o cancelamento da reserva do cartão consignado.

Restrições

O cancelamento via API só é permitido antes do desembolso do saque (Status: pending_withdrawal_disbursement ou anterior). Caso o saque já tenha sido realizado ou o cartão já esteja emitido, o cancelamento deve ser tratado via suporte, pois envolve estorno financeiro.

PATCH

/payroll_card_reservation/social_security/[PAYROLL-CARD-RESERVATION-KEY]/cancel

Testar no Playground

Response

STATUS

200 (OK)

A requisição foi processada com sucesso. Não há retorno de conteúdo (Body vazio).

// Empty response body

1. Consulta da reserva do cartão consignado​

Query Params​

Response​

Payload withdrawal​

Payload withdrawal_data​

Payload prefixed_interest_rate​

Payload disbursement_options​

Payload installments​

Payload payroll_card​

Payload attached_documents​

Payload signature_data​

Payload benefit​

2. Consulta de reservas do cartão consignado por CPF​

Response​

3. Máquinas de Status​

Payroll Card Reservation​

Descrição dos Status​

Withdrawal​

Descrição dos Status​

Benefit​

Descrição dos Status​

4. Cancelamento da reserva​

Response​

1. Consulta da reserva do cartão consignado

Query Params

Response

Payload withdrawal

Payload withdrawal_data

Payload prefixed_interest_rate

Payload disbursement_options

Payload installments

Payload payroll_card

Payload attached_documents

Payload signature_data

Payload benefit

2. Consulta de reservas do cartão consignado por CPF

Response

3. Máquinas de Status

Payroll Card Reservation

Descrição dos Status

Withdrawal

Descrição dos Status

Benefit

Descrição dos Status

4. Cancelamento da reserva

Response