# QI Tech — Banking-as-a-Service › Cartões Pós-Pago
Documentação da QI Tech em texto corrido, para colar em um LLM.
Fonte: https://docs.qitech.com.br
33 página(s).
Índice:
- Configuração do contactless (/documentation/cartao_pos_pago/cartao/atualizar/atualizar_contactless)
- Atualizar endereço de entrega (/documentation/cartao_pos_pago/cartao/atualizar/atualizar_endereco_entrega)
- Alterar senha cartão físico (/documentation/cartao_pos_pago/cartao/atualizar/atualizar_senha)
- Simulação de cenários (/documentation/cartao_pos_pago/cartao/atualizar/simulacao_de_cenarios)
- Buscar cartão por chave (/documentation/cartao_pos_pago/cartao/busca/buscar_cartao_por_chave)
- Buscar entrega por chave de cartão (/documentation/cartao_pos_pago/cartao/busca/buscar_dados_entrega_por_chave)
- Buscar dados PCI (/documentation/cartao_pos_pago/cartao/busca/buscar_dados_pci)
- Buscar Senha PCI (/documentation/cartao_pos_pago/cartao/busca/buscar_senha)
- Ativar cartão físico (/documentation/cartao_pos_pago/cartao/status/ativar_cartao)
- Atualizar status (/documentation/cartao_pos_pago/cartao/status/atualizar_status_cartao)
- Alteração de Limite de Carteira (/documentation/cartao_pos_pago/faturas/carteira/alteracao_de_limite)
- Buscar Entrada de Carteira por Chave (/documentation/cartao_pos_pago/faturas/carteira/consulta_entrada_por_chave)
- Consulta de Carteira por Chave (/documentation/cartao_pos_pago/faturas/carteira/consulta_por_chave)
- Criação de Carteira (Wallet) (/documentation/cartao_pos_pago/faturas/carteira/criacao_de_carteira)
- Listar de Carteiras (Wallets) (/documentation/cartao_pos_pago/faturas/carteira/listar_carteiras)
- Listar Entradas de Carteira (/documentation/cartao_pos_pago/faturas/carteira/listar_entradas_da_carteira)
- Buscar Boleto da Carteira (/documentation/cartao_pos_pago/faturas/fatura/boleto_de_pagamento_da_fatura)
- Buscar Fatura por Chave (/documentation/cartao_pos_pago/faturas/fatura/consulta_por_chave)
- Listar Faturas (/documentation/cartao_pos_pago/faturas/fatura/listar_faturas)
- Simulação de cenários - Fechamento e Vencimento de Faturas (/documentation/cartao_pos_pago/faturas/fatura/simulacao_de_cenarios)
- Alteração de Limite de Instrumento de Pagamento (/documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/alteracao_de_limite)
- Cancelamento de Instrumento de Pagamento (/documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/cancelamento_de_instrumento_de_pagamento)
- Buscar Entrada de Instrumento de Pagamento por Chave (/documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/consulta_entrada_por_chave)
- Criação de Instrumento de Pagamento (/documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/criacao_de_instrumento_de_pagamento)
- Listar Entradas de Instrumentos de Pagamento (/documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/listar_entradas_do_instrumento_de_pagamento)
- Listar Instrumentos de Pagamento (/documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/listar_instrumentos_de_pagamento)
- Simulação de cenários (/documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/simulacao_de_cenarios)
- Webhooks de Carteira (/documentation/cartao_pos_pago/faturas/webhooks/carteira)
- Webhooks de Entradas de Carteira (/documentation/cartao_pos_pago/faturas/webhooks/entrada_da_carteira)
- Webhooks de Entradas de Instrumento de Pagamento (/documentation/cartao_pos_pago/faturas/webhooks/entrada_do_instrumento_de_pagamento)
- Webhooks de Fatura (/documentation/cartao_pos_pago/faturas/webhooks/fatura)
- Webhooks de Pagamento de Fatura (/documentation/cartao_pos_pago/faturas/webhooks/pagamento_da_fatura)
- Introdução (/documentation/cartao_pos_pago/introducao)
---
# Configuração do contactless
URL: /documentation/cartao_pos_pago/cartao/atualizar/atualizar_contactless
Ativar ou desativar a funcionalidade de pagamento por aproximação (contactless) para uso presencial.
Para ativar ou desativar o pagamento por aproximação do cartão, o status do cartão deve ser do tipo **Ativo** ou **Bloqueio temporário**. (Para obter informações sobre os tipos de status, consulte [aqui](../../credit_cards/status/atualiar_status_cartao#enumeradores-card_status))
## Request
ENDPOINT /wallet/ WALLET_KEY /card/ CARD_KEY /contactless
MÉTODO PATCH
### Path params
| Campo | Tipo | Descrição | Caracteres |
|--------------|--------|-----------------------------------|------------|
| `WALLET_KEY` * | string | Chave de identificação do carteira. | uuid |
| `CARD_KEY` * | string | Chave de identificação do cartão. | uuid |
Request Body
```json
{
"contactless_enabled": false
}
```
### Body params
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|-----------------------------------|------------|
| `contactless_enabled` * | Boolean | Indica se está habilitado ou não. | true/false |
## Response
STATUS SUCCESS 200
Response Body
```json
{
"card_key": "05fd3654-1f5d-479d-ade5-64239fdf214d",
"status": "active",
"account_key": "3571e292-3a83-4011-904d-20ee963022ef",
"program_key": "6b6ebaac-043b-4390-8d62-e8098ec901e9",
"type": "virtual",
"card_name": "ecommerce",
"printed_name": "Aurora Catarina",
"brand": "visa",
"last_four_digits": "5695",
"created_at": "2023-02-20T19:28:16Z",
"updated_at": "2023-02-22T19:28:16Z",
"cvv_rotation_interval_hours": 72
}
```
### Erros
STATUS 4XX
Response Body
```json
{
"title": "Bad Request",
"description": "We're sorry, but the card could not be update contactless. Please try again later.",
"translation": "Unexpected error update contactless card",
"code": "CARD000026"
}
```
| Código | Status code | Descrição |
|:---------:|:------------:|:-------------------------------|
| QIT000001 | 400 | Invalid Json schema.|
| CARD000011| 404 | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000023| 406 | The card type is invalid for this operation. Only plastic cards are allowed.|
| CARD000026| 400 | We're sorry, but the card could not be update contactless. Please try again later.|
| CARD000025| 406 | The status \{status\} is invalid for the operation.|
---
# Atualizar endereço de entrega
URL: /documentation/cartao_pos_pago/cartao/atualizar/atualizar_endereco_entrega
A atualização do endereço de entrega serve para corrigir o endereço caso alguma inconsistência seja encontrada ou a entrega seja mal sucedida três vezes.
## Request
ENDPOINT /wallet/ WALLET_KEY /card/ CARD_KEY /address
MÉTODO PATCH
### Path params
| Campo | Tipo | Descrição | Caracteres |
|--------------|--------|-----------------------------------|------------|
| `WALLET_KEY` * | string | Chave de identificação do carteira. | uuid |
| `CARD_KEY` * | string | Chave de identificação do cartão. | uuid |
Request Body
```json
{
"postal_code": "5425020",
"street": "Rua Gilberto Sabino",
"number": 215,
"complement": "4 andar",
"neighborhood": "Pinheiros",
"city": "So Paulo",
"state": "SP",
"reference": "Terminal Pinheiros",
"address_type": "commercial",
"notes": ["obs1", "obs2"],
"phones": [
{"country_code": "55", "area_code": "19", "number": "983151110"},
{"country_code": "55", "area_code": "16", "number": "992334318"},
],
}
```
### Request Body
### Objeto address
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|--------|----------------------------------------------------|------------|
| `street` * | string | Logradouro | 100 |
| `number` * | string | Número | 10 |
| `neighborhood` * | string | Bairro | 100 |
| `postal_code` * | string | CEP | 8 |
| `city` * | string | Cidade | 100 |
| `complement` | string | Complemento | 100 |
| `reference` | string | Ponto de referência | 100 |
| `notes` | string array | Observações relacionadas ao endereço | 100 |
| `phones` | object array | Telefones de contato | **[Objeto phone](#objeto-phone)** |
| `state` * | string | Estado (UF) | **[Enumeradores state](#enumeradores-state)** |
| `address_type` * | string | Tipo de endereço | **[Enumeradores address_type](#enumeradores-address_type)** |
:::caution Atenção!
Podem ser enviados até dois telefones de contato e quatro observações. Caso não haja telefone de contato e/ou observações, esses campos (`phones` e `notes`) não devem ser enviados.
:::
### Objeto phone
| Campo | Tipo | Descrição | Caracteres |
|---------------------------------|--------|----------------------------------------------|------------|
| `international_dial_code` * | string | Código DDI (Discagem Direta Internacional) | 2 |
| `area_code` * | string | Código DDD (Discagem Direta à Distância) | 2 |
| `number` * | string | Complemento | 9 |
### Enumeradores address_type
| Enumerador | Descrição |
|--------------------|--------------------------|
| residential | endereço residencial |
| commercial | endereço comercial |
| other | outros tipos de endereço |
### Enumeradores state
| Enumerador | Descrição |
|--------------------|-----------------------|
| AC | Acre |
| AL | Alagoas |
| AM | Amazonas |
| AP | Amapá |
| BA | Bahia |
| CE | Ceará |
| DF | Distrito federal |
| ES | Espírito Santo |
| GO | Goiás |
| MA | Maranhão |
| MG | Minas Gerais |
| MS | Mato Grosso do Sul |
| MT | Mato Grosso |
| PA | Pará |
| PB | Paraíba |
| PE | Pernambuco |
| PI | Piauí |
| PR | Paraná |
| RJ | Rio de Janeiro |
| RN | Rio Grande do Norte |
| RO | Rondônia |
| RR | Roraima |
| RS | Rio Grande do Sul |
| SC | Santa Catarina |
| SE | Sergipe |
| SP | São Paulo |
| TO | Tocantins |
| EX | Exceção |
## Response
STATUS 200
Response Body
```json
{
"card_key": "1e3183f0-1bac-4e59-81e8-2d89db224040",
"tracking_code": "FD89B071241022",
"address": {
"city": "So Paulo",
"notes": [
"obs1",
"obs2"
],
"state": "SP",
"number": 215,
"phones": [
{
"number": "983151110",
"area_code": "19",
"country_code": "55"
},
{
"number": "992334318",
"area_code": "16",
"country_code": "55"
}
],
"street": "Rua Gilberto Sabino",
"reference": "Terminal Pinheiros",
"complement": "4 andar",
"postal_code": "5425020",
"address_type": "commercial",
"neighborhood": "Pinheiros"
}
}
```
### Response Body Params
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|--------|-------------------------------------------------------------------------------------------------|------------|
| `card_key` * | uuidv4 | Chave única de identificação do cartão, no formato uuid v4 | 36 |
| `tracking_code` * | string | Código de rastreio da entrega do cartão | 14 |
| `address` | object | Objeto do tipo `address`, semelhante ao que é enviado na requisição | **[Objeto address](#objeto-address)** |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (pt-br)
`translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 403 | QIT000005 | Permission Validator Error | Selected agent and person_key are different | Agente selecionado e person_key são diferentes |
| 400 | TRACK000004 | Bad Request | Invalid status to change delivery address. | Status inválido para mudar o endereço de entrega. |
| 500 | TRACK000007 | Internal Server Error | Failed to update delivery address at delivery service provider. Please, try again later! | Falha ao atualizar endereço de entrega junto à provedora de serviços de delivery. Por favor, tente novamente mais tarde! |
| 404 | TRACK000012 | Not Found | Tracking not found for the given 'card_key'. | Rastreio não encontrado para a 'card_key' fornecida. |
---
# Alterar senha cartão físico
URL: /documentation/cartao_pos_pago/cartao/atualizar/atualizar_senha
Todo cartão físico tem uma senha para autorizar a transação, e ela pode ser atualizada caso necessária.
Para atualizar a senha do cartão o status tem que ter o tipo **Active** ou **Temporary block**.(Para conhecer sobre status consulte [aqui](../../credit_cards/status/atualiar_status_cartao#enumeradores-card_status))
:::caution Atenção
Por motivos de segurança, cuidado ao atualizar uma senha, pois ela pode impactar na autorização de um cartão.
Crie regras para melhorar a segurança da autorização da senha, como não utilizar data de aniversário, números repetidos (ex: 3333).
:::
## Request
ENDPOINT /wallet/ WALLET_KEY /card/ CARD_KEY /password
MÉTODO PATCH
### Path params
| Campo | Tipo | Descrição | Caracteres |
|--------------|--------|-----------------------------------|------------|
| `WALLET_KEY` * | string | Chave de identificação do carteira. | uuid |
| `CARD_KEY` * | string | Chave de identificação do cartão. | uuid |
Request Body
```json
{
"pin": "2143"
}
```
### Body params
| Campo | Tipo | Descrição | Caracteres |
|-----------|--------|-----------------------------------------------|------------|
| `pin` * | string | Senha do cartão para autorizar uma transação. | 4 |
## Response
STATUS SUCCESS 200
Response Body
```json
{
"card_key": "05fd3654-1f5d-479d-ade5-64239fdf214d",
"status": "active",
"account_key": "3571e292-3a83-4011-904d-20ee963022ef",
"program_key": "6b6ebaac-043b-4390-8d62-e8098ec901e9",
"type": "virtual",
"card_name": "ecommerce",
"printed_name": "Aurora Catarina",
"brand": "visa",
"last_four_digits": "5695",
"created_at": "2023-02-20T19:28:16Z",
"updated_at": "2023-02-22T19:28:16Z",
"cvv_rotation_interval_hours": 72
}
```
### Erros
STATUS 4XX
Response Body
```json
{
"title": "Bad Request",
"description": "We're sorry, but the card could not be update password. Please try again later.",
"translation": "Unexpected error update password card",
"code": "CARD000024"
}
```
| Código | Status code | Descrição |
|:---------:|:------------:|:-------------------------------|
| QIT000001 | 400 | Invalid Json schema.|
| CARD000011| 404 | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000023| 406 | The card type is invalid for this operation. Only plastic cards are allowed.|
| CARD000024| 400 | We're sorry, but the card could not be update password. Please try again later.|
| CARD000025| 406 | The status \{status\} is invalid for the operation.|
---
# Simulação de cenários
URL: /documentation/cartao_pos_pago/cartao/atualizar/simulacao_de_cenarios
Esta página descreve como simular a atualização do status de rastreamento de cartões pós-pagos para testar o fluxo de atualizações de entrega. Essas simulações são úteis para homologação e testes de integração.
:::info Informação
Essas requisições simulam atualizações de status de rastreamento e retornam o status HTTP com os dados atualizados do rastreamento.
:::
## 1 - Simulação de atualização de status de rastreamento
Simula a atualização do status de rastreamento de um cartão pós-pago, permitindo transicionar entre diferentes estados do processo de entrega. A atualização cria um novo evento no histórico de rastreamento.
ENDPOINT /mock/wallet/ WALLET_KEY /card/ CARD_KEY /tracking
MÉTODO PATCH
### Path Parameters
| Campo | Tipo | Descrição | Caracteres |
|------------------------------|--------|----------------------------------------------|------------|
| `wallet_key` * | string | Chave única da carteira no formato UUID v4 | 36 |
| `card_key` * | string | Chave única do cartão no formato UUID v4 | 36 |
Request Body
```json
{
"status": "posted",
"place": "São Paulo - SP",
"description": "Postado - logística iniciada",
"reason": "Processamento concluído"
}
```
### Objeto Request Body
| Campo | Tipo | Descrição | Máx. Caract. |
|------------------------------------------|---------|------------------------------------------------------------------------------------|--------------|
| `status` * | string | Novo status do rastreamento | **[Enumeradores status](#enumeradores-status)** |
| `place` * | string | Local onde ocorreu o evento | 100 |
| `description` * | string | Descrição do evento de rastreamento | 255 |
| `reason` | string | Motivo adicional do evento (opcional) | 100 |
### Enumeradores status
| Enumerador | Descrição |
|-----------------------------|-----------------------------------------------------------------------------------|
| `pending` | Pendente - aguardando processamento inicial |
| `posted` | Postado - logística iniciada |
| `prepared` | Preparado - cartão preparado para transferência |
| `in_transfer` | Em transferência - cartão em trânsito |
| `in_delivery_unit` | Na unidade de entrega - cartão chegou à unidade de distribuição |
| `on_route` | Em rota - cartão saiu para entrega |
| `attempt_failed` | Tentativa falhou - tentativa de entrega não foi bem-sucedida |
| `awaiting_withdrawal` | Aguardando retirada - cartão disponível para retirada |
| `returning` | Retornando - cartão em processo de devolução |
| `delivered` | Entregue - cartão foi entregue com sucesso |
| `returned` | Devolvido - cartão foi devolvido |
| `canceled` | Cancelado - rastreamento foi cancelado |
| `failed` | Falhou - falha no processo de entrega |
| `resend` | Reenvio - cartão será reenviado |
| `redispatch_error` | Erro no redespacho - erro ao redespachar o cartão |
| `waiting_for_address_update`| Aguardando atualização de endereço - aguardando confirmação de endereço |
### Response
STATUS 204
Response Body
```json
{}
```
:::tip Comportamento
- A simulação atualiza o status do rastreamento e cria um novo evento no histórico
- As transições de status seguem uma ordem específica e validações são aplicadas:
- Não é possível retroceder para status anteriores (exceto status especiais)
- Não é possível alterar status a partir de status finais (`delivered`, `returned`, `canceled`, `failed`)
- Não é possível transicionar de `waiting_for_address_update` para outro status que não seja `pending`
- Não é possível transicionar para `waiting_for_address_update` a partir de status finais
- Status especiais (`attempt_failed`, `resend`, `redispatch_error`) podem ser utilizados em qualquer momento após o status inicial
- O campo `reason` é opcional e, quando fornecido, é concatenado à descrição do evento
:::
---
# Buscar cartão por chave
URL: /documentation/cartao_pos_pago/cartao/busca/buscar_cartao_por_chave
## Request
ENDPOINT /wallet/ WALLET_KEY /card/ CARD_KEY
MÉTODO GET
### Path params
| Campo | Tipo | Descrição | Caracteres |
|--------------|--------|-----------------------------------|------------|
| `WALLET_KEY` * | string | Chave de identificação do carteira. | uuid |
| `CARD_KEY` * | string | Chave de identificação do cartão. | uuid |
## Response
STATUS 200
Response Body
```json
{
"card_key": "05fd3654-1f5d-479d-ade5-64239fdf214d",
"status": "active",
"account_key": "3571e292-3a83-4011-904d-20ee963022ef",
"program_key": "6b6ebaac-043b-4390-8d62-e8098ec901e9",
"type": "virtual",
"card_name": "ecommerce",
"printed_name": "Aurora Catarina",
"brand": "visa",
"last_four_digits": "5695",
"created_at": "2023-02-20T19:28:16Z",
"updated_at": "2023-02-22T19:28:16Z",
"cvv_rotation_interval_hours": 72
}
```
### Erros
STATUS 4XX
Response Body
```json
{
"title": "Not Found",
"description": "It was not possible to fetch the Card for the card_key f6bf148a-30b6-4a07-8c5b-3383a98ea32b.",
"translation": "Not Found Card",
"code": "CARD000011"
}
```
| Code | Status code | Descrição |
|:---------:|:------------:|:-------------------------------|
| CARD000011| 404 | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000016| 400 | We're sorry, but the card could not be fetch. Please try again later.|
---
# Buscar entrega por chave de cartão
URL: /documentation/cartao_pos_pago/cartao/busca/buscar_dados_entrega_por_chave
## Request
ENDPOINT /wallet/ WALLET_KEY /card/ CARD_KEY /tracking
MÉTODO GET
### Path params
| Campo | Tipo | Descrição | Caracteres |
|--------------|--------|-----------------------------------|------------|
| `WALLET_KEY` * | string | Chave de identificação do carteira. | uuid |
| `CARD_KEY` * | string | Chave de identificação do cartão. | uuid |
## Response
STATUS 200
Response Body
```json
{
"card_key": "92b4e2bd-4a6f-4c56-859e-17c729e1f0c8",
"tracking_code": "4F68A72B902317",
"status": "posted",
"recipient": "João Silva",
"address": {
"zip_code": "1234567",
"street": "Rua das Flores",
"number": 123,
"complement": "Bloco A",
"neighborhood": "Centro",
"city": "Cidade Exemplo",
"state": "SP"
},
"event": [
{
"created_at": "2024-02-27T08:30:00Z",
"old_status": "pending",
"new_status": "posted",
"description": "Pedido recebido e postado",
"place": "SAO PAULO"
}
]
}
```
### Enumeradores DeliveryStatus
| Enumerador | Tradução |
|--------------------|---------------------|
| pending | Pendente |
| posted | Postado |
| prepared | Preparado |
| in_transfer | Em transferência |
| in_delivery_unit | Na unidade de entrega |
| on_route | Em rota |
| attempt_failed | Tentativa falhou |
| awaiting_withdrawal| Aguardando retirada |
| returning | Retornando |
| delivered | Entregue |
| returned | Devolvido |
| canceled | Cancelado |
| failed | Falhou |
| resend | Reenviado |
### Erros
STATUS 4XX
Response Body
```json
{
"title": "Not Found",
"description": "It was not possible to fetch the Tracking for the card_key f6bf148a-30b6-4a07-8c5b-3383a98ea32b.",
"translation": "Not Found",
"code": "TRACK000011"
}
```
| Code | Status code | Descrição |
|:---------:|:------------:|:-------------------------------|
| TRACK000011| 404 | It was not possible to fetch the Tracking for the card_key \{card_key\}.|
| TRACK000016| 400 | We're sorry, but the tracking could not be fetch. Please try again later.|
---
# Buscar dados PCI
URL: /documentation/cartao_pos_pago/cartao/busca/buscar_dados_pci
## Request
ENDPOINT /wallet/ WALLET_KEY /card/ CARD_KEY /pci
MÉTODO GET
### Path params
| Campo | Tipo | Descrição | Caracteres |
|--------------|--------|-----------------------------------|------------|
| `WALLET_KEY` * | string | Chave de identificação do carteira. | uuid |
| `CARD_KEY` * | string | Chave de identificação do cartão. | uuid |
## Response
STATUS 200
Response Body
```json
{
"printed_name": "Aurora Catarina",
"valid_until": "2023-02-20T10:04:12Z",
"expiration_date": "03/24",
"card_number": "4539347744299311",
"cvv": "713"
}
```
### Erros
STATUS 4XX
Response Body
```json
{
"title": "Not Found",
"description": "It was not possible to fetch the Card for the card_key f6bf148a-30b6-4a07-8c5b-3383a98ea32b.",
"translation": "Not Found Card",
"code": "CARD000011"
}
```
| Code | Status code | Descrição |
|:---------:|:------------:|:-------------------------------|
| CARD000011| 404 | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000012| 400 | It was not possible to fetch PCI for the card_key \{card_key\}.|
---
# Buscar Senha PCI
URL: /documentation/cartao_pos_pago/cartao/busca/buscar_senha
## Request
ENDPOINT /wallet/ WALLET_KEY /card/ CARD_KEY /pci/password
MÉTODO GET
### Path params
| Campo | Tipo | Descrição | Caracteres |
|--------------|--------|-----------------------------------|------------|
| `WALLET_KEY` * | string | Chave de identificação do carteira. | uuid |
| `CARD_KEY` * | string | Chave de identificação do cartão. | uuid |
## Response
STATUS 200
Response Body
```json
{
"pin": "1234"
}
```
### Erros
STATUS 4XX
Response Body
```json
{
"title": "Bad Request",
"description": "It was not possible to fetch PCI for the card_key f6bf148a-30b6-4a07-8c5b-3383a98ea32b.",
"translation": "Fetch PCI failed",
"code": "CARD000012"
}
```
| Code | Status code | Descrição |
|:---------:|:------------:|:-------------------------------|
| CARD000011| 404 | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000012| 400 | It was not possible to fetch PCI for the card_key \{card_key\}.|
---
# Ativar cartão físico
URL: /documentation/cartao_pos_pago/cartao/status/ativar_cartao
Todo cartão físico precisa ser ativado através de um código de ativação que é enviado junto do cartão físico, ao portador.
Ao receber o cartão por correspondência, o portador do cartão precisa informar ao parceiro da QI, para que o parceiro realize a ativação do cartão através deste endpoint.
:::caution Atenção
Por motivos de segurança, não existe a possibilidade de consulta do código de ativação via API por parte do parceiro.
Este código é enviado, exclusivamente ao portador do cartão, no momento da postagem do cartão físico.
Para realizar testes de integração, esse código é devolvido em ambiente de sandobox ao consultar um cartão.
:::
## Request
ENDPOINT /wallet/ WALLET_KEY /card/ CARD_KEY /activate
MÉTODO PATCH
### Path params
| Campo | Tipo | Descrição | Caracteres |
|--------------|--------|-----------------------------------|------------|
| `WALLET_KEY` * | string | Chave de identificação do carteira. | uuid |
| `CARD_KEY` * | string | Chave de identificação do cartão. | uuid |
Request Body
```json
{
"code": "253615"
}
```
### Body params
| Campo | Tipo | Descrição | Caracteres |
|-----------|--------|-------------------------------|------------|
| `code` * | string | Código de ativação do cartão. | 6 |
## Response
STATUS 200
Response Body
```json
{
"card_key": "05fd3654-1f5d-479d-ade5-64239fdf214d",
"status": "active",
"account_key": "3571e292-3a83-4011-904d-20ee963022ef",
"program_key": "6b6ebaac-043b-4390-8d62-e8098ec901e9",
"type": "virtual",
"card_name": "ecommerce",
"printed_name": "Aurora Catarina",
"brand": "visa",
"last_four_digits": "5695",
"created_at": "2023-02-20T19:28:16Z",
"updated_at": "2023-02-22T19:28:16Z",
"cvv_rotation_interval_hours": 72
}
```
### Erros
STATUS 4XX
Response Body
```json
{
"title": "Not Acceptable",
"description": "Invalid activation code [1254].",
"translation": "Unable to activate card",
"code": "CARD000020"
}
```
| Code | Status code | Description |
|:---------:|:------------:|:-------------------------------|
| QIT000001 | 400 | Invalid Json schema.|
| CARD000011| 404 | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000017| 406 | The activation operation is not valid for the current card status [\{card_status\}].|
| CARD000018| 400 | We're sorry, but the card could not be activate. Please try again later.|
| CARD000020| 406 | Invalid activation code [\{code\}].|
| CARD000023| 406 | The card type is invalid for this operation. Only plastic cards are allowed.|
---
# Atualizar status
URL: /documentation/cartao_pos_pago/cartao/status/atualizar_status_cartao
## Request
ENDPOINT /wallet/ WALLET_KEY /card/ CARD_KEY
MÉTODO PATCH
### Path params
| Campo | Tipo | Descrição | Caracteres |
|--------------|--------|-----------------------------------|------------|
| `WALLET_KEY` * | string | Chave de identificação do carteira. | uuid |
| `CARD_KEY` * | string | Chave de identificação do cartão. | uuid |
Request Body
```json
{
"status": "blocked"
}
```
### Body params
| Campo | Tipo | Descrição | Caracteres |
|-------------|--------|-------------------|-----------------------------------------------|
| `status` * | string | Status do cartão. | **[Enumeradores](#enumeradores-card_status)** |
### Enumeradores card_status
| Enumerador | Tradução | Tipo |
|------------|---------------------|-----------------|
| created | Criação solicitada | Initial |
| building | Em construção | Initial |
| active | Apto a transacionar | Active |
| embossing | Em produção | Temporary block |
| blocked | Bloqueado | Temporary block |
| warning | Com suspeita | Temporary block |
| pending | Pendente | Temporary block |
| lost | Perdido | Terminated |
| robbed | Roubado | Terminated |
| fraud | Fraudado | Terminated |
| canceled | Cancelado | Terminated |
| theft | Furtado | Terminated |
### Erros
STATUS 4XX
Response Body
```json
{
"title": "Not Acceptable",
"description": "The operation is not valid for the current status of the card [canceled]",
"translation": "Unable to transition",
"code": "CARD000014"
}
```
| Code | Status code | Descrição |
|:---------:|:------------:|:-------------------------------|
| QIT000001 | 400 | Invalid Json schema.|
| CARD000011| 404 | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000013| 406 | Unable to transition from \{old_status\} to \{new_status\}.|
| CARD000014| 406 | The operation is not valid for the current status of the card [\{card_status\}].|
| CARD000015| 400 | We're sorry, but the card could not be update. Please try again later|
### Webhook
WEBHOOK_TYPE baas.pospaid_card.card
Webhook Body
```json
{
"webhook_type": "baas.pospaid_card.card",
"event_datetime": "2023-07-25T12:00:00.000Z",
"data": {
"card_key": "9bd93e97-bb6d-410f-8981-06b2765f12a1",
"type": "virtual",
"status": "active",
"old_status": "created"
}
}
```
---
# Alteração de Limite de Carteira
URL: /documentation/cartao_pos_pago/faturas/carteira/alteracao_de_limite
A alteração de limite de carteira permite alterar o valor do limite de crédito pós-pago de uma carteira existente.
## Request
ENDPOINT /wallet/ WALLET_KEY /wallet_limit/ WALLET_LIMIT_KEY
MÉTODO PATCH
### Path Parameters
| Campo | Tipo | Descrição | Caracteres |
|------------------------------|--------|----------------------------------------------|------------|
| `wallet_key` * | uuidv4 | Chave única da carteira no formato UUID v4 | 36 |
| `wallet_limit_key` * | uuidv4 | Chave única do limite de carteira no formato UUID v4 | 36 |
Request Body
```json
{
"limit_amount": 10000.00
}
```
### Request Body Params
| Campo | Tipo | Descrição | Caracteres |
|------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `limit_amount` * | float | Novo valor do limite de crédito pós-pago | - |
:::info Observação
- O novo valor do limite deve ser maior ou igual ao limite utilizado (`used_limit`)
- Apenas limites do tipo `postpaid_credit_limit` podem ser atualizados
- Apenas carteiras do tipo `default` podem ter seus limites atualizados
- A atualização do limite também atualiza o limite no serviço de cartões
:::
## Response
STATUS 200
Response Body: Limite de carteira atualizado
```json
{
"wallet_limit_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"limit_type": "postpaid_credit_limit",
"limit_amount": 10000.00,
"used_limit": 2500.00
}
```
### Response Body Params
| Campo | Tipo | Descrição | Caracteres |
|----------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `wallet_limit_key` * | uuidv4 | Chave única de identificação do limite atualizado no formato UUID v4 | 36 |
| `limit_type` * | string | Tipo do limite atualizado | **[Enumeradores limit_type](#enumeradores-limit_type)** |
| `limit_amount` * | float | Novo valor do limite de crédito pós-pago após a atualização | - |
| `used_limit` * | float | Valor do limite utilizado no momento da atualização | - |
### Enumeradores limit_type
| Enumerador | Descrição |
|-------------------------|-----------------------------------------|
| postpaid_credit_limit | Limite de crédito pós-pago |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (pt-br)
`translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | CIN000110 | Bad Request | New limit amount is less than used limit | Novo valor do limite é menor que o valor utilizado |
| 400 | CIN000111 | Bad Request | Error while updating postpaid wallet limit in card service, try again in a few minutes. | Erro ao atualizar limite de carteira pós-pago no serviço de cartão, tente novamente em alguns minutos. |
| 400 | CIN000112 | Bad Request | Requester postpaid limit exceeded for this client | Limite das carteiras pós-pagas do cliente excedido |
| 403 | CIN000108 | Forbidden | Wallet type payroll is not allowed for this operation | Tipo de carteira payroll não é permitido para esta operação |
| 403 | CIN000109 | Forbidden | Wallet limit type payroll_withdraw_limit is not allowed for this operation | Tipo de limite de carteira payroll_withdraw_limit não é permitido para esta operação |
| 404 | CIN000007 | Wallet not Found | Wallet with key: e91d68d4-2904-4f9d-a6ef-50c82c34531e was not found | Carteira com a chave: e91d68d4-2904-4f9d-a6ef-50c82c34531e não foi encontrado |
| 404 | CIN000107 | Not Found | Wallet limit not found | Limite de carteira não foi encontrado |
---
# Buscar Entrada de Carteira por Chave
URL: /documentation/cartao_pos_pago/faturas/carteira/consulta_entrada_por_chave
A busca de entrada de carteira por chave retornará os detalhes completos de uma entrada específica, incluindo todos os itens da fatura relacionados.
## Request
ENDPOINT /wallet/ WALLET_KEY /wallet_entry/ WALLET_ENTRY_KEY
MÉTODO GET
### Path Parameters
| Campo | Tipo | Descrição | Caracteres |
|-------------------|--------|----------------------------------------------|------------|
| `wallet_key` | uuidv4 | Chave única da carteira no formato UUID v4 | 36 |
| `wallet_entry_key`| uuidv4 | Chave única da entrada no formato UUID v4 | 36 |
## Response
STATUS 200
Response Body: Detalhes da entrada de carteira
```json
{
"wallet_entry_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"wallet_entry_amount": 150.00,
"wallet_entry_settlement_key": "cc8fb19b-d1e4-4ce6-ad4c-61e0609a8f8d",
"wallet_entry_type": "revolving_credit",
"wallet_entry_status": "concluded",
"invoice_items": [
{
"invoice_item_key": "3571e292-3a83-4011-904d-20ee963022ef",
"invoice_key": "f2cad6b4-2a68-9572-99a7-2849c8d6ecf8",
"wallet_entry_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"payment_instrument_entry_key": null,
"installment_number": 1,
"invoice_description": "Crédito rotativo - Taxa de juros",
"amount": 150.00,
"used_limit": 150.00,
"invoice_item_status": "concluded",
"invoice_item_due_date": "2024-02-15",
"created_at": "2024-01-15T10:30:00Z"
}
],
"created_at": "2024-01-15T10:30:00Z"
}
```
### Response Body Params
| Campo | Tipo | Descrição | Caracteres |
|------------------------------|--------------|---------------------------------------|---------------------------------------------|
| `wallet_entry_key` * | uuidv4 | Chave única de identificação da entrada no formato uuid v4 | 36 |
| `wallet_entry_amount` * | float | Valor da entrada | - |
| `wallet_entry_settlement_key` * | string | Chave de liquidação da entrada | - |
| `wallet_entry_type` * | string | Tipo da entrada da carteira | **[Enumeradores wallet_entry_type](#enumeradores-wallet_entry_type)** |
| `wallet_entry_status` * | string | Status da entrada da carteira | **[Enumeradores wallet_entry_status](#enumeradores-wallet_entry_status)** |
| `invoice_items` * | object array | Itens da fatura relacionados | **[Objeto invoice_item](#objeto-invoice_item)** |
| `created_at` * | string | Data de criação (formato ISO 8601 UTC) | - |
### Objeto invoice_item
| Campo | Tipo | Descrição | Caracteres |
|------------------------------------|---------|-----------------------------------------------------------------------------------|------------|
| `invoice_item_key` * | uuidv4 | Chave única de identificação do item da fatura no formato uuid v4 | 36 |
| `invoice_key` * | uuidv4 | Chave única de identificação da fatura no formato uuid v4 | 36 |
| `wallet_entry_key` | uuidv4 | Chave única de identificação da entrada da carteira no formato uuid v4 | 36 |
| `payment_instrument_entry_key` | uuidv4 | Chave única de identificação da entrada do instrumento de pagamento no formato uuid v4 | 36 |
| `installment_number` * | integer | Número da parcela | - |
| `invoice_description` * | string | Descrição do item da fatura | - |
| `amount` * | float | Valor do item | - |
| `used_limit` * | float | Limite utilizado | - |
| `invoice_item_status` * | string | Status do item da fatura | **[Enumeradores invoice_item_status](#enumeradores-invoice_item_status)** |
| `invoice_item_due_date` * | string | Data de vencimento do item (formato YYYY-MM-DD) | 10 |
| `created_at` * | string | Data de criação (formato ISO 8601 UTC) | - |
### Enumeradores wallet_entry_type
| Enumerador | Descrição |
|-------------------|-----------------------------------------------------------------------------------|
| revolving_credit | Crédito rotativo |
| payroll_withdraw | Saque de folha |
| payroll_overdue | Atraso de folha |
:::info Tipos de Entrada de Carteira
- **`revolving_credit`**: Valores de crédito disponibilizados para o cliente
- **`payroll_withdraw`**: Dívida gerada pelo saque do limite e que vai ser descontada todo mês do INSS
- **`payroll_overdue`**: Dívida gerada pelo não pagamento da fatura e também vai ser descontada todo mês do INSS
:::
### Enumeradores wallet_entry_status
| Enumerador | Descrição |
|------------|-----------------------------------------|
| concluded | Entrada concluída |
### Enumeradores invoice_item_status
| Enumerador | Descrição |
|------------|-----------------------------------------|
| concluded | Item concluído |
| canceled | Item cancelado |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (pt-br)
`translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 404 | CIN000007 | Wallet not Found | Wallet with key: abeca0d0-a09d-4b3b-a495-40b553422ced was not found | Carteira com a chave: abeca0d0-a09d-4b3b-a495-40b553422ced não foi encontrado |
| 404 | CIN000078 | Not Found | Wallet entry with key: 8cb70dea-9fb0-4a68-9572-99a72849c8d6 was not found | Dívida da carteira com a chave: 8cb70dea-9fb0-4a68-9572-99a72849c8d6 não foi encontrado |
---
# Consulta de Carteira por Chave
URL: /documentation/cartao_pos_pago/faturas/carteira/consulta_por_chave
A consulta de carteira por chave retorna os detalhes completos de uma carteira específica, incluindo suas configurações de fatura e limites de crédito.
## Request
ENDPOINT /wallet/ WALLET_KEY
MÉTODO GET
### Path Parameters
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|--------|----------------------------------------------|------------|
| `wallet_key` | uuidv4 | Chave única de identificação da carteira | 36 |
## Response
STATUS 200
Response Body: Detalhes da carteira
```json
{
"request_control_key": "f7947b9d-9be3-49d8-aca2-4b3249e5fa65",
"wallet_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"owner_person_key": "ecf87b4b-fa6e-49c0-a7f0-f2cad6b42d79",
"owner_document_number": "12345678901",
"invoice_configuration": {
"closing_date_configuration": {
"type": "fixed",
"fixed_day": 15
},
"due_date_configuration": {
"type": "fixed",
"fixed_day": 20,
"offset_months": 0
},
"invoice_payment_type": "bank_slip",
"interest_base": "calendar_days",
"monthly_interest_percentage": 2.0,
"fine_percentage": 2.0
},
"wallet_status": "active",
"wallet_type": "default",
"wallet_limits": [
{
"wallet_limit_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"limit_type": "postpaid_credit_limit",
"limit_amount": 5000.00,
"used_limit": 0.00
}
],
"created_at": "2024-01-15T10:30:00Z"
}
```
### Response Body Params
| Campo | Tipo | Descrição | Caracteres |
|------------------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `wallet_key` * | string | Chave única de identificação da carteira | 36 |
| `owner_person_key` * | string | Chave de identificação do proprietário da carteira | 36 |
| `owner_document_number` * | string | CPF/CNPJ do proprietário da carteira | 11-14 |
| `invoice_configuration` * | object | Configurações de fatura da carteira | **[Objeto invoice_configuration](#objeto-invoice_configuration)** |
| `wallet_status` * | string | Status atual da carteira | **[Enumeradores wallet_status](#enumeradores-wallet_status)** |
| `wallet_type` * | string | Tipo da carteira | **[Enumeradores wallet_type](#enumeradores-wallet_type)** |
| `wallet_limits` * | array | Lista de limites da carteira | **[Objeto wallet_limits](#objeto-wallet_limits)** |
| `created_at` * | string | Data de criação (formato ISO 8601 UTC) | - |
### Objeto invoice_configuration
| Campo | Tipo | Descrição | Caracteres |
|------------------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `closing_date_configuration` * | object | Configuração da data de fechamento da fatura | **[Objeto closing_date_configuration](#objeto-closing_date_configuration)** |
| `due_date_configuration` * | object | Configuração da data de vencimento da fatura | **[Objeto due_date_configuration](#objeto-due_date_configuration)** |
| `invoice_payment_type` * | string | Tipo de pagamento da fatura | **[Enumeradores invoice_payment_type](#enumeradores-invoice_payment_type)** |
| `interest_base` | string | Base de cálculo dos juros | **[Enumeradores interest_base](#enumeradores-interest_base)** |
| `monthly_interest_percentage` | float | Percentual de juros mensais por atraso (0-100) | - |
| `fine_percentage` | float | Percentual de multa por atraso (0-100) | - |
:::info
Nota Carteiras do tipo `payroll` não possuem os campos `interest_base`, `monthly_interest_percentage` e `fine_percentage`.
:::
### Objeto closing_date_configuration
#### Configuração Fixa (`type: "fixed"`)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `type` * | string | Tipo de configuração (deve ser "fixed") | - |
| `fixed_day` * | integer | Dia fixo do mês para fechamento (1-27) | - |
#### Configuração Baseada em Regras (`type: "rule_based"`)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `type` * | string | Tipo de configuração (deve ser "rule_based") | - |
| `rule` * | object | Regra para cálculo da data | **[Objeto rule (closing_date_configuration)](#objeto-rule-closing_date_configuration)** |
### Objeto rule (closing_date_configuration)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `day_of_week` * | string | Dia da semana | **[Enumeradores day_of_week](#enumeradores-day_of_week)** |
| `occurrence` * | string | Ocorrência do dia no mês | **[Enumeradores occurrence](#enumeradores-occurrence)** |
| `fallback_strategy` * | string | Estratégia para dias não úteis | **[Enumeradores fallback_strategy](#enumeradores-fallback_strategy)** |
### Objeto due_date_configuration
#### Configuração Fixa (`type: "fixed"`)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `type` * | string | Tipo de configuração (deve ser "fixed") | - |
| `offset_months` * | integer | Meses de offset a partir do fechamento | - |
| `fixed_day` * | integer | Dia fixo do mês para vencimento (2-27) | - |
#### Configuração Baseada em Regras (`type: "rule_based"`)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `type` * | string | Tipo de configuração (deve ser "rule_based") | - |
| `offset_months` * | integer | Meses de offset a partir do fechamento | - |
| `rule` * | object | Regra para cálculo da data | **[Objeto rule (due_date_configuration)](#objeto-rule-due_date_configuration)** |
### Objeto rule (due_date_configuration)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `day_of_week` * | string | Dia da semana | **[Enumeradores day_of_week](#enumeradores-day_of_week)** |
| `occurrence` * | string | Ocorrência do dia no mês | **[Enumeradores occurrence](#enumeradores-occurrence)** |
| `fallback_strategy` * | string | Estratégia para dias não úteis | **[Enumeradores fallback_strategy](#enumeradores-fallback_strategy)** |
### Objeto wallet_limits
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `limit_type` * | string | Tipo do limite | **[Enumeradores limit_type](#enumeradores-limit_type)** |
| `limit_amount` * | float | Valor total do limite | - |
| `used_limit` * | float | Valor utilizado do limite | - |
### Enumeradores wallet_status
| Enumerador | Descrição |
|--------------------|-----------------------------------------|
| pending_analysis | Carteira pendente de análise KYC |
| active | Carteira ativa e disponível para uso |
| rejected | Carteira rejeitada |
### Enumeradores wallet_type
| Enumerador | Descrição |
|-------------|------------------------------|
| default | Carteira padrão |
| payroll | Carteira para cartão consignao |
### Enumeradores limit_type
| Enumerador | Descrição |
|---------------------------|------------------------------|
| postpaid_credit_limit | Limite de crédito pós-pago |
| payroll_withdraw_limit | Limite para saque de folha de pagamento (salário/consignado) |
:::info Limites em Carteiras Payroll
Carteiras do tipo `payroll` possuem dois limites distintos:
- **`postpaid_credit_limit`**: Limite de crédito pós-pago para compras e transações com o cartão
- **`payroll_withdraw_limit`**: Limite específico para saques de folha de pagamento (salário/consignado), que são descontados automaticamente na folha de pagamento do cliente
:::
### Enumeradores day_of_week
| Enumerador | Descrição |
|-------------|-----------|
| monday | Segunda-feira |
| tuesday | Terça-feira |
| wednesday | Quarta-feira |
| thursday | Quinta-feira |
| friday | Sexta-feira |
| saturday | Sábado |
| sunday | Domingo |
### Enumeradores occurrence
| Enumerador | Descrição |
|-------------|-----------|
| first | Primeira ocorrência |
| second | Segunda ocorrência |
| third | Terceira ocorrência |
| fourth | Quarta ocorrência |
| last | Última ocorrência |
### Enumeradores fallback_strategy
| Enumerador | Descrição |
|----------------------|------------------------------|
| next_business_day | Próximo dia útil |
| previous_business_day| Dia útil anterior |
| same_day | Mesmo dia |
### Enumeradores invoice_payment_type
| Enumerador | Descrição |
|-------------|----------------|
| bank_slip | Boleto bancário |
### Enumeradores interest_base
| Enumerador | Descrição |
|-----------------|------------------|
| calendar_days | Dias corridos |
### Objeto wallet_limits
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `wallet_limit_key` * | uuidv4 | Chave única de identificação do limite atualizado no formato UUID v4 | 36 |
| `limit_type` * | string | Tipo do limite | **[Enumeradores limit_type](#enumeradores-limit_type)** |
| `limit_amount` * | float | Valor total do limite | - |
| `used_limit` * | float | Valor utilizado do limite | - |
### Enumeradores limit_type
| Enumerador | Descrição |
|---------------------------|------------------------------|
| postpaid_credit_limit | Limite de crédito pós-pago |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (pt-br)
`translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 404 | WLT000001 | Wallet Not Found | Wallet with key 8cb70dea-9fb0-4a68-9572-99a72849c8d6 not found | Carteira com chave 8cb70dea-9fb0-4a68-9572-99a72849c8d6 não encontrada |
---
# Criação de Carteira (Wallet)
URL: /documentation/cartao_pos_pago/faturas/carteira/criacao_de_carteira
A criação de carteira (wallet) permite registrar uma nova carteira de crédito para uma pessoa física ou jurídica.
:::info O que é uma Wallet
A **wallet** representa a fatura de um cliente e funciona como um centralizador para gerenciar múltiplos meios de pagamento atrelados. É importante entender que:
- **Uma wallet = fatura**: Cada carteira corresponde à fatura de um cliente específico (identificado por CPF/CNPJ)
- **Múltiplos meios de pagamento**: A mesma wallet pode ter diferentes instrumentos de pagamento (cartões, PIX, etc.)
- **Instrumentos separados**: Após criar a wallet, será necessário criar separadamente os instrumentos de pagamento (cartões de crédito, limites, etc.)
- **Gestão centralizada**: A wallet centraliza todas as operações e configurações relacionadas àquele cliente
:::
## Request
ENDPOINT /wallet
MÉTODO POST
Request Body
```json
{
"owner": {
"request_control_key": "f7947b9d-9be3-49d8-aca2-4b3249e5fa65",
"person_type": "natural",
"name": "João Silva",
"document_number": "12345678901",
"birthdate": "1990-01-01",
"email": "joao.silva@email.com",
"phone": {
"number": "99999999",
"area_code": "11",
"country_code": "55"
},
"address": {
"street": "Rua das Flores",
"number": "123",
"neighborhood": "Centro",
"postal_code": "01234567",
"city": "São Paulo",
"state": "SP",
"complement": "Apto 1"
}
},
"invoice_configuration": {
"closing_date_configuration": {
"type": "fixed",
"fixed_day": 15
},
"due_date_configuration": {
"type": "fixed",
"fixed_day": 20,
"offset_months": 0
},
"invoice_payment_type": "bank_slip",
"interest_base": "calendar_days",
"monthly_interest_percentage": 2.0,
"fine_percentage": 2.0
},
"limits": {
"postpaid_credit_limit": 5000.00
}
}
```
### Request Body Params
| Campo | Tipo | Descrição | Caracteres |
|------------------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `request_control_key` | uuidv4 | Chave única de identificação da request utilizada pelo cliente. | 36 |
| `owner` | object | Dados do proprietário da carteira (pessoa física ou jurídica) | **[Objeto owner](#objeto-owner)** |
| `person_key` | string | Chave única de identificação da pessoa no formato UUID v4 | 36 |
| `invoice_configuration` * | object | Configuração de fechamento e vencimento de faturas | **[Objeto invoice_configuration](#objeto-invoice_configuration)** |
| `limits` * | object | Limites de crédito da carteira | **[Objeto limits](#objeto-limits)** |
:::info Campos Condicionais
- **`owner`**: Obrigatório quando não for enviado `person_key`
- **`person_key`**: Obrigatório quando não for enviado `owner`
- Os campos são mutuamente exclusivos
:::
### Objeto owner
#### Pessoa Física (`person_type: "natural"`)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|--------|----------------------------------------------|------------|
| `person_type` * | string | Tipo da pessoa (deve ser "natural") | - |
| `name` * | string | Nome completo da pessoa | 100 |
| `document_number` * | string | CPF da pessoa (apenas números) | 11 |
| `birthdate` * | string | Data de nascimento (formato YYYY-MM-DD) | 10 |
| `email` * | string | E-mail de contato | 254 |
| `phone` * | object | Telefone de contato | **[Objeto phone](#objeto-phone)** |
| `address` * | object | Endereço completo | **[Objeto address](#objeto-address)** |
#### Pessoa Jurídica (`person_type: "legal"`)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|--------|----------------------------------------------|------------|
| `person_type` * | string | Tipo da pessoa (deve ser "legal") | - |
| `name` * | string | Razão social da empresa | 100 |
| `trading_name` * | string | Nome fantasia da empresa | 100 |
| `document_number` * | string | CNPJ da empresa (apenas números) | 14 |
| `foundation_date` * | string | Data de fundação (formato YYYY-MM-DD) | 10 |
| `email` * | string | E-mail de contato | 254 |
| `phone` * | object | Telefone de contato | **[Objeto phone](#objeto-phone)** |
| `address` * | object | Endereço completo | **[Objeto address](#objeto-address)** |
| `legal_representatives` * | array | Lista de representantes legais (pessoas físicas) | - |
### Objeto phone
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|--------|----------------------------------------------|------------|
| `country_code` * | string | Código do país (DDI) | 2-3 |
| `area_code` * | string | Código de área (DDD) | 2 |
| `number` * | string | Número do telefone | 8-9 |
### Objeto address
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|--------|----------------------------------------------|------------|
| `street` * | string | Nome da rua/avenida | 500 |
| `number` * | string | Número do endereço | 10 |
| `neighborhood` * | string | Bairro | 100 |
| `postal_code` * | string | CEP (apenas números) | 8 |
| `city` * | string | Cidade | 100 |
| `state` * | string | Estado (UF) | **[Enumeradores state](#enumeradores-state)** |
| `complement` | string | Complemento do endereço | 500 |
### Enumeradores state
| Enumerador | Descrição |
|-------------|----------------|
| AC | Acre |
| AL | Alagoas |
| AM | Amazonas |
| AP | Amapá |
| BA | Bahia |
| CE | Ceará |
| DF | Distrito Federal |
| ES | Espírito Santo |
| GO | Goiás |
| MA | Maranhão |
| MG | Minas Gerais |
| MS | Mato Grosso do Sul |
| MT | Mato Grosso |
| PA | Pará |
| PB | Paraíba |
| PE | Pernambuco |
| PI | Piauí |
| PR | Paraná |
| RJ | Rio de Janeiro |
| RN | Rio Grande do Norte |
| RO | Rondônia |
| RR | Roraima |
| RS | Rio Grande do Sul |
| SC | Santa Catarina |
| SE | Sergipe |
| SP | São Paulo |
| TO | Tocantins |
| EX | Exceção |
### Objeto invoice_configuration
| Campo | Tipo | Descrição | Caracteres |
|------------------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `closing_date_configuration` * | object | Configuração da data de fechamento da fatura | **[Objeto closing_date_configuration](#objeto-closing_date_configuration)** |
| `due_date_configuration` * | object | Configuração da data de vencimento da fatura | **[Objeto due_date_configuration](#objeto-due_date_configuration)** |
| `invoice_payment_type` * | string | Tipo de pagamento da fatura | **[Enumeradores invoice_payment_type](#enumeradores-invoice_payment_type)** |
| `interest_base` * | string | Base de cálculo dos juros | **[Enumeradores interest_base](#enumeradores-interest_base)** |
| `monthly_interest_percentage` * | float | Percentual de juros mensais por atraso (0-100) | - |
| `fine_percentage` * | float | Percentual de multa por atraso (0-100) | - |
### Objeto closing_date_configuration
#### Configuração Fixa (`type: "fixed"`)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `type` * | string | Tipo de configuração (deve ser "fixed") | - |
| `fixed_day` * | integer | Dia fixo do mês para fechamento (1-27) | - |
#### Configuração Baseada em Regras (`type: "rule_based"`)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `type` * | string | Tipo de configuração (deve ser "rule_based") | - |
| `rule` * | object | Regra para cálculo da data | **[Objeto rule (closing_date_configuration)](#objeto-closing_date_configuration)** |
### Objeto rule (closing_date_configuration)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `day_of_week` * | string | Dia da semana | **[Enumeradores day_of_week](#enumeradores-day_of_week)** |
| `occurrence` * | string | Ocorrência do dia no mês | **[Enumeradores occurrence](#enumeradores-occurrence)** |
| `fallback_strategy` * | string | Estratégia para dias não úteis | **[Enumeradores fallback_strategy](#enumeradores-fallback_strategy)** |
### Objeto due_date_configuration
#### Configuração Fixa (`type: "fixed"`)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `type` * | string | Tipo de configuração (deve ser "fixed") | - |
| `offset_months` * | integer | Meses de offset a partir do fechamento | - |
| `fixed_day` * | integer | Dia fixo do mês para vencimento (2-27) | - |
#### Configuração Baseada em Regras (`type: "rule_based"`)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `type` * | string | Tipo de configuração (deve ser "rule_based") | - |
| `offset_months` * | integer | Meses de offset a partir do fechamento | - |
| `rule` * | object | Regra para cálculo da data | **[Objeto rule (closing_date_configuration)](#objeto-due_date_configuration)** |
### Objeto rule (due_date_configuration)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `day_of_week` * | string | Dia da semana | **[Enumeradores day_of_week](#enumeradores-day_of_week)** |
| `occurrence` * | string | Ocorrência do dia no mês | **[Enumeradores occurrence](#enumeradores-occurrence)** |
| `fallback_strategy` * | string | Estratégia para dias não úteis | **[Enumeradores fallback_strategy](#enumeradores-fallback_strategy)** |
:::caution Validações de Data
- A data de vencimento deve ser pelo menos 2 dia após a data de fechamento
- Para configurações baseadas em regras, deve existir ao menos um dia de diferença entre os dias da semana escolhidos para fechamento e vencimento (ex: fechamento na segunda-feira e vencimento na quarta-feira de qualquer semana)
:::
### Enumeradores day_of_week
| Enumerador | Descrição |
|-------------|-----------|
| monday | Segunda-feira |
| tuesday | Terça-feira |
| wednesday | Quarta-feira |
| thursday | Quinta-feira |
| friday | Sexta-feira |
| saturday | Sábado |
| sunday | Domingo |
### Enumeradores occurrence
| Enumerador | Descrição |
|-------------|-----------|
| first | Primeira ocorrência |
| second | Segunda ocorrência |
| third | Terceira ocorrência |
| fourth | Quarta ocorrência |
| last | Última ocorrência |
### Enumeradores fallback_strategy
| Enumerador | Descrição |
|----------------------|------------------------------|
| next_business_day | Próximo dia útil |
| previous_business_day| Dia útil anterior |
| same_day | Mesmo dia |
### Enumeradores invoice_payment_type
| Enumerador | Descrição |
|-------------|----------------|
| bank_slip | Boleto bancário |
### Enumeradores interest_base
| Enumerador | Descrição |
|-----------------|------------------|
| calendar_days | Dias corridos |
### Objeto limits
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `postpaid_credit_limit` * | float | Limite para crédito pós-pago | - |
## Response
### Sucesso - Carteira Criada com Análise Pendente
STATUS 202
Response Body: Carteira pendente de análise
```json
{
"wallet_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"owner_person_key": null,
"wallet_status": "pending_analysis"
}
```
:::info Informação
Caso seja retornado **HTTP Status 202** com o campo `wallet_status` com valor `pending_analysis`, a criação será processada assincronamente.
Posteriormente será enviado posteriormente um webhook informando se a carteira foi aprovada ou rejeitada na análise KYC. Para mais detalhes sobre webhooks, consulte a [documentação de webhooks](/documentation/cartao_pos_pago/faturas/webhooks/carteira)
:::
:::note Observação
Para casos que requerem análise KYC, o campo `owner_person_key` será retornado como `null` na resposta inicial. A pessoa titular da carteira só será criada no sistema ao final do processo de KYC, caso seja aprovada. Neste caso, a chave da pessoa será enviada posteriormente através do webhook de aprovação, consulte a [documentação de webhooks](/documentation/cartao_pos_pago/faturas/webhooks/carteira)
:::
### Sucesso - Carteira Criada Ativa
STATUS 201
Response Body: Carteira ativa
```json
{
"wallet_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"owner_person_key": "ecf87b4b-fa6e-49c0-a7f0-f2cad6b42d79",
"wallet_status": "active"
}
```
### Response Body Params
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|--------|-----------------------------------------------------------------------------------|------------|
| `wallet_key` * | uuidv4 | Chave única de identificação da carteira no formato uuid v4 | 36 |
| `owner_person_key` * | string | Chave de identificação do proprietário da carteira | 36 |
| `wallet_status` * | string | Status da carteira | - |
### Enumeradores wallet_status
| Enumerador | Descrição |
|--------------------|-----------------------------------------|
| pending_analysis | Carteira pendente de análise KYC |
| active | Carteira ativa e disponível para uso |
| rejected | Carteira rejeitada |
:::info Status da Carteira
- **`pending_analysis`**: Retornado quando a carteira é criada com dados completos do proprietário. Será submetida a análise KYC.
- **`active`**: Retornado quando a carteira é criada com chave de pessoa existente. Disponível para uso imediato.
:::
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (pt-br)
`translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | CIN000020 | Requester not Found | No requester configuration found for requester key: 8e1e6b46-beb3-467b-965c-6c545707d467 | Solicitante não encontrado para requester key: 8e1e6b46-beb3-467b-965c-6c545707d467 |
| 404 | CIN000062 | Not Found | Person not found by person key: e51070e4-7494-468d-a20e-bf14789fa8ff | Pessoa não encontrada para a person key: e51070e4-7494-468d-a20e-bf14789fa8ff |
| 409 | CIN000043 | Conflict | Active wallet found | Carteira ativa já existe |
| 400 | CIN000063 | Bad Request | Expiration date too close to closing date | Data de vencimento muito próxima da data de fechamento |
| 400 | CIN000064 | Bad Request | Invalid offset months for rule-based configuration | Meses de offset inválidos para configuração baseada em regras |
| 400 | CIN000065 | Bad Request | Weekdays too close for rule-based configuration | Dias da semana muito próximos para configuração baseada em regras |
| 400 | CIN000002 | Bad Request | Invalid signer document number | Número do documento do signatário inválido |
| 400 | CIN000066 | Bad Request | Error while creating wallet in card service | Erro ao criar carteira no serviço de cartão |
| 409 | CIN000099 | Conflict | Request control key already exists. | Request control key já existe. |
---
# Listar de Carteiras (Wallets)
URL: /documentation/cartao_pos_pago/faturas/carteira/listar_carteiras
A listagem de carteiras retornará todas as carteiras que se enquadrarem nos query parameters enviados na request.
## Request
ENDPOINT /wallets
MÉTODO GET
### Query Parameters
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `owner_document_number` | string | CPF/CNPJ do proprietário da carteira | 11-14 |
| `wallet_status` | string | Status da carteira para filtrar | **[Enumeradores wallet_status](#enumeradores-wallet_status)** |
| `page` | integer | Número da página para paginação | - |
| `page_size` | integer | Quantidade de itens por página | - |
:::caution Validações
- **Paginação**: Valores de página e tamanho devem ser inteiros válidos
- **Tamanho da página**: Máximo de 100 itens por página
:::
### Enumeradores wallet_status
| Enumerador | Descrição |
|--------------------|-----------------------------------------|
| pending_analysis | Carteira pendente de análise KYC |
| active | Carteira ativa e disponível para uso |
| rejected | Carteira rejeitada |
## Response
STATUS 200
Response Body: Lista de carteiras
```json
{
"data": [
{
"request_control_key": "f7947b9d-9be3-49d8-aca2-4b3249e5fa65",
"wallet_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"owner_person_key": "ecf87b4b-fa6e-49c0-a7f0-f2cad6b42d79",
"owner_document_number": "12345678901",
"invoice_configuration": {
"closing_date_configuration": {
"type": "fixed",
"fixed_day": 15
},
"due_date_configuration": {
"type": "fixed",
"fixed_day": 20,
"offset_months": 0
},
"invoice_payment_type": "bank_slip",
"interest_base": "calendar_days",
"monthly_interest_percentage": 2.0,
"fine_percentage": 2.0
},
"wallet_status": "active",
"wallet_type": "default",
"created_at": "2024-01-15T10:30:00Z"
},
{
"request_control_key": "e1d7ca45-8180-48e4-a293-1f08a046693e",
"wallet_key": "9db81efb-0ac1-5b79-0683-00b8395a9e7",
"owner_document_number": "98765432100",
"invoice_configuration": {
"closing_date_configuration": {
"type": "rule_based",
"rule": {
"day_of_week": "friday",
"occurrence": "last",
"fallback_strategy": "previous_business_day"
}
},
"due_date_configuration": {
"type": "rule_based",
"offset_months": 1,
"rule": {
"day_of_week": "monday",
"occurrence": "first",
"fallback_strategy": "next_business_day"
}
},
"invoice_payment_type": "bank_slip",
"interest_base": "calendar_days",
"monthly_interest_percentage": 1.5,
"fine_percentage": 2.0
},
"wallet_status": "pending_analysis",
"wallet_type": "default",
"created_at": "2024-01-14T14:45:00Z"
}
],
"pagination": {
"current_page": 1,
"rows_per_page": 100,
}
}
```
### Response Body Params
| Campo | Tipo | Descrição | Caracteres |
|------------------|--------------|---------------------------------------|---------------------------------------------|
| `data` * | object array | Carteiras | **[Objeto wallet](#objeto-wallet)** |
| `pagination` * | object | Informações de paginação | **[Objeto pagination](#objeto-pagination)** |
### Objeto wallet
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|--------|----------------------------------------------|------------|
| `wallet_key` * | uuidv4 | Chave única de identificação da carteira | 36 |
| `owner_person_key` * | string | Chave de identificação do proprietário da carteira | 36 |
| `owner_document_number` * | string | CPF/CNPJ do proprietário da carteira | 11 ou 14 |
| `invoice_configuration` * | object | Configuração de fechamento e vencimento | **[Objeto invoice_configuration](#objeto-invoice_configuration)** |
| `wallet_status` * | string | Status atual da carteira | **[Enumeradores wallet_status](#enumeradores-wallet_status)** |
| `wallet_type` * | string | Tipo da carteira | **[Enumeradores wallet_type](#enumeradores-wallet_type)** |
| `created_at` * | string | Data de criação (formato ISO 8601 UTC) | - |
### Objeto pagination
| Campo | Tipo | Descrição | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `current_page` * | integer | Página atual | - |
| `rows_per_page` * | integer | Itens por página | - |
### Enumeradores wallet_type
| Enumerador | Descrição |
|-------------|------------------------------|
| default | Carteira padrão |
| payroll | Carteira para cartão consignado |
### Objeto invoice_configuration
| Campo | Tipo | Descrição | Caracteres |
|------------------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `closing_date_configuration` * | object | Configuração da data de fechamento da fatura | **[Objeto closing_date_configuration](#objeto-closing_date_configuration)** |
| `due_date_configuration` * | object | Configuração da data de vencimento da fatura | **[Objeto due_date_configuration](#objeto-due_date_configuration)** |
| `invoice_payment_type` * | string | Tipo de pagamento da fatura | **[Enumeradores invoice_payment_type](#enumeradores-invoice_payment_type)** |
| `interest_base` | string | Base de cálculo dos juros | **[Enumeradores interest_base](#enumeradores-interest_base)** |
| `monthly_interest_percentage` | float | Percentual de juros mensais por atraso (0-100) | - |
| `fine_percentage` | float | Percentual de multa por atraso (0-100) | - |
:::info
Nota Carteiras do tipo `payroll` não possuem os campos `interest_base`, `monthly_interest_percentage` e `fine_percentage`.
:::
### Objeto closing_date_configuration
#### Configuração Fixa (`type: "fixed"`)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `type` * | string | Tipo de configuração (deve ser "fixed") | - |
| `fixed_day` * | integer | Dia fixo do mês para fechamento (1-27) | - |
#### Configuração Baseada em Regras (`type: "rule_based"`)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `type` * | string | Tipo de configuração (deve ser "rule_based") | - |
| `rule` * | object | Regra para cálculo da data | **[Objeto rule (closing_date_configuration)](#objeto-closing_date_configuration)** |
### Objeto rule (closing_date_configuration)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `day_of_week` * | string | Dia da semana | **[Enumeradores day_of_week](#enumeradores-day_of_week)** |
| `occurrence` * | string | Ocorrência do dia no mês | **[Enumeradores occurrence](#enumeradores-occurrence)** |
| `fallback_strategy` * | string | Estratégia para dias não úteis | **[Enumeradores fallback_strategy](#enumeradores-fallback_strategy)** |
### Objeto due_date_configuration
#### Configuração Fixa (`type: "fixed"`)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `type` * | string | Tipo de configuração (deve ser "fixed") | - |
| `offset_months` * | integer | Meses de offset a partir do fechamento | - |
| `fixed_day` * | integer | Dia fixo do mês para vencimento (2-27) | - |
#### Configuração Baseada em Regras (`type: "rule_based"`)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `type` * | string | Tipo de configuração (deve ser "rule_based") | - |
| `offset_months` * | integer | Meses de offset a partir do fechamento | - |
| `rule` * | object | Regra para cálculo da data | **[Objeto rule (closing_date_configuration)](#objeto-due_date_configuration)** |
### Objeto rule (due_date_configuration)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `day_of_week` * | string | Dia da semana | **[Enumeradores day_of_week](#enumeradores-day_of_week)** |
| `occurrence` * | string | Ocorrência do dia no mês | **[Enumeradores occurrence](#enumeradores-occurrence)** |
| `fallback_strategy` * | string | Estratégia para dias não úteis | **[Enumeradores fallback_strategy](#enumeradores-fallback_strategy)** |
### Enumeradores day_of_week
| Enumerador | Descrição |
|-------------|-----------|
| monday | Segunda-feira |
| tuesday | Terça-feira |
| wednesday | Quarta-feira |
| thursday | Quinta-feira |
| friday | Sexta-feira |
| saturday | Sábado |
| sunday | Domingo |
### Enumeradores occurrence
| Enumerador | Descrição |
|-------------|-----------|
| first | Primeira ocorrência |
| second | Segunda ocorrência |
| third | Terceira ocorrência |
| fourth | Quarta ocorrência |
| last | Última ocorrência |
### Enumeradores fallback_strategy
| Enumerador | Descrição |
|----------------------|------------------------------|
| next_business_day | Próximo dia útil |
| previous_business_day| Dia útil anterior |
| same_day | Mesmo dia |
### Enumeradores invoice_payment_type
| Enumerador | Descrição |
|-------------|----------------|
| bank_slip | Boleto bancário |
### Enumeradores interest_base
| Enumerador | Descrição |
|-----------------|------------------|
| calendar_days | Dias corridos |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (pt-br)
`translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | BKS000012 | Bad Request | Invalid integer value for page or size query string parameters | Valor inválido para parâmetros de página ou tamanho de página |
| 400 | BKS000013 | Bad Request | Invalid query wallet status | Status de consulta de carteira inválido |
---
# Listar Entradas de Carteira
URL: /documentation/cartao_pos_pago/faturas/carteira/listar_entradas_da_carteira
A listagem de entradas de carteira retornará todas as entradas de uma carteira específica que se enquadrarem nos query parameters enviados na request.
## Request
ENDPOINT /wallet/ WALLET_KEY /wallet_entries
MÉTODO GET
### Path Parameters
| Campo | Tipo | Descrição | Caracteres |
|--------------|--------|----------------------------------------------|------------|
| `wallet_key` | uuidv4 | Chave única da carteira no formato UUID v4 | 36 |
### Query Parameters
| Campo | Tipo | Descrição | Caracteres |
|------------------------------|---------|----------------------------------------------|------------|
| `wallet_entry_type` * | string | Tipo da entrada da carteira | **[Enumeradores wallet_entry_type](#enumeradores-wallet_entry_type)** |
| `wallet_entry_status` * | string | Status da entrada da carteira | **[Enumeradores wallet_entry_status](#enumeradores-wallet_entry_status)** |
| `page` | integer | Número da página para paginação | - |
| `page_size` | integer | Quantidade de itens por página | - |
:::caution Validações
- **Paginação**: Valores de página e tamanho devem ser inteiros válidos
- **Tamanho da página**: Máximo de 100 itens por página
:::
### Enumeradores wallet_entry_type
| Enumerador | Descrição |
|-------------------|-----------------------------------------------------------------------------------|
| revolving_credit | Crédito rotativo |
| payroll_withdraw | Saque de folha |
| payroll_overdue | Atraso de folha |
:::info Tipos de Entrada de Carteira
- **`revolving_credit`**: Valores de crédito disponibilizados para o cliente
- **`payroll_withdraw`**: Dívida gerada pelo saque do limite e que vai ser descontada todo mês do INSS
- **`payroll_overdue`**: Dívida gerada pelo não pagamento da fatura e também vai ser descontada todo mês do INSS
:::
### Enumeradores wallet_entry_status
| Enumerador | Descrição |
|------------|-----------------------------------------|
| concluded | Entrada concluída |
## Response
STATUS 200
Response Body: Lista de entradas de carteira
```json
{
"data": [
{
"wallet_entry_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"wallet_entry_amount": 150.00,
"wallet_entry_settlement_key": "cc8fb19b-d1e4-4ce6-ad4c-61e0609a8f8d",
"wallet_entry_type": "revolving_credit",
"wallet_entry_status": "concluded",
"created_at": "2024-01-15T10:30:00Z"
},
{
"wallet_entry_key": "9db81efb-0ac1-5b79-0683-00b8395a9e7",
"wallet_entry_amount": 150.00,
"wallet_entry_settlement_key": "20cbf6e7-9535-44b4-88e3-f2c7a178a198",
"wallet_entry_type": "payroll_withdraw",
"wallet_entry_status": "concluded",
"created_at": "2024-01-14T14:45:00Z"
}
],
"pagination": {
"current_page": 1,
"rows_per_page": 100
}
}
```
### Response Body Params
| Campo | Tipo | Descrição | Caracteres |
|------------------|--------------|---------------------------------------|---------------------------------------------|
| `data` * | object array | Entradas de carteira | **[Objeto wallet_entry](#objeto-wallet_entry)** |
| `pagination` * | object | Informações de paginação | **[Objeto pagination](#objeto-pagination)** |
### Objeto wallet_entry
| Campo | Tipo | Descrição | Caracteres |
|------------------------------|---------|-----------------------------------------------------------------------------------|------------|
| `wallet_entry_key` * | uuidv4 | Chave única de identificação da entrada no formato uuid v4 | 36 |
| `wallet_entry_amount` * | float | Valor da entrada | - |
| `wallet_entry_settlement_key` * | string | Chave de liquidação da entrada | - |
| `wallet_entry_type` * | string | Tipo da entrada da carteira | **[Enumeradores wallet_entry_type](#enumeradores-wallet_entry_type)** |
| `wallet_entry_status` * | string | Status da entrada da carteira | **[Enumeradores wallet_entry_status](#enumeradores-wallet_entry_status)** |
| `created_at` * | string | Data de criação (formato ISO 8601 UTC) | - |
### Objeto pagination
| Campo | Tipo | Descrição | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `current_page` * | integer | Página atual | - |
| `rows_per_page` * | integer | Itens por página | - |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (pt-br)
`translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | CIN000069 | Bad Request | Invalid integer value for page or size query string parameters | Valor inválido para parâmetros de página ou tamanho de página |
| 400 | CIN000076 | Bad Request | Invalid query wallet entry status | Status de consulta de dívida da carteira inválido |
| 400 | CIN000077 | Bad Request | Invalid query wallet entry type | Tipo de consulta de dívida da carteira inválido |
| 404 | CIN000007 | Wallet not Found | Wallet with key: abeca0d0-a09d-4b3b-a495-40b553422ced was not found | Carteira com a chave: abeca0d0-a09d-4b3b-a495-40b553422ced não foi encontrado |
---
# Buscar Boleto da Carteira
URL: /documentation/cartao_pos_pago/faturas/fatura/boleto_de_pagamento_da_fatura
A busca de boleto da carteira retornará as informações do boleto bancário associado à carteira, incluindo código de barras e linha digitável.
:::warning Atenção
O boleto da carteira **só é gerado a partir do fechamento da primeira fatura**.
:::
## Request
ENDPOINT /v2/invoice/wallet/ WALLET_KEY /wallet_bank_slip
MÉTODO GET
### Path Parameters
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|----------------------------------------------|------------|
| `wallet_key` | uuidv4 | Chave única da carteira no formato UUID v4 | 36 |
## Response
STATUS 200
Response Body: Detalhes do boleto
```json
{
"wallet_bank_slip_key": "3571e292-3a83-4011-904d-20ee963022ef",
"wallet_bank_slip_status": "accepted",
"bank_slip_amount": 150.00,
"bank_slip_due_date": "2024-02-15",
"bank_slip_data": {
"barcode": "32991090000000150001234567890123456789012345",
"digitable_line": "32991234567890123456789012345678901234567890123"
}
}
```
### Response Body Params
| Campo | Tipo | Descrição | Caracteres |
|--------------------------|--------|-----------------------------------------------------------------------------------|------------|
| `wallet_bank_slip_key` * | uuidv4 | Chave única de identificação do boleto da carteira no formato uuid v4 | 36 |
| `wallet_bank_slip_status` * | string | Status do boleto | **[Enumeradores wallet_bank_slip_status](#enumeradores-wallet_bank_slip_status)** |
| `bank_slip_amount` * | float | Valor do boleto | - |
| `bank_slip_due_date` * | string | Data de vencimento do boleto (formato YYYY-MM-DD) | 10 |
| `bank_slip_data` * | object | Dados do boleto contendo código de barras e linha digitável | **[Objeto bank_slip_data](#objeto-bank_slip_data)** |
### Objeto bank_slip_data
| Campo | Tipo | Descrição | Caracteres |
|--------------------------|--------|-----------------------------------------------------------------------------------|------------|
| `barcode` * | string | Código de barras do boleto | 44 |
| `digitable_line` * | string | Linha digitável do boleto | 47 |
### Enumeradores wallet_bank_slip_status
| Enumerador | Descrição |
|------------|-----------------------------------------|
| accepted | Boleto aceito, aguardando confirmação do registro |
| registered | Boleto registrado e disponível para pagamento |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (pt-br)
`translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 404 | CIN000007 | Wallet not Found | Wallet with key: abeca0d0-a09d-4b3b-a495-40b553422ced was not found | Carteira com a chave: abeca0d0-a09d-4b3b-a495-40b553422ced não foi encontrado |
| 404 | CIN000093 | Not Found | Wallet bank slip was not found | Boleto da carteira não foi encontrado |
---
# Buscar Fatura por Chave
URL: /documentation/cartao_pos_pago/faturas/fatura/consulta_por_chave
A busca de fatura por chave retornará os detalhes completos de uma fatura específica, incluindo todos os itens da fatura.
## Request
ENDPOINT /wallet/ WALLET_KEY /invoice/ INVOICE_KEY
MÉTODO GET
### Path Parameters
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|----------------------------------------------|------------|
| `wallet_key` | uuidv4 | Chave única da carteira no formato UUID v4 | 36 |
| `invoice_key` | uuidv4 | Chave única da fatura no formato UUID v4 | 36 |
## Response
STATUS 200
Response Body: Detalhes da fatura
```json
{
"invoice_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"due_date": "2024-02-15",
"closing_date": "2024-01-31",
"invoice_status": "opened",
"total_amount": 350.00,
"paid_amount": 0.00,
"invoice_items": [
{
"invoice_item_key": "3571e292-3a83-4011-904d-20ee963022ef",
"invoice_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"wallet_entry_key": null,
"payment_instrument_entry_key": "g3ebe8d6-4c8a-1794-22d9-406c0f8g3dbe",
"installment_number": 1,
"invoice_description": "Compra no estabelecimento XYZ",
"amount": 150.00,
"used_limit": 150.00,
"paid_amount": 0.00,
"invoice_item_status": "concluded",
"invoice_item_due_date": "2024-02-15",
"created_at": "2024-01-15T10:30:00Z"
},
{
"invoice_item_key": "b2c3d4e5-f6g7-8901-bcde-f23456789012",
"invoice_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"wallet_entry_key": null,
"payment_instrument_entry_key": "g3ebe8d6-4c8a-1794-22d9-406c0f8g3dbe",
"installment_number": 2,
"invoice_description": "Parcela 2 de 3 - Compra parcelada",
"amount": 200.00,
"used_limit": 200.00,
"invoice_item_status": "concluded",
"invoice_item_due_date": "2024-02-15",
"created_at": "2024-01-16T14:45:00Z"
}
],
"invoice_payments": [
{
"invoice_payment_key": "c3d4e5f6-g7h8-9012-cdef-345678901234",
"total_amount": 350.00,
"paid_amount": 0.00,
"invoice_payment_type": "bank_slip",
"invoice_payment_status": "paid"
}
],
"invoice_payments_chargebacks": [
{
"invoice_item_key": "3571e292-3a83-4011-904d-20ee963022ef",
"chargeback_paid_amount": 50.00
}
],
"created_at": "2024-01-15T10:30:00Z"
}
```
### Response Body Params
| Campo | Tipo | Descrição | Caracteres |
|------------------|--------------|---------------------------------------|---------------------------------------------|
| `invoice_key` * | uuidv4 | Chave única de identificação da fatura no formato uuid v4 | 36 |
| `due_date` * | string | Data de vencimento da fatura (formato YYYY-MM-DD) | 10 |
| `closing_date` * | string | Data de fechamento da fatura (formato YYYY-MM-DD) | 10 |
| `invoice_status` * | string | Status da fatura | **[Enumeradores invoice_status](#enumeradores-invoice_status)** |
| `total_amount` * | number | Valor total da fatura | - |
| `paid_amount` * | number | Valor pago da fatura | - |
| `invoice_items` * | object array | Itens da fatura | **[Objeto invoice_item](#objeto-invoice_item)** |
| `invoice_payments` * | object array | Pagamentos da fatura | [Objeto invoice_payment](#objeto-invoice_payment) |
| `invoice_payments_chargebacks` * | object array | Estornos dos pagamentos da fatura | [Objeto invoice_payment_chargeback](#objeto-invoice_payment_chargeback) |
| `created_at` * | string | Data de criação (formato ISO 8601 UTC) | - |
### Objeto invoice_item
| Campo | Tipo | Descrição | Caracteres |
|------------------------------------|---------|-----------------------------------------------------------------------------------|------------|
| `invoice_item_key` * | uuidv4 | Chave única de identificação do item da fatura no formato uuid v4 | 36 |
| `invoice_key` * | uuidv4 | Chave única de identificação da fatura no formato uuid v4 | 36 |
| `wallet_entry_key` | uuidv4 | Chave única de identificação da entrada da carteira no formato uuid v4 | 36 |
| `payment_instrument_entry_key` | uuidv4 | Chave única de identificação da entrada do instrumento de pagamento no formato uuid v4 | 36 |
| `installment_number` * | integer | Número da parcela | - |
| `invoice_description` * | string | Descrição do item da fatura | - |
| `amount` * | float | Valor do item | - |
| `used_limit` * | float | Limite utilizado | - |
| `invoice_item_status` * | string | Status do item da fatura | **[Enumeradores invoice_item_status](#enumeradores-invoice_item_status)** |
| `invoice_item_due_date` * | string | Data de vencimento do item (formato YYYY-MM-DD) | 10 |
| `created_at` * | string | Data de criação (formato ISO 8601 UTC) | - |
### Objeto invoice_payment
| Campo | Tipo | Descrição | Caracteres |
|------------------------------------|---------|-----------------------------------------------------------------------------------|------------|
| invoice_payment_key * | uuidv4 | Chave única de identificação do pagamento da fatura no formato uuid v4 | 36 |
| total_amount | number | Valor total do pagamento | - |
| paid_amount | number | Valor pago do pagamento | - |
| invoice_payment_type * | string | Tipo de pagamento da fatura | [Enumeradores invoice_payment_type](#enumeradores-invoice_payment_type) |
| invoice_payment_status * | string | Status do pagamento da fatura | [Enumeradores invoice_payment_status](#enumeradores-invoice_payment_status) |
### Objeto invoice_payment_chargeback
| Campo | Tipo | Descrição | Caracteres |
|------------------------------------|---------|-----------------------------------------------------------------------------------|------------|
| invoice_item_key * | uuidv4 | Chave única de identificação do item da fatura relacionado ao estorno no formato uuid v4 | 36 |
| chargeback_paid_amount | number | Valor do estorno utilizado | - |
### Enumeradores invoice_status
| Enumerador | Descrição |
|------------|-----------------------------------------|
| opened | Fatura aberta |
| processing_closing | Processando fechamento |
| processing_expiration | Processando expiração |
| closed | Fatura fechada |
| processing_payment | Aguardando pagamento |
| paid | Fatura paga |
:::info Observação
O status `processing_payment` é aplicado apenas para carteiras do tipo `payroll` no cenário em que o valor possível para pagamento já foi realizado e está restando o valor a ser pago com o benefício.
:::
### Enumeradores invoice_payment_type
| Enumerador | Descrição |
|------------|-----------------------------------------|
| bank_slip | Boleto bancário |
| payroll_discount | Desconto via INSS |
:::info Observação
O tipo `payroll_discount` existe apenas para carteiras do tipo `payroll` e representa o valor que vai ser descontado via benefício.
:::
### Enumeradores invoice_payment_status
| Enumerador | Descrição |
|------------|-----------------------------------------|
| processing_payment | Aguardando pagamento |
| paid | Pago |
:::info Observação
- Para pagamentos do tipo `payroll_discount`: o pagamento é criado no momento do fechamento da fatura com o status `processing_payment` e o desconto é solicitado no INSS. Quando o pagamento do desconto é realizado, o status muda para `paid`.
- Para pagamentos do tipo `bank_slip`: o pagamento é criado com status `processing_payment` quando recebemos o aviso de pagamento do boleto. No momento da liquidação do boleto, o status muda para `paid`. O pagamento pode ser criado com status `paid` diretamente caso não seja recebido um aviso de pagamento.
:::
### Enumeradores invoice_item_status
| Enumerador | Descrição |
|------------|-----------------------------------------|
| concluded | Item concluído |
| canceled | Item cancelado |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (pt-br)
`translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 404 | CIN000007 | Wallet not Found | Wallet with key: abeca0d0-a09d-4b3b-a495-40b553422ced was not found | Carteira com a chave: abeca0d0-a09d-4b3b-a495-40b553422ced não foi encontrado |
| 404 | CIN000016 | Invoice Not Found | Invoice with key: 8cb70dea-9fb0-4a68-9572-99a72849c8d6 was not found | Fatura com a chave: 8cb70dea-9fb0-4a68-9572-99a72849c8d6 não foi encontrado |
---
# Listar Faturas
URL: /documentation/cartao_pos_pago/faturas/fatura/listar_faturas
A listagem de faturas retornará todas as faturas de uma carteira específica que se enquadrarem nos query parameters enviados na request.
## Request
ENDPOINT /wallet/ WALLET_KEY /invoices
MÉTODO GET
### Path Parameters
| Campo | Tipo | Descrição | Caracteres |
|--------------|--------|----------------------------------------------|------------|
| `wallet_key` | uuidv4 | Chave única da carteira no formato UUID v4 | 36 |
### Query Parameters
| Campo | Tipo | Descrição | Caracteres |
|------------------------------|---------|----------------------------------------------|------------|
| `invoice_status` * | string | Status da fatura | **[Enumeradores invoice_status](#enumeradores-invoice_status)** |
| `page` | integer | Número da página para paginação | - |
| `page_size` | integer | Quantidade de itens por página | - |
:::caution Validações
- **Paginação**: Valores de página e tamanho devem ser inteiros válidos
- **Tamanho da página**: Máximo de 100 itens por página
:::
### Enumeradores invoice_status
| Enumerador | Descrição |
|------------|-----------------------------------------|
| opened | Fatura aberta |
| processing_closing | Processando fechamento |
| processing_expiration | Processando expiração |
| closed | Fatura fechada |
| processing_payment | Aguardando pagamento |
| paid | Fatura paga |
## Response
STATUS 200
Response Body: Lista de faturas
```json
{
"data": [
{
"invoice_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"due_date": "2024-02-15",
"closing_date": "2024-01-31",
"invoice_status": "opened",
"total_amount": 350.00,
"paid_amount": 0.00,
"created_at": "2024-01-15T10:30:00Z"
},
{
"invoice_key": "9db81efb-0ac1-5b79-0683-00b8395a9e7",
"due_date": "2024-01-15",
"closing_date": "2023-12-31",
"invoice_status": "opened",
"total_amount": 500.00,
"paid_amount": 0.00,
"created_at": "2024-01-14T14:45:00Z"
}
],
"pagination": {
"current_page": 1,
"rows_per_page": 100
}
}
```
### Response Body Params
| Campo | Tipo | Descrição | Caracteres |
|------------------|--------------|---------------------------------------|---------------------------------------------|
| `data` * | object array | Faturas | **[Objeto invoice](#objeto-invoice)** |
| `pagination` * | object | Informações de paginação | **[Objeto pagination](#objeto-pagination)** |
### Objeto invoice
| Campo | Tipo | Descrição | Caracteres |
|------------------------------|---------|-----------------------------------------------------------------------------------|------------|
| `invoice_key` * | uuidv4 | Chave única de identificação da fatura no formato uuid v4 | 36 |
| `due_date` * | string | Data de vencimento da fatura (formato YYYY-MM-DD) | 10 |
| `closing_date` * | string | Data de fechamento da fatura (formato YYYY-MM-DD) | 10 |
| `invoice_status` * | string | Status da fatura | **[Enumeradores invoice_status](#enumeradores-invoice_status)** |
| `total_amount` * | number | Valor total da fatura | - |
| `paid_amount` * | number | Valor pago da fatura | - |
| `created_at` * | string | Data de criação (formato ISO 8601 UTC) | - |
### Objeto pagination
| Campo | Tipo | Descrição | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `current_page` * | integer | Página atual | - |
| `rows_per_page` * | integer | Itens por página | - |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (pt-br)
`translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | CIN000069 | Bad Request | Invalid integer value for page or size query string parameters | Valor inválido para parâmetros de página ou tamanho de página |
| 400 | CIN000079 | Bad Request | Invalid query invoice status | Status de consulta de fatura inválido |
| 404 | CIN000007 | Wallet not Found | Wallet with key: abeca0d0-a09d-4b3b-a495-40b553422ced was not found | Carteira com a chave: abeca0d0-a09d-4b3b-a495-40b553422ced não foi encontrado |
---
# Simulação de cenários - Fechamento e Vencimento de Faturas
URL: /documentation/cartao_pos_pago/faturas/fatura/simulacao_de_cenarios
Esta página descreve como simular o fechamento e vencimento de faturas para testar o fluxo de transações com cartões pós-pagos. Essas simulações são úteis para homologação e testes de integração.
## 1 - Simulação de fechamento de fatura
Simula o fechamento de uma fatura aberta, alterando seu status para `processing_closing` e publicando a mensagem na fila de fechamento. A fatura será processada conforme a configuração da carteira.
ENDPOINT /mock/invoice/ INVOICE_KEY /close
MÉTODO PATCH
### Path Parameters
| Campo | Tipo | Descrição | Caracteres |
|------------------------------|--------|----------------------------------------------|------------|
| `invoice_key` * | string | Chave única da fatura no formato UUID v4 | 36 |
### Headers
### Request Body
Esta requisição não possui body.
### Response
STATUS 204
Response Body
```json
{}
```
### Response Body Params
Esta resposta não possui parâmetros no body.
:::tip Comportamento
- A simulação altera o status da fatura para `processing_closing`
- A fatura deve estar com status `opened` para poder ser fechada
- Uma notificação de mudança de status é enviada ao cliente
:::
## 2 - Simulação de vencimento de fatura
Simula o vencimento de uma fatura fechada, alterando seu status para `processing_expiration` e publicando a mensagem na fila de vencimento. A fatura será processada conforme a configuração da carteira.
ENDPOINT /mock/invoice/ INVOICE_KEY /expire
MÉTODO PATCH
### Path Parameters
| Campo | Tipo | Descrição | Caracteres |
|------------------------------|--------|----------------------------------------------|------------|
| `invoice_key` * | string | Chave única da fatura no formato UUID v4 | 36 |
### Request Body
Esta requisição não possui body.
### Response
STATUS 204
Response Body
```json
{}
```
### Response Body Params
Esta resposta não possui parâmetros no body.
:::tip Comportamento
- A simulação altera o status da fatura para `processing_expiration`
- A fatura não pode estar com status `opened` (deve estar fechada)
- A carteira deve ter pelo menos uma fatura aberta
- A próxima data de fechamento da carteira não pode ser anterior à próxima data de vencimento
- Uma notificação de mudança de status é enviada ao cliente
:::
---
# Alteração de Limite de Instrumento de Pagamento
URL: /documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/alteracao_de_limite
A alteração de limite de instrumento de pagamento permite alterar o valor do limite de um instrumento de pagamento existente.
## Request
ENDPOINT /wallet/ WALLET_KEY /payment_instrument/ PAYMENT_INSTRUMENT_KEY
MÉTODO PATCH
### Path Parameters
| Campo | Tipo | Descrição | Caracteres |
|------------------------------|--------|----------------------------------------------|------------|
| `wallet_key` * | uuidv4 | Chave única da carteira no formato UUID v4 | 36 |
| `payment_instrument_key` * | uuidv4 | Chave única do instrumento de pagamento no formato UUID v4 | 36 |
Request Body
```json
{
"limit_amount": 3000.00
}
```
### Request Body Params
| Campo | Tipo | Descrição | Caracteres |
|------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `limit_amount` * | float | Novo valor do limite do instrumento de pagamento | - |
:::info Observação
- O novo valor do limite deve ser maior ou igual ao limite utilizado (`used_limit`)
- O novo valor do limite não pode ser maior que o limite de crédito pós-pago da carteira (`postpaid_credit_limit`)
- Apenas instrumentos de pagamento do tipo `postpaid_card` podem ter seus limites atualizados
- Apenas carteiras do tipo `default` podem ter instrumentos de pagamento com limites atualizados
- O instrumento de pagamento deve estar com status `active` para ter seu limite atualizado
:::
## Response
STATUS 200
Response Body: Limite de instrumento de pagamento atualizado
```json
{
"payment_instrument_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"limit_amount": 3000.00,
"payment_instrument_status": "active"
}
```
### Response Body Params
| Campo | Tipo | Descrição | Caracteres |
|----------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `payment_instrument_key` * | uuidv4 | Chave única de identificação do instrumento atualizado no formato UUID v4 | 36 |
| `limit_amount` * | float | Novo valor do limite do instrumento após a atualização | - |
| `payment_instrument_status` * | string | Status do instrumento de pagamento | **[Enumeradores payment_instrument_status](#enumeradores-payment_instrument_status)** |
### Enumeradores payment_instrument_status
| Enumerador | Descrição |
|------------|-----------------------------------------|
| active | Instrumento ativo |
| canceled | Instrumento cancelado |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (pt-br)
`translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | CIN000074 | Bad Request | Limit amount is greater than postpaid credit limit of the wallet. | Limite é maior que o limite de crédito pós-pago da carteira. |
| 400 | CIN000081 | Bad Request | Payment instrument is not active | Instrumento de pagamento não está ativo |
| 400 | CIN000110 | Bad Request | New limit amount is less than used limit | Novo valor do limite é menor que o valor utilizado |
| 403 | CIN000108 | Forbidden | Wallet type payroll is not allowed for this operation | Tipo de carteira payroll não é permitido para esta operação |
| 403 | CIN000113 | Forbidden | Payment instrument type is not allowed for this operation | Tipo de instrumento de pagamento não é permitido para esta operação |
| 404 | CIN000007 | Wallet not Found | Wallet with key: e503fa60-285e-4632-96b6-bf3ad908a23c was not found | Carteira com a chave: e503fa60-285e-4632-96b6-bf3ad908a23c não foi encontrado |
| 404 | CIN000080 | Payment Instrument Not Found | Payment instrument was not found | Instrumento de pagamento não foi encontrado |
---
# Cancelamento de Instrumento de Pagamento
URL: /documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/cancelamento_de_instrumento_de_pagamento
O cancelamento de instrumento de pagamento permite cancelar um instrumento de pagamento existente, alterando seu status para `canceled` e cancelando o cartão pós-pago associado.
## Request
ENDPOINT /wallet/ WALLET_KEY /payment_instrument/ PAYMENT_INSTRUMENT_KEY /cancel
MÉTODO PATCH
### Path Parameters
| Campo | Tipo | Descrição | Caracteres |
|------------------------------|--------|----------------------------------------------|------------|
| `wallet_key` * | uuidv4 | Chave única da carteira no formato UUID v4 | 36 |
| `payment_instrument_key` * | uuidv4 | Chave única do instrumento de pagamento no formato UUID v4 | 36 |
:::info Observação
Esta requisição não possui request body. O cancelamento é realizado apenas através dos path parameters.
:::
## Response
STATUS 200
Response Body: Instrumento de pagamento cancelado
```json
{
"payment_instrument_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"payment_instrument_status": "canceled"
}
```
### Response Body Params
| Campo | Tipo | Descrição | Caracteres |
|----------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `payment_instrument_key` * | uuidv4 | Chave única de identificação do instrumento cancelado no formato UUID v4 | 36 |
| `payment_instrument_status` * | string | Status do instrumento após o cancelamento | **[Enumeradores payment_instrument_status](#enumeradores-payment_instrument_status)** |
### Enumeradores payment_instrument_status
| Enumerador | Descrição |
|------------|-----------------------------------------|
| canceled | Instrumento cancelado |
:::tip Comportamento
- O instrumento de pagamento será movido para o status `canceled` após o cancelamento
- O cartão pós-pago associado ao instrumento também será cancelado automaticamente
- O instrumento cancelado não poderá ser utilizado para novas transações
- O instrumento cancelado ainda poderá ser consultado e listado, mas aparecerá com status `canceled`
:::
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (pt-br)
`translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | CIN000081 | Bad Request | Payment instrument is not active | Instrumento de pagamento não está ativo |
| 400 | CIN000100 | Bad Request | Error canceling card in card service | Erro ao cancelar cartão no serviço de cartões |
| 404 | CIN000007 | Wallet not Found | Wallet with key: abeca0d0-a09d-4b3b-a495-40b553422ced was not found | Carteira com a chave: abeca0d0-a09d-4b3b-a495-40b553422ced não foi encontrado |
| 404 | CIN000080 | Payment Instrument Not Found | Payment instrument was not found | Instrumento de pagamento não foi encontrado |
---
# Buscar Entrada de Instrumento de Pagamento por Chave
URL: /documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/consulta_entrada_por_chave
A busca de entrada de instrumento de pagamento por chave retornará os detalhes completos de uma entrada específica, incluindo todos os itens da fatura relacionados.
## Request
ENDPOINT /wallet/ WALLET_KEY /payment_instrument/ PAYMENT_INSTRUMENT_KEY /payment_instrument_entry/ PAYMENT_INSTRUMENT_ENTRY_KEY
MÉTODO GET
### Path Parameters
| Campo | Tipo | Descrição | Caracteres |
|--------------------------------|--------|----------------------------------------------|------------|
| `wallet_key` | uuidv4 | Chave única da carteira no formato UUID v4 | 36 |
| `payment_instrument_key` | uuidv4 | Chave única do instrumento de pagamento no formato UUID v4 | 36 |
| `payment_instrument_entry_key` | uuidv4 | Chave única da entrada no formato UUID v4 | 36 |
## Response
STATUS 200
Response Body: Detalhes da entrada de instrumento de pagamento
```json
{
"payment_instrument_entry_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"payment_instrument_entry_amount": 150.00,
"payment_instrument_entry_type": "purchase",
"payment_instrument_entry_status": "concluded",
"payment_instrument_entry_data": {
"merchant_name": "Merchant Name",
"merchant_country": "Merchant Country",
"merchant_postal_code": "Merchant Postal Code",
"merchant_city": "Merchant City",
"merchant_street": "Merchant Street"
},
"invoice_items": [
{
"invoice_item_key": "3571e292-3a83-4011-904d-20ee963022ef",
"invoice_key": "f2cad6b4-2a68-9572-99a7-2849c8d6ecf8",
"wallet_entry_key": null,
"payment_instrument_entry_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"installment_number": 1,
"invoice_description": "Compra no estabelecimento XYZ",
"amount": 150.00,
"used_limit": 150.00,
"invoice_item_status": "concluded",
"invoice_item_due_date": "2024-02-15",
"created_at": "2024-01-15T10:30:00Z"
}
],
"created_at": "2024-01-15T10:30:00Z"
}
```
### Response Body Params
| Campo | Tipo | Descrição | Caracteres |
|---------------------------------------|--------------|---------------------------------------|---------------------------------------------|
| `payment_instrument_entry_key` * | uuidv4 | Chave única de identificação da entrada no formato uuid v4 | 36 |
| `payment_instrument_entry_amount` * | number | Valor da entrada | - |
| `payment_instrument_entry_type` * | string | Tipo da entrada do instrumento de pagamento | **[Enumeradores payment_instrument_entry_type](#enumeradores-payment_instrument_entry_type)** |
| `payment_instrument_entry_status` * | string | Status da entrada do instrumento | **[Enumeradores payment_instrument_entry_status](#enumeradores-payment_instrument_entry_status)** |
| `invoice_items` * | object array | Itens da fatura relacionados | **[Objeto invoice_item](#objeto-invoice_item)** |
| `payment_instrument_entry_data` | object | Dados do adicionais | **[Objeto payment_instrument_entry_data](#objeto-payment_instrument_entry_data)** |
| `created_at` * | string | Data de criação (formato ISO 8601 UTC) | - |
### Objeto payment_instrument_entry_data (purchase | withdraw)
| Campo | Tipo | Descrição | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `merchant_name` * | string | Nome do estabelecimento comercial | - |
| `merchant_country` * | string | País do estabelecimento comercial | - |
| `merchant_postal_code` * | string | Código postal do estabelecimento comercial | - |
| `merchant_city` * | string | Cidade do estabelecimento comercial | - |
| `merchant_street` * | string | Rua do estabelecimento comercial | - |
### Objeto payment_instrument_entry_data (postpaid_card_issuance)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `postpaid_card_issuance_name` * | string | Nome da emissão do cartão pós-pago | - |
| `payment_instrument_key` * | string | Chave única do instrumento de pagamento no formato UUID v4 | 36 |
| `postpaid_card_key` * | string | Chave única do cartão pós-pago no formato UUID v4 | 36 |
:::info Observação
Esta entrada existe apenas para cartões de carteira de cartão consignado.
:::
### Enumeradores payment_instrument_entry_type
| Enumerador | Descrição |
|-------------------------|-----------------------------------------------------------------------------------|
| purchase | Compra |
| withdraw | Saque |
| postpaid_card_issuance | Emissão de cartão pós-pago |
### Enumeradores payment_instrument_entry_status
| Enumerador | Descrição |
|-------------------------|-----------------------------------------|
| processing_conclusion | Entrada em processamento de conclusão |
| processing_cancellation | Entrada em processamento de cancelamento |
| concluded | Entrada concluída |
| canceled | Entrada cancelada |
:::info Observação
A entrada do instrumento de pagamento pode transicionar diretamente de `processing_conclusion` para `processing_cancellation` e `canceled`. Nesse caso, nenhum invoice item é criado.
:::
### Objeto invoice_item
| Campo | Tipo | Descrição | Caracteres |
|------------------------------------|---------|-----------------------------------------------------------------------------------|------------|
| `invoice_item_key` * | uuidv4 | Chave única de identificação do item da fatura no formato uuid v4 | 36 |
| `invoice_key` * | uuidv4 | Chave única de identificação da fatura no formato uuid v4 | 36 |
| `wallet_entry_key` | uuidv4 | Chave única de identificação da entrada da carteira no formato uuid v4 | 36 |
| `payment_instrument_entry_key` | uuidv4 | Chave única de identificação da entrada do instrumento de pagamento no formato uuid v4 | 36 |
| `installment_number` * | integer | Número da parcela | - |
| `invoice_description` * | string | Descrição do item da fatura | - |
| `amount` * | number | Valor do item | - |
| `used_limit` * | number | Limite utilizado | - |
| `invoice_item_status` * | string | Status do item da fatura | **[Enumeradores invoice_item_status](#enumeradores-invoice_item_status)** |
| `invoice_item_due_date` * | string | Data de vencimento do item (formato YYYY-MM-DD) | 10 |
| `created_at` * | string | Data de criação (formato ISO 8601 UTC) | - |
### Enumeradores invoice_item_status
| Enumerador | Descrição |
|------------|-----------------------------------------|
| concluded | Item concluído (fatura ao qual o mesmo pertence não foi paga) |
| canceled | Item cancelado |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (pt-br)
`translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 404 | CIN000007 | Wallet not Found | Wallet with key: abeca0d0-a09d-4b3b-a495-40b553422ced was not found | Carteira com a chave: abeca0d0-a09d-4b3b-a495-40b553422ced não foi encontrado |
| 404 | CIN000017 | Payment Instrument Not Found | Payment instrument was not found | Instrumento de pagamento não foi encontrado |
| 404 | CIN000086 | Not Found | Payment instrument entry was not found | Transação para instrumento de pagamento não foi encontrada |
---
# Criação de Instrumento de Pagamento
URL: /documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/criacao_de_instrumento_de_pagamento
A criação de instrumento de pagamento permite registrar um novo meio de pagamento (como cartão pós-pago) para uma carteira existente.
## Request
ENDPOINT /wallet/ WALLET_KEY /payment_instrument
MÉTODO POST
### Path Parameters
| Campo | Tipo | Descrição | Caracteres |
|--------------|--------|----------------------------------------------|------------|
| `wallet_key` | uuidv4 | Chave única da carteira no formato UUID v4 | 36 |
Request Body
```json
{
"request_control_key": "f7947b9d-9be3-49d8-aca2-4b3249e5fa65",
"owner": {
"person_type": "natural",
"name": "João Silva",
"document_number": "12345678901",
"birthdate": "1990-01-01",
"email": "joao.silva@email.com",
"phone": {
"number": "99999999",
"area_code": "11",
"country_code": "55"
},
"address": {
"street": "Rua das Flores",
"number": "123",
"neighborhood": "Centro",
"postal_code": "01234567",
"city": "São Paulo",
"state": "SP",
"complement": "Apto 1"
}
},
"payment_instrument_type": "postpaid_card",
"limit_amount": 2000.00,
"postpaid_card_data": {
"card_type": "physical",
"card_name": "Cartão Principal",
"printed_name": "JOAO SILVA",
"cvv_rotation_interval_hours": 24,
"contactless_enabled": true,
"delivery_address": {
"street": "Rua das Flores",
"number": "123",
"neighborhood": "Centro",
"postal_code": "01234567",
"city": "São Paulo",
"state": "SP",
"complement": "Apto 1"
}
}
}
```
### Request Body Params
| Campo | Tipo | Descrição | Caracteres |
|------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `request_control_key` | uuidv4 | Chave única de identificação da request utilizada pelo cliente. | 36 |
| `owner` | object | Dados do proprietário do instrumento (pessoa física ou jurídica) | **[Objeto owner](#objeto-owner)** |
| `person_key` | string | Chave única de identificação da pessoa no formato UUID v4 | 36 |
| `payment_instrument_type` * | string | Tipo do instrumento de pagamento | **[Enumeradores payment_instrument_type](#enumeradores-payment_instrument_type)** |
| `limit_amount` | float | Limite de crédito do instrumento (deve ser menor ou igual ao limite da carteira) | - |
| `postpaid_card_data` | object | Dados específicos do cartão pós-pago | **[Objeto postpaid_card_data](#objeto-postpaid_card_data)** |
:::info Campos Condicionais
- **`owner`**: Obrigatório quando não for enviado `person_key`
- **`person_key`**: Obrigatório quando não for enviado `owner`
- **`postpaid_card_data`**: Obrigatório quando `payment_instrument_type` for "postpaid_card"
- Os campos `owner` e `person_key` são mutuamente exclusivos
:::
:::caution Validações de Limite
- O `limit_amount` **não é obrigatório**
- Quando informado, não pode ser maior que o limite de crédito pós-pago da carteira
- Se não informado, o instrumento utilizará o limite total da carteira
:::
### Objeto owner
#### Pessoa Física (`person_type: "natural"`)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|--------|----------------------------------------------|------------|
| `person_type` * | string | Tipo da pessoa (deve ser "natural") | - |
| `name` * | string | Nome completo da pessoa | 100 |
| `document_number` * | string | CPF da pessoa (apenas números) | 11 |
| `birthdate` * | string | Data de nascimento (formato YYYY-MM-DD) | 10 |
| `email` * | string | E-mail de contato | 254 |
| `phone` * | object | Telefone de contato | **[Objeto phone](#objeto-phone)** |
| `address` * | object | Endereço completo | **[Objeto address](#objeto-address)** |
#### Pessoa Jurídica (`person_type: "legal"`)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|--------|----------------------------------------------|------------|
| `person_type` * | string | Tipo da pessoa (deve ser "legal") | - |
| `name` * | string | Razão social da empresa | 100 |
| `trading_name` * | string | Nome fantasia da empresa | 100 |
| `document_number` * | string | CNPJ da empresa (apenas números) | 14 |
| `foundation_date` * | string | Data de fundação (formato YYYY-MM-DD) | 10 |
| `email` * | string | E-mail de contato | 254 |
| `phone` * | object | Telefone de contato | **[Objeto phone](#objeto-phone)** |
| `address` * | object | Endereço completo | **[Objeto address](#objeto-address)** |
| `legal_representatives` * | array | Lista de representantes legais (pessoas físicas) | - |
### Objeto phone
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|--------|----------------------------------------------|------------|
| `country_code` * | string | Código do país (DDI) | 2-3 |
| `area_code` * | string | Código de área (DDD) | 2 |
| `number` * | string | Número do telefone | 8-9 |
### Objeto address
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|--------|----------------------------------------------|------------|
| `street` * | string | Nome da rua/avenida | 500 |
| `number` * | string | Número do endereço | 10 |
| `neighborhood` * | string | Bairro | 100 |
| `postal_code` * | string | CEP (apenas números) | 8 |
| `city` * | string | Cidade | 100 |
| `state` * | string | Estado (UF) | **[Enumeradores state](#enumeradores-state)** |
| `complement` | string | Complemento do endereço | 500 |
### Enumeradores state
| Enumerador | Descrição |
|-------------|----------------|
| AC | Acre |
| AL | Alagoas |
| AM | Amazonas |
| AP | Amapá |
| BA | Bahia |
| CE | Ceará |
| DF | Distrito Federal |
| ES | Espírito Santo |
| GO | Goiás |
| MA | Maranhão |
| MG | Minas Gerais |
| MS | Mato Grosso do Sul |
| MT | Mato Grosso |
| PA | Pará |
| PB | Paraíba |
| PE | Pernambuco |
| PI | Piauí |
| PR | Paraná |
| RJ | Rio de Janeiro |
| RN | Rio Grande do Norte |
| RO | Rondônia |
| RR | Roraima |
| RS | Rio Grande do Sul |
| SC | Santa Catarina |
| SE | Sergipe |
| SP | São Paulo |
| TO | Tocantins |
| EX | Exceção |
### Enumeradores payment_instrument_type
| Enumerador | Descrição |
|-----------------|------------------|
| postpaid_card | Cartão pós-pago |
### Objeto postpaid_card_data
| Campo | Tipo | Descrição | Caracteres |
|---------------------------------|---------|----------------------------------------------|------------|
| `card_type` * | string | Tipo do cartão | **[Enumeradores card_type](#enumeradores-card_type)** |
| `card_name` * | string | Nome do cartão | 1-50 |
| `printed_name` * | string | Nome impresso no cartão | 2-26 |
| `cvv_rotation_interval_hours` | int | Intervalo de rotação do CVV em horas | - |
| `contactless_enabled` | boolean | Habilita pagamento por aproximação | - |
| `delivery_address` | object | Endereço de entrega do cartão | **[Objeto delivery_address](#objeto-delivery_address)** |
### Enumeradores card_type
| Enumerador | Descrição |
|-------------|------------------|
| virtual | Cartão virtual |
| plastic | Cartão plástico |
:::info Campos Condicionais
- **`cvv_rotation_interval_hours`**: Obrigatório para `card_type: "virtual"`. Não permitido para `card_type: "plastic"`.
- **`delivery_address`**: Não permitido para `card_type: "virtual"`. Opcional para `card_type: "plastic"`, se não informado será usado o endereço do `owner` ou o previamente cadastrado para a `person_key` informada
- **`contactless_enabled`**: Não permitido para `card_type: "virtual"`, obrigatório para `card_type: "plastic"`
:::
### Objeto delivery_address
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|--------|----------------------------------------------|------------|
| `street` * | string | Nome da rua/avenida | 500 |
| `number` * | string | Número do endereço | 10 |
| `neighborhood` * | string | Bairro | 100 |
| `postal_code` * | string | CEP (apenas números) | 8 |
| `city` * | string | Cidade | 100 |
| `state` * | string | Estado (UF) | **[Enumeradores state](#enumeradores-state)** |
| `complement` | string | Complemento do endereço | 500 |
## Response
### Sucesso - Instrumento Criado
STATUS 201
Response Body: Instrumento criado
```json
{
"request_control_key": "f7947b9d-9be3-49d8-aca2-4b3249e5fa65",
"payment_instrument_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"postpaid_card_key": "ecf87b4b-fa6e-49c0-a7f0-f2cad6b42d79",
"owner_person_key": "f2cad6b4-2a68-9572-99a7-2849c8d6ecf8"
}
```
### Response Body Params
| Campo | Tipo | Descrição | Caracteres |
|------------------------------|---------|-----------------------------------------------------------------------------------|------------|
| `request_control_key` | uuidv4 | Chave única de identificação da request utilizada pelo cliente. | 36 |
| `payment_instrument_key` * | uuidv4 | Chave única de identificação do instrumento no formato uuid v4 | 36 |
| `postpaid_card_key` * | uuidv4 | Chave única de identificação do cartão pós-pago no formato uuid v4 | 36 |
| `owner_person_key` * | uuidv4 | Chave única de identificação do proprietário no formato uuid v4 | 36 |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (pt-br)
`translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | CIN000062 | Not Found | Person not found by person key: e51070e4-7494-468d-a20e-bf14789fa8ff | Pessoa não encontrada para a person key: e51070e4-7494-468d-a20e-bf14789fa8ff |
| 404 | CIN000007 | Wallet not Found | Wallet with key: abeca0d0-a09d-4b3b-a495-40b553422ced was not found | Carteira com a chave: abeca0d0-a09d-4b3b-a495-40b553422ced não foi encontrado |
| 400 | CIN000073 | Bad Request | Limit amount is greater than postpaid credit limit of the wallet | Limite é maior que o limite de crédito pós-pago da carteira |
| 400 | CIN000074 | Bad Request | Limit amount is greater than ccb limit of the wallet | Limite é maior que o limite de ccb da carteira |
| 400 | CIN000072 | Bad Request | Error while creating postpaid card in card service, try again in a few minutes | Erro ao criar postpaid card no serviço de cartão, tente novamente em alguns minutos |
| 400 | CIN000067 | Bad Request | Error while creating owner of the wallet. Try again in a few minutes | Erro ao criar owner da carteira. Tente novamente em alguns minutos |
| 409 | CIN000099 | Conflict | Request control key already exists. | Request control key já existe. |
---
# Listar Entradas de Instrumentos de Pagamento
URL: /documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/listar_entradas_do_instrumento_de_pagamento
A listagem de entradas de instrumentos de pagamento retornará todas as entradas de um instrumento de pagamento específico que se enquadrarem nos query parameters enviados na request.
## Request
ENDPOINT /wallet/ WALLET_KEY /payment_instrument/ PAYMENT_INSTRUMENT_KEY /payment_instrument_entries
MÉTODO GET
### Path Parameters
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|--------|----------------------------------------------|------------|
| `wallet_key` | uuidv4 | Chave única da carteira no formato UUID v4 | 36 |
| `payment_instrument_key` | uuidv4 | Chave única do instrumento de pagamento no formato UUID v4 | 36 |
### Query Parameters
| Campo | Tipo | Descrição | Caracteres |
|---------------------------------------|---------|----------------------------------------------|------------|
| `payment_instrument_entry_type` * | string | Tipo da entrada do instrumento de pagamento | **[Enumeradores payment_instrument_entry_type](#enumeradores-payment_instrument_entry_type)** |
| `payment_instrument_entry_status` * | string | Status da entrada do instrumento | **[Enumeradores payment_instrument_entry_status](#enumeradores-payment_instrument_entry_status)** |
| `page` | integer | Número da página para paginação | - |
| `page_size` | integer | Quantidade de itens por página | - |
:::caution Validações
- **Paginação**: Valores de página e tamanho devem ser inteiros válidos
- **Tamanho da página**: Máximo de 100 itens por página
:::
### Enumeradores payment_instrument_entry_type
| Enumerador | Descrição |
|-------------------------|-----------------------------------------------------------------------------------|
| purchase | Compra |
| withdraw | Saque |
| postpaid_card_issuance | Emissão de cartão pós-pago |
### Enumeradores payment_instrument_entry_status
| Enumerador | Descrição |
|-------------------------|-----------------------------------------|
| processing_conclusion | Entrada em processamento de conclusão |
| processing_cancellation | Entrada em processamento de cancelamento |
| concluded | Entrada concluída |
| canceled | Entrada cancelada |
:::info Observação
A entrada do instrumento de pagamento pode transicionar diretamente de `processing_conclusion` para `processing_cancellation` e `canceled`. Nesse caso, nenhum invoice item é criado.
:::
## Response
STATUS 200
Response Body: Lista de entradas de instrumentos de pagamento
```json
{
"data": [
{
"payment_instrument_entry_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"payment_instrument_entry_amount": 150.00,
"payment_instrument_entry_type": "purchase",
"payment_instrument_entry_status": "concluded",
"payment_instrument_entry_data": {
"merchant_name": "Merchant Name",
"merchant_country": "Merchant Country",
"merchant_postal_code": "Merchant Postal Code",
"merchant_city": "Merchant City",
"merchant_street": "Merchant Street"
},
"created_at": "2024-01-15T10:30:00Z"
},
{
"payment_instrument_entry_key": "9db81efb-0ac1-5b79-0683-00b8395a9e7",
"payment_instrument_entry_amount": 200.00,
"payment_instrument_entry_type": "withdraw",
"payment_instrument_entry_status": "canceled",
"payment_instrument_entry_data": {
"merchant_name": "Merchant Name",
"merchant_country": "Merchant Country",
"merchant_postal_code": "Merchant Postal Code",
"merchant_city": "Merchant City",
"merchant_street": "Merchant Street"
},
"created_at": "2024-01-14T14:45:00Z"
}
],
"pagination": {
"current_page": 1,
"rows_per_page": 100
}
}
```
### Response Body Params
| Campo | Tipo | Descrição | Caracteres |
|------------------|--------------|---------------------------------------|---------------------------------------------|
| `data` * | object array | Entradas de instrumentos de pagamento | **[Objeto payment_instrument_entry](#objeto-payment_instrument_entry)** |
| `pagination` * | object | Informações de paginação | **[Objeto pagination](#objeto-pagination)** |
### Objeto payment_instrument_entry
| Campo | Tipo | Descrição | Caracteres |
|---------------------------------------|---------|-----------------------------------------------------------------------------------|------------|
| `payment_instrument_entry_key` * | uuidv4 | Chave única de identificação da entrada no formato uuid v4 | 36 |
| `payment_instrument_entry_amount` * | float | Valor da entrada | - |
| `payment_instrument_entry_type` * | string | Tipo da entrada do instrumento de pagamento | **[Enumeradores payment_instrument_entry_type](#enumeradores-payment_instrument_entry_type)** |
| `payment_instrument_entry_status` * | string | Status da entrada do instrumento | **[Enumeradores payment_instrument_entry_status](#enumeradores-payment_instrument_entry_status)** |
| `payment_instrument_entry_data` | object | Dados do adicionais | **[Objeto payment_instrument_entry_data](#objeto-payment_instrument_entry_data)** |
| `created_at` * | string | Data de criação (formato ISO 8601 UTC) | - |
### Objeto payment_instrument_entry_data (purchase | withdraw)
| Campo | Tipo | Descrição | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `merchant_name` * | string | Nome do estabelecimento comercial | - |
| `merchant_country` * | string | País do estabelecimento comercial | - |
| `merchant_postal_code` * | string | Código postal do estabelecimento comercial | - |
| `merchant_city` * | string | Cidade do estabelecimento comercial | - |
| `merchant_street` * | string | Rua do estabelecimento comercial | - |
### Objeto payment_instrument_entry_data (postpaid_card_issuance)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `postpaid_card_issuance_name` * | string | Nome da emissão do cartão pós-pago | - |
| `payment_instrument_key` * | string | Chave única do instrumento de pagamento no formato UUID v4 | 36 |
| `postpaid_card_key` * | string | Chave única do cartão pós-pago no formato UUID v4 | 36 |
:::info Observação
Esta entrada existe apenas para cartões de carteira de cartão consignado.
:::
### Objeto pagination
| Campo | Tipo | Descrição | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `current_page` * | integer | Página atual | - |
| `rows_per_page` * | integer | Itens por página | - |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (pt-br)
`translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | CIN000069 | Bad Request | Invalid integer value for page or size query string parameters | Valor inválido para parâmetros de página ou tamanho de página |
| 400 | CIN000084 | Bad Request | Invalid query payment instrument entry status | Status de consulta de instrumento de pagamento inválido |
| 400 | CIN000085 | Bad Request | Invalid query payment instrument entry type | Tipo de consulta de instrumento de pagamento inválido |
| 404 | CIN000007 | Wallet not Found | Wallet with key: abeca0d0-a09d-4b3b-a495-40b553422ced was not found | Carteira com a chave: abeca0d0-a09d-4b3b-a495-40b553422ced não foi encontrado |
| 404 | CIN000017 | Payment Instrument Not Found | Payment instrument was not found | Instrumento de pagamento não foi encontrado |
---
# Listar Instrumentos de Pagamento
URL: /documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/listar_instrumentos_de_pagamento
A listagem de instrumentos de pagamento retornará todos os instrumentos de pagamento de uma carteira específica que se enquadrarem nos query parameters enviados na request.
## Request
ENDPOINT /wallet/ WALLET_KEY /payment_instruments
MÉTODO GET
### Path Parameters
| Campo | Tipo | Descrição | Caracteres |
|--------------|--------|----------------------------------------------|------------|
| `wallet_key` | uuidv4 | Chave única da carteira no formato UUID v4 | 36 |
### Query Parameters
| Campo | Tipo | Descrição | Caracteres |
|------------------------------|---------|----------------------------------------------|------------|
| `owner_document_number` | string | CPF/CNPJ do proprietário do instrumento | 11-14 |
| `payment_instrument_type` * | string | Tipo do instrumento de pagamento | **[Enumeradores payment_instrument_type](#enumeradores-payment_instrument_type)** |
| `payment_instrument_status` *| string | Status do instrumento | **[Enumeradores payment_instrument_status](#enumeradores-payment_instrument_status)** |
| `page` | integer | Número da página para paginação | - |
| `page_size` | integer | Quantidade de itens por página | - |
:::caution Validações
- **Paginação**: Valores de página e tamanho devem ser inteiros válidos
- **Tamanho da página**: Máximo de 100 itens por página
:::
### Enumeradores payment_instrument_type
| Enumerador | Descrição |
|-----------------|------------------|
| postpaid_card | Cartão pós-pago |
### Enumeradores payment_instrument_status
| Enumerador | Descrição |
|------------|-----------------------------------------|
| active | Instrumento ativo e disponível para uso |
| rejected | Instrumento rejeitado |
| canceled | Instrumento cancelado |
## Response
STATUS 200
Response Body: Lista de instrumentos de pagamento
```json
{
"data": [
{
"request_control_key": "f7947b9d-9be3-49d8-aca2-4b3249e5fa65",
"payment_instrument_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"postpaid_card_key": "ecf87b4b-fa6e-49c0-a7f0-f2cad6b42d79",
"owner_person_key": "f2cad6b4-2a68-9572-99a7-2849c8d6ecf8",
"owner_document_number": "12345678901",
"payment_instrument_type": "postpaid_card",
"payment_instrument_status": "active",
"limit_amount": 2000.00,
"used_limit": 500.00,
"created_at": "2024-01-15T10:30:00Z"
},
{
"request_control_key": "3aaad5ea-3a0f-4018-93a8-ab02f5207833",
"payment_instrument_key": "9db81efb-0ac1-5b79-0683-00b8395a9e7",
"postpaid_card_key": "f3dad7c5-3b79-0683-11c8-395b9e7f2cad",
"owner_person_key": "g4ebe8d6-4c8a-1794-22d9-406c0f8g3dbe",
"owner_document_number": "98765432100",
"payment_instrument_type": "postpaid_card",
"payment_instrument_status": "canceled",
"limit_amount": 1500.00,
"used_limit": 0.00,
"created_at": "2024-01-14T14:45:00Z"
}
],
"pagination": {
"current_page": 1,
"rows_per_page": 100,
}
}
```
### Response Body Params
| Campo | Tipo | Descrição | Caracteres |
|------------------|--------------|---------------------------------------|---------------------------------------------|
| `data` * | object array | Instrumentos de pagamento | **[Objeto payment_instrument](#objeto-payment_instrument)** |
| `pagination` * | object | Informações de paginação | **[Objeto pagination](#objeto-pagination)** |
### Objeto payment_instrument
| Campo | Tipo | Descrição | Caracteres |
|------------------------------|---------|-----------------------------------------------------------------------------------|------------|
| `request_control_key` | uuidv4 | Chave única de identificação da request utilizada pelo cliente. | 36 |
| `payment_instrument_key` * | uuidv4 | Chave única de identificação do instrumento no formato uuid v4 | 36 |
| `postpaid_card_key` * | uuidv4 | Chave única de identificação do cartão pós-pago no formato uuid v4 | 36 |
| `owner_person_key` * | uuidv4 | Chave única de identificação do proprietário no formato uuid v4 | 36 |
| `owner_document_number` * | string | CPF/CNPJ do proprietário do instrumento | 11 ou 14 |
| `payment_instrument_type` * | string | Tipo do instrumento de pagamento | **[Enumeradores payment_instrument_type](#enumeradores-payment_instrument_type)** |
| `payment_instrument_status` *| string | Status do instrumento | **[Enumeradores payment_instrument_status](#enumeradores-payment_instrument_status)** |
| `limit_amount` * | float | Limite de crédito do instrumento | - |
| `used_limit` * | float | Limite utilizado do instrumento | - |
| `created_at` * | string | Data de criação (formato ISO 8601 UTC) | - |
### Objeto pagination
| Campo | Tipo | Descrição | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `current_page` * | integer | Página atual | - |
| `rows_per_page` * | integer | Itens por página | - |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (pt-br)
`translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | CIN000069 | Bad Request | Invalid integer value for page or size query string parameters | Valor inválido para parâmetros de página ou tamanho de página |
| 400 | CIN000070 | Bad Request | Invalid query payment instrument status | Status de consulta de instrumento de pagamento inválido |
| 400 | CIN000071 | Bad Request | Invalid query payment instrument type | Tipo de consulta de instrumento de pagamento inválido |
| 404 | CIN000007 | Wallet not Found | Wallet with key: abeca0d0-a09d-4b3b-a495-40b553422ced was not found | Carteira com a chave: abeca0d0-a09d-4b3b-a495-40b553422ced não foi encontrado |
---
# Simulação de cenários
URL: /documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/simulacao_de_cenarios
Esta página descreve como simular a criação e cancelamento de entradas de instrumentos de pagamento para testar o fluxo de transações com cartões pós-pagos. Essas simulações são úteis para homologação e testes de integração.
:::info Informação
Essas requisições simulam transações externas e retornam o status HTTP com a chave da entrada criada ou cancelada.
:::
## 1 - Simulação de criação de entrada de instrumento de pagamento
Simula a criação de uma entrada de instrumento de pagamento (transação), como uma compra ou saque realizado com o cartão pós-pago. A entrada será automaticamente vinculada a itens de fatura conforme a configuração de parcelamento.
ENDPOINT /mock/invoice/payment_instrument/ POSTPAID_CARD_KEY /payment_instrument_entry
MÉTODO POST
### Path Parameters
| Campo | Tipo | Descrição | Caracteres |
|------------------------------|--------|----------------------------------------------|------------|
| `postpaid_card_key` * | string | Chave única do cartão pós-pago no formato UUID v4 | 36 |
Request Body
```json
{
"request_control_key": "f7947b9d-9be3-49d8-aca2-4b3249e5fa65",
"payment_instrument_entry_amount": 100.50,
"number_of_installments": 3,
"installment_amount": 33.50,
"payment_instrument_entry_type": "purchase",
"payment_instrument_entry_data": {
"merchant_name": "Test Merchant",
"merchant_country": "BR",
"merchant_postal_code": "01310-100",
"merchant_city": "São Paulo",
"merchant_street": "Av. Paulista"
}
}
```
### Objeto Request Body
| Campo | Tipo | Descrição | Máx. Caract. |
|------------------------------------------|---------|------------------------------------------------------------------------------------|--------------|
| `request_control_key` * | uuidv4 | Chave única de identificação da requisição utilizada pelo cliente | 36 |
| `payment_instrument_entry_amount` * | float | Valor total da transação | - |
| `number_of_installments` * | integer | Número de parcelas da transação | - |
| `installment_amount` * | float | Valor de cada parcela | - |
| `payment_instrument_entry_type` * | string | Tipo da entrada do instrumento de pagamento | **[Enumeradores payment_instrument_entry_type](#enumeradores-payment_instrument_entry_type)** |
| `payment_instrument_entry_data` * | object | Dados adicionais da transação | **[Objeto payment_instrument_entry_data](#objeto-payment_instrument_entry_data)** |
### Enumeradores payment_instrument_entry_type
| Enumerador | Descrição |
|-------------------------|-----------------------------------------------------------------------------------|
| `purchase` | Compra realizada com o cartão |
| `withdraw` | Saque realizado com o cartão |
| `postpaid_card_issuance`| Emissão de cartão pós-pago |
### Objeto payment_instrument_entry_data
| Campo | Tipo | Descrição | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `merchant_name` * | string | Nome do estabelecimento comercial | - |
| `merchant_country` * | string | País do estabelecimento comercial | - |
| `merchant_postal_code` * | string | Código postal do estabelecimento comercial | - |
| `merchant_city` * | string | Cidade do estabelecimento comercial | - |
| `merchant_street` * | string | Rua do estabelecimento comercial | - |
### Response
STATUS 201
Response Body
```json
{
"payment_instrument_entry_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6"
}
```
### Response Body Params
| Campo | Tipo | Descrição | Caracteres |
|----------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `payment_instrument_entry_key` * | uuidv4 | Chave única de identificação da entrada criada no formato UUID v4 | 36 |
:::tip Comportamento
- A simulação cria uma entrada de instrumento de pagamento com status `active`
- A entrada será automaticamente vinculada a itens de fatura (invoice items) conforme o número de parcelas informado
- Os itens de fatura serão organizados em faturas (invoices) conforme a configuração de fechamento da carteira
- O limite do instrumento de pagamento e da carteira serão validados antes de permitir a criação da entrada
:::
## 2 - Simulação de cancelamento de entrada de instrumento de pagamento
Simula o cancelamento de uma entrada de instrumento de pagamento existente, alterando seu status para `canceled` e liberando o limite utilizado.
ENDPOINT /mock/invoice/payment_instrument/ POSTPAID_CARD_KEY /payment_instrument_entry/ REQUEST_CONTROL_KEY /cancel
MÉTODO PATCH
### Path Parameters
| Campo | Tipo | Descrição | Caracteres |
|------------------------------|--------|----------------------------------------------|------------|
| `postpaid_card_key` * | string | Chave única do cartão pós-pago no formato UUID v4 | 36 |
| `request_control_key` * | uuidv4 | Chave única de identificação da requisição original utilizada na criação da entrada | 36 |
Request Body
```json
{
"payment_instrument_entry_amount": 100.50
}
```
### Objeto Request Body
| Campo | Tipo | Descrição | Máx. Caract. |
|----------------------------------|---------|------------------------------------------------------------------------------------|--------------|
| `payment_instrument_entry_amount` * | float | Valor do cancelamento. | - |
### Response
STATUS 200
Response Body
```json
{
"payment_instrument_entry_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6"
}
```
### Response Body Params
| Campo | Tipo | Descrição | Caracteres |
|----------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `payment_instrument_entry_key` * | uuidv4 | Chave única de identificação da entrada cancelada no formato UUID v4 | 36 |
:::tip Comportamento
- **Faturas abertas**: Cancelamentos em faturas abertas liberam o limite imediatamente e removem o valor da fatura
- **Faturas fechadas**: Cancelamentos em faturas fechadas criam chargebacks que aparecerão no campo `invoice_payments_chargebacks` quando forem utilizados na próxima fatura
:::
---
# Webhooks de Carteira
URL: /documentation/cartao_pos_pago/faturas/webhooks/carteira
:::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).
:::
## Introdução
Após a criação de uma carteira (`wallet`) dentro do nosso sistema, serão enviados webhooks com os seguintes status:
| Enumerador | Tradução | Descrição |
|-------------------------------|------------------------|------------------------------------------------------------|
| active | ativa | Carteira ativa e disponível para uso |
| rejected | rejeitada | Carteira rejeitada na análise KYC |
:::info Informação
O timeout para resposta de nosso webhooks é de 10 segundos.
:::
## Exemplos
----
### Confirmação de abertura
Webhook Body
```json
{
"webhook_type": "baas.invoice.wallet",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"wallet_key": "fd86d9b1-2a5e-4e03-9a59-a043c7632c97",
"owner_person_key": "ecf87b4b-fa6e-49c0-a7f0-f2cad6b42d79",
"wallet_status": "active"
}
}
```
### Campos do Webhook
| Campo | Tipo | Descrição | Caracteres |
|--------------------|---------|-----------------------------------------------------------------------------------|------------|
| wallet_key | string | Chave única de identificação da carteira no formato uuid v4 | 36 |
| owner_person_key | string | Chave única de identificação do proprietário da carteira no formato uuid v4 | 36 |
| wallet_status | string | Status da carteira | **[Enumeradores wallet_status](#enumeradores-wallet_status)** |
### Enumeradores wallet_status
| Enumerador | Descrição |
|------------|-----------------------------------------------------------------------------------|
| active | Carteira ativa e disponível para uso |
| rejected | Carteira rejeitada na análise KYC |
---
# Webhooks de Entradas de Carteira
URL: /documentation/cartao_pos_pago/faturas/webhooks/entrada_da_carteira
:::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).
:::
## Introdução
Após a criação de uma entrada de carteira (`wallet_entry`) dentro do nosso sistema, serão enviados webhooks com os seguintes status:
| Enumerador | Tradução | Descrição |
|-------------------------------|------------------------|------------------------------------------------------------|
| concluded | concluída | Entrada de carteira concluída |
:::info Informação
O timeout para resposta de nosso webhooks é de 10 segundos.
:::
## Exemplos
----
### Confirmação de criação
Webhook Body
```json
{
"webhook_type": "baas.invoice.wallet_entry",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"wallet_key": "ecf87b4b-fa6e-49c0-a7f0-f2cad6b42d79",
"wallet_entry_key": "fd86d9b1-2a5e-4e03-9a59-a043c7632c97",
"wallet_entry_amount": 150.00,
"wallet_entry_type": "revolving_credit",
"wallet_entry_status": "concluded"
}
}
```
### Campos do Webhook
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|---------|-----------------------------------------------------------------------------------|------------|
| wallet_key | string | Chave única de identificação da carteira no formato uuid v4 | 36 |
| wallet_entry_key | string | Chave única de identificação da entrada da carteira no formato uuid v4 | 36 |
| wallet_entry_amount | number | Valor da entrada da carteira | - |
| wallet_entry_type | string | Tipo da entrada da carteira | **[Enumeradores wallet_entry_type](#enumeradores-wallet_entry_type)** |
| wallet_entry_status | string | Status da entrada da carteira | **[Enumeradores wallet_entry_status](#enumeradores-wallet_entry_status)** |
### Enumeradores wallet_entry_type
| Enumerador | Descrição |
|-------------------|-----------------------------------------------------------------------------------|
| revolving_credit | Crédito rotativo |
| payroll_withdraw | Saque de folha |
| payroll_overdue | Atraso de folha |
:::info Tipos de Entrada de Carteira
- **`revolving_credit`**: Valores de crédito disponibilizados para o cliente
- **`payroll_withdraw`**: Dívida gerada pelo saque do limite e que vai ser descontada todo mês do INSS
- **`payroll_overdue`**: Dívida gerada pelo não pagamento da fatura e também vai ser descontada todo mês do INSS
:::
### Enumeradores wallet_entry_status
| Enumerador | Descrição |
|------------|-----------------------------------------------------------------------------------|
| concluded | Entrada de carteira concluída |
---
# Webhooks de Entradas de Instrumento de Pagamento
URL: /documentation/cartao_pos_pago/faturas/webhooks/entrada_do_instrumento_de_pagamento
:::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).
:::
## Introdução
Após a criação de uma entrada de instrumento de pagamento (`payment_instrument_entry`) dentro do nosso sistema, serão enviados webhooks com os seguintes status:
| Enumerador | Tradução | Descrição |
|-------------------------------|------------------------|------------------------------------------------------------|
| processing_conclusion | processando conclusão | Entrada de instrumento de pagamento em processamento de conclusão |
| processing_cancellation | processando cancelamento | Entrada de instrumento de pagamento em processamento de cancelamento |
| concluded | concluída | Entrada de instrumento de pagamento concluída |
| canceled | cancelada | Entrada de instrumento de pagamento foi cancelada |
:::info Informação
O timeout para resposta de nosso webhooks é de 10 segundos.
:::
## Exemplos
----
### Confirmação de criação
Webhook Body
```json
{
"webhook_type": "baas.invoice.payment_instrument_entry",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"payment_instrument_key": "ecf87b4b-fa6e-49c0-a7f0-f2cad6b42d79",
"payment_instrument_entry_key": "fd86d9b1-2a5e-4e03-9a59-a043c7632c97",
"payment_instrument_entry_amount": 150.00,
"payment_instrument_entry_type": "purchase",
"payment_instrument_entry_status": "concluded"
}
}
```
### Confirmação de cancelamento
Webhook Body
```json
{
"webhook_type": "baas.invoice.payment_instrument_entry",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"payment_instrument_key": "ecf87b4b-fa6e-49c0-a7f0-f2cad6b42d79",
"payment_instrument_entry_key": "fd86d9b1-2a5e-4e03-9a59-a043c7632c97",
"payment_instrument_entry_amount": 150.00,
"payment_instrument_entry_type": "purchase",
"payment_instrument_entry_status": "canceled"
}
}
```
### Processando ativação
Webhook Body
```json
{
"webhook_type": "baas.invoice.payment_instrument_entry",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"payment_instrument_key": "ecf87b4b-fa6e-49c0-a7f0-f2cad6b42d79",
"payment_instrument_entry_key": "fd86d9b1-2a5e-4e03-9a59-a043c7632c97",
"payment_instrument_entry_amount": 150.00,
"payment_instrument_entry_type": "purchase",
"payment_instrument_entry_status": "processing_conclusion"
}
}
```
### Processando cancelamento
Webhook Body
```json
{
"webhook_type": "baas.invoice.payment_instrument_entry",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"payment_instrument_key": "ecf87b4b-fa6e-49c0-a7f0-f2cad6b42d79",
"payment_instrument_entry_key": "fd86d9b1-2a5e-4e03-9a59-a043c7632c97",
"payment_instrument_entry_amount": 150.00,
"payment_instrument_entry_type": "purchase",
"payment_instrument_entry_status": "processing_cancellation"
}
}
```
### Campos do Webhook
| Campo | Tipo | Descrição | Caracteres |
|------------------------------------|---------|-----------------------------------------------------------------------------------|------------|
| payment_instrument_key | string | Chave única de identificação do instrumento de pagamento no formato uuid v4 | 36 |
| payment_instrument_entry_key | string | Chave única de identificação da entrada do instrumento de pagamento no formato uuid v4 | 36 |
| payment_instrument_entry_amount | number | Valor da entrada do instrumento de pagamento | - |
| payment_instrument_entry_type | string | Tipo da entrada do instrumento de pagamento | **[Enumeradores payment_instrument_entry_type](#enumeradores-payment_instrument_entry_type)** |
| payment_instrument_entry_status | string | Status da entrada do instrumento de pagamento | **[Enumeradores payment_instrument_entry_status](#enumeradores-payment_instrument_entry_status)** |
### Enumeradores payment_instrument_entry_type
| Enumerador | Descrição |
|-------------------------|-----------------------------------------------------------------------------------|
| purchase | Compra |
| withdrawal | Saque |
| postpaid_card_issuance | Emissão de cartão pós-pago |
### Enumeradores payment_instrument_entry_status
| Enumerador | Descrição |
|-------------------------|-----------------------------------------------------------------------------------|
| processing_conclusion | Entrada de instrumento de pagamento em processamento de conclusão |
| processing_cancellation | Entrada de instrumento de pagamento em processamento de cancelamento |
| concluded | Entrada de instrumento de pagamento concluída |
| canceled | Entrada de instrumento de pagamento foi cancelada |
:::info Observação
A entrada do instrumento de pagamento pode transicionar diretamente de `processing_conclusion` para `processing_cancellation` e `canceled`. Nesse caso, nenhum invoice item é criado.
:::
---
# Webhooks de Fatura
URL: /documentation/cartao_pos_pago/faturas/webhooks/fatura
:::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).
:::
## Introdução
Após o fechamento de uma fatura (`invoice`) dentro do nosso sistema, será enviado um webhook com a mudança de status da fatura:
| Enumerador | Tradução | Descrição |
|-------------------------------|------------------------|------------------------------------------------------------|
| processing_closing | processando fechamento | Fatura em processamento de fechamento |
| processing_expiration | processando expiração | Fatura em processamento de expiração |
| closed | fechada | Fatura fechada, não recebe mais itens e os pagamentos foram processados |
| processing_payment | aguardando pagamento | Fatura aguardando pagamento (aplicável apenas para carteiras do tipo `payroll` quando há valor restante a ser pago) |
| paid | paga | Fatura paga |
:::info Informação
O timeout para resposta de nosso webhooks é de 10 segundos.
:::
## Exemplos
### Confirmação de fechamento de fatura
Webhook Body
```json
{
"webhook_type": "baas.invoice.invoice_status_change",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"invoice_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"total_amount": 350.00,
"paid_amount": 0.00,
"closing_date": "2024-01-31",
"due_date": "2024-02-15",
"invoice_status": "closed"
}
}
```
### Fatura aguardando pagamento (carteira payroll)
Webhook Body
```json
{
"webhook_type": "baas.invoice.invoice_status_change",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"invoice_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"total_amount": 350.00,
"paid_amount": 0.00,
"closing_date": "2024-01-31",
"due_date": "2024-02-15",
"invoice_status": "processing_payment"
}
}
```
### Campos do Webhook
| Campo | Tipo | Descrição | Caracteres |
|-----------------|---------|-----------------------------------------------------------------------------------|------------|
| invoice_key | string | Chave única de identificação da fatura no formato uuid v4 | 36 |
| total_amount | number | Valor total da fatura | - |
| paid_amount | number | Valor pago da fatura | - |
| closing_date | string | Data de fechamento da fatura (formato YYYY-MM-DD) | 10 |
| due_date | string | Data de vencimento da fatura (formato YYYY-MM-DD) | 10 |
| invoice_status | string | Status da fatura | **[Enumeradores invoice_status](#enumeradores-invoice_status)** |
### Enumeradores invoice_status
| Enumerador | Descrição |
|-----------------------|-----------------------------------------------------------------------------------|
| processing_closing | Fatura em processamento de fechamento |
| processing_expiration | Fatura em processamento de expiração |
| closed | Fatura fechada, não recebe mais itens e os pagamentos foram processados |
| processing_payment | Fatura aguardando pagamento (aplicável apenas para carteiras do tipo `payroll` quando há valor restante a ser pago) |
| paid | Fatura paga |
---
# Webhooks de Pagamento de Fatura
URL: /documentation/cartao_pos_pago/faturas/webhooks/pagamento_da_fatura
:::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).
:::
## Introdução
Após a mudança de status de um pagamento de fatura (`invoice_payment`) dentro do nosso sistema, será enviado um webhook com a mudança de status do pagamento:
| Enumerador | Tradução | Descrição |
|-------------------------------|------------------------|------------------------------------------------------------|
| processing_payment | aguardando pagamento | Pagamento de fatura aguardando pagamento |
| paid | pago | Pagamento de fatura pago |
:::info Informação
O timeout para resposta de nosso webhooks é de 10 segundos.
:::
## Exemplos
### Pagamento de fatura (payroll_discount)
Webhook Body
```json
{
"webhook_type": "baas.invoice.invoice_payment_status_change",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"wallet_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"invoice_payment_key": "3571e292-3a83-4011-904d-20ee963022ef",
"total_amount": 350.00,
"paid_amount": 0.00,
"payment_date": "2024-02-15",
"invoice_payment_type": "payroll_discount",
"invoice_payment_status": "processing_payment"
}
}
```
### Pagamento de fatura (bank_slip)
Webhook Body
```json
{
"webhook_type": "baas.invoice.invoice_payment_status_change",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"wallet_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"invoice_payment_key": "3571e292-3a83-4011-904d-20ee963022ef",
"total_amount": 350.00,
"paid_amount": 0.00,
"payment_date": "2024-02-15",
"invoice_payment_type": "bank_slip",
"invoice_payment_status": "processing_payment"
}
}
```
### Campos do Webhook
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|---------|-----------------------------------------------------------------------------------|------------|
| wallet_key | string | Chave única de identificação da carteira no formato uuid v4 | 36 |
| invoice_payment_key | string | Chave única de identificação do pagamento de fatura no formato uuid v4 | 36 |
| total_amount | number | Valor total do pagamento de fatura | - |
| paid_amount | number | Valor pago do pagamento de fatura | - |
| payment_date | string | Data do pagamento (formato YYYY-MM-DD) | 10 |
| invoice_payment_type | string | Tipo do pagamento de fatura | **[Enumeradores invoice_payment_type](#enumeradores-invoice_payment_type)** |
| invoice_payment_status | string | Status do pagamento de fatura | **[Enumeradores invoice_payment_status](#enumeradores-invoice_payment_status)** |
### Enumeradores invoice_payment_type
| Enumerador | Descrição |
|-------------------|-----------------------------------------------------------------------------------|
| bank_slip | Boleto bancário |
| payroll_discount | Desconto via folha de pagamento |
### Enumeradores invoice_payment_status
| Enumerador | Descrição |
|-----------------------|-----------------------------------------------------------------------------------|
| processing_payment | Pagamento de fatura aguardando pagamento |
| paid | Pagamento de fatura pago |
:::info Observação
- Para pagamentos do tipo `payroll_discount`: o pagamento é criado no momento do fechamento da fatura com o status `processing_payment` e o desconto é solicitado no INSS. Quando o pagamento do desconto é realizado, o status muda para `paid`.
- Para pagamentos do tipo `bank_slip`: o pagamento é criado com status `processing_payment` quando recebemos o aviso de pagamento do boleto. No momento da liquidação do boleto, o status muda para `paid`. O pagamento pode ser criado com status `paid` diretamente caso não seja recebido um aviso de pagamento.
:::
---
# Introdução
URL: /documentation/cartao_pos_pago/introducao
## Cartão Pós-Pago
As APIs para emissão de cartões pós-pago oferecem aos parceiros da QI Tech uma maneira simples e eficiente de permitir que seus clientes solicitem e emitam Cartões Pós-Pagos, tanto **físicos** quanto **virtuais**.
Na QI Tech, proporcionamos aos nossos parceiros a oportunidade de se tornarem subemissores. Por meio de nossas APIs, eles podem oferecer aos seus próprios clientes a possibilidade de emitir cartões pós-pagos, criando uma solução completa para serviços bancários e financeiros.
Para compreender melhor nosso sistema, apresentamos uma visão geral de como funciona o ecossistema de cartões pós-pagos. Contudo, é importante ressaltar que, assim como em todas as nossas APIs, a liberação do serviço deve ser realizada junto ao nosso time, e as **[chamadas são autenticadas](/documentation/primeiros_passos/teste_de_autenticacao)**.
O cartão pós-pago é um cartão vinculado a uma linha de crédito que permite ao portador realizar transações, com o pagamento sendo feito posteriormente. Diferente dos cartões pré-pagos, os cartões pós-pagos não exigem que o saldo da conta seja pré-carregado. O usuário pode realizar compras e pagar posteriormente, conforme o limite de crédito aprovado.
As transações realizadas por meio do cartão pós-pago serão cobradas na fatura do portador, com um prazo determinado para o pagamento. Caso o pagamento não seja realizado até a data de vencimento, o portador pode estar sujeito a encargos financeiros, como juros e taxas.
## Programa
Para realizar a emissão de um cartão pós-pago, o parceiro precisa ter um programa configurado na integração com a QI Tech. O programa define as regras e parâmetros necessários para a emissão de cartões em conformidade com as bandeiras, como o VISA.
Aqui estão algumas informações importantes sobre o programa:
* **Tipo do programa** - Refere-se à modalidade de utilização do cartão. Neste caso, trata-se da modalidade Pós-Pago.
* **Bandeira** - Utilizamos a bandeira VISA para os cartões emitidos.
* **Layout do cartão** - Refere-se ao design do cartão, tanto para o modelo físico quanto virtual, que será exibido na interface gráfica.
:::caution Atenção
Para configurar um novo programa de cartões pós-pago, é necessário envolver os times comerciais e de implantação da QI Tech.
:::
## Carteira (Wallet)
Para emitir cartões de crédito pós-pagos, é necessário primeiro criar uma **carteira (wallet)** que organiza a fatura do cliente. A carteira funciona como um "conta" onde ficam todos os cartões e configurações de faturamento.
:::info O que é uma Wallet
A **wallet** é como a conta do cliente onde ficam todos os cartões e faturas:
- **Uma wallet = fatura**: Cada carteira corresponde à fatura de um cliente específico (identificado por CPF/CNPJ)
- **Múltiplos meios de pagamento**: A mesma wallet pode ter diferentes instrumentos de pagamento (cartões, PIX, etc.)
- **Instrumentos separados**: Após criar a wallet, será necessário criar separadamente os instrumentos de pagamento (cartões de crédito, limites, etc.)
- **Gestão centralizada**: A wallet centraliza todas as operações e configurações relacionadas àquele cliente
:::
Para mais detalhes sobre a criação de carteiras, consulte a **[documentação completa de criação de carteira](/documentation/cartao_pos_pago/faturas/carteira/criacao_de_carteira)**.
## Fluxo de Emissão
Para emitir cartões de crédito pós-pagos, o processo segue uma sequência lógica que começa com a criação de uma carteira (wallet) para o cliente. Esta carteira funciona como um "conta" para organizar todos os cartões e configurações de faturamento.
Após a criação da carteira, é necessário criar um **instrumento de pagamento** do tipo `postpaid_card`. Este instrumento é responsável por gerenciar todas as transações e compras realizadas com o cartão. Ao criar o instrumento, um cartão físico ou virtual é criado automaticamente conforme solicitado.
:::info Instrumento de Pagamento
O instrumento de pagamento do tipo `postpaid_card`:
- **Centraliza as transações**: Todas as compras realizadas com o cartão ficam atreladas a este instrumento para gerenciamento
- **Cria o cartão automaticamente**: Ao criar o instrumento, um cartão físico ou virtual é criado automaticamente conforme solicitado
- **Gerencia o ciclo de vida**: O acompanhamento do status e operações do cartão é feito através dos **[endpoints de gestão do cartão pós-pago](/documentation/cartao_pos_pago/cartao/busca/buscar_cartao_por_chave)**
:::
Para criar o instrumento de pagamento, consulte a **[documentação de criação de PaymentInstrument](/documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/criacao_de_instrumento_de_pagamento)**.
### Configuração de Limites
A carteira possui um limite global de crédito que define o teto máximo disponível para uso. **Limites individuais para os instrumentos de pagamento também podem ser configurados**.
:::info Como Funcionam os Limites
- **Limite da carteira**: Define o teto máximo de crédito disponível para uso
- **Limite dos instrumentos**: Cada instrumento pode ter seu próprio limite configurado, desde que seja menor que o da carteira
- **Exemplo prático**: Uma carteira com limite de R$ 100 pode ter dois instrumentos com limites de R$ 100 e R$ 80, mas quando o uso dos dois instrumentos chegar a R$ 100, não será possível fazer mais compras
- **Validação em tempo real**: Tanto o limite do instrumento quanto o limite da carteira são validados antes de permitir uma nova transação
:::
:::info Limites em Carteiras Payroll
Carteiras do tipo `payroll` possuem dois limites distintos:
- **`postpaid_credit_limit`**: Limite de crédito pós-pago para compras e transações com o cartão
- **`payroll_withdraw_limit`**: Limite específico para saques de folha de pagamento (salário/benefício), que são descontados automaticamente na folha de pagamento do cliente
Ambos os limites aparecem na lista `wallet_limits` da carteira e funcionam de forma independente, permitindo que o cliente tenha um limite para compras com o cartão e outro limite específico para saques de benefício.
:::
### Gestão e Acompanhamento do Cartão
Com a carteira e o instrumento de pagamento configurados, o cartão (físico ou virtual) é criado automaticamente e fica disponível para uso. A carteira centraliza todas as informações de faturamento, permitindo o acompanhamento de transações, pagamentos e configurações de juros e multas.
O acompanhamento do status e ciclo de vida do cartão pode ser realizado através dos **[endpoints de gestão do cartão pós-pago](/documentation/cartao_pos_pago/cartao/busca/buscar_cartao_por_chave)**, que permitem monitorar todas as etapas do ciclo de vida do cartão, desde a criação até a baixa ou cancelamento.
## Entradas da Carteira (Wallet Entry)
As **entradas da carteira (wallet entries)** são dívidas que ficam registradas na carteira do cliente. Essas dívidas podem ser de diferentes tipos:
- **Crédito rotativo (`revolving_credit`)**: Valores de crédito disponibilizados para o cliente
- **Saque de folha (`payroll_withdraw`)**: Dívida gerada pelo saque do limite e que vai ser descontada todo mês do INSS
- **Atraso de folha (`payroll_overdue`)**: Dívida gerada pelo não pagamento da fatura e também vai ser descontada todo mês do INSS
:::info Como Funcionam as Wallet Entries
- **Uma entrada = uma dívida**: Cada entrada é uma dívida específica
- **Vira item na fatura**: Cada parcela vira automaticamente um item na fatura
- **Organiza na fatura**: Os itens são organizados em faturas
- **Tudo centralizado**: Todas as dívidas ficam organizadas na carteira
:::
Para mais informações e consulta das entradas da carteira (Wallet Entry), consulte a **[documentação de Wallet Entries](/documentation/cartao_pos_pago/faturas/carteira/listar_entradas_da_carteira)**.
:::tip Webhooks de Wallet Entry
Para acompanhar em tempo real as mudanças de status das entradas da carteira, utilize os **[webhooks de Wallet Entry](/documentation/cartao_pos_pago/faturas/webhooks/wallet_entry)**.
:::
## Entradas de Instrumento de Pagamento (Payment Instrument Entry)
As **entradas de instrumento de pagamento (payment instrument entries)** são as transações feitas com o cartão. Cada compra ou saque vira uma entrada:
- **Transações do cartão**: Compras realizadas com o cartão pós-pago
- **Saques do cartão**: Saques realizados com o cartão pós-pago
- **Outras operações**: Demais transações relacionadas ao instrumento
:::info Como Funcionam as Payment Instrument Entries
- **Vinculação automática**: Cada entrada é automaticamente atrelada a um **invoice item**
- **Organização em faturas**: Os invoice items são organizados em **invoices**
- **Criação automática de faturas**: Quando uma nova transação é criada, o sistema automaticamente cria as faturas necessárias para acomodar todas as parcelas da transação, baseado na configuração de fechamento da carteira
:::
:::warning Importante sobre Cancelamentos
- **Faturas abertas**: Cancelamentos em faturas abertas liberam o limite imediatamente e removem o valor da fatura
- **Faturas fechadas**: Cancelamentos em faturas fechadas criam chargebacks que aparecerão no campo `invoice_payments_chargebacks` e serão utilizados na próxima fatura
:::
Para mais informações e consulta das entradas de instrumento de pagamento (Payment Instrument Entry), consulte a **[documentação de Payment Instrument Entries](/documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/listar_entradas_do_instrumento_de_pagamento)**.
:::tip Webhooks de Payment Instrument Entry
Para acompanhar em tempo real as mudanças de status das entradas de instrumento de pagamento, utilize os **[webhooks de Payment Instrument Entry](/documentation/cartao_pos_pago/faturas/webhooks/payment_instruction_entry)**.
:::
## Faturas (Invoice)
As **faturas (invoices)** são criadas automaticamente conforme a necessidade dos invoice items. Elas funcionam como contêineres que agrupam os itens relacionados:
- **Criação automática**: São criadas automaticamente quando necessário, baseadas na configuração de fechamento da carteira
- **Status inicial**: Todas começam com status `opened` (aberta)
- **Recebe novos itens**: Novas compras e transações vão para faturas abertas
- **Fechamento automático**: Faturas são fechadas automaticamente um dia após sua data de fechamento
:::info Ciclo de Vida das Faturas
- **`opened`**: Fatura aberta, recebendo novos itens. Neste status, novos invoice items podem ser adicionados à fatura
- **`closed`**: Fatura fechada, não recebe mais itens. Neste status, a fatura foi processada e o boleto da fatura é atualizado com o novo valor e vencimento. O boleto pode ser consultado através dos endpoints de boleto
- **`processing_payment`**: Aguardando pagamento. Aplicado apenas para carteiras do tipo `payroll` quando há apenas valor restante a ser pago com o benefício após o desconto em folha
:::
:::info Carteiras Payroll
Para carteiras do tipo `payroll`, o fechamento funciona de forma especial:
- **Desconto em folha**: Valores de desconto no INSS são agrupados em um invoice payment do tipo `payroll_discount` que será descontado automaticamente na folha de pagamento. Este pagamento é criado com status `processing_payment` quando o desconto é solicitado no INSS e muda para `paid` quando o pagamento do desconto é realizado
- **Boleto atualizado**: Quando há valor restante após o desconto em folha, o boleto da fatura é atualizado com o novo valor. O boleto pode ser consultado, mas o invoice payment do tipo `bank_slip` só será criado quando o boleto for efetivamente pago
- **Status processing_payment**: Se não há valor a ser pago via boleto, a fatura fica com status `processing_payment` até que o pagamento do benefício seja realizado
:::
Para mais informações e consulta dos itens da fatura (Invoice), consulte a **[documentação de Faturas](/documentation/cartao_pos_pago/faturas/fatura/listar_faturas)**.
## Itens de Fatura (Invoice Item)
Os **itens de fatura (invoice items)** são criados automaticamente para cada parcela das entradas (wallet entry ou payment instrument entry). Eles representam os componentes individuais que compõem uma fatura:
- **Parcelas de dívidas**: Cada parcela de uma wallet entry gera um invoice item
- **Transações individuais**: Cada parcela de um payment instrument entry gera um invoice item
- **Detalhamento da fatura**: Permitem o controle granular de cada item
:::info Características dos Invoice Items
- **Vinculação obrigatória**: Todo invoice item deve estar vinculado a uma **invoice**
- **Rastreabilidade**: Mantêm referência à entrada original
- **Status individual**: Cada item pode ter seu próprio status (pending, paid, canceled)
- **Valores detalhados**: Contêm informações específicas como valor, limite utilizado e valor pago
:::
Para mais informações e consulta dos itens da fatura (Invoice Item), consulte a **[documentação de Invoice Items](/documentation/cartao_pos_pago/faturas/fatura/consulta_por_chave)**.