Buscar Item

Retorna o status e detalhes de uma conexão específica, incluindo informações de autenticação OAuth e avisos.

Endpoint

Método e URL:

GET /v1/items/:id

Parâmetros da URL:

• id (string, obrigatório): Identificador único do item (UUID v7)

Campos da Resposta

• status: Status da operação ("success")
• data: Dados do item
  • id: Identificador único do item
  • connectorId: Identificador do conector da instituição associado ao item
  • status: Status atual da conexão
  • auth: Informações de autenticação OAuth (presente apenas quando há ação pendente)
    • authUrl: URL para autenticação OAuth
    • expiresAt: Data de expiração da URL de autenticação
    • userAction: Ação que o usuário precisa realizar para concluir a autenticação
  • warnings: Array de avisos e alertas
    • type: Tipo do aviso
    • code: Código específico do aviso
    • severity: Nível de severidade (LOW, MEDIUM, HIGH)
    • message: Mensagem do aviso
    • providerMessage: Mensagem original do provedor
  • updatedAt: Data da última atualização
  • createdAt: Data de criação

Status Possíveis

• pending: Conexão em andamento
• syncing: Sincronizando dados
• synced: Sincronizado com sucesso
• merging: Mesclando dados
• out_of_sync: Dados desatualizados
• auth_error: Erro de autenticação
• waiting_user_input: Aguardando entrada do usuário (ex: OAuth)

Exemplo de Uso

Requisição:

GET /v1/items/01985c42-1234-5678-9abc-def123456789

Resposta

Resposta de sucesso - Item conectado (200):

{
  "status": "success",
  "data": {
    "id": "01985c42-1234-5678-9abc-def123456789",
    "status": "synced",
    "auth": null,
    "warnings": [],
    "updatedAt": "2024-01-01T10:30:00Z",
    "createdAt": "2024-01-01T10:00:00Z"
  }
}

Resposta de sucesso - Item aguardando OAuth (200):

{
  "status": "success",
  "data": {
    "id": "01985c42-1234-5678-9abc-def123456789",
    "status": "waiting_user_input",
    "auth": {
      "authUrl": "https://oauth.bank.com/auth?token=abc123",
      "expiresAt": "2024-01-01T11:00:00Z"
    },
    "warnings": [],
    "updatedAt": "2024-01-01T10:30:00Z",
    "createdAt": "2024-01-01T10:00:00Z"
  }
}

Resposta com avisos (200):

{
  "status": "success",
  "data": {
    "id": "01985c42-1234-5678-9abc-def123456789",
    "status": "synced",
    "auth": null,
    "warnings": [
      {
        "type": "CREDENTIALS",
        "code": "WEAK_PASSWORD",
        "severity": "MEDIUM",
        "message": "Recomendamos atualizar sua senha",
        "providerMessage": "Password strength is below recommended level"
      }
    ],
    "updatedAt": "2024-01-01T10:30:00Z",
    "createdAt": "2024-01-01T10:00:00Z"
  }
}

Resposta de erro (404):

{
  "status": "error",
  "message": "Item not found."
}

Fluxo de Autenticação OAuth

Quando o item retorna com status waiting_user_input e campo auth preenchido:

1. Redirecione o usuário para auth.authUrl
2. O usuário completa a autenticação na instituição
3. A instituição redireciona de volta para sua aplicação
4. Verifique novamente o status do item - deve mudar para synced

Notas

• Monitore este endpoint regularmente após criar um item para acompanhar o progresso
• URLs de autenticação OAuth têm prazo de validade limitado
• Avisos não impedem o funcionamento, mas fornecem informações importantes
• O campo auth só aparece quando autenticação OAuth é necessária