Gestão de Endereço

Navegação

• Documentos e Assinatura (anterior)

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

1. Webhook de problema no endereço

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

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

Ação Necessária

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

Prazo para Falha de Entrega (delivery_failure)

Após o recebimento de um webhook de falha na entrega, o cliente tem um prazo de 10 dias para atualizar o endereço do beneficiário. Caso o prazo não seja cumprido, o cartão físico será cancelado e será necessária uma nova emissão do cartão através do endpoint de Reemissão de Cartão.

WEBHOOK TYPE

laas.payroll_card_reservation.address

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

Webhook Body — address_mismatch

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

1.2 Exemplo: Falha na entrega do cartão

Webhook Body — delivery_failure

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

---

2. Atualização de Endereço

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

informação

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

Request

PATCH

/payroll_card_reservation/{collateral_type}/{payroll_card_reservation_key}/address

Testar no Playground

Request Body

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

Params Details

Campo	Tipo	Descrição	Formatação	Obrigatório
city	string	Cidade	1 a 100 caracteres	Sim
state	string	Estado (UF)	Sigla da UF em maiúsculas (ex.: MG)	Sim
number	string	Número	1 a 10 caracteres	Sim
street	string	Logradouro	1 a 100 caracteres	Sim
complement	string	Complemento	1 a 100 caracteres	Não
postal_code	string	CEP	Exatamente 8 dígitos, sem hífen	Sim
neighborhood	string	Bairro	1 a 100 caracteres	Sim

Campos não listados nesta tabela são rejeitados.

Response

STATUS

200 (OK)

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

Erros

Status	Código	Descrição
400	QIT000001	O corpo da requisição viola as regras de formatação da tabela de campos. O campo description indica a regra violada e o caminho do campo (ex.: address.number).

---

3. Reemissão de Cartão

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

Preservação da operação

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

Cobrança da re-emissão

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

Status elegíveis do cartão

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

Atualização de endereço no mesmo fluxo

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

Request

POST

/payroll_card_reservation/{collateral_type}/{payroll_card_reservation_key}/reissue_card

Testar no Playground

Request Body (opcional)

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

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

Request Body Details

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

Payload delivery_address

Campo	Tipo	Descrição	Formatação	Obrigatório
city	string	Cidade	1 a 100 caracteres	Sim
state	string	Estado (UF)	Sigla da UF em maiúsculas (ex.: MG)	Sim
number	string	Número	1 a 10 caracteres	Sim
street	string	Logradouro	1 a 100 caracteres	Sim
complement	string	Complemento	1 a 100 caracteres	Não
postal_code	string	CEP	Exatamente 8 dígitos, sem hífen	Sim
neighborhood	string	Bairro	1 a 100 caracteres	Sim

Campos não listados nesta tabela são rejeitados.

Limite do campo number

O campo number aceita no máximo 10 caracteres. Valide o tamanho de todos os campos antes do envio: a API rejeita a requisição inteira e o cartão não é reemitido.

Response

STATUS

200 (OK)

Retorna o DTO completo da reserva do cartão consignado, já com o novo payroll_card (nova payroll_card_key, card_key e payment_instrument_key). A estrutura do retorno é a mesma descrita na criação da reserva.

Erros

Status	Código	Descrição
400	QIT000001	O corpo da requisição viola as regras de formatação da tabela de campos. O campo description indica a regra violada e o caminho do campo (ex.: delivery_address.number).

Exemplo: number com mais de 10 caracteres

{
    "code": "QIT000001",
    "title": "Bad Request",
    "description": "'12345678901' is too long in delivery_address.number",
    "translation": "Payload Invalido"
}