Avisos e Códigos de Status

Entendendo os códigos de aviso e seus significados ao recuperar dados dos conectores Pluggy.

Visão Geral#

Ao recuperar dados de instituições financeiras através do Pluggy, você pode encontrar situações em que alguns dados estão indisponíveis ou não podem ser recuperados por várias razões. O Pluggy utiliza um sistema de aviso padronizado para informá-lo sobre essas situações sem falhar em todo o processo de coleta de dados.

Os avisos são retornados como parte do statusDetail para cada tipo de produto (Contas, Cartões de Crédito, Transações, etc.) e incluem:

• Um código: Um identificador único para o tipo de aviso
• Uma mensagem: Uma descrição legível por humanos do problema
• Uma providerMessage (opcional): A mensagem exata da Instituição Financeira em português, sem tratamento

Isso permite que você lide com essas situações de forma elegante em sua aplicação e forneça feedback apropriado aos seus usuários.

Quando os Avisos Ocorrem#

Os avisos estão incluídos no statusDetail nestes cenários:

• O produto não pôde ser recuperado, e contém o motivo (isUpdated: false)
• O produto foi recuperado corretamente, mas pode ser melhorado com alguma ação do usuário (isUpdated: true)

Por exemplo: se o usuário não tem acesso a transações, nós as retornamos como vazias, mas um aviso sobre transações informa que, com mais permissões, poderíamos estar recuperando transações.

Cenários Comuns#

Problemas de Permissão#

O usuário não concedeu as permissões necessárias durante o fluxo de consentimento, ou o consentimento expirou.

Status do Recurso#

Um recurso específico (conta, cartão de crédito, empréstimo ou investimento) está em um estado que impede a recuperação de dados:

• Autorização Pendente: O recurso está aguardando autorização do usuário na instituição financeira
• Indisponível Temporariamente: O recurso está temporariamente indisponível (por exemplo, manutenção)
• Indisponível: O recurso está permanentemente indisponível

Nos itens de Open Finance, o hasResourcesPendingAuthorization do Item resume os recursos pendentes em todos os produtos, e GET /items/{id}/resources?status=PENDING_AUTHORISATION lista-os.

Limites de Taxa#

A instituição financeira atingiu seu limite de taxa operacional para o período atual. Veja Limites de Taxa Operacional para mais informações sobre limites de taxa de Open Finance.

Problemas de Sincronização#

Alguns dados não puderam ser sincronizados, mas dados de fallback de uma sincronização bem-sucedida anterior estão sendo usados em vez disso.

Lidando com Avisos#

Os avisos estão incluídos na resposta para cada produto. Aqui está um exemplo de como os avisos aparecem na resposta da API:

Conectores OF

{
  "accounts": [],
  "warnings": {
    "accounts": [
      {
        "code": "ACCT_002",
        "message": "A conta c0a7d38c-d967-3b94-9d0b-c391068f4b20 está pendente de autorização"
      }
    ],
    "creditCards": [],
    "transactions": [],
    "loans": []
  }
}

Conectores Diretos

{
  "accounts": [],
  "warnings": {
    "investments": [
      {
        "code": "001",
        "message": "O usuário não tem permissões para visualizar investimentos nesta conta",
        "providerMessage": "Seu perfil de usuário não está habilitado para esta transação."
      }
    ],
    "creditCards": [],
    "transactions": [],
    "loans": []
  }
}

Neste exemplo, uma conta está pendente de autorização e não foi incluída na lista de contas.

Referência de Códigos de Aviso#

Conectores de Open Finance#

Os conectores de Open Finance utilizam um sistema de aviso padronizado e tipado com códigos específicos por produto.

Contas (ACCOUNTS)#

Cartões de Crédito (CREDIT_CARDS)#

Transações (TRANSACTIONS)#

Empréstimos (LOANS)#

Investimentos (INVESTMENTS)#

Identidade (IDENTITY)#

Conectores Diretos#

Os conectores diretos podem usar códigos genéricos (como 001, 002, 003) com significados específicos do conector. O campo providerMessage fornece contexto em português da instituição.

Aqui está uma lista de avisos conhecidos para Conectores Diretos: