# QI Tech — Cartões

Documentação da QI Tech em texto corrido, para colar em um LLM.
Fonte: https://docs.qitech.com.br
7 página(s).

Índice:
- Manual Cartão Consignado - Acompanhamento (/documentation/manual_cartao_beneficio/manual_cartao_beneficio_acompanhamento)
- Documentos e Assinatura (/documentation/manual_cartao_beneficio/manual_cartao_beneficio_documentos)
- Manual Cartão Consignado - Criação (/documentation/manual_cartao_beneficio/manual_cartao_beneficio_emissao)
- Gestão de Endereço (/documentation/manual_cartao_beneficio/manual_cartao_beneficio_endereco)
- Manual Cartão Consignado - Webhook (/documentation/manual_cartao_beneficio/manual_cartao_beneficio_webhook)
- QI Cartões - Pré-pago (/documentation/manual_pre_pago/casos_uso)
- QI FATURA (/documentation/manual_qi_fatura/pix_parcelado)

---

# Manual Cartão Consignado - Acompanhamento

URL: /documentation/manual_cartao_beneficio/manual_cartao_beneficio_acompanhamento

:::info Navegação
- [Emissão](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_emissao) (anterior)
- [Webhooks](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_webhook) (próximo)
:::

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

:::warning 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**

```json
{
  "request_control_key": "550e8400-e29b-41d4-a716-446655440000",
  "payroll_card_reservation_key": "3571e292-3a83-4011-904d-20ee963022ef",
  "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**

```json
{
   "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:

![Status e transições da entidade Payroll Card Reservation](/img/diagrams/manual-cartao-beneficio-manual-cartao-beneficio-acompanhamento-1.svg)

#### 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_additional_documents_submission` | Onboarding aprovado. Aguardando envio do vídeo de confirmação |
| `pending_additional_documents_validation` | Aguardando validação do vídeo de confirmação |
| `pending_collateral_reservation` | Documentos adicionais aprovados. Aguardando reserva de margem na Dataprev |
| `pending_withdrawal_disbursement` | Margem averbada. 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:

![Status e transições da entidade Withdrawal](/img/diagrams/manual-cartao-beneficio-manual-cartao-beneficio-acompanhamento-2.svg)

#### 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:

![Status e transições da entidade Benefit](/img/diagrams/manual-cartao-beneficio-manual-cartao-beneficio-acompanhamento-3.svg)

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

:::warning 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).

```json
// Empty response body
```

---

# Documentos e Assinatura

URL: /documentation/manual_cartao_beneficio/manual_cartao_beneficio_documentos

:::info Navegação
- [Webhooks](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_webhook) (anterior)
- [Gestão de Endereço](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_endereco) (próximo)
:::

Esta seção detalha o fluxo de geração de documentos e o processo de assinatura eletrônica, seja via fluxo externo ou via Qi Sign.

:::info Obs
Caso o cliente esteja integrado no fluxo de assinatura do QISign, os itens dessa secção são opcionais.
:::

## 1. Webhook de Documentos

Após a criação da operação, os documentos (`payroll_card_term`, `withdrawal_operation_term` e `payroll_card_consent_term`) são gerados assincronamente. A API envia um webhook para cada documento notificando a mudança de status do documento.

:::caution Atenção
Caso o cliente não utilize o QISign, o cliente deve implementar o tratamento deste webhook para capturar as URLs dos documentos e direcionar o beneficiário para a assinatura através da certificadora externa escolhida.
:::

:::info Acompanhamento via Webhook
Para conferir a estrutura completa dos payloads, os cenários de eventos e implementar a captura das URLs, consulte a seção **[Webhook de Documentos (Geração e Validação)](./manual_cartao_beneficio_webhook.md#2-webhook-de-documentos-geração-e-validação)** no Manual de Webhooks.
:::

## 2. Assinatura externa de documentos

Este endpoint é utilizado quando a coleta da assinatura e biometria é feita pela interface do cliente (Client Side) ou parceiro externo. O cliente deve enviar os documentos assinados e os dados biométricos para validação.

:::caution Atenção
Esta etapa só deve ser chamada se o fluxo de assinatura **não** for o Qi Sign. Se estiver utilizando Qi Sign, a confirmação será automática.
:::

:::tip Antes de enviar
Realize o upload dos 5 documentos obrigatórios (selfie, frentes/verso do RG, contrato de cartão e contrato de saque) utilizando o endpoint de Upload de Documentos para obter as `document_key`s.
:::

### Request

**POST**
/payroll_card_reservation/social_security/{payroll_card_reservation_key}/signature

Testar no Playground

**Request Body**

```json
{
  "documents": [
    { "document_type": "selfie", "document_key": "2c8f2b3d-8c7a-4e3b-9f6a-1234567890ab" },
    { "document_type": "document_identification", "document_key": "b1a2c3d4-e5f6-7890-abcd-ef0123456789" },
    { "document_type": "document_identification_back", "document_key": "0a1b2c3d-4e5f-6789-0abc-def123456789" },
    { "document_type": "payroll_card_term", "document_key": "9f8e7d6c-5b4a-3210-fedc-ba9876543210" }, 
    { "document_type": "payroll_card_consent_term", "document_key": "d9b64eae-6e11-4b82-92f0-a0e1a3049eee" }, 
    { "document_type": "withdrawal_operation_term", "document_key": "a05c74eb-542a-4820-8954-eef92ebb383f" }
  ],
  "ip_address": "192.168.1.100",
  "signature_datetime": "2025-01-15T14:30:00Z",
  "similarity_score": 0.95,
  "biometry_analysis_reference": "serpro"
}
```

**Request Body Details**

| Campo | Tipo | Descrição | Obrigatório |
|---|---|---|---|
| documents | array | Lista dos 5 documentos exigidos | Sim |
| biometry_analysis_reference | string | Referência da análise biométrica | Sim |
| signature_datetime | string | Data e hora da assinatura (ISO 8601) | Sim |
| ip_address | string | Endereço IP de onde foi feita a assinatura | Sim |
| similarity_score | float | Score de similaridade biométrica | Sim |

#### Enumeradores _Biometry Analysis Reference_

| Enumerador    | Descrição                                                                                                                                                                                                                                                          |
|---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| serpro    | Utilizado quando o similarity_score for retornado através de consulta realizada na base de documentos com foto do Detran (Serviço prestado através da Serpro)                                                                                                      |
| tse       | Utilizado quando o similarity_score for retornado através de consulta realizada na base de documentos com foto do TSE                                                                                                                                              |
| not_found | Deve ser informado quando a biometria facial não for localizada em nenhuma das bases governamentais anteriores (serpro ou tse). Neste caso o similarity_score deve ser null ou o grau de similaridade da selfie com o documento oficial com foto, retornado pelo parceiro. |

#### Item de documents

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| document_type | string | Tipo do documento | Enum: "selfie", "document_identification", "document_identification_back", "payroll_card_term", "payroll_card_consent_term", "withdrawal_operation_term" | Sim |
| document_key | string | Chave única do documento | UUID v4 | Sim |

**Observações sobre os tipos de documento:**
- `selfie`: Foto do beneficiário
- `document_identification`: Frente do documento de identificação
- `document_identification_back`: Verso do documento de identificação  
- `payroll_card_term`: Termos e condições do cartão **assinado** 
- `payroll_card_consent_term`: Termo de consentimento da contratação do cartão **assinado** 
- `withdrawal_operation_term`: Termo da operação de saque **assinado** 

:::danger QI Sign
A QI Tech oferece o serviço de assinatura que atende ao determinado pela IN 138. Com biometria facial e envio de documentos.

Para receber uma cotação consulte nosso time comercial:

comercial@qitech.com.br ou (11) 2339-4763
:::

### Response

STATUS
**200** (OK)

**Response Body**

```json
{
  "payroll_card_reservation_key": "d4e5f6g7-h8i9-0123-defg-456789012345",
  "payroll_card_reservation_status": "pending_onboarding",
  "attached_documents": [
    {
      "document_key": "0b6c9bb9-0bc1-4fd2-9aab-3ccf5c8bc69d",
      "document_type": "withdrawal_operation_term",
      "document_certifier": "electronic_client_side",
      "document_url": "https://storage.googleapis.com/live-doc-api/documents/withdrawal_operation_term.pdf",
      "document_status": "signed",
      "document_batch_key": "ccc42bc6-efbc-4e8f-a7da-fb6cb77e4146",
      "signature_url": "https://storage.googleapis.com/live-doc-api/documents/withdrawal_operation_term_signed.pdf",
    },
    {
      "document_key": "f974bb60-ff4c-4027-9d88-399470586691",
      "document_type": "payroll_card_term",
      "document_certifier": "electronic_client_side",
      "document_url": "https://storage.googleapis.com/live-doc-api/documents/payroll_card_term.pdf",
      "document_status": "signed",
      "document_batch_key": "ccc42bc6-efbc-4e8f-a7da-fb6cb77e4146",
      "signature_url": "https://storage.googleapis.com/live-doc-api/documents/payroll_card_term_signed.pdf",
    },
    {
      "document_key": "0133eda8-0e82-41d9-ae8d-7020f023b0f9",
      "document_type": "payroll_card_consent_term",
      "document_certifier": "electronic_client_side",
      "document_url": "https://storage.googleapis.com/live-doc-api/documents/payroll_card_consent_term.pdf",
      "document_status": "signed",
      "document_batch_key": "ccc42bc6-efbc-4e8f-a7da-fb6cb77e4146",
      "signature_url": "https://storage.googleapis.com/live-doc-api/documents/payroll_card_consent_term.pdf",
    },
    {
      "document_key": "2c8f2b3d-8c7a-4e3b-9f6a-1234567890ab",
      "document_type": "selfie",
      "document_certifier": "electronic_client_side",
      "document_url": "https://storage.googleapis.com/live-doc-api/documents/selfie.pdf",
      "document_status": "generated"
    },
    {
      "document_key": "b1a2c3d4-e5f6-7890-abcd-ef0123456789",
      "document_type": "document_identification",
      "document_certifier": "electronic_client_side",
      "document_url": "https://storage.googleapis.com/live-doc-api/documents/document_identification.pdf",
      "document_status": "generated"
    },
    {
      "document_key": "0a1b2c3d-4e5f-6789-0abc-def123456789",
      "document_type": "document_identification_back",
      "document_certifier": "electronic_client_side",
      "document_url": "https://storage.googleapis.com/live-doc-api/documents/document_identification_back.pdf",
      "document_status": "generated"
    }
  ]
}
```

**Response Body Details**

| Campo | Tipo | Descrição |
|---|---|---|
| payroll_card_reservation_key | string | Chave da reserva do cartão consignado |
| payroll_card_reservation_status | string | Status da reserva (pending_onboarding) |
| attached_documents | array | Lista de documentos e seus status |

:::info Informação
Após a confirmação da assinatura dos dois documentos, o status do cartão consignado será alterado para "pending_onboarding", indicando que a operação está aguardando o processo de onboarding do cartão.
:::

#### Erros comuns

**404 - Document Not Found**

```json
{
  "title": "Document Not Found",
  "description": "Document selfie not found",
  "translation": "Documento selfie não encontrado"
}
```

**Explicação:** Este erro ocorre quando a `document_key` informada no request não foi encontrada no sistema. Verifique se a `document_key` foi obtida corretamente através do endpoint de Upload de documentos

---

## 3. Confirmação de Assinatura

Independente do método de assinatura (Externa ou Qi Sign), quando o processo for concluído com sucesso, você receberá um webhook de mudança de status da reserva.

Consulte a seção **Webhooks de Alteração de Status** no [Manual do Fluxo Principal](./manual_cartao_beneficio_emissao.md) para ver o exemplo de payload com status `pending_onboarding`.

---

# Manual Cartão Consignado - Criação

URL: /documentation/manual_cartao_beneficio/manual_cartao_beneficio_emissao

:::info Navegação
- [Acompanhamento](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_acompanhamento) (próximo)
:::

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

---

:::info **Consultas de Benefícios**
Para consulta de dados do benefício e consulta da lista de benefícios, visite os seguintes itens na documentação do INSS:

- [Consulta da lista de benefícios](/documentation/manual_inss/manual_credito_novo/#1---consulta-da-lista-de-benefícios-com-formalização-do-termo-de-autorização-realizada-através-do-parceiro)
- [Consulta de dados do benefício](/documentation/manual_inss/manual_credito_novo/#2---consulta-de-dados-do-benefício)
:::

## 1. Consulta de elegibilidade do beneficiário

A consulta de elegibilidade permite verificar se um CPF está elegível para o cartão consignado/benefício do INSS. Esta operação é síncrona e retorna imediatamente o resultado da verificação.

Em posse dos dados de **CPF** e **data de nascimento**, é possível consultar a elegibilidade do beneficiário. Atualmente, a única validação de elegibilidade realizada é se a idade do beneficiário está entre 18 e 65 anos.

### Request

**GET**
/payroll_card_reservation/social_security/eligibility

Testar no Playground

**Params**

| Campo             | Tipo   | Descrição                    | Obrigatório | Formatação |
|-------------------|--------|------------------------------|-------------|------------|
| document_number | string | Número de CPF do beneficiário | Sim         | 11 dígitos numéricos |
| birth_date     | date   | Data de nascimento           | Sim         | YYYY-MM-DD |

### Response

STATUS
**200** (OK)

**Exemplos de Response**

**Elegível:**
```json
{
    "status": "eligible"
}
```

**Não elegível - Idade fora do intervalo:**
```json
{
    "status": "not_eligible",
    "error_description": "Age 66 is not within the eligible range (18-65 years)"
}
```

**Response Body Details**

| Campo     | Tipo    | Descrição                                    |
|-----------|---------|----------------------------------------------|
| status | string | Status da elegibilidade (eligible/not_eligible) |
| error_description | string | Descrição do erro quando não elegível (opcional) |

---

## 2. Simulação de saque e limite do cartão

A simulação permite calcular o valor de saque disponível e o limite do cartão consignado baseado nos parâmetros financeiros informados. Esta operação é útil para apresentar ao beneficiário as condições antes da contratação.

### Request
**POST**
/payroll_card_reservation/social_security/simulation

Testar no Playground

**Request Body**

```json
{
  "financial": {
    "salary_amount": 5000.00,
    "number_of_installments": 96,
    "monthly_interest_rate": 0.0246
  },
  "withdrawal": {
    "disbursement_date": "2026-01-02",
    "limit_days_to_disburse": 1,
    "withdrawal_ratio": 0.7
  },
  "collateral": {
    "collateral_type": "social_security_benefit_card"
  }
}
```

**Request Body Details**

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| financial | object | Dados financeiros da operação | - | Sim |
| withdrawal | object | Dados do saque | - | Sim |
| collateral | object | Dados do colateral | - | Sim |

#### Payload financial

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| salary_amount | number | Valor do salário do beneficiário | Mínimo: 1 | Sim |
| number_of_installments | number  | Número de parcelas da CCB de saque | Mínimo: 1, Máximo: 96 | Sim |
| monthly_interest_rate | number  | Taxa de juros mensal da CCB de saque | Mínimo: 0.01, Máximo: 0.0246 | Sim |

#### Payload withdrawal

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| disbursement_date | date  | Data do desembolso da CCB de saque | YYYY-MM-DD | Sim |
| limit_days_to_disburse | number  | Número de dias limite para desembolso da CCB de saque | Mínimo: 1, Máximo: 10| Sim |
| withdrawal_ratio | number  | Parte do limite que será usado para o saque | Mínimo: 0.5, Máximo: 0.7 | Não (default: 0.7) |

#### Payload collateral

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| collateral_type | string | Tipo do cartão | Enum: "social_security_benefit_card", "social_security_payroll_card" | Sim |

### Response

STATUS
**201** (Created)

**Response Body**

```json
{
   "total_limit_amount": 8000,
   "reservation_amount": 250,
   "withdrawal": {
      "withdrawal_amount": 5600,
      "withdrawal_data": {
         "prefixed_interest_rate": {
            "interest_base": "calendar_days",
            "annual_rate": 0.3386043084,
            "monthly_rate": 0.0246,
            "daily_rate": 0.0008104046
         },
         "disbursement_options": [
            {
               "disbursement_date": "2026-01-02",
               "cet": 0.0261,
               "annual_cet": 0.3618,
               "total_iof": 193.55,
               "disbursed_issue_amount": 5600,
               "issue_amount": 5793.55,
               "installments": [
                  {
                     "total_amount": 160.51,
                     "due_date": "2026-02-10",
                     "business_due_date": "2026-02-11",
                     "installment_number": 1
                  },
                  {
                     "total_amount": 160.51,
                     "due_date": "2026-03-10",
                     "business_due_date": "2026-03-11",
                     "installment_number": 2
                  },
                  {
                     "total_amount": 160.51,
                     "due_date": "2026-04-10",
                     "business_due_date": "2026-04-13",
                     "installment_number": 3
                  },
                  ...
               ]
            }
         ]
      }
   },
   "payroll_card": {
      "card_limit": 2400
   }
}
```

**Response Body Details**

| Campo | Tipo | Descrição |
|---|---|---| 
| total_limit_amount | number | Valor total do limite disponível considerando saque e cartão | 
| reservation_amount | number | Valor da reserva do cartão consignado | 
| withdrawal | object | Dados do saque |
| withdrawal.withdrawal_amount | number | Valor de desembolso calculado para CCB de saque | 
| withdrawal.withdrawal_data | object | Dados detalhados do saque | 
| payroll_card | object | Dados do cartão consignado | 
| payroll_card.card_limit | number | Limite total calculado para o cartão | 

#### Payload withdrawal.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 | 

---

## 3. Criação da operação de saque e geração do termo

A criação da operação de saque inicia o processo de contratação do cartão consignado. Esta operação cria a reserva do cartão, gera os documentos necessários e retorna as chaves para acompanhamento do processo.

**POST**
/payroll_card_reservation/social_security

Testar no Playground

### Request

**Request Body**

```json
{
  "request_control_key": "150e8400-e29b-41d4-a716-446655440000",
  "purchaser_document_number": "55566677000177",
  "card_holder": {
    "name": "Carlos Eduardo Lima",
    "email": "carlos.lima@email.com",
    "phone": {
      "number": "654321098",
      "area_code": "31",
      "country_code": "055"
    },
    "gender": "male",
    "address": {
      "city": "Belo Horizonte",
      "state": "MG",
      "number": "789",
      "street": "Rua das Palmeiras",
      "complement": "Casa 3",
      "postal_code": "30112000",
      "neighborhood": "Savassi"
    },
    "birth_date": "1990-09-18",
    "mother_name": "Fernanda Lima",
    "nationality": "Brasileiro",
    "document_number": "55566677788",
    "document_identification": {
      "document_identification_date": "2012-05-20",
      "document_identification_type": "rg",
      "document_identification_number": "555666777"
    }
  },
  "related_parties": [
    {
      "name": "Pedro Costa",
      "email": "pedro.costa@email.com",
      "phone": {
        "number": "765432109",
        "area_code": "21",
        "country_code": "055"
      },
      "address": {
        "city": "Rio de Janeiro",
        "state": "RJ",
        "number": "789",
        "street": "Rua Ipanema",
        "complement": "Apto 12",
        "postal_code": "22080001",
        "neighborhood": "Ipanema"
      },
      "role_type": "issuer_legal_representative",
      "person_type": "natural",
      "is_pep": false,
      "individual_document_number": "11122233344",
      "birth_date": "1980-12-05",
      "mother_name": "Lucia Costa",
      "document_identification": {
        "document_identification_date": "2017-01-14",
        "document_identification_type": "rg",
        "document_identification_number": "222333444"
      }
    }
  ],
  "withdrawal": {
    "disbursement_date": "2026-01-02",
    "limit_days_to_disburse": 1,
    "withdrawal_ratio": 0.7,
    "contract_number": "PCR12345678",
    "disbursement_bank_account": {
      "name": "Carlos Eduardo Lima",
      "bank_code": "104",
      "account_digit": "3",
      "branch_number": "5678",
      "account_number": "987654321",
      "document_number": "55566677788",
      "transfer_method": "pix",
      "account_type": "checking_account"
    }
  },
  "financial": {
    "salary_amount": 5000.00,
    "number_of_installments": 96,
    "monthly_interest_rate": 0.0246,
    "emission_installments": 1
  },
  "collateral": {
    "state": "MG",
    "benefit_number": "5556667777",
    "collateral_type": "social_security_benefit_card",
    "subcorban_document_number": "12123456000101",
    "assistance_type": "pension_by_death_rural_worker"
  },
  "credit_agent": {
    "document_number": "44455566677",
    "name": "Agente de Crédito Lima"
  }
}
```

**Request Body Details**

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| request_control_key | string | Chave de identificação da requisição | UUID v4 | Sim |
| purchaser_document_number | string | CNPJ do comprador | 14 dígitos numéricos | Sim |
| card_holder | object | Dados do portador do cartão | - | Sim |
| withdrawal | object | Dados do saque | - | Sim |
| financial | object | Dados financeiros da operação | - | Sim |
| collateral | object | Dados do colateral | - | Sim |
| credit_agent | object | Dados do agente de crédito | - | Sim |
| related_parties | array | Lista de partes relacionadas | - | Não |

#### Payload card_holder

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| name | string | Nome completo do portador | Mínimo: 1 caractere válido | Sim |
| email | string | Email do portador | Formato de email válido | Sim |
| phone | object | Dados do telefone | - | Sim |
| gender | string | Gênero | Enum: "male", "female" | Sim |
| address | object | Endereço do portador e de entrega do cartão. | - | Sim |
| birth_date | date | Data de nascimento | YYYY-MM-DD | Sim |
| mother_name | string | Nome da mãe | Mínimo: 1 caractere válido | Sim |
| nationality | string | Nacionalidade | Mínimo: 1 caractere | Sim |
| document_number | string | CPF do portador | 11 dígitos numéricos | Sim |
| document_identification | object | Dados do documento de identificação | - | Sim |

#### Payload related_parties

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| name | string | Nome da parte relacionada | Mínimo: 1 caractere válido | Sim |
| email | string | Email da parte relacionada | Formato de email válido | Sim |
| phone | object | Dados do telefone | - | Sim |
| address | object | Endereço da parte relacionada | - | Sim |
| role_type | string | Tipo de papel | Enum: "issuer_legal_representative", "issuer_attorney" | Sim |
| person_type | string | Tipo de pessoa | Enum: "natural" | Sim |
| is_pep | boolean | Se é pessoa politicamente exposta | true/false | Sim |
| individual_document_number | string | CPF da parte relacionada | 11 dígitos numéricos | Sim |
| birth_date | date | Data de nascimento | YYYY-MM-DD | Sim |
| mother_name | string | Nome da mãe | Mínimo: 1 caractere válido | Sim |
| document_identification | object | Dados do documento de identificação | - | Sim |

#### Payload phone

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| number | string | Número do telefone | Apenas números | Sim |
| area_code | string | Código de área | Apenas números | Sim |
| country_code | string | Código do país | Apenas números | Sim |

#### Payload address

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| city | string | Cidade | Mínimo: 1 caractere | Sim |
| state | string | Estado | 2 caracteres | Sim |
| number | string | Número | Mínimo: 1 caractere | Sim |
| street | string | Rua | Mínimo: 1 caractere | Sim |
| complement | string | Complemento | Mínimo: 1 caractere | Não |
| postal_code | string | CEP | 8 dígitos numéricos | Sim |
| neighborhood | string | Bairro | Mínimo: 1 caractere | Sim |

#### Payload document_identification

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| document_identification_date | date | Data de emissão do documento | YYYY-MM-DD | Sim |
| document_identification_type | string | Tipo do documento | Enum: "rg", "passport", "other" | Sim |
| document_identification_number | string | Número do documento | Mínimo: 1 caractere | Sim |

#### Payload withdrawal

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| disbursement_date | date | Data do desembolso | YYYY-MM-DD | Sim |
| limit_days_to_disburse | number | Número de dias limite para desembolso | Mínimo: 1, Máximo: 10 | Sim |
| contract_number | string | Número do contrato | 3 letras maiúsculas + 8 números | Sim |
| disbursement_bank_account | object | Conta bancária para desembolso | - | Sim |

#### Payload disbursement_bank_account

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| name | string | Nome do titular da conta | Mínimo: 1 caractere válido | Sim |
| bank_code | string | Código do banco | 3 dígitos numéricos | Sim |
| account_digit | string | Dígito da conta | 1 dígito numérico | Sim |
| branch_number | string | Número da agência | Apenas números | Sim |
| account_number | string | Número da conta | Apenas números | Sim |
| document_number | string | CPF do titular | 11 dígitos numéricos | Sim |
| transfer_method | string | Método de transferência | Enum: "pix", "ted" | Sim |
| account_type | string | Tipo de conta | Enum: "checking_account","deposit_account","guaranteed_account","investment_account","payment_account","saving_account","salary_account" | Sim |

#### Payload financial

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| salary_amount | number | Valor do salário do beneficiário (valor total do benefício) | Mínimo: 1 | Sim |
| number_of_installments | number | Número de parcelas das CCBs (saque e rotativo) | Mínimo: 1, Máximo: 96 | Sim |
| monthly_interest_rate | number | Taxa de juros mensal das CCBs (saque e rotativo) | Mínimo: 0.01, Máximo: 0.0246 | Sim |
| emission_installments | number | Número de Parcelas da taxa de emissão do cartão (Conforme coletado com o beneficiário) | Mínimo: 1, Máximo: 3 | Sim |

#### Payload collateral

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| state | string | Estado | 2 caracteres | Sim |
| benefit_number | string | Número do benefício | Mínimo: 1 caractere | Sim |
| collateral_type | string | Tipo da garantia | Enum: "social_security_benefit_card" (Cartão Benefício), "social_security_payroll_card" (Cartão Consignado) | Sim |
| subcorban_document_number | string | Número do documento do correspondente bancário (ou filial de correspondnte bancário) responsável pela operação | 14 dígitos numéricos | Sim |

| assistance_type | string | Tipo do benefício | Enum: [Enumeradores](#benefit_type_enumerator)  | Sim |

#### Payload credit_agent

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| document_number | string | CPF do agente de crédito | 11 ou 14 dígitos numéricos | Sim |
| name | string | Nome do agente de crédito | Mínimo: 1 caractere válido | Sim |

### Response

STATUS
**201** (Created)

**Response Body**

```json
{
   "request_control_key": "150e8400-e29b-41d4-a716-446655440000",
   "payroll_card_type": "social_security_benefit_card",
   "payroll_card_reservation_key": "72d63aea-15b6-402c-a18b-d12cd4619c9d",
   "card_holder_document_number": "55566677788",
   "identifier_number": "5556667777",
   "total_limit_amount": 8000,
   "reservation_amount": 250,
   "withdrawal": {
      "withdrawal_key": "56cfe7b7-ed6e-4212-8744-c9fcff309ec0",
      "withdrawal_amount": 5600,
      "credit_operation_key": null,
      "withdrawal_status": "pending_signature",
      "contract_number": "PCR12345678",
      "withdrawal_data": {
         "prefixed_interest_rate": {
            "interest_base": "calendar_days",
            "annual_rate": 0.3386043084,
            "monthly_rate": 0.0246,
            "daily_rate": 0.0008104046
         },
         "disbursement_options": [
            {
               "disbursement_date": "2026-01-02",
               "cet": 0.0261,
               "annual_cet": 0.3618,
               "total_iof": 193.55,
               "disbursed_issue_amount": 5600,
               "issue_amount":  5793.55,
               "installments": [
                  {
                     "total_amount": 160.51,
                     "due_date": "2026-02-10",
                     "business_due_date": "2026-02-11",
                     "installment_number": 1
                  },
                  {
                     "total_amount": 160.51,
                     "due_date": "2026-03-10",
                     "business_due_date": "2026-03-11",
                     "installment_number": 2
                  },
                  {
                     "total_amount": 160.51,
                     "due_date": "2026-04-10",
                     "business_due_date": "2026-04-13",
                     "installment_number": 3
                  },
                  ...
               ]
            }
         ]
      },
      "wallet_entry_key": null
   },
   "payroll_card": {
      "payroll_card_key": "572650c7-67f6-4f73-8444-b9da72000057",
      "payroll_card_status": "pending_issuance",
      "card_key": null,
      "payment_instrument_key": null,
      "card_issuance_entry_key": null,
      "card_issuance_entry_amount": 17.28,
      "card_limit": 2400
   },
   "attached_documents": [
      {
         "document_key": "32f5e5e2-a15a-40af-9ddc-cddaba1966cf",
         "document_type": "withdrawal_operation_term",
         "document_certifier": "qi_sign",
         "document_status": "pending_generation",
         "document_url": null,
         "document_batch_key": "f4f2b64c-5608-44bb-a2df-bf62cf26cc76"
      },
      {
         "document_key": "7767e30e-417e-4dd7-b061-bba722451d10",
         "document_type": "payroll_card_term",
         "document_certifier": "qi_sign",
         "document_status": "pending_generation",
         "document_url": null,
         "document_batch_key": "f4f2b64c-5608-44bb-a2df-bf62cf26cc76"
      },
      {
         "document_key": "6c839b10-9558-4e6e-9f7d-d1e494cf6156",
         "document_type": "payroll_card_consent_term",
         "document_certifier": "qi_sign",
         "document_status": "pending_generation",
         "document_url": null,
         "document_batch_key": "f4f2b64c-5608-44bb-a2df-bf62cf26cc76"
      }
   ],
   "payroll_card_reservation_status": "pending_document_generation",
   "wallet_key": null,
   "reservation_contract_number": "PCR0000000822"
}
```

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

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

---

---

## 4. Envio de documentos adicionais

Após a aprovação do onboarding, a reserva é atualizada para o status `pending_additional_documents_submission`. Para prosseguir com a reserva de margem e o desembolso da operação, é obrigatório o envio dos documentos adicionais (Para o produto de Cartão Consignado/Benefício de INSS, o **vídeo de confirmação da contratação**).

O processamento do upload é assíncrono. O upload bem sucedido aciona a transição automática da reserva para `pending_additional_documents_validation`, disparando os webhooks de [alteração de status](./manual_cartao_beneficio_webhook.md) e de [atualização de documentos](./manual_cartao_beneficio_documentos.md), e acionando a validação dos documentos.

:::info Reprovação e Re-envio de Documentos Adicionais
Caso os documentos adicionais sejam rejeitados na validação do sistema, a reserva retornará para o status `pending_additional_documents_submission` e será possível realizar o re-envio dos documentos adicionais por este mesmo endpoint. Não é possível realizar o re-envio dos documentos adicionais antes da aprovação/rejeição pela análise do sistema, e existe um limite de 5 análises por reserva e tipo de documento.
:::

:::warning Atenção: Gatilho de Desembolso
O envio e a subsequente aprovação pelo sistema dos documentos adicionais são tratados como autorização para o desembolso da operação de crédito. Após a validação bem sucedida dos dos arquivos, a operação seguirá automaticamente para a averbação e para a criação da operação de crédito e será efetuado o desembolso na conta do beneficiário, **sem etapas adicionais de aprovação**.
:::

### Request

**POST**
/payroll_card_reservation/social_security/[PAYROLL-CARD-RESERVATION-KEY]/additional_documents

Testar no Playground

**Params**

| Campo | Tipo | Descrição | Obrigatório |
|---|---|---|---|
| payroll_card_reservation_key | string | Chave única da reserva (UUID) | Sim |

**Request Body**

```json
{
  "documents": [
      {
        "document_type": "payroll_card_confirmation_video", 
        "document_url": "https://download.samplelib.com/mp4/sample-5s.mp4"
      }
  ]
}
```

**Request Body Details**

| Campo | Tipo | Descrição | Obrigatório |
|---|---|---|---|
| documents | array | Lista de documentos a serem anexados | Sim |

#### Payload documents

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| document_type | string | Tipo do documento | Enum: "payroll_card_confirmation_video" | Sim |
| document_url | string | URL pública para download do arquivo de vídeo | URL válida | Sim |

:::info **URL do Vídeo**
Garanta que a URL enviada é acessível por usuários externos, para conseguirmos efetuar o upload do arquivo para o banco de dados interno da QI.

- Formatos de arquivo suportados: .mp4
- Tamanho máximo do arquivo: 256MB
:::

### Response

STATUS
**200** (OK)

A requisição foi recebida com sucesso e o documento será processado assincronamente.

```json
{
   "attached_documents": [
      {
         "document_key": "2fc216c6-5d1c-4713-b70b-6e1f75f8bb17",
         "document_type": "payroll_card_confirmation_video",
         "document_certifier": "electronic_client_side",
         "document_status": "pending_generation",
         "document_url": ""
      }
   ],
}
```

---

## 5. Reapresentação de Pagamento do Saque

Caso o pagamento não seja processado devido a dados incorretos, é possível pode ajustar as informações da conta bancária para reapresentação através do seguinte endpoint:

**PATCH**
/payroll_card_reservation/social_security/[PAYROLL-CARD-RESERVATION-KEY]/disbursement_account

Testar no Playground

### Request

**Request Body**

```json
{
   "disbursement_bank_account": {
      "name": "Carlos Eduardo Lima",
      "bank_code": "001",
      "account_digit": "3",
      "branch_number": "5678",
      "account_number": "987654321",
      "document_number": "55566677788",
      "transfer_method": "pix",
      "account_type": "checking_account"
   }
}
```

**Request Body Details**

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| disbursement_bank_account | object | Conta bancária para desembolso | - | Sim |

#### Payload disbursement_bank_account

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| name | string | Nome do titular da conta | Mínimo: 1 caractere válido | Sim |
| bank_code | string | Código do banco | 3 dígitos numéricos | Sim |
| account_digit | string | Dígito da conta | 1 dígito numérico | Sim |
| branch_number | string | Número da agência | Apenas números | Sim |
| account_number | string | Número da conta | Apenas números | Sim |
| document_number | string | CPF do titular | 11 dígitos numéricos | Sim |
| transfer_method | string | Método de transferência | Enum: "pix", "ted" | Sim |
| account_type | string | Tipo de conta | Enum: "checking_account","deposit_account","guaranteed_account","investment_account","payment_account","saving_account","salary_account" | Sim |

### Response

STATUS
**200** (OK)

---

## 6. Anexos 

### Referências
:::info **Fura Fila**
A funcionalidade de [Fura Fila](/docs/guides/INSS/reservations/priority-request.md) (Averbação Síncrona) está disponível apra o Cartão INSS, utilizando a payroll_card_reservation_key como a \{deby_key\} da requisição.:
:::

### Ambiente de Homologação (Mocks)

Para facilitar os testes de integração em ambiente de **Sandbox**, o sistema simula diferentes comportamentos baseados no **primeiro dígito do CPF do beneficiário** enviado no payload de criação.

Utilize a tabela abaixo para simular cenários de sucesso e erro:

| 1º Dígito do CPF | Cenário | Comportamento Interno | Resultado Final (Cliente) |
| :---: | --- | --- | --- |
| **1** | **Fluxo Ideal (Completo)** | **Sucesso** na Assinatura <br/> **Sucesso** no Onboarding <br/> **Sucesso** na Averbação (Dataprev) | **Cartão emitido** <br/> (Status: `card_issued`) |
| **2** | **Erro na Consulta Dataprev** | **Sucesso** na Assinatura <br/> **Sucesso** no Onboarding <br/> **Falha** na Consulta de Benefício | **Reserva cancelada** <br/> (Status: `canceled`) <br/> + **Envio de Webhook de status** <br/> (Status: `canceled`) |
| **3** | **Erro na Averbação Dataprev** | **Sucesso** na Assinatura <br/> **Sucesso** no Onboarding <br/> **Falha** na Averbação/Reserva de Margem | **Reserva cancelada** <br/> (Status: `canceled`) <br/> + **Envio de Webhook de status** <br/> (Status: `canceled`) |
| **4** | **Erro de Endereço** | **Sucesso** na Assinatura <br/> **Sucesso** no Onboarding (Endereço Divergente) <br/> **Sucesso** na Averbação (Dataprev) | **Cartão emitido** <br/> (Status: `card_issued`) <br/> + **Envio de Webhook de atualização de endereço** |
| **5** | **Onboarding Rejeitado** | **Sucesso** na Assinatura <br/> **Rejeição** no Onboarding/KYC | **Reserva cancelada** <br/> (Status: `canceled`) <br/> + **Envio de Webhook de status** <br/> (Status: `canceled`) |
| **6** | **Inelegível (Idade > 65)** | **Sucesso** na Assinatura <br/> **Sucesso** no Onboarding (Retorna idade superior a 65 anos) | **Reserva cancelada** <br/> (Status: `canceled`) <br/> + **Envio de Webhook de status** <br/> (Status: `canceled`) |
| **7** | **Inelegível (Idade < 18)** | **Sucesso** na Assinatura <br/> **Sucesso** no Onboarding (Retorna idade inferior a 18 anos) | **Reserva cancelada** <br/> (Status: `canceled`) <br/> + **Envio de Webhook de status** <br/> (Status: `canceled`) |
| **8** | **Teimosinha (Retentativa)** | **Sucesso** na Assinatura <br/> **Sucesso** no Onboarding <br/> **Falha Temporária** na Averbação (Dataprev) | **Aguardando liberação** <br/> (Status: `pending_reservation`) <br/> + **Envio de Webhook de Collateral** |

:::tip Dica
Para testar o **Fluxo ideal**, certifique-se de usar um CPF que comece com o dígito `1` (ex: `123.456.789-00`) e que seja válido (cálculo de dígitos verificadores correto).
:::

:::warning Aviso
Os mocks de sucesso estão configurados para simular benefícios de até R$10.000,00. Caso valores de benefício acima deste sejam usados, o sistema irá retornar erro de margem excedida na averbação, cancelando a reserva.
:::
---

### Tabela de benefícios {#benefit_type_enumerator}

| código   | benefício                                   |
| --- | ------------------------------------------------ |
| 1   | pension_by_death_rural_worker                    |
| 2   | pension_by_death_accident_rural_worker           |
| 3   | pension_by_death_rural_employer                  |
| 4   | retirement_invalidity_rural_emploee              |
| 5   | retirement_invalidity_accident_rural_worker      |
| 6   | retirement_invalidity_rural_employer             |
| 7   | retirement_by_eldness_rural_worker               |
| 8   | retirement_by_age_rural_employer                 |
| 9   | complement_by_work_accident_rural_worker         |
| 11  | support_invalidity_rural_worker                  |
| 12  | support_by_age_rural_worker                      |
| 13  | aid_sickness_rural_worker                        |
| 15  | aid_time_off_rural_worker                        |
| 16  | aid_federal                                      |
| 17  | international_agreement                          |
| 18  | inclusion_benefit                                |
| 19  | pension_student_law7004                          |
| 20  | pension_by_death_diplomat                        |
| 21  | pension_by_death                                 |
| 22  | pension_by_death_statute                         |
| 23  | pension_by_death_veteran                         |
| 24  | pension_special_institutional_act                |
| 25  | aid_time_off                                     |
| 26  | pension_by_death_special_law593                  |
| 27  | pension_by_death_federal_emploee                 |
| 28  | pension_by_death_general_regime_law20465         |
| 29  | pension_by_death_marine_veteran                  |
| 30  | monthly_income_lifetime_invalidity               |
| 31  | aid_sickness                                     |
| 32  | retirement_invalidity_social_security            |
| 33  | retirement_invalidity_aeronautic                 |
| 34  | retirement_invalidity_marine_law1756             |
| 35  | aid_sickness_veteran                             |
| 36  | aid_social_security_accident                     |
| 37  | retirement_capin_extra_emploee                   |
| 38  | retirement_federal_extra_emploee                 |
| 39  | aid_invalidity_student_law7004                   |
| 40  | monthly_income_lifetime_by_age_upper70_law6179   |
| 41  | retirement_by_age                                |
| 42  | retirement_by_contribution_time                  |
| 43  | retirement_by_time_of_service_veteran            |
| 44  | retirement_special_aeronautic                    |
| 45  | retirement_by_time_of_service_journalist         |
| 46  | retirement_special                               |
| 47  | allowance_25                                     |
| 48  | allowance_20                                     |
| 49  | retirement_ordinary                              |
| 50  | aid_sickness_extinct_basic_plan                  |
| 51  | retirement_invalidity_extinct_basic_plan         |
| 52  | retirement_by_age_extinct_basic_plan             |
| 53  | aid_time_off_extinct_basic_plan                  |
| 54  | pension_indemnity_federal                        |
| 55  | pension_by_death_extinct_basic_plan              |
| 56  | pension_lifetime_syndrome_thalidomide            |
| 57  | retirement_by_teacher_labor_time                 |
| 58  | retirement_anisty                                |
| 59  | pension_by_death_amnesty                         |
| 60  | indemnity                                        |
| 61  | aid_birth                                        |
| 62  | aid_funeral                                      |
| 63  | aid_funeral_rural_worker                         |
| 64  | aid_funeral_rural_employer                       |
| 65  | savings_special_autarchy                         |
| 67  | savings_mandatory_ipase_law5128                  |
| 68  | savings_special_retirement_ps_affiliated_upper60 |
| 69  | savings_student_law7004                          |
| 70  | restitution                                      |
| 71  | monthly_income                                   |
| 72  | retirement_by_time_of_service_law1756            |
| 73  | monthly_income_family_statute                    |
| 74  | complement_pension_federal                       |
| 75  | complement_retirement_federal                    |
| 76  | monthly_income_statute                           |
| 77  | monthly_income_sinpas_family_statute             |
| 78  | retirement_by_age_law1756                        |
| 79  | advantage                                        |
| 80  | monthly_income_maternity                         |
| 81  | compulsory_retirement                            |
| 82  | retirement_by_time_of_service_sasse              |
| 83  | retirement_invalidity_ex_sasse                   |
| 84  | pension_by_death_sasse                           |
| 85  | pension_lifetime_rubber_tapper_law7986           |
| 86  | pension_lifetime_rubber_tapper_dependent_law7986 |
| 87  | continuous_aid_physical_disabilities             |
| 88  | continuous_aid_eldness                           |
| 89  | pension_special_hemodialysis_victim_caruaru      |
| 90  | medic_assistency_work_accident                   |
| 91  | aid_sickness_by_work_accident                    |
| 92  | retirement_invalidity_work_accident              |
| 93  | pension_by_death_work_accident                   |
| 94  | aid_work_accident                                |
| 95  | aid_additional_work_accident                     |
| 96  | pension_special_leprosy_law11520                 |
| 97  | savings_by_death_work_accident                   |
| 98  | aid_longshoreman                                 |
| 99  | time_off_15                                      |

---

# Gestão de Endereço

URL: /documentation/manual_cartao_beneficio/manual_cartao_beneficio_endereco

:::info Navegação
- [Documentos e Assinatura](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_documentos) (anterior)
:::

Durante o processo de Onboarding e KYC, o endereço do beneficiário é validado tanto por nossos processos de análise quanto pelo próprio beneficiário. Além disso, problemas de endereço também podem ser identificados durante a tentativa de entrega do cartão. Em ambos os casos, o cliente será notificado via webhook para realizar a confirmação ou a correção dos dados junto ao beneficiário.

## 1. Webhook de problema no endereço

Este webhook é disparado quando é identificado um problema relacionado ao endereço do beneficiário. Existem dois cenários possíveis, identificados pelo campo `rejected_reason`:

- **`address_mismatch`**: Inconsistência detectada durante o processo de KYC entre o endereço enviado e o endereço em nossa base.
- **`delivery_failure`**: Falha na tentativa de entrega do cartão físico no endereço cadastrado.

:::caution Ação Necessária
Ao receber este webhook, o cliente deve contatar o beneficiário e solicitar a correção dos dados através do endpoint de **Atualização de Endereço**. 
Estes webhooks também são informados ao beneficiário final através do aplicativo. No entanto, o cliente deve acompanhar e tratar esses casos independentemente, garantindo que a correção do endereço seja realizada pelo cliente ou pelo beneficiário.
:::

:::danger Prazo para Falha de Entrega (`delivery_failure`)
Após o recebimento de um webhook de falha na entrega, o cliente tem um prazo de **10 dias** para atualizar o endereço do beneficiário. Caso o prazo não seja cumprido, o cartão físico será cancelado e será necessária uma nova emissão do cartão através do endpoint de [Reemissão de Cartão](#3-reemissão-de-cartão).
:::

WEBHOOK TYPE
laas.payroll_card_reservation.address

### 1.1 Exemplo: Inconsistência de endereço (KYC)

**Webhook Body — address_mismatch**

```json
{
    "key": "3571e292-3a83-4011-904d-20ee963022ef",
    "webhook_type": "laas.payroll_card_reservation.address",
    "status": "pending_card_issuance",
    "event_datetime": "2025-01-15T16:45:00Z",
    "data": {
        "address": {
          "city": "Belo Horizonte",
          "state": "MG",
          "postal_code": "30112000",
          "street": "Rua Inexistente",
          "number": "000",
          "neighborhood": "Savassi"
        }, 
        "rejected_reason": "address_mismatch",
        "rejection_details": {
            "cancel_reason_description": "Endereço não encontrado na base de validação",
            "cancel_reason_translation": "Endereço não encontrado na base de validação"
        }
    }
}
```

### 1.2 Exemplo: Falha na entrega do cartão

**Webhook Body — delivery_failure**

```json
{
    "key": "3571e292-3a83-4011-904d-20ee963022ef",
    "webhook_type": "laas.payroll_card_reservation.address",
    "status": "card_issued",
    "event_datetime": "2025-01-15T16:45:00Z",
    "data": {
        "address": {
          "city": "Belo Horizonte",
          "state": "MG",
          "postal_code": "30112000",
          "street": "Rua das Palmeiras",
          "number": "789",
          "neighborhood": "Savassi"
        }, 
        "rejected_reason": "delivery_failure",
        "rejection_details": {
            "cancel_reason_description": "Delivery Failure",
            "cancel_reason_translation": "Falha na entrega"
        }
    }
}
```

---

## 2. Atualização de Endereço

Endpoint utilizado para corrigir o endereço do beneficiário após o recebimento de um webhook de erro de validação.

:::info 
Caso o beneficiário confirme o endereço, não é necessário enviar uma requisição de atualização de endereço, e o endereço já cadastrado será utilizado para o envio do cartão.
:::

### Request

**PATCH**
/payroll_card_reservation/social_security/{payroll_card_reservation_key}/address

Testar no Playground

**Request Body**

```json
{
    "address": {
        "city": "Belo Horizonte",
        "state": "MG",
        "number": "789",
        "street": "Rua das Palmeiras",
        "complement": "Casa 3",
        "postal_code": "30112000",
        "neighborhood": "Savassi"
    }
}
```

**Params Details**

| Campo | Tipo | Descrição | Obrigatório |
|---|---|---|---|
| city | string | Cidade | Sim |
| state | string | Estado (UF) | Sim |
| number | string | Número | Sim |
| street | string | Logradouro | Sim |
| complement | string | Complemento | Não |
| postal_code | string | CEP (apenas números) | Sim |
| neighborhood | string | Bairro | Sim |

### Response

STATUS
**200** (OK)

A operação será automaticamente reprocessada no fluxo de KYC, potencialmente resultando em um novo webhook de erro caso seja detectada alguma inconsistência novamente.

---

## 3. Reemissão de Cartão

Endpoint utilizado para **cancelar o cartão físico atual e emitir um novo cartão** para uma reserva já finalizada (`card_issued`). Deve ser utilizado quando o cartão ainda está em produção ou entrega (ex.: endereço incorreto, falha de entrega, cartão extraviado antes da ativação).

:::info Preservação da operação
A reemissão **não cancela** a reserva, a operação de crédito nem a averbação na Dataprev.
:::

:::caution Cobrança da re-emissão
A taxa de produção e de entrega da re-emissão do cartão é cobrada do correspondente bancário automaticamente via sistema.
:::

:::caution Status elegíveis do cartão
A reemissão só é permitida enquanto o cartão estiver em produção ou entrega. São aceitos cartões nos seguintes status: `building`, `embossing` ou `canceled`. Cartões já ativos (`active`) não podem ser reemitidos por este endpoint.
:::

:::tip Atualização de endereço no mesmo fluxo
Opcionalmente, é possível enviar um novo endereço de entrega no corpo da requisição. Quando informado, o endereço do beneficiário na reserva é atualizado e o novo cartão é produzido/entregue neste endereço.
:::

### Request

**POST**
/payroll_card_reservation/social_security/{payroll_card_reservation_key}/reissue_card

Testar no Playground

**Request Body (opcional)**

```json
{
    "delivery_address": {
        "city": "Belo Horizonte",
        "state": "MG",
        "number": "789",
        "street": "Rua das Palmeiras",
        "complement": "Casa 3",
        "postal_code": "30112000",
        "neighborhood": "Savassi"
    }
}
```

O corpo da requisição é opcional. Caso não seja enviado, o novo cartão será emitido utilizando o endereço atualmente cadastrado na reserva.

**Request Body Details**

| Campo | Tipo | Descrição | Obrigatório |
|---|---|---|---|
| delivery_address | object | Novo endereço de entrega. Quando enviado, também atualiza o endereço cadastrado na reserva. | Não |

#### Payload delivery_address

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| city | string | Cidade | Mínimo: 1 caractere | Sim |
| state | string | Estado (UF) | 2 caracteres | Sim |
| number | string | Número | Mínimo: 1 caractere | Sim |
| street | string | Logradouro | Mínimo: 1 caractere | Sim |
| complement | string | Complemento | Mínimo: 1 caractere | Não |
| postal_code | string | CEP (apenas números) | 8 dígitos numéricos | Sim |
| neighborhood | string | Bairro | Mínimo: 1 caractere | Sim |

### Response

STATUS
**200** (OK)

Retorna o DTO completo da reserva do cartão consignado, já com o novo `payroll_card` (nova `payroll_card_key`, `card_key` e `payment_instrument_key`). A estrutura do retorno é a mesma descrita na [criação da reserva](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_emissao#3-criação-da-operação-de-saque-e-geração-do-termo).

---

# Manual Cartão Consignado - Webhook

URL: /documentation/manual_cartao_beneficio/manual_cartao_beneficio_webhook

:::info Navegação
- [Acompanhamento](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_acompanhamento) (anterior)
- [Documentos e Assinatura](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_documentos) (próximo)
:::

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

---

## 1. Webhook de Alteração de Status (Global)

Para acompanhar a evolução do pedido (Assinatura concluída, Falha no Onboarding, Desembolso realizado ou Cartão Emitido), a API envia um webhook único notificando a mudança de status da reserva.

WEBHOOK TYPE
laas.payroll_card_reservation.status_change

### Estrutura Geral do Webhook

| Campo | Tipo | Descrição |
|---|---|---|
| key | string | Chave da reserva do cartão |
| status | string | Novo status da reserva |
| webhook_type | string | `laas.payroll_card_reservation.status_change` |
| event_datetime | string | Data e hora do evento |
| data | object | Objeto contendo dados relevantes para a mudança de estado |

### Cenários

#### A. Assinatura Concluída (Pending Onboarding)
Ocorre quando os documentos são assinados (via Qi Sign ou externamente). O status da reservation muda para `pending_onboarding` e o fluxo segue para onboarding. 

Retorna a lista dos attached documents da Reserva, além dos dados da análise facial do assinante .

**Exemplo de Payload**

```json
{
    "key": "3571e292-3a83-4011-904d-20ee963022ef",
    "status": "pending_onboarding",
    "webhook_type": "laas.payroll_card_reservation.status_change",
    "event_datetime": "2025-01-15T14:30:00Z",
    "data": {
        "attached_documents": [
            {
                "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":"0f0651de-bf3f-45f8-891f-f81b9c24df10",
                "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":"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":"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"
            }
        ],
        "signature_data": {
            "document_similarity_score": 1,
            "similarity_score": 0.75,
            "biometry_analysis_reference": "internal",
        }
    }
}
```

**Response Body Details**

| Campo | Tipo | Descrição |
|---|---|---|
| attached_documents | array | Lista de documentos criados para a reserva |
| signature_data | object | Dados biométricos coletados na 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 |

#### B. Envio de Documentos Adicionais (Pending Additional Documents Submission)
Ocorre quando o onboarding é aprovado com sucesso **OU** quando a operação retorna da etapa de validação devido à rejeição do documento adicional (vídeo).

Este webhook indica que a operação está aguardando o envio (ou reenvio) do vídeo de confirmação via endpoint `/additional_documents`. Caso seja um reenvio por rejeição, o payload retornará o campo `rejection_reason`.

**Exemplo de Payload**

```json
{
    "key": "3571e292-3a83-4011-904d-20ee963022ef",
    "status": "pending_additional_documents_submission",
    "webhook_type": "laas.payroll_card_reservation.status_change",
    "event_datetime": "2025-01-15T16:00:00Z",
    "data": {
        "rejection_reason": "Vídeo sem áudio ou ilegível" // Presente apenas quando retornando do status pending_additional_documents_validation após a rejeição de um documento
    }
}
```

#### C. Validação de Documentos Adicionais (Pending Additional Documents Validation)
Ocorre após o envio com sucesso do vídeo de confirmação. O status muda para `pending_additional_documents_validation`, indicando que o vídeo/documento adicional entrou na fila para validação e análise.

**Exemplo de Payload**

```json
{
    "key": "3571e292-3a83-4011-904d-20ee963022ef",
    "status": "pending_additional_documents_validation",
    "webhook_type": "laas.payroll_card_reservation.status_change",
    "event_datetime": "2025-01-15T16:15:00Z",
    "data": {}
}
```

#### D. Documentos Adicionais Aprovados (Pending Collateral Reservation)
Ocorre após a etapa de validação analisar e aprovar o vídeo de confirmação. O status muda para `pending_collateral_reservation` (aguardando reserva de margem na Dataprev).

**Exemplo de Payload**

```json
{
    "key": "3571e292-3a83-4011-904d-20ee963022ef",
    "status": "pending_collateral_reservation",
    "webhook_type": "laas.payroll_card_reservation.status_change",
    "event_datetime": "2025-01-15T17:00:00Z",
    "data": {}
}
```

#### E. Margem Averbada (Pending Withdrawal Disbursement)
Ocorre quando a margem é reservada com sucesso na Dataprev e a operação de crédito é criada e está aguardando desembolso. O status muda para `pending_withdrawal_disbursement` (aguardando desembolso do saque).

**Exemplo de Payload**

```json
{
    "key": "3571e292-3a83-4011-904d-20ee963022ef",
    "status": "pending_withdrawal_disbursement",
    "webhook_type": "laas.payroll_card_reservation.status_change",
    "event_datetime": "2025-01-15T17:30:00Z",
    "data": {
        "credit_operation_key": "3571e292-3a83-4011-904d-20ee963022ef"
    }
}
```

#### F. Desembolso Realizado (Pending Card Issuance)
Ocorre quando o saque é efetivado. O status muda para `pending_card_issuance` (aguardando emissão do cartão) e o fluxo segue para a emissão do cartão.

Não retorna nenhuma informação adicional.

**Exemplo de Payload**

```json
{
    "key": "3571e292-3a83-4011-904d-20ee963022ef",
    "status": "pending_card_issuance",
    "webhook_type": "laas.payroll_card_reservation.status_change",
    "event_datetime": "2025-01-15T17:00:00Z",
    "data": {
        "wallet_key": "9a7b7982-8bf7-4a2c-942c-588166811623"
    }
}
```

#### G. Cartão Emitido (Card Issued)
Ocorre quando a wallet e o cartão são criados.

**Exemplo de Payload**

```json
{
    "key": "3571e292-3a83-4011-904d-20ee963022ef",
    "status": "card_issued",
    "webhook_type": "laas.payroll_card_reservation.status_change",
    "event_datetime": "2025-01-15T18:30:00Z",
    "data": {
        "card_key": "7c6b421e-7ae0-4419-b021-87bcc0be8748"
    }
}
```

---

#### H. Cancelamento (Canceled)
Ocorre quando a operação é cancelada por algum motivo (Rejeição nas validações de identidade ou crédito, erro na reserva da margem na Dataprev, etc).

Retorna o motivo do cancelamento e detalhes.

**Exemplo de Payload**

```json
{
    "key": "3571e292-3a83-4011-904d-20ee963022ef",
    "status": "canceled",
    "webhook_type": "laas.payroll_card_reservation.status_change",
    "event_datetime": "2025-01-15T16:45:00Z",
    "data": {
        "cancel_reason": "not_eligible", 
        "cancel_details": "Age 15 is not within the eligible range (18-79 years)"
    }
}
```

---

## 2. Webhook de Documentos (Geração e Validação)

Este webhook notifica alterações nos status individuais de cada documento anexado à operação. Isso inclui a geração de contratos, a etapa de coleta de assinaturas, e as respostas da etapa de validação de documentos adicionais (como o vídeo de confirmação).

WEBHOOK TYPE
laas.payroll_card_reservation.attached_document.status_change

### Estrutura Geral do Webhook

| Campo | Tipo | Descrição |
|---|---|---|
| key | string | Chave do documento |
| status | string | Novo status do documento (`generated`, `pending_signature`, `approved`, `rejected`) |
| webhook_type | string | `laas.payroll_card_reservation.attached_document.status_change` |
| event_datetime | string | Data e hora do evento |
| data | object | Objeto contendo dados relevantes para a mudança de status |

#### Detalhes do objeto `data`

| Campo | Tipo | Descrição |
| --- | --- | --- |
| payroll_card_reservation_key | string | Chave da reserva do cartão |
| document_key | string | Chave única do documento |
| document_type | string | Tipo do documento |
| document_url | string | Link para visualização do documento |
| signature_url | string | Link para o fluxo de assinatura. Apenas quando o `status` é `pending_signature`. |
| rejection_reason | string | Motivo da rejeição. Apenas quando o `status` é `rejected`. |

### Cenários

#### A. Documento Gerado (generated)
Ocorre quando os contratos de operação são gerados com sucesso e estão prontos para visualização.

**Exemplo de Payload**

```json
{
    "key": "332017f4-a0d6-463a-8557-e925a9485251",
    "status": "generated",
    "webhook_type": "laas.payroll_card_reservation.attached_document.status_change",
    "event_datetime": "2025-01-15T14:30:00Z",
    "data": {
        "payroll_card_reservation_key": "910e8de5-16af-4bc5-8ee1-4a0652ca0cbf",
        "document_key": "332017f4-a0d6-463a-8557-e925a9485251",
        "document_type": "payroll_card_term",
        "document_url": "https://storage.googleapis.com/example_document.pdf",
        "signature_url": null
    }
}
```

#### B. Assinatura Pendente (pending_signature)
Ocorre quando os contratos estão gerados e prontos para assinatura pelo beneficiário. Retorna a `signature_url`.

**Exemplo de Payload**

```json
{
    "key": "332017f4-a0d6-463a-8557-e925a9485251",
    "status": "pending_signature",
    "webhook_type": "laas.payroll_card_reservation.attached_document.status_change",
    "event_datetime": "2025-01-15T14:30:00Z",
    "data": {
        "payroll_card_reservation_key": "910e8de5-16af-4bc5-8ee1-4a0652ca0cbf",
        "document_key": "332017f4-a0d6-463a-8557-e925a9485251",
        "document_type": "payroll_card_term",
        "document_url": "https://storage.googleapis.com/example_document.pdf",
        "signature_url": "https://test.sign.qitech.com.br/s/SVomf6J"
    }
}
```

#### C. Documento Adicional Aprovado (approved)
Ocorre como resposta da validação de um documento adicional (como o vídeo de confirmação), indicando que ele foi validado e aceito pelo nosso time ou sistema de checagem.

**Exemplo de Payload**

```json
{
    "key": "2fc216c6-5d1c-4713-b70b-6e1f75f8bb17",
    "status": "approved",
    "webhook_type": "laas.payroll_card_reservation.attached_document.status_change",
    "event_datetime": "2025-01-15T16:45:00Z",
    "data": {
        "payroll_card_reservation_key": "910e8de5-16af-4bc5-8ee1-4a0652ca0cbf",
        "document_key": "2fc216c6-5d1c-4713-b70b-6e1f75f8bb17",
        "document_type": "payroll_card_confirmation_video",
        "document_url": "https://storage.googleapis.com/video.mp4",
        "signature_url": null
    }
}
```

#### D. Documento Adicional Rejeitado (rejected)
Ocorre como resposta negativa da validação de um documento adicional. Neste cenário, o arquivo foi recusado e o payload incluirá a propriedade `rejection_reason` informando o porquê.

**Exemplo de Payload**

```json
{
    "key": "2fc216c6-5d1c-4713-b70b-6e1f75f8bb17",
    "status": "rejected",
    "webhook_type": "laas.payroll_card_reservation.attached_document.status_change",
    "event_datetime": "2025-01-15T16:50:00Z",
    "data": {
        "payroll_card_reservation_key": "910e8de5-16af-4bc5-8ee1-4a0652ca0cbf",
        "document_key": "2fc216c6-5d1c-4713-b70b-6e1f75f8bb17",
        "document_type": "payroll_card_confirmation_video",
        "document_url": "https://storage.googleapis.com/video_bad.mp4",
        "signature_url": null,
        "rejection_reason": "Áudio inaudível e rosto do cliente não visível"
    }
}
```

---

## 3. Webhook de Retorno da Dataprev (Collateral)

Este webhook notifica sobre o andamento da reserva de margem junto à Dataprev. 

É utilizado principalemte em cenários de **"Teimosinha"**, onde falhas temporárias (como margem presa ou valor de parcela excedido momentaneamente) não cancelam a reserva imediatamente. Nesses casos, a reserva permanece na fila de averbação até a última data de desembolso configurada.

WEBHOOK TYPE
social_security.collateral

### Estrutura Geral do Webhook

| Campo | Tipo | Descrição |
|---|---|---|
| key | string | Chave da **Reserva do Cartão** (`payroll_card_reservation_key`) |
| webhook_type | string | Sempre `social_security.collateral` |
| event_time | string | Data e hora do evento |
| data | object | Dados detalhados do retorno da Dataprev |
| data.collateral_constituted | boolean | Indica se a garantia foi constituída com sucesso (`true` ou `false`) |
| data.collateral_data.status | string | Status da reserva (ex: `pending_reservation`) |
| data.collateral_data.last_response | object | Contém a lista de erros retornada pela Dataprev (ex: `installment_limit_excceded`) |

**Exemplo de Payload - Falha Temporária**

```json
{
  "event_time": "2026-01-06 18:48:51",
  "key": "b670553f-28f4-4cf2-a3b5-e33c5ae86bb5",
  "webhook_type": "social_security.collateral",
  "data": {
    "collateral_data": {
      "last_response": {
        "errors": [
          {
            "enumerator": "installment_limit_excceded"
          }
        ]
      },
      "status": "pending_reservation",
      "last_response_event_datetime": "2026-01-06T18:48:51Z",
      "reservation_method": "social_security_payroll_card"
    },
    "collateral_type": "social_security_payroll_card",
    "collateral_constituted": false
  }
}
```

---

## 4. Webhook de Operação de Crédito (Desembolso e Status da CCB)

Este webhook notifica a mudança de status da **Operação de Crédito** (CCB) vinculada à reserva. Ele é disparado em dois momentos principais:
1.  **Sucesso (`opened`):** O valor foi transferido com sucesso para a conta do cliente.
2.  **Cancelamento (`canceled`):** Ocorreu um erro bancário no desembolso (ex: conta inválida, divergência de titularidade) e a operação foi cancelada.

WEBHOOK TYPE
laas.credit_operation.status_change

### Estrutura Geral do Webhook

| Campo | Tipo | Descrição |
|---|---|---|
| key | string | Chave da **Operação de Crédito** (`credit_operation_key`) |
| status | string | Novo status da operação: `opened` (Sucesso) ou `canceled` (Falha) |
| webhook_type | string | Sempre `laas.credit_operation.status_change` |
| event_datetime | string | Data e hora do evento |
| data | object | Objeto variável contendo detalhes do sucesso ou motivo do erro |

---

### Cenário A: Desembolso com Sucesso (`opened`)

Quando o status é `opened`, o objeto `data` contém os detalhes financeiros finais e o comprovante da transação.

| Campo (dentro de `data`) | Tipo | Descrição |
|---|---|---|
| installments | array | Lista de parcelas confirmadas com datas e valores finais |
| transaction_receipts | array | Lista de comprovantes de transferência bancária |
| requester_identifier_key | string | Identificador único do solicitante |

**Exemplo de Payload - Sucesso**

```json
{
    "key": "550e8400-e29b-41d4-a716-446655440000",
    "status": "opened",
    "webhook_type": "laas.credit_operation.status_change",
    "event_datetime": "2025-10-14 13:26:52",
    "data": {
      "installments": [
        {
          "due_date": "2025-12-28",
          "total_amount": 315.02,
          "installment_key": "123e4567-e89b-12d3-a456-426614174000",
          "pre_fixed_amount": 212.35873015,
          "installment_number": 1,
          "principal_amortization_amount": 102.66126985
        },
        {
          "due_date": "2026-01-28",
          "total_amount": 315.02,
          "installment_key": "123e4567-e89b-12d3-a456-426614174001",
          "pre_fixed_amount": 76.17371273,
          "installment_number": 2,
          "principal_amortization_amount": 238.84628727
        },
        {
          "due_date": "2026-02-28",
          "total_amount": 315.02,
          "installment_key": "123e4567-e89b-12d3-a456-426614174002",
          "pre_fixed_amount": 59.12264515,
          "installment_number": 3,
          "principal_amortization_amount": 255.89735485
        },
        {
          "due_date": "2026-03-28",
          "total_amount": 315.02,
          "installment_key": "123e4567-e89b-12d3-a456-426614174003",
          "pre_fixed_amount": 36.77641144,
          "installment_number": 4,
          "principal_amortization_amount": 278.24358856
        },
        {
          "due_date": "2026-04-28",
          "total_amount": 315.02,
          "installment_key": "123e4567-e89b-12d3-a456-426614174004",
          "pre_fixed_amount": 20.98850053,
          "installment_number": 5,
          "principal_amortization_amount": 294.03149947
        }
      ],
      "disbursement_type": "pix",
      "transaction_receipts": [
        {
          "fee": 0,
          "url": "https://bank-receipt-url.com/receipt.pdf",
          "amount": 1151.15,
          "origin": {
            "name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
            "type": "payment_account",
            "branch": "0001",
            "document": "32402502000135",
            "bank_code": "329",
            "account_key": "acc_origin_uuid",
            "branch_digit": null,
            "account_digit": "1",
            "account_branch": "0001",
            "account_number": "1234567",
            "financial_institution_name": "QI SCD S.A."
          },
          "timestamp": "2025-10-14T13:26:52",
          "description": "1234567 - Roberto Alves",
          "destination": {
            "name": "Roberto Alves",
            "type": "checking_account",
            "branch": "0001",
            "purpose": "Crédito PIX em Conta",
            "document": "12345678911",
            "bank_ispb": "12121212",
            "branch_digit": null,
            "account_digit": "2",
            "account_number": "123456",
            "financial_institution_name": "BANCO"
          },
          "end_to_end_id": "E32402502202510141326",
          "transaction_key": "tx_key_uuid",
          "origin_transaction_key": "origin_tx_key_uuid"
        }
      ],
      "requester_identifier_key": "req_id_key_uuid"
    }
}
```

---

### Cenário B: Falha no Desembolso (`canceled`)

Quando o status é `canceled`, o objeto `data` contém o motivo da recusa bancária (Pix ou TED devolvido).

| Campo (dentro de `data`) | Tipo | Descrição |
|---|---|---|
| cancel_reason | string | Motivo macro do cancelamento (ex: `pix_refusal`, `ted_refusal`) |
| cancel_reason_enumerator | string | Enumerador do motivo (ex: `pix_refusal`) |
| pix_refusal | object | Detalhes da recusa caso seja Pix (opcional) |
| ted_refusal | object | Detalhes da recusa caso seja TED (opcional) |
| [refusal].reason | string | Mensagem descritiva do erro bancário |
| [refusal].reason_enumerator | string | Código do erro bancário (ex: `invalid_account`) |

**Exemplo de Payload - Erro no Desembolso**

```json
{
    "key": "30e8917d-2b1f-4c79-baf5-cc18bb6e0277",
    "status": "canceled",
    "webhook_type": "laas.credit_operation.status_change",
    "event_datetime": "2026-01-06 20:57:04",
    "data": {
        "cancel_reason": "pix_refusal",
        "cancel_reason_enumerator": "pix_refusal",
        "pix_refusal": {
            "reason": "Número da conta de destino é inexistente ou inválido.",
            "reason_enumerator": "invalid_account",
            "cancel_reason_enumerator": "invalid_account"
        }
    }
}
```

:::info Reapresentação
O cancelamento da Operação de Crédito associada a uma reserva não necessariamente implica no cancelamento da reserva em sí. Em casos de erro de desembolso, a reserva permanece aberta e a operação de crédito permanece apta a reapresentação até a data de envio do cartão.

Para mais detalhes, ver tópico [5. Reapresentação de Pagamento do Saque](./manual_cartao_beneficio_emissao.md) em Criação da Reserva
:::

## 5. Webhook de Criação da Apólice de Seguro/Benefício

Este webhook notifica a emissão do seguro associado ao cartão, e retorna a URL da apólice do benefício. 
A emissão do seguro ocorre de forma assíncrona após a emissão do cartão, podendo demorar algumas horas para ser confirmada.

WEBHOOK TYPE
laas.payroll_card_reservation.benefit.emission

### Estrutura Geral do Webhook

| Campo | Tipo | Descrição |
|---|---|---|
| key | string | Chave da **Reserva do Cartão** (`payroll_card_reservation_key`) |
| status | string | `active` (Seguro ativo) |
| webhook_type | string | Sempre `laas.payroll_card_reservation.benefit.emission` |
| event_datetime | string | Data e hora do evento |
| data | object | Objeto variável contendo detalhes da apólice |
| data.benefit_key | string | Chave do Benefício/Seguro associado a uma reserva (`benefit.benefit_key`) |
| data.policy_url | string | URL do documento da apólice do seguro |

**Exemplo de Webhook**

```json
{
    "key": "550e8400-e29b-41d4-a716-446655440000",
    "status": "active",
    "webhook_type": "laas.payroll_card_reservation.benefit.emission",
    "event_datetime": "2025-10-14 13:26:52",
    "data": {
      "benefit_key": "29dbece4-9f57-40ae-b85c-8e04bf2c4cdf",
      "policy_url": "https://example.com/policy.pdf",
    }
}
```

---

# QI Cartões - Pré-pago

URL: /documentation/manual_pre_pago/casos_uso

## Casos de Uso

:::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 facilitar o entendimento, o cliente de BaaS que irá emitir e fornece o serviço de cartões para seus clientes será tratado como "Cliente". O cliente final portador do cartão emitido será tratado com "Portador".

## 1. Autorização e confirmação completa de uma transação

Este é o caminho mais comum para as transações de cartão, o Portador passa seu cartão para uma transação de valor financeiro X e a adquirente captura exatamente este valor do emissor do cartão. O processo inicia com o Portador utilizando seu cartão em um POS. A autorização será recebida pela QI e uma autorização será solicitada ao cliente conforme descrito na [Requisição de Autorização](/documentation/cards/autorizacao/). O cliente então, faz suas validações e opta por responder a requisção informando um parecer *autorization_request_response* = authorized.

O [Objeto Autorização](/documentation/cards/search/buscar_autorizacao) pode ser detalhado [nesta](/documentation/cards/search/buscar_autorizacao) referência.

A QI irá responder a autorização para a rede de cartões e o Portador irá ter seu saldo em conta descontado do valor da transação.

Neste momento, será enviado um webhook referenciando a autorização que acaba de ser aprovada.

Webhook de autorização autorizada

```json
{
	"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
	"data": {
		"merchant_currency_code": "BRL",
		"merchant_amount": 25,
		"billing_currency_code": "BRL",
		"billing_amount": 25,
		"processing_datetime": "2023-07-24T12:00:00.000Z",
		"authorization_event_type": "authorization",
		"authorization": {Objeto da Autorização}
	},
	"webhook_type": "prepaid_card.authorization_event",
	"event_datetime": "2023-07-24T12:00:00.000Z"
}
```

A adquirente, após ter uma transação autorizada, realiza a captura deste valor. Essa captura é processada pela QI e um webhook de atualização de estado da autorização é enviado passando essa transação para o estado *completed*. O valor capturado pode ser consultado na variável *captured_amount* do objeto `Authorization`.

Webhook de autorização confirmada

```json
{
	"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
	"data": {
		"merchant_currency_code": "BRL",
		"merchant_amount": 25,
		"billing_currency_code": "BRL",
		"billing_amount": 25,
		"processing_datetime": "2023-07-24T12:00:00.000Z",
		"authorization_event_type": "capture",
		"authorization": {Objeto da Autorização}
	},
	"webhook_type": "prepaid_card.authorization_event",
	"event_datetime": "2023-07-24T12:00:00.000Z"
}
```

## 2. Autorização e confirmação a menor de uma transação

Neste caso, a adquirente captura um valor menor do que o valor estipulado na autorização. O processo inicia com o Portador utilizando seu cartão em um POS. A autorização será recebida pela QI e uma autorização será solicitada ao cliente conforme descrito na [Requisição de Autorização](/documentation/cards/autorizacao/). O cliente então, faz suas validações e opta por responder a requisição informando um parecer *autorization_request_response* = authorized.

A QI irá responder a autorização para a rede de cartões e o Portador irá ter seu saldo em conta descontado do valor da transação.

Neste momento, será enviado um webhook referenciando a autorização que acaba de ser aprovada.

Webhook de autorização autorizada

```json
{
	"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
	"data": {
		"merchant_currency_code": "BRL",
		"merchant_amount": 25,
		"billing_currency_code": "BRL",
		"billing_amount": 25,
		"processing_datetime": "2023-07-24T12:00:00.000Z",
		"authorization_event_type": "authorization",
		"authorization": {Objeto da Autorização}
	},
	"webhook_type": "prepaid_card.authorization_event",
	"event_datetime": "2023-07-24T12:00:00.000Z"
}
```

A adquirente, após ter uma transação autorizada, realiza a captura deste valor. Essa captura é processada pela QI e um webhook de atualização de estado da autorização é enviado passando essa autorização para o estado *completed*. O valor capturado pode ser consultado na variável *captured_amount* do objeto `Authorization`. 

Webhook de autorização confirmada a menor

```json
{
	"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
	"data": {
		"merchant_currency_code": "BRL",
		"merchant_amount": 23,
		"billing_currency_code": "BRL",
		"billing_amount": 23,
		"processing_datetime": "2023-07-24T12:00:00.000Z",
		"authorization_event_type": "capture",
		"authorization": {Objeto da Autorização}
	},
	"webhook_type": "prepaid_card.authorization_event",
	"event_datetime": "2023-07-24T12:00:00.000Z"
}
```

Caso a autorização expire sem ter seu valor total capturado, o excedente será creditado em conta para o Portador no valor da diferença pendente.

## 3. Autorização e confirmação a maior de uma transação

Neste caso, a adquirente captura um valor maior do que o valor estipulado na autorização. O processo inicia com o Portador utilizando seu cartão em um POS. A autorização será recebida pela QI e uma autorização será solicitada ao cliente conforme descrito na [Requisição de Autorização](/documentation/cards/autorizacao/). O cliente então, faz suas validações e opta por responder a requisção informando um parecer *autorization_request_response* = authorized.

A QI irá responder a autorização para a rede de cartões e o Portador irá ter seu saldo em conta descontado do valor da transação.

Neste momento, será enviado um webhook referenciando a transação que acaba de ser autorizada.

Webhook de autorização autorizada

```json
{
	"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
	"data": {
		"merchant_currency_code": "BRL",
		"merchant_amount": 25,
		"billing_currency_code": "BRL",
		"billing_amount": 25,
		"processing_datetime": "2023-07-24T12:00:00.000Z",
		"authorization_event_type": "authorization",
		"authorization": {Objeto da Autorização}
	},
	"webhook_type": "prepaid_card.authorization_event",
	"event_datetime": "2023-07-24T12:00:00.000Z"
}
```

A adquirente, após ter uma transação autorizada, realiza a captura deste valor. Essa captura é processada pela QI e um webhook de atualização de estado da autorização é enviado passando essa autorização para o estado *completed*. O valor capturado pode ser consultado na variável *captured_amount* do objeto `Authorization`. Neste caso de uso, o valor capturado será maior do que o valor original autorizado.

Webhook de autorização confirmada a maior

```json
{
	"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
	"data": {
		"merchant_currency_code": "BRL",
		"merchant_amount": 27,
		"billing_currency_code": "BRL",
		"billing_amount": 27,
		"processing_datetime": "2023-07-24T12:00:00.000Z",
		"authorization_event_type": "capture",
		"authorization": {Objeto da Autorização}
	},
	"webhook_type": "prepaid_card.authorization_event",
	"event_datetime": "2023-07-24T12:00:00.000Z"
}
```

Esta situação produzirá um débito em conta para o Portador no valor da diferença a maior, neste exemplo seria debitado R$ 2,00 na QI Conta do Portador. Caso não seja possível realizar esse débito em nenhuma instância a QI irá tratar particularmente esses casos junto ao cliente (Cliente de BaaS utilizando serviço de cartões da QI).

### Cancelamento parcial

Ainda nesta situação de confirmação a maior, a adquirente pode decidir corrigir o eventual engano enviano o reembolso total `refund` ou parcial `partial_refund` que serão representados na forma de eventos de autorização. Abaixo um exemplo de reembolso parcial dos R$2,00 cobrados indevidamente.

Webhook de autorização com reembolso parcial

```json
{
	"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
	"data": {
		"merchant_currency_code": "BRL",
		"merchant_amount": 2,
		"billing_currency_code": "BRL",
		"billing_amount": 2,
		"processing_datetime": "2023-07-24T12:00:00.000Z",
		"authorization_event_type": "partial_refund",
		"authorization": {Objeto da Autorização}
	},
	"webhook_type": "prepaid_card.authorization_event",
	"event_datetime": "2023-07-24T12:00:00.000Z"
}
```

## 4. Autorização e cancelamento de uma transação

Neste caso, a transação é autorizada mas por algum motivo o vendedor decide cancelar essa transação no POS antes que ela seja capturada. O processo inicia com o Portador utilizando seu cartão em um POS. A autorização será recebida pela QI e uma autorização será solicitada ao cliente conforme descrito na [Requisição de Autorização](/documentation/cards/autorizacao/). O cliente então, faz suas validações e opta por responder a requisção informando um parecer *approve* = true.

A QI irá responder a autorização para a rede de cartões e o Portador irá ter seu saldo em conta descontado do valor da transação.

Neste momento, será enviado um webhook referenciando a transação que acaba de ser autorizada

Webhook de transação autorizada

```json
{
	"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
	"data": {
		"merchant_currency_code": "BRL",
		"merchant_amount": 25,
		"billing_currency_code": "BRL",
		"billing_amount": 25,
		"processing_datetime": "2023-07-24T12:00:00.000Z",
		"authorization_event_type": "authorization",
		"authorization": {Objeto da Autorização}
	},
	"webhook_type": "prepaid_card.authorization_event",
	"event_datetime": "2023-07-24T12:00:00.000Z"
}
```

A vendedor, após ter uma transação autorizada, decide cancelar essa transação por algum motivo, um erro de digitação por exemplo. Esse mensagem de cancelamento é processada pela QI e um webhook de atualização de estado da transação é enviado passando essa transação para o estado de estornada *reversed*. Nesta situação, o valor total da autorização foi cancelado.

Webhook de autorização estornada

```json
{
	"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
	"data": {
		"merchant_currency_code": "BRL",
		"merchant_amount": 27,
		"billing_currency_code": "BRL",
		"billing_amount": 27,
		"processing_datetime": "2023-07-24T12:00:00.000Z",
		"authorization_event_type": "authorization_reversal",
		"authorization": {Objeto da Autorização}
	},
	"webhook_type": "prepaid_card.authorization_event",
	"event_datetime": "2023-07-24T12:00:00.000Z"
}
```

Nesta situação um crédito no valor total cancelado é feito na Qi Conta do Portador.

### Autorização expirada

Pode ocorrer que uma autorização seja aprovada, mas não seja capturada dentro dos prazos estipulados pela bandeira do cartão. Nesta situação, será enviado um webhook de autorização expirada e o um crédito no valor não capturado será feito na Qi Conta do portador.

Webhook de autorização expirada

```json
{
	"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
	"data": {
		"merchant_currency_code": "BRL",
		"merchant_amount": 25,
		"billing_currency_code": "BRL",
		"billing_amount": 25,
		"processing_datetime": "2023-07-24T12:00:00.000Z",
		"authorization_event_type": "authorization_expiration",
		"authorization": {Objeto da Autorização}
	},
	"webhook_type": "prepaid_card.authorization_event",
	"event_datetime": "2023-07-24T12:00:00.000Z"
}
```

---

# QI FATURA

URL: /documentation/manual_qi_fatura/pix_parcelado

## Experiência de cartão com PIX Parcelado

---

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

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

## 1. Criar uma Carteira Digital

Para ser possível o lançamento de itens na fatura (entradas de pix lastreadas em ccb) é necessário, primeiramente, a criação de uma carteira digital por cliente.

### Request

ENDPOINT /card_invoice/wallet
MÉTODO POST

Testar no Playground

Request Body

```json
{
    "owner": {
        "person_type": "natural",
        "name": "\<NOME TITULAR DA CARTEIRA\>",
        "document_number": "\<CPF TITULAR DA CARTEIRA\>",
        "address": {
            "street": "\<RUA TITULAR DA CARTEIRA\>",
            "state": "\<ESTADO TITULAR DA CARTEIRA\>",
            "city": "\<CIDADE TITULAR DA CARTEIRA\>",
            "neighborhood": "\<BAIRRO TITULAR DA CARTEIRA\>",
            "number": "\<No. TITULAR DA CARTEIRA\>",
            "postal_code": "\<CEP TITULAR DA CARTEIRA\>",
            "complement": "\<COMPLEMENTO TITULAR DA CARTEIRA\>"
        },
        "phone": {
            "number": "\<CELULAR TITULAR DA CARTEIRA\>",
            "area_code": "\<DDD TITULAR DA CARTEIRA\>",
            "country_code": "55",
            },
        "email": "\<EMAIL TITULAR DA CARTEIRA\>",
        "document_identification_number":"\<NÚMERO DO DOCUMENTO DE IDENTIFICAÇÃO DO TITULAR DA CARTEIRA\>",
        "document_identification":"\<CHAVE DO DOCUMENTO DE IDENTICAÇÃO DO TITULAR\>",
        "document_identification_back":"\<CHAVE DO VERSO DO DOCUMENTO DE IDENTICAÇÃO DO TITULAR\>",
        "selfie":"\<CHAVE DA SELFIE DO TITULAR\>",
        "document_identification_type": "\<TIPO DO DOCUMENTO DE IDENTIFICAÇÃO DO TITULAR\>"

    },
    "invoice_configuration":{
        "closing_day": "\<DATA DE FECHAMENTO DA FATURA\>", 
        "due_day": "\<DATA DE VENCIMENTO DA FATURA\>", 
        "grace_months": "\<DIFERENÇA, EM MESES, ENTRE closing_day e due_day\>", 
        "issuing_and_due_day_difference": "\<DIAS ANTES DO VENCIMENTO QUE A FATURA DEVE SER EMITIDA\>", 
        "invoice_payment_type": "bankslip", 
        "delay_fine_percentage": "\<CONFIGURAÇÃO DE ATRASO - VALOR DA MORA\>", 
        "delay_monthly_interest_rate": "\<CONFIGURAÇÃO DE ATRASO -VALOR DOS JUROS POR DIA\>"
    },
    "invoice_authorization": {
        "signature": {
            "signer": {
                "name": "\<NOME ASSINANTE\>",
                "email": "\<EMAIL ASSINANTE\>",
                "phone": {
                    "number": "\<CELULAR ASSINANTE\>",
                    "area_code": "\<DDD ASSINANTE\>",
                    "country_code": "55",
                },
                "document_number": "CPF ASSINANTE"
                },
            "authentication_type": "opt_in",
            "authenticity": {
                "timestamp": "\<DATA E HORA DA ASSINATURA\>",
                "ip_address": "\<IP DO ASSINANTE\>",
                "fingerprint": {},
                "third_party_additional_data": {},
                "session_id": "\<ID DA SESSÃO DO ASSINANTE\>"
                },
            "signed_object": {
                "document_key": "\<CHAVE DO DOCUMENTO NA QI\>"
                }
            }
        },
    "limit": "\<VALOR DO LIMITE DA WALLET\>",
    "default_monthly_interest_rate": "\<TAXA DE JUROS MENSAL, DEFAULT DA CARTEIRA, CONSIDERADA PARA CADA ENTRADA (PIX)\>"
  }
```

### Request body details
#### Payload wallet

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---|---|
| `owner` | object  | Objeto Dono da carteira |**[Objeto owner](#objeto-owner)**  |
| `invoice_configuration` | object  | Objeto Configurações da Fatura para cada Carteira |**[Objeto invoicer_configuration](#objeto-invoicer_configuration)**  |
| `invoice_authorization` | object  | Objeto Autorização |**[Objeto invoice_authorization](#objeto-invoice_authorization)**  |
| `limit` | number  | Limite da carteira | |
| `default_monthly_interest_rate` | number  | Taxa de juros default da carteira. | |

#### Objeto owner

| Campo | Tipo | Descrição | Caracteres |
|---| ---| ---| ---| 
| `person_type` | string | Identificador de que o objeto enviado é uma pessoa física ou jurídica.|  |
| `name` | string |  Razão social em caso de operações PJ ou Nome da pessoa em caso de operações PF. | 100 |
| `document_number` | string | CPF da pessoa (apenas números). Limitado a 11 caracteres. |  |
| `address` | string | Endereço do cliente. | **[Objeto adress](#objeto-address)** |  |
| `phone` | string | Objeto com dados do telefone | **[Objeto phone](#objeto-phone)**|
| `email` | string |  Email do cliente. |  |

#### Objeto address 

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

| Campo | Descrição | Exemplo |  Máx. Caracteres | 
| --- | --- | --- | --- | 
| `closing_day` | number |  Dia de fechamento da fatura (data de corte para registro de entradas me uma fatura).| |
| `due_day` | number |  Dia de vencimento da fatura. Opções: 1,5,10 | |
| `grace_months` | number |  Diferença de meses entre a data de fechamento e vencimento.| |
| `delay_fine_percentage` | number |  Valor da mora, em caso de atraso no pagamento da fatura.| |
| `delay_monthly_interest_rate` | number |  Valor do juros, por mês, em caso de atraso no pagamento da fatura.| |
| `issuing_and_due_day_difference` | number | Número de dia entre a emissão da fatura e vencimento, para fins de cálculo da data de emissão da fatura| |
| `invoice_payment_type` | string |  Meio de pagamento da fatura. Opções: 'bankslip'| |

:::info CONFIGURAÇÕES DA INVOICE 
Na configuração da invoice (invoice_configuration), os dados fixos, como "delay_fine_percentage", "grace_months", "delay_monthly_interest_rate",  "invoice_payment_type", "issuing_and_due_day_difference", podem estar diretamente configurado no setup inicial do parceiro na API, simplificando o payload de criação da wallet. As informações configuradas no setup inicial do parceiro na API serão fixas para todos os clientes. 
:::

:::caution 
O número de dias entre a data de vencimento da fatura “invoice_configuration.due_day“ e a data fechamento “invoice_configuration.closing_day“, precisa ser maior ou igual a 8 dias e menor ou igual a 10 dias.
:::

### Response

ENDPOINT /card_invoice/wallet
MÉTODO POST
HTTP STATUS 201

Response Body

```json
{
    "wallet_key": "0f4581d6-f4a4-4430-b94e-5db700e4baed",
    "status": "active"
}
```

### Response body details

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---|---|
| `wallet_key` | string  |  Identificador único da carteira (uuid) | |
| `status` | string  |  Status da carteira | |

## 1.1. Consultar carteiras existentes: 

#### QUERY PARAMETERS

| Enumerador                   | Descrição                                                   |
|------------------------------|-------------------------------------------------------------|
| **owner_document_number**    |  CPF do titular da carteira                                 |
| **page**                     |  Número da página da consulta                               |
| **page_size**                |  Tamanho da página requisitada na consulta                  |

### Request

ENDPOINT /card_invoice/wallets
MÉTODO GET

Testar no Playground

### Response

ENDPOINT /card_invoice/wallets
MÉTODO GET
HTTP STATUS 200

Response Body

```json
{
    "page": 1,
    "last_page": true,
    "data": [
        {
            "wallet_key": "0f4581d6-f4a4-4430-b94e-5db700e4baed",
            "owner": {
                "person_type": "natural",
                "name": "Nome Sobrenome",
                "document_number": "12345678911",
                "address": {
                    "street": "RUA DEZENOVE",
                    "state": "SP",
                    "city": "JARDINÓPOLIS",
                    "neighborhood": "JARDINS DO IMPÉRIO",
                    "number": "19",
                    "postal_code": "13348719",
                    "complement": ""
                },
                "phone": {
                            "number": "912345678",
                            "area_code": "21",
                            "country_code": "55"
                        },
                "email": "teste@teste.com.br"
            },
            "collaterals": [],
            "cards": [
                {"card_key":"067cba94-4d57-4a75-9766-7e5b95c87367"}
            ],
            "invoice_authorization": {
                "signature": {
                    "signer": {
                        "name": "Nome Sobrenome",
                        "document_number": "12345678911",
                        "email": "teste@teste.com.br",
                        "phone": {
                            "number": "912345678",
                            "area_code": "21",
                            "country_code": "55"
                        }
                    },
                    "authentication_type": "opt_in",
                    "authenticity": {
                        "timestamp": "2022-11-18T11:17:46",
                        "ip_address": "104.101.21.0",
                        "fingerprint": {
                            "browser": "Mozila"
                        },
                        "third_party_additional_data": {},
                        "session_id": "8df91773-c537-4662-b08b-025f03bf79dc"
                    },
                    "signed_object": {
                        "document_key": "27A0BA3D-A89D-4218-AB06-BC39B94CE23C"
                    }
                }
            },
            "interest_base": "calendar_days_365",
            "default_monthly_interest_rate": 0.035,
            "invoice_configuration": {
                "due_day": 10,
                "closing_day": 1,
                "grace_months": 1,
                "invoice_payment_type": "bankslip",
                "delay_fine_percentage": 0,
                "delay_monthly_interest_rate": 0,
                "issuing_and_due_day_difference": 9
            },
            "status": "active",
            "limit": 800,
            "current_limit": 800
}
    ]
}
```

## 1.2. Consultar carteira específica:
### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]
MÉTODO GET

Testar no Playground

### Response

ENDPOINT /card_invoice/wallet/[WALLET-KEY]
MÉTODO GET
HTTP STATUS 200

Response Body

```json
        {
            "wallet_key": "0f4581d6-f4a4-4430-b94e-5db700e4baed",
            "owner": {
                "person_type": "natural",
                "name": "Nome Sobrenome",
                "document_number": "12345678911",
                "address": {
                    "street": "RUA DEZENOVE",
                    "state": "SP",
                    "city": "JARDINÓPOLIS",
                    "neighborhood": "JARDINS DO IMPÉRIO",
                    "number": "19",
                    "postal_code": "13348719",
                    "complement": ""
                },
                "phone": {
                            "number": "912345678",
                            "area_code": "21",
                            "country_code": "55"
                        },
                "email": "teste@teste.com.br"
            },
            "collaterals": [],
            "cards": [
                {"card_key":"067cba94-4d57-4a75-9766-7e5b95c87367"}
            ],
            "invoice_authorization": {
                "signature": {
                    "signer": {
                        "name": "Nome Sobrenome",
                        "document_number": "12345678911",
                        "email": "teste@teste.com.br",
                        "phone": {
                            "number": "912345678",
                            "area_code": "21",
                            "country_code": "55"
                        }
                    },
                    "authentication_type": "opt_in",
                    "authenticity": {
                        "timestamp": "2022-11-18T11:17:46",
                        "ip_address": "104.101.21.0",
                        "fingerprint": {
                            "browser": "Mozila"
                        },
                        "third_party_additional_data": {},
                        "session_id": "8df91773-c537-4662-b08b-025f03bf79dc"
                    },
                    "signed_object": {
                        "document_key": "27A0BA3D-A89D-4218-AB06-BC39B94CE23C"
                    }
                }
            },
            "interest_base": "calendar_days_365",
            "default_monthly_interest_rate": 0.035,
            "invoice_configuration": {
                "due_day": 10,
                "closing_day": 1,
                "grace_months": 1,
                "invoice_payment_type": "bankslip",
                "delay_fine_percentage": 0,
                "delay_monthly_interest_rate": 0,
                "issuing_and_due_day_difference": 9
            },
            "status": "active",
            "limit": 800,
            "current_limit": 800
}
```

## 1.3. Alterar Limite de uma carteira:

### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]
MÉTODO PATCH

Testar no Playground

Request Body

```json
{
    "limit": 123
}
```

### Response

ENDPOINT /card_invoice/wallet/[WALLET-KEY]
MÉTODO PATCH
HTTP STATUS 200

Response Body

```json
        {
            "wallet_key": "0f4581d6-f4a4-4430-b94e-5db700e4baed",
            "owner": {
                "person_type": "natural",
                "name": "Nome Sobrenome",
                "document_number": "12345678911",
                "address": {
                    "street": "RUA DEZENOVE",
                    "state": "SP",
                    "city": "JARDINÓPOLIS",
                    "neighborhood": "JARDINS DO IMPÉRIO",
                    "number": "19",
                    "postal_code": "13348719",
                    "complement": ""
                },
                "phone": {
                            "number": "912345678",
                            "area_code": "21",
                            "country_code": "55"
                        },
                "email": "teste@teste.com.br"
            },
            "collaterals": [],
            "invoice_authorization": {
                "signature": {
                    "signer": {
                        "name": "Nome Sobrenome",
                        "document_number": "12345678911",
                        "email": "teste@teste.com.br",
                        "phone": {
                            "number": "912345678",
                            "area_code": "21",
                            "country_code": "55"
                        }
                    },
                    "authentication_type": "opt_in",
                    "authenticity": {
                        "timestamp": "2022-11-18T11:17:46",
                        "ip_address": "104.101.21.0",
                        "fingerprint": {
                            "browser": "Mozila"
                        },
                        "third_party_additional_data": {},
                        "session_id": "8df91773-c537-4662-b08b-025f03bf79dc"
                    },
                    "signed_object": {
                        "document_key": "27A0BA3D-A89D-4218-AB06-BC39B94CE23C"
                    }
                }
            },
            "interest_base": "calendar_days_365",
            "default_monthly_interest_rate": 0.035,
            "invoice_configuration": {
                "due_day": 10,
                "closing_day": 1,
                "grace_months": 1,
                "invoice_payment_type": "bankslip",
                "delay_fine_percentage": 0,
                "delay_monthly_interest_rate": 0,
                "issuing_and_due_day_difference": 9
            },
            "status": "active",
            "limit": 123,
            "current_limit": 1000
}
```

## 2. Adicionar Cartões a uma carteira digital existente:
Após a criação da carteira digital para o cliente, é necessário criar um cartão, vinculado à esta carteira

### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/card
MÉTODO POST

Testar no Playground

Request Body

```json
{
    "settlement_method": "credit_operation"
}
```

### Request body details
#### Payload card

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---|---|
| `settlement_method` | string  |  Tipo de lastro. Ou seja, como as transações serão lastreadas. Opções: "credit_operation" | |

### Response

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/card
MÉTODO POST
HTTP STATUS 201

Response Body

```json
{
    "card_key": "dabd10b6-80a8-4c9c-8a8e-e25a56668525"
}
```

### Response body details

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---|---|
| `card_key` | string  |  Identificador único do cartão (uuid)  | |

## 3. Simular operação:

Simular as transações (PIX).
### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry/simulation
MÉTODO POST

Testar no Playground

Request Body

```json
{
  "amount": 200,
  "number_of_installments": 4,
  "monthly_interest_rate": 0.035
}
```

:::note ATENÇÃO
Não é necessário informar o campo "monthly_interest_rate", quando não informado, a transação assumirá o default da carteira.
:::

### Response

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry/simulation
MÉTODO POST
HTTP STATUS 201

Response Body

```json
{
    "amount": 200,
    "final_amount": 221.16,
    "number_of_installments": 4,
    "monthly_interest_rate": 0.035,
    "cet": 0.03,
    "annual_cet": 0.5040,
    "total_iof": 100.44,
    "items": [
        {
            "amount": 55.29,
            "used_limit":50,
            "installment_number": 1,
            "invoice": {
                "due_date": "2023-09-10"
            }
        },
        {
            "amount": 55.29,
            "used_limit":50,
            "installment_number": 2,
            "invoice": {
                "due_date": "2023-10-10"
            }
        },
        {
            "amount": 55.29,
            "used_limit":50,
            "installment_number": 3,
            "invoice": {
                "due_date": "2023-11-10"
            }
        },
        {
            "amount": 55.29,
            "used_limit":50,
            "installment_number": 4,
            "invoice": {
                "due_date": "2023-12-10"
            }
        }
    ]
}
```

## 4. Incluir transações em um cartão:

Incluir as transações (PIX). É nesta etapa que é gerada a ccb, em que é verificado se há limite disponível para realizar a transação. A liquidação da transação é processada de forma síncrona.

### Request

:::note ATENÇÃO
Não é necessário informar o campo "monthly_interest_rate", quando não informado, a transação assumirá o default da carteira.
:::

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry
MÉTODO POST

Testar no Playground

Request Body

```json
{
  "disbursement": {
    "method": "pix",
    "data": {
      "pix_key": "\<CHAVE PIX\>",
      "end_to_end_id": "\<CHAVE END TO END DO PIX\>"
    }
  },
  "description": "Compra Padaria do João",
  "amount": 200,
  "request_control_key": "275619e6-23d1-485e-81ca-5552aa235761",
  "number_of_installments": 4,
  "monthly_interest_rate": 0.027,
  "authorization": {
    "document_number": "01975273702",
    "signature": {
      "signed_object": {
        "document_key": "6254c56e-c980-4b38-ad99-ac5ec7535d68"
      },
      "authenticity": {
        "ip_address": "192.168.0.0",
        "third_party_additional_data": {
          "hash": "23A2581A8D524035FEB2950D28727CF5 | 192.168.0.0 | 23/02/2023 17:38:45"
        },
        "timestamp": "2023-02-23T17:38:45.610458300"
      },
      "authentication_type": "opt_in",
      "signer": {
        "document_number": "01975273702",
        "phone": {
          "number": "986243444",
          "country_code": "55",
          "area_code": "21"
        },
        "name": "Master Tester",
        "email": "mail@mail.com"
      }
    }
  }
}
```

Desembolsar com Chave Pix
```json
{
    "disbursement": {
    "method": "pix",
    "data": {
      "pix_key": "\<CHAVE PIX\>",
      "end_to_end_id": "\<CHAVE END TO END DO PIX\>"
    }
  }
}
```

Desembolsar com Pix QR Code
```json
{
    "disbursement": {
    "method": "pix_qrcode",
    "data": {
      "qr_code_url": "\<URL DO PIX\>",
      "end_to_end_id": "\<CHAVE END TO END DO PIX QR CODE\>"
    }
  }
}
```

Desembolsar com Pix Manual
```json
{
    "disbursement": {
    "method": "pix_manual",
    "data": {
        "ispb": "\<BASE DO CNPJ DO BANCO\>",
        "branch_number": "\<AGÊNCIA DA CONTA DE DESEMBOLSO\>",
        "account_number": "\<NÚMERO DA CONTA SEM O DÍGITO\>",
        "account_digit": "\<DIGITO DA CONTA DE DESEMBOLSO\>",
        "document_number": "\<CPF/ CNPJ DO TITULAR DA CONTA\>",
        "name": "\<NOME DO TITULAR DA CONTA\>"
    }
  }
}
```

### Response

Em caso de sucesso no desembolso da transação:

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry
MÉTODO POST
HTTP STATUS 201

Response Body

```json
{
    "card_entry_key": "ad8e073a-2159-479b-b141-cd5d8ceb8567",
    "status": "active",
    "signed_url":"https://storage.googleapis.com/live-doc-api/documents/XXXXXXXXXXXXXXX.pdf"
}
```

:::caution ATENÇÃO
Por instabilidade do Bacen ou do banco de destino da transação, pode ocorrer atraso na transação do contrato, dessa forma o mesmo assumirá o status "pending_activation", e será atualizado quando a transação for realizada com sucesso ou o contrato for cancelado. Dessa forma, o fluxo migrará de síncrono para assíncrono devendo esperar o [webhook](#92-alteração-de-status-da-transação) de sucesso ou falha da transação .
:::

## 4.1 Consultar uma transação (card entry) específica:
### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry/[CARD-ENTRY-KEY]
MÉTODO GET

Testar no Playground

### Response

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry/[CARD-ENTRY-KEY]
MÉTODO GET
HTTP STATUS 200

Response Transação Pix Manual

```json
{
    "transaction_key": "75b800f3-12ba-41b3-a7d5-cbb3ae2199f2",
    "end_to_end_id": "E324025022023082120064RNfdmEDTxV", 
    "transacted_at": "2023-08-21T20:07:46",
    "amount": 2242.8,
    "number_of_installments": 2,
    "monthly_interest_rate": 0.027,
    "final_amount":2250,
    "cet": 0.03,
    "annual_cet": 0.5040,
    "total_iof": 100.44,
    "description":"Compra Padaria do João",
    "disbursement": {
        "method": "pix_manual",
        "data": {
            "ispb": 32402502,
            "branch_number": 1,
            "account_number": 15570,
            "account_digit": 1,
            "document_number": "12345678911",
            "name": "XXXXX XXXX XXXX"
        }
    },
    "card_entry_datetime": "2023-06-07T10:29:49Z",
    "signed_url":"https://storage.googleapis.com/live-doc-api/documents/XXXXXXXXXXXXXXX.pdf",
    "items": [
        {
            "item_key":"37ebad25-7eef-4a46-b497-ce46c2c04f68",
            "amount": 1125,
            "used_limit":1121.4,
            "status":"active",
            "installment_number": 1,
            "invoice": {
                "invoice_key": "b32e7eae-eaab-4402-9126-9fcf42741c24",
                "due_date": "2023-07-10",
                "status": "opened"
                },
        },
        {
            "item_key":"60e4801f-75ce-411e-aaf0-99b951c05308",
            "amount": 1125,
            "used_limit":1121.4,
            "installment_number": 2,
            "status":"active",
            "invoice": {
                "invoice_key": "2af90944-1377-447c-aa70-0efd24c17d6f",
                "due_date": "2023-08-10",
                "status": "opened"
                },
        }
	], 
    "status": "active"
}
```

Response Transação Pix Key

```json
{
    "transaction_key": "75b800f3-12ba-41b3-a7d5-cbb3ae2199f2",
    "end_to_end_id": "E324025022023082120064RNfdmEDTxV", 
    "transacted_at": "2023-08-21T20:07:46",
    "amount": 2242.8,
    "final_amount":2250,
    "number_of_installments": 2,
    "monthly_interest_rate": 0.027,
    "cet": 0.03,
    "annual_cet": 0.5040,
    "total_iof": 100.44,
    "description":"Compra Padaria do João",
    "disbursement": {
 		"data": {
 			"end_to_end_id": "E3240250220210928212926341670923",
 			"pix_key": "+5516983068432"
 		},
 		"method": "pix"
    },
    "card_entry_datetime": "2023-06-07T10:29:49Z",
    "signed_url":"https://storage.googleapis.com/live-doc-api/documents/XXXXXXXXXXXXXXX.pdf",
    "items": [
        {
            "item_key":"37ebad25-7eef-4a46-b497-ce46c2c04f68",
            "amount": 1125,
            "used_limit":1121.4,
            "installment_number": 1,
            "status":"active",
            "invoice": {
                "invoice_key": "b32e7eae-eaab-4402-9126-9fcf42741c24",
                "due_date": "2023-07-10",
                "status": "opened"
                },
        },
        {
            "item_key":"60e4801f-75ce-411e-aaf0-99b951c05308",
            "amount": 1125,
            "used_limit":1121.4,
            "status":"active",
            "installment_number": 2,
            "invoice": {
                "invoice_key": "2af90944-1377-447c-aa70-0efd24c17d6f",
                "due_date": "2023-08-10",
                "status": "opened"
                },
        }
	], 
    "status": "active"
}
```

Response Transação Pix QR Code

```json
{
    "transaction_key": "75b800f3-12ba-41b3-a7d5-cbb3ae2199f2",
    "end_to_end_id": "E324025022023082120064RNfdmEDTxV", 
    "transacted_at": "2023-08-21T20:07:46",
    "amount": 2242.8,
    "final_amount":2250,
    "number_of_installments": 2,
    "monthly_interest_rate": 0.027,
    "cet": 0.03,
    "annual_cet": 0.5040,
    "total_iof": 100.44,
    "description":"Compra Padaria do João",
    "disbursement": {
 		"method": "pix_qrcode",
        "data": {
            "qr_code_url": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/a1908d67-bcc8-40cd-a63d-6b6fb510b35c5204000053039865802BR5925QI SOCIEDADE DE CREDITO D6009Sao Paulo61080145200062070503***63042184",
            "end_to_end_id": "E3240250220220822211350711639780"
        }
    },
    "card_entry_datetime": "2023-06-07T10:29:49Z",
    "signed_url":"https://storage.googleapis.com/live-doc-api/documents/XXXXXXXXXXXXXXX.pdf",
    "items": [
        {
            "item_key":"37ebad25-7eef-4a46-b497-ce46c2c04f68",
            "amount": 1125,
            "used_limit":1121.4,
            "installment_number": 1,
            "status":"active",
            "invoice": {
                "invoice_key": "b32e7eae-eaab-4402-9126-9fcf42741c24",
                "due_date": "2023-07-10",
                "status": "opened"
                },
        },
        {
            "item_key":"60e4801f-75ce-411e-aaf0-99b951c05308",
            "amount": 1125,
            "used_limit":1121.4,
            "installment_number": 2,
            "status":"active",
            "invoice": {
                "invoice_key": "2af90944-1377-447c-aa70-0efd24c17d6f",
                "due_date": "2023-08-10",
                "status": "opened"
                },
        }
	], 
    "status": "active"
}
```

#### Enumeradores Card Entry status

| Enumerador                   | Descrição                                            |
|------------------------------|------------------------------------------------------|
| **active**                   | Contrato ativo e desembolsado                        |
| **pending_activation**       | Contrato aguardando desembolso                       |
| **canceled**                 | Contrato cancelado                                   |
| **paid**                     | Contrato liquidado                                   |

## 4.2 Gerar comprovante da transação:
### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry/[CARD-ENTRY-KEY]/receipt
MÉTODO GET

Testar no Playground

### Response

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry/[CARD-ENTRY-KEY]/receipt
MÉTODO GET
HTTP STATUS 200

Response Body

```json
    {
        "base64_receipt": ""
    }
```

## 5. Listar faturas de uma carteira digital:

### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/invoices
MÉTODO GET
<div className='badge
badge--primary'>PARAMETERS page, page_size

Testar no Playground

### Response

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/invoices
MÉTODO GET
HTTP STATUS 200
Limite de itens retornados por página: 100
Response Body

```json
{
    "wallet_key": "9798d733-7f68-4929-8877-a00bfda9735e",
    "invoice_closing_day": 2,
    "invoice_due_day": 10,
    "page": "1",
	"last_page": "False",
    "invoices": [
        {
            "invoice_key": "b32e7eae-eaab-4402-9126-9fcf42741c24",
            "due_date": "2023-04-10",
            "closing_date": "2023-04-02",
            "status": "opened",
            "number_of_items": 2
        },
        {
            "invoice_key": "2af90944-1377-447c-aa70-0efd24c17d6f",
            "due_date": "2023-05-10",
            "closing_date": "2023-05-02",
            "status": "opened",
            "number_of_items": 12
        },
        {
            "invoice_key": "26e18c39-8f67-4399-9a42-8d18bc175da2",
            "due_date": "2023-04-10",
            "closing_date": "2023-04-02",
            "status": "opened",
            "number_of_items": 1
        },
        {
            "invoice_key": "6991f8e6-7b1d-4496-a08f-8a9eef263f07",
            "due_date": "2023-06-10",
            "closing_date": "2023-06-02",
            "status": "opened",
            "number_of_items": 12
        }
    ]
    
}
```

## 6. Listar transações de uma fatura:
### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]
MÉTODO GET

Testar no Playground

### Response

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]
MÉTODO GET
HTTP STATUS 200

Response Body

```json
{
    "due_date": "2023-06-10",
    "closing_date": "2023-06-02",
    "status": "closed",
    "amount": 12345.67,
    "paid_amount": 0,
    "delay_interest_total_amount": 0,
    "delay_fine_total_amount": 0,
    "number_of_items": 1,
    "invoice_payments": [
        {
            "invoice_payment_key": "63a7c7a2-9e13-48cf-aea2-3b494125d14b",
            "invoice_payment_type": "bankslip",
            "charge_type": "ordinary",
            "data": {
                "digitable_line": "32990001039000000000104620768103992260000004183",
                "qr_code_url": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/881979cb-1c15-4dea-a05e-316caae22f5e5204000053039865802BR5925LOTEAMENTO RESIDENCIAL PO6014PORTO NACIONAL61087750000062070503***630414B8"
            },
            "expiration": "2023-07-10",
            "status": "opened",
            "total_amount": 0,
            "paid_amount": 0,
            "chargeback_amount": 50
        }
    ],
    "items": [
        {
            "item_key": "37ebad25-7eef-4a46-b497-ce46c2c04f68",
            "amount": 12345.67,
            "used_limit": 12300,
            "status": "active",
            "card_entry": {
                "card_entry_key": "ad8e073a-2159-479b-b141-cd5d8ceb8567",
                "card_entry_datetime": "2022-11-13T10:29:49",
                "description": "Compra Padaria do João",
                "final_amount": 12345.67,
                "number_of_installments": 2,
                "card": {
                    "card_key": "d41bd53e-eedc-4d62-97dd-26bbaefadb20"
                }
            },
            "installment_number": 1
        }
    ]
}
```

#### Enumeradores Item status

| Enumerador                   | Descrição                                                                                   |
|------------------------------|---------------------------------------------------------------------------------------------|
| **pending_activation**       | Item aguardando ativação, o valor do item compôe o valor da fatura                          |
| **active**                   | Item ativo, o valor do item compôe o valor da fatura                                        |
| **canceled**                 | Item cancelado, o valor do item é removido do valor da fatura                               |
| **paid**                     | Item pago na fatura do mês, o valor do item compôe o valor da fatura                        |
| **paid_early**               | Item pago adiantado, o valor do item não compôe mais o valor da fatura                      |
| **reversed**                 | Item cancelado após fechamento da fatura, o valor do item gerará um estorno                   |

## 7. Geração de boletos:

A geração do boleto ordinário acontecerá automaticamente no dia de fechamento da fatura e poderá ser resgatado através do get de pagamento da fatura. O query parameter "shorten_url" é uma flag para solicitar a URL do boleto encurtada.

:::caution ATENÇÃO
O boleto pode ser pago em até 30 dias após o vencimento da fatura.
:::

:::danger ATENÇÃO
O encurtamento de URL é limitado a 60 requisições por minuto.
:::

### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]/invoice_payment/[INVOICE-PAYMENT-KEY]
MÉTODO GET
<div className='badge
badge--primary'>PARAMETER shorten_url

Testar no Playground

### Response

#### Parameter shorten_url=False

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]/invoice_payment/[INVOICE-PAYMENT-KEY]?shorten_url=False
MÉTODO GET
HTTP STATUS 200

Response Body

```json
    {
        "invoice_payment_key": "63a7c7a2-9e13-48cf-aea2-3b494125d14b",
        "invoice_payment_type": "bankslip",
        "charge_type": "ordinary",
        "data": {
            "bank_slip_key": "dc4a27db-2fe1-474d-aa02-88d6fffb8d0d",
            "digitable_line": 32990001039000000000104620768103992260000004183,
            "qr_code_url": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/881979cb-1c15-4dea-a05e-316caae22f5e5204000053039865802BR5925LOTEAMENTO RESIDENCIAL PO6014PORTO NACIONAL61087750000062070503***630414B8",
            "bank_slip_url": "\<URL BOLETO EM PDF\>"
        },
        "expiration": "2023-07-10",
        "status": "issued",
        "total_amount": 0,
        "paid_amount": 0,
        "chargeback_amount": 50,
    }
```

#### Parameter shorten_url=True

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]/invoice_payment/[INVOICE-PAYMENT-KEY]?shorten_url=True
MÉTODO GET
HTTP STATUS 200

Response Body

```json
    {
        "invoice_payment_key": "63a7c7a2-9e13-48cf-aea2-3b494125d14b",
        "invoice_payment_type": "bankslip",
        "charge_type": "ordinary",
        "data": {
            "bank_slip_key": "dc4a27db-2fe1-474d-aa02-88d6fffb8d0d",
            "digitable_line": 32990001039000000000104620768103992260000004183,
            "qr_code_url": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/881979cb-1c15-4dea-a05e-316caae22f5e5204000053039865802BR5925LOTEAMENTO RESIDENCIAL PO6014PORTO NACIONAL61087750000062070503***630414B8",
            "bank_slip_url": "\<URL BOLETO EM PDF\>",
            "short_bank_slip_url": "\<URL BOLETO EM PDF ENCURTADA\>"
        },
        "expiration": "2023-07-10",
        "status": "issued",
        "total_amount": 0,
        "paid_amount": 0
    }
```

## 7.1 Geração de boleto extraordinário de adiantamento:

### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]/invoice_payment
MÉTODO POST

Testar no Playground

Request Body

```json
{
    "invoice_payment_type": "bankslip",
    "charge_type": "early",
    "expiration": "2023-08-15",
    "invoice_items": [
	    "key_1",
	    "key_2"
    ]
}
```

:::note ATENÇÃO
Condição: "expiration" deve ser dois dias úteis menor que a data de fechamento da fatura para garantir que o pagamento não irá interferir
em tal rotina.
:::

### Response

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]/invoice_payment
MÉTODO POST
HTTP STATUS 200

Response Body

```json
     {
        "invoice_payment_key": "63a7c7a2-9e13-48cf-aea2-3b494125d14b",
        "invoice_payment_type": "bankslip",
        "charge_type": "early",
        "data": {
            "digitable_line": 32990001039000000000104620768103992260000004183,
            "qr_code_url": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/881979cb-1c15-4dea-a05e-316caae22f5e5204000053039865802BR5925LOTEAMENTO RESIDENCIAL PO6014PORTO NACIONAL61087750000062070503***630414B8",
        },
        "expiration": "2023-08-15",
        "status": "issued",
        "total_amount": 200,
        "paid_amount": 0
 }
```

## 7.2 Simulação de boleto extraordinário de atraso:

:::caution ATENÇÃO
A simulação só pode ser solicitada após o termino do prazo de pagamento do boleto ordinário.
:::

### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]/invoice_payment/simulation
MÉTODO POST

Testar no Playground

Request Body

```json
    {
        "invoice_payment_type": "bankslip",
        "charge_type": "delay",
        "expiration": "2023-08-15"
    }
```

### Request com desconto

Request Body

```json
    {
        "invoice_payment_type": "bankslip",
        "charge_type": "delay",
        "expiration": "2023-08-15",
        "discount_amount": 50
    }
```

### Response

Response Body

```json
    {
        "invoice_payment_type": "bankslip",
        "charge_type": "delay",
        "total_amount": 150,
        "discount_amount": 50
    }
```

## 7.3 Geração de boleto extraordinário de atraso:

:::caution ATENÇÃO
O boleto de atraso só pode ser gerado após o termino do prazo de pagamento do boleto ordinário.
:::

### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]/invoice_payment
MÉTODO POST

Testar no Playground

Request Body

```json
    {
        "invoice_payment_type": "bankslip",
        "charge_type": "delay",
        "expiration": "2023-08-15"
    }
```

### Request com desconto

Request Body

```json
    {
        "invoice_payment_type": "bankslip",
        "charge_type": "delay",
        "expiration": "2023-08-15",
        "discount_amount": 50
    }
```

### Response

Response Body

```json
    {
        "invoice_payment_key": "63a7c7a2-9e13-48cf-aea2-3b494125d14b",
        "invoice_payment_type": "bankslip",
        "charge_type": "delay",
        "data": {
            "digitable_line": 32990001039000000000104620768103992260000004183,
            "qr_code_url": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/881979cb-1c15-4dea-a05e-316caae22f5e5204000053039865802BR5925LOTEAMENTO RESIDENCIAL PO6014PORTO NACIONAL61087750000062070503***630414B8",
        },
        "expiration": "2023-07-10",
        "status": "issued",
        "total_amount": 0,
        "paid_amount": 0,
        "discount_amount": 50
    }
```

## 7.4 Cancelamento de boleto de pagamento de fatura

### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]/invoice_payment/[INVOICE-PAYMENT-KEY]
MÉTODO DELETE

Testar no Playground

### Response

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]/invoice_payment/[INVOICE-PAYMENT-KEY]
MÉTODO DELETE
HTTP STATUS 204

Response Body

```json
    {}
```

## 8. Estornos:

## 8.1. Consultar estornos:

### Request

ENDPOINT
        /card_invoice/wallet/[WALLET-KEY]/chargebacks
MÉTODO
        GET

Testar no Playground

#### PATH PARAMETERS

| Enumerador                   | Descrição                                                   |
|------------------------------|-------------------------------------------------------------|
| **status**                   | Status do estorno('active'/'used'/'pending_payment')        |

### Response

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/chargebacks
MÉTODO GET
HTTP STATUS 200

Response Body

```json
    {
        "page": 1,
        "last_page": true,
        "data": [
            {
                "charge_back_key": "key",
                "amount": 100,
                "used_amount": 0,
                "status": "active",
                "reference_card_entry_key": "key",
                "reference_item_key": "key"
            }
        ]
    }

```

## 9. Webhooks:

## 9.1. Alteração de status de fatura:
### Webhook

WEBHOOK_TYPE card_invoice.invoice.status_change
STATUS opened

Webhook Body

```json
{
	"webhook_type": "card_invoice.invoice.status_change",
	"key": "\<INVOICE-KEY\>",
	"event_datetime": "\<DATA E HORA DO ENVIO DO WEBHOOK\>",
	"status": "opened",
    "data": {
        "wallet_key":"\<CHAVE DA CARTEIRA\>",
        "due_date": "2023-07-10",
        "closing_date": "2023-07-02"
    }
}
```

:::note ATENÇÃO
O conteúdo do campo "data" mantém o mesmo padrão para todos os status
:::

#### Enumeradores Invoice status

| Enumerador                   | Descrição                                            |
|------------------------------|------------------------------------------------------|
| **opened**                   | Fatura aberta                                        |
| **closed**                   | Fatura fechada                                       |
| **paid**                     | Fatura paga dentro da data de vencimento             |
| **paid_overdue**             | Fatura paga em atraso                                |

## 9.2. Alteração de status da transação:
### Webhook

WEBHOOK_TYPE card_invoice.card_entry.status_change
STATUS active

Webhook Body

```json
{
	"webhook_type": "card_invoice.card_entry.status_change",
	"key": "\<CARD-ENTRY-KEY\>",
	"event_datetime": "\<DATA E HORA DO ENVIO DO WEBHOOK\>",
	"status": "active",
    "data": {
        "wallet_key":"\<CHAVE DA CARTEIRA\>"
    }
}
```

#### Enumeradores Card Entry status

| Enumerador                   | Descrição                                            |
|------------------------------|------------------------------------------------------|
| **active**                   | Contrato ativo e desembolsado                        |
| **canceled**                 | Contrato cancelado                                   |

:::caution ATENÇÃO
O envio deste webhook só ocorrerá quando a transação estiver no status de "pending_activation"
:::

## 9.3. Criação do boleto após fechamento da fatura:
### Webhook

WEBHOOK_TYPE card_invoice.invoice_payment.status_change
STATUS issued

Webhook Body

```json
{
	"webhook_type": "card_invoice.invoice_payment.status_change",
	"key": "\<INVOICE-PAYMENT-KEY\>",
	"event_datetime": "\<DATA E HORA DO ENVIO DO WEBHOOK\>",
	"status": "issued",
    "data": {
        "charge_type": "ordinary",
        "wallet_key":"\<CHAVE DA CARTEIRA\>",
        "invoice_key":"\<CHAVE DA FATURA\>",
        "digitable_line":"\<LINHA DIGITAVEL DO BOLETO\>",
        "qr_code_url":"\<URL DO QR CODE DO BOLETO\>"
    }
}
```

#### Enumeradores Charge type

| Enumerador                   | Descrição                                            |
|------------------------------|------------------------------------------------------|
| **ordinary**                 | Pagamento ordinário                                  |
| **early**                    | Pagamento extraordinário de adiantamento             |
| **delay**                    | Pagamento extraordinário de atraso                   |

## 9.4. Alteração de status do pagamento da fatura:
### Webhook

WEBHOOK_TYPE card_invoice.invoice_payment.status_change
STATUS paid

Webhook Body

```json
{
	"webhook_type": "card_invoice.invoice_payment.status_change",
	"key": "\<INVOICE-PAYMENT-KEY\>",
	"event_datetime": "\<DATA E HORA DO ENVIO DO WEBHOOK\>",
	"status": "paid",
    "data": {
        "wallet_key":"\<CHAVE DA CARTEIRA\>",
        "charge_type": "ordinary",
        "invoice_key":"\<CHAVE DA FATURA\>",
        "paid_amount": 150.0
    }
}
```

#### Enumeradores Invoice Payment status

| Enumerador                   | Descrição                                            |
|------------------------------|------------------------------------------------------|
| **issued**                   | Emissão do boleto para pagamento da fatura           |
| **paid**                     | Boleto pago                                          |
| **canceled**                 | Pagamento do boleto cancelado                        |

## 9.5. Alteração de status do estorno:

### Webhook

WEBHOOK_TYPE card_invoice.chargeback.status_change
STATUS active

Webhook Body

```json
{
	"webhook_type": "card_invoice.chargeback.status_change",
	"key": "\<CHARGEBACK-KEY\>",
	"event_datetime": "\<DATA E HORA DO ENVIO DO WEBHOOK\>",
	"status": "active",
    "data": {
        "wallet_key":"\<CHAVE DA CARTEIRA\>",
        "chargeback_amount":150.00,
        "reference_card_entry_key":"\<CHAVE DA TRANSAÇÃO DE REFERÊNCIA DO ESTORNO\>",
        "reference_item_key" :"\<CHAVE DO ITEM DE REFERÊNCIA DO ESTORNO\>"
    }
}
```

#### Enumeradores status estorno

| Enumerador                   | Descrição                                                   |
|------------------------------|-------------------------------------------------------------|
| **active**                   | Estorno ativo para ser utilizado em um pagamento de fatura  |
| **used**                     | Estorno ja utilizado no pagamento de uma fatura             |
| **pending_payment**          | Estorno aguardando pagamento para ser ativado               |

:::caution Status 'pending_payment' 
O status pending_payment representa o estorno de um item que pertence a uma fatura fechada que ainda não foi paga, o valor do estorno só pode ser utilizado após o pagamento da fatura.
:::

## 9.6.1 Rejeição de renegociação de transação:
### Webhook

WEBHOOK_TYPE card_invoice.renegotiation.status_change
STATUS rejected

Webhook Body

```json
{
    "webhook_type": "card_invoice.renegotiation.status_change",
    "key": "\\<RENEGOTIATION-KEY\\>",
    "event_datetime": "\\<DATA E HORA DO ENVIO DO WEBHOOK\\>",
    "status": "rejected",
    "data": {
        "wallet_key": "\\<CHAVE DA CARTEIRA\\>"
    }
}

```

## 9.6.2 Pagamento de renegociação de transação:
### Webhook

WEBHOOK_TYPE card_invoice.renegotiation.status_change
STATUS paid

Webhook Body

```json
{
    "webhook_type": "card_invoice.renegotiation.status_change",
    "key": "\\<RENEGOTIATION-KEY\\>",
    "event_datetime": "\\<DATA E HORA DO ENVIO DO WEBHOOK\\>",
    "status": "paid",
    "data": {
        "wallet_key": "\\<CHAVE DA CARTEIRA\\>",
        "paid_method_type": "<METODO DE PAGAMENTO>",
        "paid_in": {
            "code_number": "<CODIGO DO BANCO LIQUIDANTE>", 
            "ispb": "<ISPB DO BANCO LIQUIDANTE>", 
            "name": "<NOME DO BANCO LIQUIDANTE>"
        }
    }
}
```

#### Enumeradores status renegociação

| Enumerador                   | Descrição                                                                                                          |
|------------------------------|--------------------------------------------------------------------------------------------------------------------|
| **pending_payment**          | Renegociação de adiantamento de pagamento aguardando pagamento                                                     |
| **paid**                     | Renegociação de adiantamento de pagamento paga                                                                     |
| **canceled**                 | Renegociação de adiantamento de pagamento cancelada                                                                |
| **rejected**                 | Renegociação de adiantamento de pagamento rejeitada por pagamento de parcela por fora da renegociação ou decurso de prazo              |

## 10. Cancelamento de compra em até 7 dias:

## 10.1. Solicitação de cancelamento de compra:

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry/[CARD-ENTRY-KEY]/reversal
MÉTODO POST

Testar no Playground

### Request

Request Body

```json
{}
```

### Response

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

## 10.2. Consulta de cancelamento de compra ativo:

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry/[CARD-ENTRY-KEY]/reversal
MÉTODO GET

Testar no Playground

### Response

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

## 11. Renegociação de compras:

## 11.1. Simular renegociação de compras:

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/renegotiation/simulation
MÉTODO POST

Testar no Playground

### Request

Request Body

```json
{
    "reference_date": "2024-07-20",
    "card_entries": [
        {
            "card_entry_key": "817dced9-3216-410b-a51c-645019ab320b",
            "items": [
                {
                    "item_key": "04318ab7-7b3c-4558-ad7b-4e9e2d9e0e6e"
                }
            ]
        },
        {
            "card_entry_key": "3a3d8bbb-be30-41b0-b5be-8d358dc059ea"
        }
    ]
}
```

### Request body details

| Campo | Tipo | Descrição | Caracteres |
|---| ---| ---| ---| 
| `reference_date` | string | Data de referencia da renegociação.|  |

### Response

Response Body

```json
    {
    "renegotiation_payment_amount": 350,
    "reference_date": "2022-07-20",
    "discount_percentage": 0,
    "discount_amount": 0,
    "card_entries": [
        {
            "card_entry_key": "817dced9-3216-410b-a51c-645019ab320b",
            "payment_amount": 125,
            "discount_amount": 0,
            "affected_items": [
                {
                    "item_key": "04318ab7-7b3c-4558-ad7b-4e9e2d9e0e6e",
                    "due_date": "2022-07-15",
                    "principal_amount": 100,
                    "interest_amount": 20,
                    "fine_amount": 5,
                    "total_amount": 125,
                    "present_amount": 100
                }
            ]
        },
        {
            "card_entry_key": "3a3d8bbb-be30-41b0-b5be-8d358dc059ea",
            "payment_amount": 225,
            "discount_amount": 0,
            "affected_items": [
                {
                    "item_key": "1249249c-95b5-45aa-81f1-967abf5e6eef",
                    "due_date": "2022-07-15",
                    "principal_amount": 100,
                    "interest_amount": 20,
                    "fine_amount": 5,
                    "total_amount": 125,
                    "present_amount": 100
                },
                {
                    "item_key": "c66dad81-ecb4-4afa-8713-a85ee8e721ec",
                    "due_date": "2022-08-15",
                    "principal_amount": 100,
                    "interest_amount": 20,
                    "fine_amount": 5,
                    "total_amount": 100,
                    "present_amount": 120
                }
            ]
        }
    ]
}
```

## 11.2. Criar uma renegociação de compras:

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/renegotiation
MÉTODO POST

Testar no Playground

:::caution Objeto 'items' 
Quando não informado o objeto "items", será considerado que todos os itens disponíveis da transação sejam incluídos na renegociação, ou seja, itens com status diferente de "active" serão ignorados. 

Além disso, caso a carteira ja possua uma renegociação aguardando pagamento, ela deve ser cancelada para que seja possível gerar uma nova renegociação.
:::

### Request

Request Body

```json
{
    "reference_date": "2024-07-20",
    "proposal_due_date": "2024-07-27",
    "card_entries": [
        {
            "card_entry_key": "817dced9-3216-410b-a51c-645019ab320b",
            "items": [
                {
                    "item_key": "04318ab7-7b3c-4558-ad7b-4e9e2d9e0e6e"
                }
            ]
        },
        {
            "card_entry_key": "3a3d8bbb-be30-41b0-b5be-8d358dc059ea"
        }
    ]
}
```

### Campos de desconto

Adicionar um destes campos na requisição permite definir um valor de desconto percentual ou absoluto na criação ou simulação da proposta de renegociação.

Desconto percentual

```json
{
  "discount_percentage": 0.5
}
```

Desconto absoluto

```json
{
  "discount_amount": 200
}
```

### Request body details

| Campo | Tipo | Descrição | Caracteres |
|---| ---| ---| ---| 
| `reference_date` | string | Data de referencia da renegociação.|  |
| `proposal_due_date` | string | Data do vencimento da proposal da renegociação.|  |

### Response

Response Body

```json
{
    "renegotiation_key": "2af29916-582b-4ce7-8440-352a0d9543f7",
    "renegotiation_payment_amount": 350,
    "reference_date": "2022-07-20",
    "renegotiation_status": "pending_payment",
    "proposal_due_date": "2022-07-27",
    "discount_percentage": 0,
    "discount_amount": 0,
    "payment": {
        "digitable_line": "",
        "qr_code_url": "",
        "qr_code_key": "",
        "bank_slip_key": "",
        "paid_method_type": null
    },
    "card_entries": [
        {
            "card_entry_key": "817dced9-3216-410b-a51c-645019ab320b",
            "payment_amount": 125,
            "discount_amount": 0,
            "affected_items": [
                {
                    "item_key": "04318ab7-7b3c-4558-ad7b-4e9e2d9e0e6e",
                    "due_date": "2022-07-15",
                    "principal_amount": 100,
                    "interest_amount": 20,
                    "fine_amount": 5,
                    "total_amount": 125,
                    "present_amount": 100
                }
            ]
        },
        {
            "card_entry_key": "3a3d8bbb-be30-41b0-b5be-8d358dc059ea",
            "payment_amount": 225,
            "discount_amount": 0,
            "affected_items": [
                {
                    "item_key": "1249249c-95b5-45aa-81f1-967abf5e6eef",
                    "due_date": "2022-07-15",
                    "principal_amount": 100,
                    "interest_amount": 20,
                    "fine_amount": 5,
                    "total_amount": 125,
                    "present_amount": 100
                },
                {
                    "item_key": "c66dad81-ecb4-4afa-8713-a85ee8e721ec",
                    "due_date": "2022-08-15",
                    "principal_amount": 100,
                    "interest_amount": 20,
                    "fine_amount": 5,
                    "total_amount": 100,
                    "present_amount": 120
                }
            ]
        }
    ]
}
```

### Response body details

| Campo | Tipo | Descrição | Caracteres |
|---| ---| ---| ---| 
| `reference_date` | string | Data de referencia da renegociação.|  |
| `proposal_due_date` | string | Data do vencimento da proposal da renegociação.|  |
| `renegotiation_key` | string | Identificador único da renegociação(uuid).|  |
| `renegotiation_payment_amount` | number | Valor total da renegociação.|  |
| `discount_percentage` | number | Valor do desconto percentual a ser aplicado na renegociação.|  |
| `discount_amount` | number | Valor de desconto absoluto a ser aplicado na renegociação.|  |
| `payment` | object | Objeto que contém as informações para pagamento da renegociação.|  |
| `card_entries` | list | Lista de transações e suas respectivas parcelas a serem renegociadas.|  |

## 11.3. Consultar uma renegociação de compras existente:

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/renegotiation/[RENEGOTIATION-KEY]
MÉTODO GET

Testar no Playground

#### QUERY PARAMETERS

| Enumerador                   | Descrição                                                        |
|------------------------------|------------------------------------------------------------------|
| **shorten_url**              |  Parâmetro utilizado para solicitar uma url de boleto encurtada  |

### Response

Response Body

```json
{
    "renegotiation_key": "2af29916-582b-4ce7-8440-352a0d9543f7",
    "renegotiation_payment_amount": 350,
    "reference_date": "2022-07-20",
    "renegotiation_status": "pending_payment",
    "proposal_due_date": "2022-07-27",
    "discount_percentage": 0,
    "discount_amount": 0,
    "payment": {
        "digitable_line": "",
        "qr_code_url": "",
        "qr_code_key": "",
        "bank_slip_key": "",
        "paid_method_type": null,
        "bank_slip_url": "\<URL BOLETO EM PDF\>",
        "short_bank_slip_url": "\<URL BOLETO EM PDF ENCURTADA\>"
    },
    "card_entries": [
        {
            "card_entry_key": "817dced9-3216-410b-a51c-645019ab320b",
            "payment_amount": 125,
            "discount_amount": 0,
            "affected_items": [
                {
                    "item_key": "04318ab7-7b3c-4558-ad7b-4e9e2d9e0e6e",
                    "due_date": "2022-07-15",
                    "principal_amount": 100,
                    "interest_amount": 20,
                    "fine_amount": 5,
                    "total_amount": 125,
                    "present_amount": 100
                }
            ]
        },
        {
            "card_entry_key": "3a3d8bbb-be30-41b0-b5be-8d358dc059ea",
            "payment_amount": 225,
            "discount_amount": 0,
            "affected_items": [
                {
                    "item_key": "1249249c-95b5-45aa-81f1-967abf5e6eef",
                    "due_date": "2022-07-15",
                    "principal_amount": 100,
                    "interest_amount": 20,
                    "fine_amount": 5,
                    "total_amount": 125,
                    "present_amount": 100
                },
                {
                    "item_key": "c66dad81-ecb4-4afa-8713-a85ee8e721ec",
                    "due_date": "2022-08-15",
                    "principal_amount": 100,
                    "interest_amount": 20,
                    "fine_amount": 5,
                    "total_amount": 100,
                    "present_amount": 120
                }
            ]
        }
    ]
}
```

## 11.4. Cancelamento manual de uma de renegociação:

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/renegotiation/[RENEGOTIATION-KEY]
MÉTODO DELETE

Testar no Playground

### Response

Response Body

```json
{
    "renegotiation_key": "2af29916-582b-4ce7-8440-352a0d9543f7",
    "renegotiation_status": "canceled"
}

```

## 12. Simulação de cenários:

## 12.1. Fechamento de fatura:

:::info DUE_DATE
O campo due date é um campo opcional, quando não informado a fatura mantém a data de vencimento já definida. a data de fechamento não pode ser informada no futuro e a data de vencimento não pode ser definida antes da data de fechamento.
:::

ENDPOINT /mock/card_invoice/invoice/[INVOICE-KEY]/close
MÉTODO PATCH

### Request

Request Body

```json
{
    "closing_date":"2024-10-08",
    "due_date":"2024-10-20"
}
```

### Response

Response Body

```json
{}

```